From ed761d546905fa3c52013c1075865991b5f485ff Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Tue, 3 Jan 2006 00:03:41 +0000 Subject: trunk/Master/texmf/doc/texinfo/ git-svn-id: svn://tug.org/texlive/trunk@60 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf/doc/texinfo/info-stnd.html | 2463 ++++ Master/texmf/doc/texinfo/info-stnd.pdf | Bin 0 -> 366035 bytes Master/texmf/doc/texinfo/info.html | 1534 +++ Master/texmf/doc/texinfo/info.pdf | Bin 0 -> 229224 bytes Master/texmf/doc/texinfo/texinfo.html | 19883 ++++++++++++++++++++++++++++++ Master/texmf/doc/texinfo/texinfo.pdf | Bin 0 -> 1603231 bytes 6 files changed, 23880 insertions(+) create mode 100644 Master/texmf/doc/texinfo/info-stnd.html create mode 100644 Master/texmf/doc/texinfo/info-stnd.pdf create mode 100644 Master/texmf/doc/texinfo/info.html create mode 100644 Master/texmf/doc/texinfo/info.pdf create mode 100644 Master/texmf/doc/texinfo/texinfo.html create mode 100644 Master/texmf/doc/texinfo/texinfo.pdf (limited to 'Master/texmf/doc') diff --git a/Master/texmf/doc/texinfo/info-stnd.html b/Master/texmf/doc/texinfo/info-stnd.html new file mode 100644 index 00000000000..3e227d9a42f --- /dev/null +++ b/Master/texmf/doc/texinfo/info-stnd.html @@ -0,0 +1,2463 @@ + + +GNU Info 4.7 + + + + + + + + + + +

GNU Info 4.7

+
+

Table of Contents

+ +
+ + + +
+


+Next: , +Up: (dir) +
+
+ +

GNU Info

+ +

This manual is for GNU Info (version 4.7, 23 March 2004), +a program for viewing documents in Info format (usually created from +Texinfo source files). + +

Copyright © 1992, 1993, 1996, 1997, 1998, 1999, 2001, 2002, +2003, 2004 Free Software Foundation, Inc. + +

+Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being “A GNU Manual,” +and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled “GNU Free Documentation +License.” + +

(a) The FSF's Back-Cover Text is: “You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.” +

+ +

This documentation is different from the documentation for the Info +reader that is part of GNU Emacs. If you do not know how to use Info, +but have a working Info reader, you should read the Emacs documentation +first, as it includes more background information and a thorough tutorial. + +

+ +
+


+Next: , +Previous: Top, +Up: Top +
+
+ +

1 What is Info?

+ +

Info is a program which is used to view Info files on an ASCII +terminal. Info files are the result of processing Texinfo files +with the program makeinfo or with one of the Emacs commands, such +as M-x texinfo-format-buffer. 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. + +

+


+Next: , +Previous: What is Info, +Up: Top +
+
+ +

2 Invoking Info

+ +

+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: + +

     info [option]... [menu-item...]
+
+

The program accepts the following options: + +

+ +
--apropos=string
Specify a string to search in every index of every Info file installed +on your system. Info looks up the named string in all the indices +it can find, prints the results to standard output, and then exits. If +you are not sure which Info file explains certain issues, this option is +your friend. Note that if your system has a lot of Info files +installed, searching all of them might take some time. + +

You can invoke the apropos command from inside Info; see +Searching Commands. + +


--directory directory-path
-d directory-path
Prepend directory-path to the list of directory paths searched +when Info needs to find a file. You may issue --directory +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 INFOPATH; --directory causes the +named directory-path to be prepended to that list. The value of +INFOPATH 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 INFOPATH, Info uses a default path defined when Info was +built as the initial list of directories. If the value of +INFOPATH 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 INFOPATH. + +


--dribble=dribble-file
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 +--restore option below. + +
--file filename
-f filename
Specify a particular Info file to visit. By default, Info visits +the file dir; if you use this option, Info will start with +(filename)Top as the first file and node. + +

If filename is an absolute file name, or begins with ./ or +../, Info looks for filename only in the directory of the +specified filename, and adds the directory of filename to +the value of INFOPATH. In contrast, if filename is in the +form of a relative file name, but without the ./ or ../ +prefix, Info will only look for it in the directories specified in +INFOPATH. In other words, Info does not treat file names +which lack ./ and ../ prefix as relative to the current +directory. + +

In every directory Info tries, if filename is not found, Info +looks for it with a number of known extensions of Info files1. For every +known extension, Info looks for a compressed file, if a regular file +isn't found. Info supports files compressed with gzip, +bzip2, compress and yabba programs; it calls +gunzip, bunzip2, uncompress and unyabba, +accordingly, to decompress such files. Compressed Info files are +assumed to have .z, .gz, .bz2, .Z, or +.Y extensions, possibly in addition to one of the known Info +files extensions2. + +

--help
-h
Produces a relatively brief description of the available Info options. + +
--index-search string
After processing all command-line arguments, go to the index in the Info +file and search for index entries which match string. If such an +entry is found, the Info session begins with displaying the node pointed +to by the first matching index entry; press , to step through the +rest of the matching entries. If no such entry exists, print no +entries found 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. + +

This command can also be invoked from inside Info; see Searching Commands. + +

--node nodename
-n nodename
Specify a particular node to visit in the initial file that Info +loads. This is especially useful in conjunction with +--file3. You may specify --node multiple times; for +an interactive Info, each nodename is visited in its own window, +for a non-interactive Info (such as when --output is given) each +nodename is processed sequentially. + +
--output filename
-o filename
Specify filename as the name of a file to which to direct output. +Each node that Info visits will be output to filename instead of +interactively viewed. A value of - for filename specifies +the standard output. + +


--raw-escapes
--no-raw-escapes
-R
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 --no-raw-escapes to make Info remove them. + +


--restore=dribble-file
Read keystrokes from dribble-file, presumably recorded during +previous Info session (see the description of the --dribble +option above). When the keystrokes in the files are all read, Info +reverts its input to the usual interactive operation. + +

+

--show-options
--usage
-O
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 +M-x goto-invocation command (see goto-invocation) from inside +Info. + +


--speech-friendly
-b
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. + +
--subnodes
This option only has meaning when given in conjunction with +--output. 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. + +
--version
Prints the version information of Info and exits. + +

+

--vi-keys
This option binds functions to keys differently, to emulate the key +bindings of vi and Less. The default key bindings are generally +modeled after Emacs. +(See Custom Key Bindings, +for a more general way of altering GNU Info's key bindings.) + +


--where
--location
-w
Show the filename that would be read and exit, instead of actually +reading it and starting Info. + +
menu-item
+Info treats its remaining arguments as the names of menu items. The +first argument is a menu item in the initial node visited (generally +dir), 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, + +
          info emacs buffers
+     
+

first selects the menu item Emacs in the node (dir)Top, +and then selects the menu item Buffers in the node +(emacs)Top. +

+ +

To avoid searching the dir files and just show some arbitrary +file, use -f and the filename, as in info -f ./foo.info. + +

The index search and the search for the node which describes program +invocation and command-line options begins after 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 +info emacs --show-options does what you'd expect. + + +

+


+Next: , +Previous: Invoking Info, +Up: Top +
+
+ +

3 Moving the Cursor

+ +

+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 User Input (the GNU Emacs Manual), if you are unfamiliar with the +notation.4 + +

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 M-x5 command name (displayed in parentheses), and a short +description of what the command does. All of the cursor motion commands +can take a numeric argument (see universal-argument. With a +numeric argument, the motion commands are simply executed that +many times; for example, a numeric argument of 4 given to +next-line causes the cursor to move down 4 lines. With a +negative numeric argument, the motion is reversed; an argument of -4 +given to the next-line command would cause the cursor to move +up 4 lines. + +

+
<C-n> (next-line)
<DOWN> (an arrow key)
Move the cursor down to the next line. + +
<C-p> (prev-line)
<UP> (an arrow key)
Move the cursor up to the previous line. + +
<C-a> (beginning-of-line)
<Home> (on DOS/Windows only)
Move the cursor to the start of the current line. + +
<C-e> (end-of-line)
<End> (on DOS/Windows only)
Move the cursor to the end of the current line. + +
<C-f> (forward-char)
<RIGHT> (an arrow key)
Move the cursor forward a character. + +
<C-b> (backward-char)
<LEFT> (an arrow key)
Move the cursor backward a character. + +
<M-f> (forward-word)
C-<RIGHT> (on DOS/Windows only)
Move the cursor forward a word. + +
<M-b> (backward-word)
C-<LEFT> (on DOS/Windows only)
Move the cursor backward a word. + +
<M-<> (beginning-of-node)
<C-<Home>> (on DOS/Windows only)
<b>
<M-b>, vi-like operation
Move the cursor to the start of the current node. + +
<M->> (end-of-node)
<C-<End>> (on DOS/Windows only)
<e>
Move the cursor to the end of the current node. + +
<M-r> (move-to-window-line)
Move the cursor to a specific line of the window. Without a numeric +argument, M-r moves the cursor to the start of the line in the +center of the window. With a numeric argument of n, M-r +moves the cursor to the start of the nth line in the window. +
+ +
+


+Next: , +Previous: Cursor Commands, +Up: Top +
+
+ +

4 Moving Text Within a Window

+ +

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

Scrolling commands are bound differently when --vi-keys operation +is in effect (see –vi-keys). These key bindings are designated +with “vi-like operation”. + +

+
<SPC> (scroll-forward)
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>. + +

The default scroll size is one screen-full, but it can be changed by +invoking the (scroll-forward-page-only-set-window) command, +z under --vi-keys, with a numeric argument. + +

<NEXT> (an arrow key) (scroll-forward-page-only)
<C-v>
<C-f>, vi-like operation
<f>, vi-like operation
<M-SPC>, vi-like operation
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. + +

The <NEXT> key is known as the <PageDown> key on some +keyboards. + +

<z> (scroll-forward-page-only-set-window, vi-like operation)
Scroll forward, like with <NEXT>, but if a numeric argument is +specified, it becomes the default scroll size for subsequent +scroll-forward and scroll-backward commands and their +ilk. + +
<DEL> (scroll-backward)
Shift the text in this window down. The inverse of +scroll-forward. +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 (scroll-backward-page-only-set-window) command, +w under --vi-keys, with a numeric argument. + +
<PREVIOUS> (arrow key) (scroll-backward-page-only)
<PRIOR> (arrow key)
<M-v>
<b>, vi-like operation
<C-b>, vi-like operation
Shift the text in this window down. The inverse of +scroll-forward-page-only. Does not scroll beyond the start of +the current node. The default scroll size can be changed by invoking +the(scroll-backward-page-only-set-window) command, w under +--vi-keys, with a numeric argument. + +
<w> (scroll-backward-page-only-set-window, vi-like operation)
Scroll backward, like with <PREVIOUS>, but if a numeric argument is +specified, it becomes the default scroll size for subsequent +scroll-forward and scroll-backward commands. + +
<C-n> (down-line, vi-like operation)
<C-e>, vi-like operation
<RET>, vi-like operation
<LFD>, vi-like operation
<DOWN>, vi-like operation
Scroll forward by one line. With a numeric argument, scroll forward +that many lines. + +
<C-p> (up-line, vi-like operation)
<UP>, vi-like operation
<y>, vi-like operation
<k>, vi-like operation
<C-k>, vi-like operation
<C-y>, vi-like operation
Scroll backward one line. With a numeric argument, scroll backward that +many lines. + +
<d> (scroll-half-screen-down, vi-like operation)
<C-d>, vi-like operation
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 d and u +commands. + +
<u> (scroll-half-screen-up, vi-like operation)
<C-u>, vi-like operation
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 u and d +commands. +
+ +

The scroll-forward and scroll-backward 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 scroll-behavior. See scroll-behavior, for more information. + +

The scroll-forward-page-only and scroll-backward-page-only +commands never scroll beyond the current node. + +

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

If your keyboard lacks the <DEL> key, look for a key called +<BS>, or BackSpace, sometimes designated with an arrow which +points to the left, which should perform the same function. + +

+
<C-l> (redraw-display)
Redraw the display from scratch, or shift the line containing the cursor +to a specified location. With no numeric argument, C-l clears +the screen, and then redraws its entire contents. Given a numeric +argument of n, the line containing the cursor is shifted so that +it is on the nth line of the window. + +
C-x <w> (toggle-wrap)
Toggles the state of line wrapping in the current window. Normally, +lines which are longer than the screen width wrap, i.e., they are +continued on the next line. Lines which wrap have a \ 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 C-x w. When a line which needs more +space than one screen width to display is displayed, a $ 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 +$ character near its left edge. +
+ +
+


+Next: , +Previous: Scrolling Commands, +Up: Top +
+
+ +

5 Selecting a Node

+ +

+This section details the numerous Info commands which select a new node +to view in the current window. + +

The most basic node commands are n, p, u, and +l. Note that the commands to select nodes are mapped differently +when --vi-keys is in effect; these keybindings are designated +below as “vi-like operation”. + +

When you are viewing a node, the top line of the node contains some Info +pointers 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: + +

+
<n> (next-node)
C-<NEXT> (on DOS/Windows only)
C-x <n>, vi-like operation
Select the `Next' node. + +

The <NEXT> key is known as the <PgDn> key on some +keyboards. + +

<p> (prev-node)
C-<PREVIOUS> (on DOS/Windows only)
Select the `Prev' node. + +

The <PREVIOUS> key is known as the <PgUp> key on some +keyboards. + +

<u> (up-node)
C-<UP> (an arrow key on DOS/Windows only)
C-x <u>, vi-like operation
Select the `Up' node. +
+ +

You can easily select a node that you have already viewed in this window +by using the l 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. + +

Each node where you press l 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. + +

+
<l> (history-node)
<C-<CENTER>> (on DOS/Windows only)
<'>, vi-like operation
Pop the most recently selected node in this window from the node +history. +
+ +

Two additional commands make it easy to select the most commonly +selected nodes; they are t and d. + +

+
<t> (top-node)
<M-t>, vi-like operation
Select the node Top in the current Info file. + +
<d> (dir-node)
<M-d>, vi-like operation
Select the directory node (i.e., the node (dir)). +
+ +

Here are some other commands which immediately result in the selection +of a different node in the current window: + +

+
<<> (first-node)
<g>, vi-like operation
Selects the first node which appears in this file. This node is most +often Top, but it does not have to be. With a numeric argument +N, select the Nth node (the first node is node 1). An +argument of zero is the same as the argument of 1. + +
<>> (last-node)
<G>, vi-like operation
Select the last node which appears in this file. With a numeric argument +N, select the Nth node (the first node is node 1). An +argument of zero is the same as no argument, i.e., it selects the last +node. + +
<]> (global-next-node)
Move forward or down through node structure. If the node that you are +currently viewing has a Next pointer, that node is selected. +Otherwise, if this node has a menu, the first menu item is selected. If +there is no Next and no menu, the same process is tried with the +Up node of this node. + +
<[> (global-prev-node)
Move backward or up through node structure. If the node that you are +currently viewing has a Prev pointer, that node is selected. +Otherwise, if the node has an Up pointer, that node is selected, +and if it has a menu, the last item in the menu is selected. +
+ +

You can get the same behavior as global-next-node and +global-prev-node while simply scrolling through the file with +<SPC> and <DEL>; See scroll-behavior, for +more information. + +

+ +
<g> (goto-node)
C-x <g>, vi-like operation
Read the name of a node and select it. While reading the node name, +completion (see completion) 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, + +
          g(emacs)Buffers
+     
+

finds the node Buffers in the Info file emacs. + +

+

<O> (goto-invocation
<I>
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 +--show-options command-line option (see –show-options), but +it also allows to specify the program name; this is important for those +manuals which describe several programs. + +

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 +I. For example, if you are reading the Emacs manual and want to +see the command-line options of the makeinfo program, type g +(texinfo) <RET> and then I makeinfo <RET>. If you don't +know what Info file documents the command, or if invoking I +doesn't display the right node, go to the (dir) node (using the +d command) and invoke I from there. + +

<G> (menu-sequence)
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 (dir) (if the (dir) node cannot be found, Info +uses Top). 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 +(dir) node. This has the same effect as if you typed the menu +item sequence on Info's command line, see Info command-line arguments processing. For example, + +
           G Texinfo,Overview,Reporting Bugs <RET>
+     
+

displays the node Reporting Bugs 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.) + +

If any of the menu items you type are not found, Info stops at the last +entry it did find and reports an error. + +

C-x <k> (kill-node)
Kill a node. The node name is prompted for in the echo area, with a +default of the current node. Killing 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. + +
C-x C-f (view-file)
Read the name of a file and selects the entire file. The command +
          C-x C-f filename
+     
+

is equivalent to typing +

          g(filename)*
+     
+
C-x C-b (list-visited-nodes)
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. + +
C-x <b> (select-visited-node)
Select a node which has been previously visited in a visible window. +This is similar to C-x C-b followed by m, but no window is +created. +
+ +
+


+Next: , +Previous: Node Commands, +Up: Top +
+
+ +

6 Searching an Info File

+ +

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

+
<s> (search)
</>
Read a string in the echo area and search for it. If the string +includes upper-case characters, the Info file is searched +case-sensitively; otherwise Info ignores the letter case. With a +numeric argument of N, search for Nth occurrence of the +string. Negative arguments search backwards. + +
<?> (search-backward, vi-like operation)
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 N, search for Nth +occurrence of the string. Negative arguments search forward. + +
<S> (search-case-sensitively
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 N, search for Nth occurrence of the string. Negative +arguments search backwards. + +
C-x <n> (search-next)
<n>, vi-like operation
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 N, search for Nth next occurrence. + +
C-x <N> (search-previous)
<N>, vi-like operation
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 N, search for Nth previous occurrence. + +
<C-s> (isearch-forward)
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. + +
<C-r> (isearch-backward)
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. + +
<i> (index-search)
Look up a string in the indices for this Info file, and select a node +to which the found index entry points. + +
<,> (next-index-match)
Move to the node containing the next matching index item from the last +i command. + +
M-x index-apropos
Grovel the indices of all the known Info files on your system for a +string, and build a menu of the possible matches. +
+ +

The most basic searching command is s or / +(search). The s 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 s commands show you the default search +string within [ and ]; pressing <RET> instead of +typing a new string will use the default search string. Under +--vi-keys (see –vi-keys), using the n or N +commands is a faster way of searching for the same string. + +

Incremental searching 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. + +

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 +S command (search-case-sensitively). The n and +N commands operate case-sensitively if the last search command +was S. + +

The most efficient means of finding something quickly in a manual is +the i command (index-search). 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 , +(next-index-match) to find more matches. A good Info manual +has all of its important concepts indexed, so the i command +lets you use a manual as a reference. + +

If you don't know what manual documents something, try the M-x +index-apropos 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 +–apropos. + +

+


+Next: , +Previous: Searching Commands, +Up: Top +
+
+ +

7 Selecting Cross References

+ +

We have already discussed the Next, Prev, and Up +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 +cross references, or xrefs for short. + +

+ +
+


+Next: , +Up: Xref Commands +
+
+ +

7.1 Parts of an Xref

+ +

Cross references have two major parts: the first part is called the +label; it is the name that you can use to refer to the cross +reference, and the second is the target; it is the full name of +the node that the cross reference points to. + +

The target is separated from the label by a colon :; 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. + +

     * Foo Label: Foo Target.        More information about Foo.
+
+

Note the . which ends the name of the target. The . is +not part of the target; it serves only to let Info know where the target +name ends. + +

A shorthand way of specifying references allows two adjacent colons to +stand for a target name which is the same as the label name: + +

     * Foo Commands::                Commands pertaining to Foo.
+
+

In the above example, the name of the target is the same as the name of +the label, in this case Foo Commands. + +

You will normally see two types of cross reference while viewing nodes: +menu references, and note references. Menu references +appear within a node's menu; they begin with a * 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. + +

Note references appear within the body of the node text; they begin with +*Note, and continue with a label and a target. + +

Like Next, Prev, and Up 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 Writing an Xref (the Texinfo Manual), for more information on creating your own texinfo cross +references. + +

+


+Previous: Parts of an Xref, +Up: Xref Commands +
+
+ +

7.2 Selecting Xrefs

+ +

The following table lists the Info commands which operate on menu items. + +

+
<1> (menu-digit)
<2> ... <9>
<M-1>, vi-like operation
<M-2> ... <M-9>, vi-like operation
Within an Info window, pressing a single digit, (such as 1), +selects that menu item, and places its node in the current window. +For convenience, there is one exception; pressing 0 selects the +last item in the node's menu. When --vi-keys is in +effect, digits set the numeric argument, so these commands are remapped +to their M- varieties. For example, to select the last menu +item, press <M-0>. + +
<0> (last-menu-item)
<M-0>, vi-like operation
Select the last item in the current node's menu. + +
<m> (menu-item)
Reads the name of a menu item in the echo area and selects its node. +Completion is available while reading the menu label. See completion. + +
M-x find-menu
Move the cursor to the start of this node's menu. +
+ +

This table lists the Info commands which operate on cross references. + +

+
<f> (xref-item)
<r>
<M-f>, vi-like operation
C-x <r>, vi-like operation
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 completion. +
+ +

Finally, the next few commands operate on menu or note references alike: + +

+
<TAB> (move-to-next-xref)
Move the cursor to the start of the next nearest menu item or note +reference in this node. You can then use <RET> +(select-reference-this-line) to select the menu or note reference. + +
<M-TAB> (move-to-prev-xref)
<Shift-<TAB>> (on DOS/Windows only)
Move the cursor the start of the nearest previous menu item or note +reference in this node. + +

On DOS/Windows only, the Shift-<TAB> key is an alias for +M-<TAB>. This key is sometimes called BackTab. + +

<RET> (select-reference-this-line)
<M-g>, vi-like operation
Select the menu item or note reference appearing on this line. +
+ +
+


+Next: , +Previous: Xref Commands, +Up: Top +
+
+ +

8 Manipulating Multiple Windows

+ +

+A window 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 +mode line, which briefly describes the node being viewed. + +

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 active 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. + +

+ +
+


+Next: , +Up: Window Commands +
+
+ +

8.1 The Mode Line

+ +

A mode line 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. + +

Here is a sample mode line for a window containing an uncompressed file +named dir, showing the node Top. + +

     -----Info: (dir)Top, 40 lines --Top-------------------------------------
+                 ^^   ^   ^^^        ^^
+               (file)Node #lines    where
+
+

When a node comes from a file which is compressed on disk, this is +indicated in the mode line with two small z'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: + +

     --zz-Info: (emacs)Top, 291 lines --Top-- Subfile: emacs-1.Z-------------
+
+

Truncation of long lines (as opposed to wrapping them to the next +display line, see toggle-wrap) is indicated by a +$ at the left edge of the mode line: + +

     --$--Info: (texinfo)Top, 480 lines --Top-- Subfile: texinfo-1-----------
+
+

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 +(*). 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: + +

     -----Info: *Completions*, 7 lines --All---------------------------------
+
+
+


+Next: , +Previous: The Mode Line, +Up: Window Commands +
+
+ +

8.2 Window Commands

+ +

It can be convenient to view more than one node at a time. To allow +this, Info can display more than one window. Each window has its +own mode line (see The Mode Line) and history of nodes viewed in that +window (see history-node). + +

+
C-x <o> (next-window)
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, C-x o 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, C-x o moves over +that many windows. A negative argument causes C-x o to select +the previous window on the screen. + +
M-x prev-window
Select the previous window on the screen. This is identical to +C-x o with a negative argument. + +
C-x <2> (split-window)
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 automatic-tiling +can cause all of the windows on the screen to be resized for you +automatically, please see automatic-tiling for more +information. + +
C-x <0> (delete-window)
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. + +
C-x <1> (keep-one-window)
Delete all of the windows excepting the current one. + +
ESC <C-v> (scroll-other-window)
Scroll the other window, in the same fashion that C-v might +scroll the current window. Given a negative argument, scroll the +"other" window backward. + +
C-x <^> (grow-window)
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. + +
C-x <t> (tile-windows)
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 automatic-tiling can cause +tile-windows to be called when a window is created or deleted. +See automatic-tiling. +
+ +
+


+Previous: Basic Windows, +Up: Window Commands +
+
+ +

8.3 The Echo Area

+ +

+The echo area 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: + +

+
<C-f> (echo-area-forward)
<RIGHT> (an arrow key)
<M-h>, vi-like operation
Move forward a character. + +
<C-b> (echo-area-backward)
<LEFT> (an arrow key)
<M-l>, vi-like operation
Move backward a character. + +
<C-a> (echo-area-beg-of-line)
<M-0>, vi-like operation
Move to the start of the input line. + +
<C-e> (echo-area-end-of-line)
<M-$>, vi-like operation
Move to the end of the input line. + +
<M-f> (echo-area-forward-word)
<C-<RIGHT>> (DOS/Windows only)
<M-w>, vi-like operation
Move forward a word. + +

On DOS/Windows, C-<RIGHT> moves forward by words. + +

<M-b> (echo-area-backward-word)
<C-<LEFT>> (DOS/Windows only)
Move backward a word. + +

On DOS/Windows, C-<LEFT> moves backward by words. + +

<C-d> (echo-area-delete)
<M-x>, vi-like operation
Delete the character under the cursor. + +
<DEL> (echo-area-rubout)
Delete the character behind the cursor. + +

On some keyboards, this key is designated <BS>, for +BackSpace. Those keyboards will usually bind <DEL> in the +echo area to echo-area-delete. + +

<C-g> (echo-area-abort)
<C-u>, vi-like operation
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. + +
<RET> (echo-area-newline)
Accept (or forces completion of) the current input line. + +
<C-q> (echo-area-quoted-insert)
<C-v>, vi-like operation
Insert the next character verbatim. This is how you can insert control +characters into a search string, for example, or the ? character +when Info prompts with completion. + +
printing character (echo-area-insert)
Insert the character. Characters that have their 8th bit set, and not +bound to M- commands, are also inserted verbatim; this is useful +for terminals which support Latin scripts. + +
<M-TAB> (echo-area-tab-insert)
<Shift-<TAB>> (on DOS/Windows only)
Insert a TAB character. + +

On DOS/Windows only, the Shift-<TAB> key is an alias for +M-<TAB>. This key is sometimes called BackTab. + +

<C-t> (echo-area-transpose-chars)
Transpose the characters at the cursor. +
+ +

The next group of commands deal with killing, and yanking +text6. For an in-depth discussion of killing and +yanking, see Killing and Deleting (the GNU Emacs Manual). + +

+
<M-d> (echo-area-kill-word)
<M-X>, vi-like operation
Kill the word following the cursor. + +
<M-DEL> (echo-area-backward-kill-word)
<M-<BS>>
Kill the word preceding the cursor. + +

On some keyboards, the Backspace key is used instead of +DEL, so M-<Backspace> has the same effect as +M-<DEL>. + +

<C-k> (echo-area-kill-line)
Kill the text from the cursor to the end of the line. + +
C-x <DEL> (echo-area-backward-kill-line)
Kill the text from the cursor to the beginning of the line. + +
<C-y> (echo-area-yank)
Yank back the contents of the last kill. + +
<M-y> (echo-area-yank-pop)
Yank back a previous kill, removing the last yanked text first. +
+ +

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 possible completions, 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 completion. + +

The following commands are available when completing in the echo area: + +

+
<TAB> (echo-area-complete)
<SPC>
Insert as much of a completion as is possible. + +
<?> (echo-area-possible-completions)
Display a window containing a list of the possible completions of what +you have typed so far. For example, if the available choices are: + +
          bar
+          foliate
+          food
+          forget
+     
+

and you have typed an f, followed by ?, Info will pop up a +window showing a node called *Completions* which lists the +possible completions like this: + +

          3 completions:
+          foliate         food
+          forget
+     
+

i.e., all of the choices which begin with f. Pressing <SPC> +or <TAB> would result in fo appearing in the echo area, since +all of the choices which begin with f continue with o. +Now, typing l followed by TAB results in foliate +appearing in the echo area, since that is the only choice which begins +with fol. + +

<ESC C-v> (echo-area-scroll-completions-window)
Scroll the completions window, if that is visible, or the "other" +window if not. +
+ +
+


+Next: , +Previous: Window Commands, +Up: Top +
+
+ +

9 Printing Nodes

+ +

+In general, we recommend that you use TeX to format the document and +print sections of it, by running tex 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. + +

+
M-x print-node
Pipe the contents of the current node through the command in the +environment variable INFO_PRINT_COMMAND. If the variable does not +exist, the node is simply piped to lpr (on DOS/Windows, the +default is to print the node to the local printer device, PRN). + +

The value of INFO_PRINT_COMMAND may begin with the > +character, as in >/dev/printer, 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. +

+ +
+


+Next: , +Previous: Printing Nodes, +Up: Top +
+
+ +

10 Miscellaneous Commands

+ +

GNU Info contains several commands which self-document GNU Info: + +

+
M-x describe-command
Read the name of an Info command in the echo area and then display a +brief description of what that command does. + +
M-x describe-key
Read a key sequence in the echo area, and then display the name and +documentation of the Info command that the key sequence invokes. + +
M-x describe-variable
Read the name of a variable in the echo area and then display a brief +description of what the variable affects. + +
M-x where-is
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. + +
<C-h> (get-help-window)
<?>
<F1> (on DOS/Windows only)
h, vi-like operation
Create (or Move into) the window displaying *Help*, and place +a node containing a quick reference card into it. This window displays +the most concise information about GNU Info available. + +
<h> (get-info-help-node)
<M-h>, vi-like operation
Try hard to visit the node (info)Help. The Info file +info.texi distributed with GNU Info contains this node. Of +course, the file must first be processed with makeinfo, and then +placed into the location of your Info directory. +
+ +

Here are the commands for creating a numeric argument: + +

+
<C-u> (universal-argument)
Start (or multiply by 4) the current numeric argument. C-u is +a good way to give a small numeric argument to cursor movement or +scrolling commands; C-u C-v scrolls the screen 4 lines, while +C-u C-u C-n moves the cursor down 16 lines. C-u followed +by digit keys sets the numeric argument to the number thus typed: +C-u 1 2 0 sets the argument to 120. + +
<M-1> (add-digit-to-numeric-arg)
<1>, vi-like operation
<M-2> ... <M-9>
<2> ... <9>, vi-like operation
<M-0>
<0>, vi-like operation
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 C-l a numeric argument of 32 by typing: + +
          C-u 3 2 C-l
+     
+

or + +

          M-3 2 C-l
+     
+
<M–> (add-digit-to-numeric-arg
<->
To make a negative argument, type -. Typing - alone makes a +negative argument with a value of -1. If you continue to type digit or +Meta-digit keys after -, the result is a negative number produced +by those digits. + +

- doesn't work when you type in the echo area, because you need to +be able to insert the - character itself; use M-- instead, +if you need to specify negative arguments in the echo area. +

+ +

C-g 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. + +

+
<C-g> (abort-key)
<C-u>, vi-like operation
Cancel current operation. +
+ +

The q command of Info simply quits running Info. Under +--vi-keys (see –vi-keys), you can also exit with :q +or ZZ. + +

+
<q> (quit)
C-x C-c
:q, vi-like operation
ZZ, vi-like operation
Exit GNU Info. +
+ +

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

+
M-x set-screen-height
Read a height value in the echo area and set the height of the +displayed screen to that value. +
+ +

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

Finally, Info provides a convenient way to display footnotes which might +be associated with the current node that you are viewing: + +

+
<ESC C-f> (show-footnotes)
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 +automatic-footnotes. See automatic-footnotes. +
+ +
+


+Next: , +Previous: Miscellaneous Commands, +Up: Top +
+
+ +

11 Manipulating Variables

+ +

GNU Info contains several variables 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. + +

There are two ways to set the value of a variable: interactively, using +the set-variable command described below, or in the #var +section of the .infokey file. See Custom Key Bindings. + +

+
M-x set-variable
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 completion); often, +completion is available when reading the value to give to the variable, +but that depends on the variable itself. If a variable does not +supply multiple choices to complete over, it expects a numeric value. + +
M-x describe-variable
Read the name of a variable in the echo area and then display a brief +description of what the variable affects. +
+ +

Here is a list of the variables that you can set in Info. + +

+
automatic-footnotes
When set to On, footnotes appear and disappear automatically; +else, they appear at the bottom of the node text. This variable is +Off 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 *Footnotes*. If a node is +selected which contains no footnotes, and a *Footnotes* window +is on the screen, the *Footnotes* 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. + +
automatic-tiling
When set to On, creating or deleting a window resizes other +windows. This variable is Off by default. Normally, typing +C-x 2 divides the current window into two equal parts. When +automatic-tiling is set to On, 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 *Completions* and *Footnotes* are not +resized through automatic tiling; they remain their original size. + +
errors-ring-bell
When set to On, errors cause the bell to ring. The default +setting of this variable is On. + +
gc-compressed-files
When set to On, Info garbage collects files which had to be +uncompressed. The default value of this variable is Off. +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. +gc-compressed-files tells Info it is okay to garbage collect the +text of the nodes of a file which was compressed on disk. + +
ISO-Latin
When set to On, Info accepts and displays ISO Latin characters. +By default, Info assumes an ASCII character set. ISO-Latin 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. + +
scroll-behavior
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 Continuous. There +are three possible values for this variable: + +
+
Continuous
Try to get the first item in this node's menu, or failing that, the +Next node, or failing that, the Next of the Up. +This behavior is identical to using the ] +(global-next-node) and [ (global-prev-node) +commands. + +
Next Only
Only try to get the Next node. + +
Page Only
Simply give up, changing nothing. If scroll-behavior is +Page Only, no scrolling command can change the node that is being +viewed. +
+ +
scroll-step
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 scroll-step 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. + +
show-index-match
When set to On, 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 On. +When Info displays the location where an index match was found, +(see next-index-match), the portion of the +string that you had typed is highlighted by displaying it in the inverse +case from its surrounding characters. + +
visible-bell
When set to On, GNU Info attempts to flash the screen instead of +ringing the bell. This variable is Off 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 +errors-ring-bell variable to Off. + +
+ +
+


+Next: , +Previous: Variables, +Up: Top +
+
+ +

12 Customizing Key Bindings and Variables

+ +

+For those whose editor/pager of choice is not Emacs and who are not +entirely satisfied with the –vi-keys option (see –vi-keys), GNU +Info provides a way to define different key-to-command bindings and +variable settings from the defaults described in this document. + +

On startup, GNU Info looks for a configuration file in the invoker's +HOME directory called .info7. If it is present, and +appears to contain Info configuration data, and was created with the +current version of the infokey command, then Info adopts the +key bindings and variable settings contained therein. + +

The .info 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 infokey command. + +

+ +
+


+Next: , +Up: Custom Key Bindings +
+
+ +

12.1 Invoking infokey

+ +

+infokey compiles a source file +($HOME/.infokey8 by default) containing Info customizations +into a binary format ($HOME/.info by default). GNU Info reads +the binary file at startup to override the default key bindings and +variable definitions. Synopsis: + +

     infokey [option...] [input-file]
+
+

Besides the standard --help and --version, the only +option is --output file. This tells infokey to +write the binary data to file instead of $HOME/.info. + +

+


+Previous: Invoking infokey, +Up: Custom Key Bindings +
+
+ +

12.2 infokey source format

+ +

+The format of the source file read by infokey is most easily +illustrated by example. For instance, here is a sample .infokey +source file suitable for aficionados of vi or less: + +

     #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
+
+

The source file consists of one or more sections. +Each section starts with a line that identifies the type of section. +Possible sections are: + +

+
#info
Key bindings for Info windows. +The start of this section is indicated by a line containing just +#info by itself. If this is the first section in the source +file, the #info line can be omitted. The rest of this section +consists of lines of the form: + +
          string whitespace action [ whitespace [ # comment ] ] newline
+     
+

Whitespace is any sequence of one or more spaces and/or tabs. Comment +is any sequence of any characters, excluding newline. string is +the key sequence which invokes the action. action is the name of +an Info command. The characters in string are interpreted +literally or prefixed by a caret (^) to indicate a control +character. A backslash followed by certain characters specifies input +keystrokes as follows: + +

+
\b
Backspace +
\e
Escape (ESC) +
\n
Newline +
\r
Return +
\t
Tab +
\ku
Up arrow +
\kd
Down arrow +
\kl
Left arrow +
\kr
Right arrow +
\kU
Page Up +
\kD
Page Down +
\kh
HOME +
\ke
END +
\kx
Delete (DEL) +
\mx
Meta-x where x is any character as described above. +
+ +

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

#echo-area
Key bindings for the echo area. +The start of this section is indicated by a line containing just +#echo-area by itself. The rest of this section has a syntax +identical to that for the key definitions for the Info area, described +above. + +
#var
Variable initializations. +The start of this section is indicated by a line containing just +#var by itself. Following this line is a list of variable +assignments, one per line. Each line consists of a variable name +(See Variables,) followed by = followed by a value. +There may be no white space between the variable name and the =, +and all characters following the =, including white space, +are included in the value. +
+ +

Blank lines and lines starting with # are ignored, except for +the special section header lines. + +

Key bindings defined in the .info file take precedence over GNU +Info's default key bindings, whether or not --vi-keys is used. A +default key binding may be disabled by overriding it in the .info +file with the action invalid. In addition, all default +key bindings can be disabled by adding this line anywhere in the +relevant section: + +

     #stop
+
+

This will cause GNU Info to ignore all the default key commands for that +section. + +

Beware: #stop 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 quit command, +for example, can lead to frustration. + +

The order in which key bindings are defined in the .info file is +not important, except that the command summary produced by the +get-help-window command only displays the first key that +is bound to each command. + + +

+


+Next: , +Previous: Custom Key Bindings, +Up: Top +
+
+ +

Appendix A Copying This Manual

+ + + +
+


+Up: Copying This Manual +
+
+ +

A.1 GNU Free Documentation License

+ +

Version 1.2, November 2002
+ +
     Copyright © 2000,2001,2002 Free Software Foundation, Inc.
+     59 Temple Place, Suite 330, Boston, MA  02111-1307, USA
+     
+     Everyone is permitted to copy and distribute verbatim copies
+     of this license document, but changing it is not allowed.
+
+
    +
  1. PREAMBLE + +

    The purpose of this License is to make a manual, textbook, or other +functional and useful document free in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +

    This License is a kind of “copyleft”, which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +

    We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +

  2. APPLICABILITY AND DEFINITIONS + +

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

    A “Modified Version” of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +

    A “Secondary Section” is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (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. + +

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

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

    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”. + +

    Examples of suitable formats for Transparent copies include plain +ascii without markup, Texinfo input format, LaTeX input +format, SGML or XML using a publicly available +DTD, and standard-conforming simple HTML, +PostScript or PDF designed for human modification. Examples +of transparent image formats include PNG, XCF and +JPG. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, SGML or +XML for which the DTD and/or processing tools are +not generally available, and the machine-generated HTML, +PostScript or PDF produced by some word processors for +output purposes only. + +

    The “Title Page” means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, “Title Page” means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +

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

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

  3. VERBATIM COPYING + +

    You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +

    You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +

  4. COPYING IN QUANTITY + +

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

    If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +

    If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a 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. + +

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

  5. MODIFICATIONS + +

    You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +

      +
    1. 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. + +
    2. 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. + +
    3. State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +
    4. Preserve all the copyright notices of the Document. + +
    5. Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +
    6. 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. + +
    7. Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +
    8. Include an unaltered copy of this License. + +
    9. 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. + +
    10. 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. + +
    11. 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. + +
    12. 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. + +
    13. Delete any section Entitled “Endorsements”. Such a section +may not be included in the Modified Version. + +
    14. Do not retitle any existing section to be Entitled “Endorsements” or +to conflict in title with any Invariant Section. + +
    15. Preserve any Warranty Disclaimers. +
    + +

    If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +

    You may add a section Entitled “Endorsements”, provided it contains +nothing but endorsements of your Modified Version by various +parties—for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +

    You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +

    The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +

  6. COMBINING DOCUMENTS + +

    You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +

    The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +

    In the combination, you must combine any sections Entitled “History” +in the various original documents, forming one section Entitled +“History”; likewise combine any sections Entitled “Acknowledgements”, +and any sections Entitled “Dedications”. You must delete all +sections Entitled “Endorsements.” + +

  7. COLLECTIONS OF DOCUMENTS + +

    You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +

    You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +

  8. AGGREGATION WITH INDEPENDENT WORKS + +

    A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, 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. + +

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

  9. TRANSLATION + +

    Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, 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. + +

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

  10. TERMINATION + +

    You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + +

  11. FUTURE REVISIONS OF THIS LICENSE + +

    The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. + +

    Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License “or any later version” applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. +

+ +

A.1.1 ADDENDUM: How to use this License for your documents

+ +

To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +

       Copyright (C)  year  your name.
+       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''.
+
+

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the “with...Texts.” line with this: + +

         with the Invariant Sections being list their titles, with
+         the Front-Cover Texts being list, and with the Back-Cover Texts
+         being list.
+
+

If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +

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

+


+Previous: Copying This Manual, +Up: Top +
+
+ +

Appendix B Index

+ +
+
+

Footnotes

[1] +.info, -info, /index, and .inf.

+ +

[2] The MS-DOS version allows for the Info +extension, such as .inf, and the short compressed file +extensions, such as .z and .gz, 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 bison, +file names like bison.igz and bison.inz will be found and +decompressed by gunzip.

+ +

[3] Of course, you can specify both the file and node +in a --node command; but don't forget to escape the open and +close parentheses and whitespace from the shell as in: info --node +"(emacs)Buffers".

+ +

[4] Here's a short summary. C-x means +press the CTRL key and the key x. M-x means +press the META key and the key x. On many terminals th +META key is known as the ALT key. SPC is the space +bar. The other keys are usually called by the names imprinted on +them.

+ +

[5] M-x is also a command; it +invokes execute-extended-command. See Executing an extended command (the GNU Emacs Manual), for more detailed +information.

+ +

[6] +Some people are used to calling these operations cut and +paste, respectively.

+ +

[7] Due to the limitations of +DOS filesystems, the MS-DOS version of Info looks for a file +_info instead. If the HOME variable is not defined, Info +additionally looks in the current directory.

+ +

[8] This file is named _infokey in +the MS-DOS version, and is looked for in the current directory if +HOME is undefined.

+ +


+ + + diff --git a/Master/texmf/doc/texinfo/info-stnd.pdf b/Master/texmf/doc/texinfo/info-stnd.pdf new file mode 100644 index 00000000000..b12ac9057e7 Binary files /dev/null and b/Master/texmf/doc/texinfo/info-stnd.pdf differ diff --git a/Master/texmf/doc/texinfo/info.html b/Master/texmf/doc/texinfo/info.html new file mode 100644 index 00000000000..c9c89eb97d9 --- /dev/null +++ b/Master/texmf/doc/texinfo/info.html @@ -0,0 +1,1534 @@ + + +Info + + + + + + + + + + +

Info

+
+

Table of Contents

+ +
+ + + +
+


+Next: , +Up: (dir) +
+
+ +

Info: An Introduction

+ +

The GNU Project distributes most of its on-line manuals in the +Info format, which you read using an Info reader. You are +probably using an Info reader to read this now. + +

+ +
+


+Next: , +Previous: Top, +Up: Top +
+
+ + +

1 Getting Started

+ +

This first part of the Info manual describes how to get around inside +of Info. The second part of the manual describes various advanced +Info commands, and how to write an Info as distinct from a Texinfo +file. The third part briefly explains how to generate Info files from +Texinfo files. + +

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

There are two ways of looking at the online version of this manual: + +

    +
  1. Type info at your shell's command line. This approach uses a +stand-alone program designed just to read Info files. + +
  2. Type emacs at the command line; then type C-h i +(Control-h, followed by i). This approach uses the Info +mode of the Emacs program, an editor with many other capabilities. +
+ +

In either case, then type mInfo (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. + + + + + +

+ +
+


+Next: , +Up: Getting Started +
+
+ +

1.1 Starting Info on a Small Screen

+ +

(In Info, you only see this section if your terminal has a small +number of lines; most readers pass by it without seeing it.) + +

Since your terminal has a relatively small number of lines on its +screen, it is necessary to give you special advice at the beginning. + +

If you see the text --All---- near the bottom right corner +of the screen, it means the entire text you are looking at fits on the +screen. If you see --Top---- 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 Backspace or DEL (on some +keyboards, this key might be labeled Delete). + +

+


+Next: , +Previous: Help-Small-Screen, +Up: Getting Started +
+
+ + +

1.2 How to use Info

+ +

You are talking to the program Info, for reading documentation. + +

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 +info. + +

Right now you are looking at one Node 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 Help in the file info. + +

The top line of a node is its header. This node's header +(look at it now) says that the Next node after this one is the +node called Help-P. An advanced Info command lets you go to +any node whose name you know. In the stand-alone Info reader program, +the header line shows the names of this node and the info file as +well. In Emacs, the header line is duplicated in a special typeface, +and the duplicate remains at the top of the window all the time even +if you scroll through the node. + +

Besides a Next, a node can have a Previous or an +Up links, or both. As you can see, this node has all of these +links. + +

Now it is time to move on to the Next node, named Help-P. + +

>> Type n to move there.  Type just one character;
+   do not type the quotes and do not type a <RET> afterward.
+
+

>> in the margin means it is really time to try a command. + +

>> If you are in Emacs and have a mouse, and if you already practiced
+   typing n to get to the next node, click now with the middle
+   mouse button on the Next link to do the same “the mouse way”.
+
+
+


+Next: , +Previous: Help, +Up: Getting Started +
+
+ + +

1.3 Returning to the Previous node

+ +

This node is called Help-P. The Previous node, as you see, +is Help, which is the one you just came from using the n +command. Another n command now would take you to the next +node, Help-^L. + +

>> But do not type n yet.  First, try the p command,
+   or click the middle mouse button on the Prev link.  That
+   takes you to the Previous node.  Then use n to return here.
+
+

If you read this in Emacs, you will see an Info item in the +menu bar, close to its right edge. Clicking the mouse on the +Info menu-bar item opens a menu of commands which include +Next and Prev (and also some others which you didn't yet +learn about). + +

This all probably seems insultingly simple so far, but please +don't 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. + +

>> Now do an n, or click the middle mouse button on the Next
+   link, to get to the node Help-^L and learn more.
+
+
+


+Next: , +Previous: Help-P, +Up: Getting Started +
+
+ + +

1.4 The Space, DEL, B and ^L commands

+ +

This node's mode line tells you that you are now at node +Help-^L, and the header line tells you that p would get +you back to Help-P. The node's title is highlighted and may be +underlined as well; it says what the node is about. + +

This is a big node and it does not all fit on your display screen. +You can tell that there is more that is not visible because you +can see the string --Top----- rather than --All---- near +the bottom right corner of the screen. + +

The <SPC>, <BACKSPACE> (or <DEL>)1 and b 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). + +

>> Now try typing a <SPC> (afterward, type a <BACKSPACE> to
+   return here).
+
+

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, usually, 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. + +

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 Next, Prev, and Up links, and you +can conveniently go to one of these links at any time by +clicking the middle mouse button on the link. + +

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

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

Many keyboards nowadays have two scroll keys labeled PageUp +and PageDown (or maybe Prior and Next). 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. + +

If your screen is ever garbaged, you can tell Info to display it +again by typing C-l (Control-L, that is—hold down +<CTRL> and type L or l). + +

>> Type C-l now.
+
+

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 +b just once. b stands for “beginning.” + +

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

If your screen is very tall, all of this node might fit at once. In +that case, b won't do anything. But you could observe the +effect of the b key if you use a smaller window. + +

You have just learned a considerable number of commands. If you +want to use one but have trouble remembering which, you should type +a ? (in Emacs it runs the Info-summary command) which +displays a brief list of commands. When you are finished looking at +the list, make it go away by typing a <SPC> repeatedly. + +

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

(If you are using the stand-alone Info reader, type C-x 0 to +return here, that is—press and hold <CTRL>, type an x, +then release <CTRL> and x, and press 0—a zero, not +the letter “o”.) + +

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

>> Now type n, or click the middle mouse button on the Next link,
+   to visit the next node.
+
+
+


+Next: , +Previous: Help-^L, +Up: Getting Started +
+
+ + +

1.5 Invisible text in Emacs Info

+ +

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 ] now. + +

In Emacs, certain text that appears in the stand-alone version is +normally hidden, technically because it has the invisibility +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. + +

You can make invisible text visible by using the command M-x +visible-mode. 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. + +

If you prefer to always see the invisible text, you can set +Info-hide-note-references to nil. 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 display property. Only the +invisibility property is affected by Visible mode. When, in this +tutorial, we refer to the Emacs behavior, we mean the +default Emacs behavior. + +

Now type ], to learn about the ] and [ commands. + +

+ +
+


+Up: Help-Inv +
+
+ +

1.5.1 The ] and [ commands

+ +

If you type n now, you get an error message saying that this +node has no next node. Similarly, if you type p, the error +message tells you that there is no previous node. (The exact message +depends on the Info reader you use.) This is because n and +p carry you to the next and previous node at the same +level. 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 +n or p could move to. + +

If you systematically move through a manual by typing n, you run +the risk of skipping many nodes. You do not run this risk if you +systematically use <SPC>, because, when you scroll to the +bottom of a node and type another <SPC>, then this carries +you to the following node in the manual regardless of level. +If you immediately want to go to that node, without having to scroll +to the bottom of the screen first, you can type ]. + +

Similarly, <BACKSPACE> 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 [. + +

For instance, typing this sequence will come back here in three steps: +[ n [. To do the same backward, type ] p ]. + +

Now type ] to go to the next node and learn about menus. + +

+


+Next: , +Previous: Help-Inv, +Up: Getting Started +
+
+ + +

1.6 Menus and the m command

+ +

With only the n (next), p (previous), <SPC>, +<BACKSPACE>, ] and [ 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 * Menu:. 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. + +

After the start of the menu, each line that starts with a * +identifies one subtopic. The line usually contains a brief name for +the subtopic (followed by a :, 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 * have no +special meaning—they are only for the human reader's benefit and do +not define additional subtopics. Here is an example: + +

     * Foo:  Node about FOO.      This tells about FOO.
+
+

The subtopic name is Foo, and the node describing it is Node +about FOO. 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 * Menu:. Also, +in a real menu item, the * would appear at the very start of +the line. This is why the “normally hidden” text in Emacs, namely +: Node about FOO., is actually visible in this example, even +when Visible mode is off.]] + +

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: + +

     * Foo::   This tells about FOO.
+
+

This means that the subtopic name and node name are the same; they are +both Foo. (The :: is normally hidden in Emacs.) + +

>> Now use <SPC> to find the menu in this node, then come back to
+   the front with a b 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
+   m command is not available.
+
+

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

The command to go to one of the subnodes is m. This is very +different from the commands you have used: it is a command that +prompts you for more input. + +

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 m command is different: it needs to know +the name of the subtopic. Once you have typed m, Info +tries to read the subtopic name. + +

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 +n or b or <SPC> or m. 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 Control-g 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. + +

The command to go to a subnode via a menu is m. After you type +the m, the line at the bottom of the screen says Menu item: . +You must then type the name of the subtopic you want, and end it with +a <RET>. In Emacs, m runs the command Info-menu. + +

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

You can also use the completion 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. + +

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

Here is a menu to give you a chance to practice. This menu gives you +three ways of going to one place, Help-FOO: + +

+ +

(Turn Visible mode on if you are using Emacs.) + +

>>  Now type just an m and see what happens:
+
+

Now you are “inside” an m command. Commands cannot be used +now; the next thing you will type must be the name of a subtopic. + +

You can change your mind about doing the m by typing +Control-g. + +

>> Try that now;  notice the bottom line clear.
+
+
>> Then type another m.
+
+
>> Now type BAR, the item name.  Do not type <RET> yet.
+
+

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

>> Press <DEL> to cancel the R.  You could type another R
+   to replace it.  But you do not have to, since BA is a valid
+   abbreviation.
+
+
>> Now you are ready to go.  Type a <RET>.
+
+

After visiting Help-FOO, you should return here. + +

Another way to move to the menu subtopic lines and between them is +to type <TAB>. Each time you type a <TAB>, you move to the +next subtopic line. To move to a previous subtopic line, type +M-<TAB>—that is, press and hold the <META> key and then +press <TAB>. (On some keyboards, the <META> key might be labeled +Alt.) + +

Once you move cursor to a subtopic line, press <RET> to go to +that subtopic's node. + +

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 * and the colon : 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. + +

Mouse-2 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 Mouse-2 with the +current position of the mouse pointer (on subtopic in the menu) will +go to that subtopic. + +

More generally, Mouse-2 in an Info buffer finds the nearest +link to another node and goes there. For example, near a cross +reference it acts like f, in a menu it acts like m, on the +node's header line it acts like n, p, or u, etc. At +end of the node's text Mouse-2 moves to the next node, or up if +there's no next node. + +

>> Type n to see more commands.
+
+
+


+Up: Help-M +
+
+ +

1.6.1 The u command

+ +

Congratulations! This is the node Help-FOO. It has an Up +pointer Help-M, the node you just came from via the m +command. This is the usual convention—the nodes you reach from a menu +have Up nodes that lead back to the menu. Menus move Down in the +tree, and Up moves Up. Previous, on the other hand, is +usually used to “stay on the same level but go backwards”. + +

You can go back to the node Help-M by typing the command +u for “Up” (the Emacs command run by u is +Info-up). That puts you at the front of the node—to +get back to where you were reading you have to type some <SPC>s. +(Some Info readers, such as the one built into Emacs, put you at the +same place where you were reading in Help-M.) + +

Another way to go Up is to click Mouse-2 on the Up +pointer shown in the header line (provided that you have a mouse). + +

>> Now type u to move back up to Help-M.
+
+
+


+Next: , +Previous: Help-M, +Up: Getting Started +
+
+ + +

1.7 Following Cross-References

+ +

In Info documentation, you will see many cross references. +Cross references look like this: See Cross. That text +is a real, live cross reference, whose name is Cross and which +points to the node named Help-Cross. (The node name is hidden +in Emacs. Do M-x visible-mode to show or hide it.) + +

There are two ways to follow a cross reference. You can move the +cursor to it and press <RET>, just as in a menu. <RET> +follows the cross reference that the cursor is on. Or you can type +f and then specify the name of the cross reference (in this +case, Cross) as an argument. In Emacs Info, f runs +Info-follow-reference, + +

In the f command, you select the cross reference with its +name, so it does not matter where the cursor was. If the cursor is on +or near a cross reference, f suggests that reference name in +parentheses as the default; typing <RET> will follow that +reference. However, if you type a different reference name, f +will follow the other reference which has that name. + +

>> Type f, followed by Cross, and then <RET>.
+
+

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 Control-g to cancel +the command. Completion is available in the f command; you can +complete among all the cross reference names in the current node by +typing a <TAB>. + +

To get a list of all the cross references in the current node, you +can type ? after an f. The f 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 Control-g +to cancel the f. + +

>> Type f? to get a list of the cross references in this node.  Then
+   type a Control-g and see how the f gives up.
+
+

The <TAB> and M-<TAB> key, which move between menu +items in a menu, also move between cross references outside of menus. + +

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 Overview of Texinfo (Texinfo: The GNU Documentation Format). (After following this link, type +l to get back to this node.) Here the name texinfo +between parentheses (shown in the stand-alone version) refers to the +file name. This file name appears in cross references and node names +if it differs from the current file. In Emacs, the file name is +hidden (along with other text). (Use M-x visible-mode to show +or hide it.) + +

The remainder of this node applies only to the Emacs version. If +you use the stand-alone version, you can type n immediately. + +

To some users, switching manuals is a much bigger switch than +switching sections. These users like to know that they are going to +be switching to another manual (and which one) before actually doing +so, especially given that, if one does not notice, Info commands like +t (see the next node) can have confusing results. + +

If you put your mouse over the cross reference and if the cross +reference leads to a different manual, then the information appearing +in a separate box (tool tip) or in the echo area, will mention the +file the cross reference will carry you to (between parentheses). +This is also true for menu subtopic names. If you have a mouse, just +leave it over the Overview cross reference above and watch what +happens. + +

If you always like to have that information available without having +to move your mouse over the cross reference, set +Info-hide-note-references to a value other than t (see Emacs Info Variables). You might also want to do that if you have a lot of +cross references to files on remote machines and have non-permanent or +slow access, since otherwise you might not be able to distinguish +between local and remote links. + +

>> Now type n to learn more commands.
+
+
+


+Next: , +Previous: Help-Xref, +Up: Getting Started +
+
+ + +

1.8 Some intermediate Info commands

+ +

The introductory course is almost over; please continue +a little longer to learn some intermediate-level commands. + +

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

You can get to the index from the main menu of the file with the +m command; then you can use the m command again in the +index node to go to the node that describes the topic you want. + +

There is also a short-cut Info command, i, 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 Info Search, for a full explanation. + +

If you have been moving around to different nodes and wish to +retrace your steps, the l command (l for last) 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 +l command revisits nodes in the history list; each successive +l command moves one step back through the history. + +

In Emacs, l runs the command Info-last. + +

>> Try typing p p n and then three l's, pausing in between
+to see what each l does.  You should wind up right back here.
+
+

Note the difference between l and p: l moves to +where you last were, whereas p always moves to the node +which the header says is the Previous node (from this node, the +Prev link leads to Help-Xref). + +

The d command (Info-directory 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. + +

>> Try doing a d, then do an l to return here (yes,
+   do return).
+
+

The t command moves to the Top 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 t +is Info-top-node. + +

Clicking Mouse-2 on or near a cross reference also follows the +reference. You can see that the cross reference is mouse-sensitive by +moving the mouse pointer to the reference and watching how the +underlying text and the mouse pointer change in response. + +

>> Now type n to see the last node of the course.
+
+

See Expert Info, for more advanced Info features. + + + +

+


+Next: , +Previous: Getting Started, +Up: Top +
+
+ +

2 Info for Experts

+ +

This chapter describes various Info commands for experts. (If you +are using a stand-alone Info reader, there are additional commands +specific to it, which are documented in several chapters of GNU Info (GNU Info).) + +

This chapter also explains how to write an Info as distinct from a +Texinfo file. (However, in most cases, writing a Texinfo file is +better, since you can use it to make a printed manual or produce other +formats, such as HTML and DocBook, as well as for generating Info +files.) See Overview of Texinfo (Texinfo: The GNU Documentation Format). + +

+ +
+


+Next: , +Up: Expert Info +
+
+ + +

2.1 Advanced Info Commands

+ +

Here are some more Info commands that make it easier to move around. + +

g goes to a node by name

+ +

If you know a node's name, you can go there by typing g, the +name, and <RET>. Thus, gTop<RET> would go to the node +called Top in this file. (This is equivalent to t, see +Help-Int.) gAdvanced<RET> would come back here. +g in Emacs runs the command Info-goto-node. + +

Unlike m, g does not allow the use of abbreviations. +But it does allow completion, so you can type <TAB> to complete a +partial node name. + +

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, +g(dir)Top<RET> would go to the Info Directory node, which is +the node Top in the Info file dir. Likewise, +g(emacs)Top<RET> goes to the top node of the Emacs manual. + +

The node name * specifies the whole file. So you can look at +all of the current file by typing g*<RET> or all of any +other file with g(filename)<RET>. + +

19 choose a menu subtopic by its number

+ +

If you begrudge each character of type-in which your system requires, +you might like to use the commands 1, 2, 3, 4, +..., 9. They are short for the m command together +with a name of a menu subtopic. 1 goes through the first item +in the current node's menu; 2 goes through the second item, etc. +In the stand-alone reader, 0 goes through the last menu item; +this is so you need not count how many entries are there. In Emacs, +the digit keys run the command Info-nth-menu-item. + +

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 * 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. + +

Some terminals don't support either multiple fonts, colors or +underlining. If you need to actually count items, it is better to use +m instead, and specify the name, or use <TAB> to quickly +move between menu items. + +

e makes Info document editable

+ +

The Info command e changes from Info mode to an ordinary +Emacs editing mode, so that you can edit the text of the current node. +Type C-c C-c to switch back to Info. The e command is allowed +only if the variable Info-enable-edit is non-nil. + +

The e command only works in Emacs, where it runs the command +Info-edit. The stand-alone Info reader doesn't allow you to +edit the Info file, so typing e there goes to the end of the +current node. + +

M-n creates a new independent Info buffer in Emacs

+ +

If you are reading Info in Emacs, you can select a new independent +Info buffer in another window by typing M-n. 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, +M-n runs the Emacs command clone-buffer.) + +

In Emacs Info, you can also produce new Info buffers by giving a +numeric prefix argument to the m and g commands. C-u +m and C-u g go to a new node in exactly the same way that +m and g do, but they do so in a new Info buffer which they +select in another window. + +

+


+Next: , +Previous: Advanced, +Up: Expert Info +
+
+ + +

2.2 How to search Info documents for specific subjects

+ +

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 reference, or when it is impractical to +read the entire manual before you start using the programs it +describes. + +

Info has powerful searching facilities that let you find things +quickly. You can search either the manual indices or its text. + +

Since most subjects related to what the manual describes should be +indexed, you should try the index search first. The i 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 , one or more times to go +through additional index entries which match your subject. + +

The i command finds all index entries which include the string +you typed as a substring. For each match, Info shows in the +echo area the full index entry it found. Often, the text of the full +index entry already gives you enough information to decide whether it +is relevant to what you are looking for, so we recommend that you read +what Emacs shows in the echo area before looking at the node it +displays. + +

Since i 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 icomplet<RET>. + +

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 i prompts you for a topic. For example, if you +want to read the description of what the C-f key does, type +i C - f <RET>. Here C-f are 3 literal characters +C, -, and f, not the “Control-f” command key +you type inside Emacs to run the command bound to C-f. + +

In Emacs, i runs the command Info-index. + +

If you don't know what manual documents something, try the M-x +info-apropos 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. + +

The s command allows you to search a whole file for a string. +It switches to the next node if and when that is necessary. You +type s followed by the string to search for, terminated by +<RET>. To search for the same string again, just s followed +by <RET> will do. The file's nodes are scanned in the order +they are in in the file, which has no necessary relationship to the +order that they may be in the tree structure of menus and next +pointers. But normally the two orders are not very different. In any +case, you can always do a b to find out what node you have +reached, if the header is not visible (this can happen, because s +puts your cursor at the occurrence of the string, not at the beginning +of the node). + +

In Emacs, Meta-s is equivalent to s. That is for +compatibility with other GNU packages that use M-s for a similar +kind of search command. Both s and M-s run in Emacs the +command Info-search. + +

+


+Next: , +Previous: Info Search, +Up: Expert Info +
+
+ + +

2.3 Adding a new node to Info

+ +

To add a new topic to the list in the Info directory, you must: + +

    +
  1. Create some nodes, in some file, to document that topic. +
  2. Put that topic in the menu in the directory. See Menu. +
+ +

Usually, the way to create the nodes is with Texinfo (see Overview of Texinfo (Texinfo: The GNU Documentation Format)); +this has the advantage that you can also make a printed manual or HTML +from them. You would use the @dircategory and +@direntry commands to put the manual into the Info directory. +However, if you want to edit an Info file manually and install it +manually, here is how. + +

The new node can live in an existing documentation file, or in a new +one. It must have a ^_ character before it (invisible to the +user; this node has one but you cannot see it), and it ends with either +a ^_, a ^L (“formfeed”), or the end of file.2 + +

The ^_ starting a node must be followed by a newline or a +^L 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 Next, Previous, and Up +nodes (if there are any). As you can see, this node's Up node +is the node Expert Info. The Next node is Menus. + +

The keywords Node, Next, Previous, and Up +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. + +

A node name has two forms. A node in the current file is named by +what appears after the Node: in that node's first line. For +example, this node's name is Add. A node in another file is +named by (filename)node-within-file, as in +(info)Add for this node. If the file name starts with “./”, +then it is relative to the current directory; otherwise, it is +relative starting from the standard directory for Info files of your +site. The name (filename)Top can be abbreviated to just +(filename). By convention, the name Top is used +for the “highest” node in any single file—the node whose Up +points out of the file. The Directory node is (dir), it +points to a file dir which holds a large menu listing all the +Info documents installed on your site. The Top node of a +document file listed in the Directory should have an Up: +(dir) in it. + +

The node name * is special: it refers to the entire file. +Thus, g* shows you the whole current file. The use of the +node * is to make it possible to make old-fashioned, +unstructured files into nodes of the tree. + +

The Node: 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 Next, Previous and +Up names may contain them. In this node, since the Up +node is in the same file, it was not necessary to use one. + +

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

+


+Next: , +Previous: Add, +Up: Expert Info +
+
+ + +

2.4 How to Create Menus

+ +

Any node in the Info hierarchy may have a menu—a list of subnodes. +The m command searches the current node's menu for the topic which it +reads from the terminal. + +

A menu begins with a line starting with * Menu:. The +rest of the line is a comment. After the starting line, every line +that begins with a * lists a single topic. The name of the +topic–what the user must type at the m'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 +Next, Previous and Up, may be terminated with a +tab, comma, or newline; it may also be terminated with a period. + +

If the node name and topic name are the same, then rather than +giving the name twice, the abbreviation * name:: may be +used (and should be used, whenever possible, as it reduces the visual +clutter in the menu). + +

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

The nodes listed in a node's menu are called its “subnodes”, and it +is their “superior”. They should each have an Up: pointing at +the superior. It is often useful to arrange all or most of the subnodes +in a sequence of Next and Previous pointers so that +someone who wants to see them all need not keep revisiting the Menu. + +

The Info Directory is simply the menu of the node (dir)Top—that +is, node Top in file .../info/dir. You can put new entries +in that menu just like any other menu. The Info Directory is not the +same as the file directory called info. 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. + +

Also, although the Info node graph is claimed to be a “hierarchy”, +in fact it can be any 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 Top; the other contains the node Help which the +h command goes to. In fact, since there is no garbage +collector, nothing terrible happens if a substructure is not pointed +to, but such a substructure is rather useless since nobody can +ever find out that it exists. + +

+


+Next: , +Previous: Menus, +Up: Expert Info +
+
+ + +

2.5 Creating Cross References

+ +

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 *note instead of *. +It cannot be terminated by a ), because )'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: + +

     *Note details: commands.  (See *note 3: Full Proof.)
+
+

These are just examples. The places they “lead to” do not +really exist! + +

+ +
+


+Up: Cross-refs +
+
+ +

2.5.1 The node reached by the cross reference in Info

+ +

This is the node reached by the cross reference named Cross. + +

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 Next, Previous or +Up links pointing back to where you came from. In general, the +l (el) command is the only way to get back there. + +

>> Type l to return to the node where the cross reference was.
+
+
+


+Previous: Help-Int, +Up: Getting Started +
+
+ + +

2.6 Quitting Info

+ +

To get out of Info, back to what you were doing before, type q +for Quit. This runs Info-exit in Emacs. + +

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

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 Info Search. + +

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

>> Type d to go to the Info directory node; then type
+   mInfo and Return, to get to the node about Info and
+   see what other help is available.
+
+
+


+Next: , +Previous: Cross-refs, +Up: Expert Info +
+
+ + +

2.7 Tags Tables for Info Files

+ +

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

To make a tags table, go to a node in the file using Emacs Info mode and type +M-x Info-tagify. Then you must use C-x C-s to save the +file. Info files produced by the makeinfo command that is part +of the Texinfo package always have tags tables to begin with. + +

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 Info-tagify command +again. + +

An Info file tags table appears at the end of the file and looks like +this: + +

     ^_^L
+     Tag Table:
+     File: info, Node: Cross-refs^?21419
+     File: info,  Node: Tags^?22145
+     ^_
+     End Tag Table
+
+

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 DEL character, and the character position in the file of the +beginning of the node. + +

+


+Next: , +Previous: Tags, +Up: Expert Info +
+
+ +

2.8 Checking an Info File

+ +

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 Next, Previous, and +Up is checked, as is every menu item and every cross reference. In +addition, any Next which does not have a Previous 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. + +

To check an Info file, do M-x Info-validate while looking at any +node of the file with Emacs Info mode. + +

+


+Previous: Checking, +Up: Expert Info +
+
+ +

2.9 Emacs Info-mode Variables

+ +

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 ~/.emacs init file. See Examining and Setting Variables (The GNU Emacs Manual). The stand-alone Info reader program has its own set of +variables, described in Manipulating Variables (GNU Info). + +

+
Info-directory-list
The list of directories to search for Info files. Each element is a +string (directory name) or nil (try default directory). If not +initialized Info uses the environment variable INFOPATH to +initialize it, or Info-default-directory-list if there is no +INFOPATH variable in the environment. + +

If you wish to customize the Info directory search list for both Emacs +info and stand-alone Info, it is best to set the INFOPATH +environment variable, since that applies to both programs. + +

Info-additional-directory-list
A list of additional directories to search for Info documentation files. +These directories are not searched for merging the dir file. + +
Info-fontify
When set to a non-nil value, enables highlighting of Info +files. The default is t. You can change how the highlighting +looks by customizing the faces info-node, info-xref, +info-header-xref, info-header-node, info-menu-5, +info-menu-header, and info-title-n-face (where +n is the level of the section, a number between 1 and 4). To +customize a face, type M-x customize-face <RET> face +<RET>, where face is one of the face names listed here. + +
Info-use-header-line
If non-nil, Emacs puts in the Info buffer a header line showing +the Next, Prev, and Up links. A header line does +not scroll with the rest of the buffer, making these links always +visible. + +
Info-hide-note-references
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 nil. Setting +it to a value that is neither nil nor t produces an +intermediate behavior, hiding a limited amount of text, but showing +all text that could potentially be useful. + +
Info-scroll-prefer-subnodes
If set to a non-nil 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 +nil 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 nil. + +
Info-enable-active-nodes
When set to a non-nil 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 DEL character) and an execute: tag, like +this: + +
          ^_execute: (message "This is an active node!")
+     
+
Info-enable-edit
Set to nil, disables the e (Info-edit) command. A +non-nil value enables it. See Edit. +
+ +
+


+Next: , +Previous: Expert Info, +Up: Top +
+
+ +

3 Creating an Info File from a Texinfo File

+ +

makeinfo is a utility that converts a Texinfo file into an Info +file; texinfo-format-region and texinfo-format-buffer are +GNU Emacs functions that do the same. + +

See Overview of Texinfo (Texinfo: The GNU Documentation Format), to learn how to write a Texinfo file. + +

See Creating an Info File (Texinfo: The GNU Documentation Format), to learn how to create an Info file from a Texinfo file. + +

See Installing an Info File (Texinfo: The GNU Documentation Format), to learn how to install an Info file after you +have created one. + +

+


+Previous: Creating an Info File, +Up: Top +
+
+ +

Index

+ +

This is an alphabetical listing of all the commands, variables, and +topics discussed in this document. + +

+
+

Footnotes

[1] 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 Backspace or <- or +DEL, or sometimes Delete.

+ +

[2] If +you put in a ^L to end a new node, be sure that there is a +^_ after it to start the next one, since ^L cannot +start a node. Also, a nicer way to make a node boundary be a +page boundary as well is to put a ^L right after the +^_.

+ +


+ + + diff --git a/Master/texmf/doc/texinfo/info.pdf b/Master/texmf/doc/texinfo/info.pdf new file mode 100644 index 00000000000..0676759673c Binary files /dev/null and b/Master/texmf/doc/texinfo/info.pdf differ diff --git a/Master/texmf/doc/texinfo/texinfo.html b/Master/texmf/doc/texinfo/texinfo.html new file mode 100644 index 00000000000..bd02990f831 --- /dev/null +++ b/Master/texmf/doc/texinfo/texinfo.html @@ -0,0 +1,19883 @@ + + +GNU Texinfo 4.7 + + + + + + + + + + +

GNU Texinfo 4.7

+
+

Short Contents

+ +
+ + + +
+

Table of Contents

+ +
+ +
+


+Next: , +Up: (dir) +
+
+ +

Texinfo

+ +

This manual is for GNU Texinfo (version 4.7, 9 April 2004), +a documentation system that can produce both online information and a +printed manual from a single source. + +

Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, 1998, +1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. + +

+Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being “A GNU Manual,” +and with the Back-Cover Texts as in (a) below. A copy of the license is +included in the section entitled “GNU Free Documentation License.” + +

(a) The FSF's Back-Cover Text is: “You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.” +

+ +

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

+

--- The Detailed Node Listing --- + +

Overview of Texinfo + +

+ +

Using Texinfo Mode + +

+ +

Updating Nodes and Menus + +

+ +

Beginning a Texinfo File + +

+ +

Texinfo File Header + +

+ +

Document Permissions + +

+ +

Title and Copyright Pages + +

+ +

The `Top' Node and Master Menu + +

+ +

Global Document Commands + +

+ +

Ending a Texinfo File + +

+ +

Chapter Structuring + +

+ +

Nodes + +

+ +

The @node Command + +

+ +

Menus + +

+ +

Cross References + +

+ +

@xref + +

+ +

Marking Words and Phrases + +

+ +

Indicating Definitions, Commands, etc. + +

+ +

Emphasizing Text + +

+ +

Quotations and Examples + +

+ +

Lists and Tables + +

+ +

Making a Two-column Table + +

+ +

@multitable: Multi-column Tables + +

+ +

Special Displays + +

+ +

Floats + +

+ +

Inserting Images + +

+ +

Footnotes + +

+ +

Indices + +

+ +

Combining Indices + +

+ +

Special Insertions + +

+ +

Inserting @ and {} and , + +

+ +

Inserting Space + +

+ +

Inserting Ellipsis and Bullets + +

+ +

Inserting TeX and Legal Symbols: ©, ® + +

+ +

Glyphs for Examples + +

+ +

Glyphs Summary + +

+ +

Forcing and Preventing Breaks + +

+ +

Definition Commands + +

+ +

The Definition Commands + +

+ +

Object-Oriented Programming + +

+ +

Conditionally Visible Text + +

+ +

@set, @clear, and @value + +

+ +

Internationalization + +

+ +

Defining New Texinfo Commands + +

+ +

Formatting and Printing Hardcopy + +

+ +

Creating and Installing Info Files + +

+ +

Creating an Info File + +

+ +

Installing an Info File + +

+ +

Generating HTML + +

+ +

HTML Cross-references + +

+ +

@-Command List + +

+ +

Sample Texinfo Files + +

+ +

Copying This Manual + +

+ +

Include Files + +

+ +

Page Headings + +

+ +

Formatting Mistakes + +

+ +

Finding Badly Referenced Nodes + +

+ +

Copying This Manual + +

+ + + + +
+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 +
+ +
+


+Next: , +Previous: Top, +Up: Top +
+
+ +

Texinfo Copying Conditions

+ +

+The programs currently being distributed that relate to Texinfo include +makeinfo, info, texindex, and texinfo.tex. +These programs are free; this means that everyone is free to use +them and free to redistribute them on a free basis. The Texinfo-related +programs are not in the public domain; they are copyrighted and there +are restrictions on their distribution, but these restrictions are +designed to permit everything that a good cooperating citizen would want +to do. What is not allowed is to try to prevent others from further +sharing any version of these programs that they might get from you. + +

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

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

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

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 GNU Free Documentation License). + +

+


+Next: , +Previous: Copying Conditions, +Up: Top +
+
+ +

1 Overview of Texinfo

+ +

+Texinfo1 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. + +

+ +
+


+Next: , +Up: Overview +
+
+ +

1.1 Reporting Bugs

+ +

We welcome bug reports and suggestions for any aspect of the Texinfo system, +programs, documentation, installation, anything. Please email them to +bug-texinfo@gnu.org. You can get the latest version of Texinfo +from ftp://ftp.gnu.org/gnu/texinfo/ and its mirrors worldwide. + +

For bug reports, please include enough information for the maintainers +to reproduce the problem. Generally speaking, that means: + +

+ +

When in doubt whether something is needed or not, include it. It's +better to include too much than to leave out something important. + +

Patches are most welcome; if possible, please make them with +diff -c (see Overview (Comparing and Merging Files)) and include ChangeLog entries (see Change Log (The GNU Emacs Manual)). + +

When sending patches, if possible please do not encode or split them in +any way; it's much easier to deal with one plain text message, however +large, than many small ones. GNU shar is a convenient way of packaging multiple and/or binary files +for email. + +

+


+Next: , +Previous: Reporting Bugs, +Up: Overview +
+
+ +

1.2 Using Texinfo

+ +

+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 Output Formats) for +details and the exact commands to generate output from the source. + +

TeX works with virtually all printers; Info works with virtually all +computer terminals; the HTML output works with virtually all web +browsers. Thus Texinfo can be used by almost any computer user. + +

A Texinfo source file is a plain ascii file containing text +interspersed with @-commands (words preceded by an @) +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 Texinfo Mode.) + +

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 GNU documentation web page. + +

+


+Next: , +Previous: Using Texinfo, +Up: Overview +
+
+ +

1.3 Output Formats

+ +

+Here is a brief overview of the output formats currently supported by +Texinfo. + +

+
Info
(Generated via makeinfo.) This format is essentially a +plain text transliteration of the Texinfo source. It adds a few +control characters to separate nodes and provide navigational +information for menus, cross-references, indices, and so on. See the +next section (see Info Files) for more details on this format. +The Emacs Info subsystem (see Getting Started (Info)), +and the standalone info program (see Info Standalone (GNU Info)), among others, can read these +files. See Creating and Installing Info Files. + +
Plain text
(Generated via makeinfo --no-headers.) This is almost the +same as Info output, except the navigational control characters are +omitted. + +
HTML
(Generated via makeinfo --html.) 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; makeinfo 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 +http://www.w3.org/MarkUp/. See Generating HTML. + +
DVI
(Generated via texi2dvi.) This DeVice Independent binary +format is output by the TeX typesetting program +(http://tug.org). This is then read by a DVI `driver', which +writes the actual device-specific commands that can be viewed or +printed, notably Dvips for translation to PostScript (see Invoking Dvips (Dvips)) and Xdvi for viewing on an X display +(http://sourceforge.net/projects/xdvi/). See Hardcopy. + +

Be aware that the Texinfo language is very different from and much +stricter than TeX's usual languages, plain TeX and LaTeX. +For more information on TeX in general, please see the book +TeX for the Impatient, available from +http://savannah.gnu.org/projects/teximpatient. + +

PDF
(Generated via texi2dvi --pdf.) This format, based on +PostScript, was developed by Adobe Systems for document interchange. +It is intended to be platform-independent and easily viewable, among +other design goals; for a discussion, see +http://tug.org/tugboat/Articles/tb22-3/tb72beebeI.pdf. Texinfo +uses the pdftex program, a variant of TeX, to output pdf; +see http://tug.org/applications/pdftex. See PDF Output. + +
XML
(Generated via makeinfo --xml.) XML is a generic syntax +specification usable for any sort of content (see, for example, +http://www.w3.org/XML/). The makeinfo 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 texinfo.dtd included in +the Texinfo source distribution. + +
Docbook
(Generated via makeinfo --docbook.) This is an XML-based +format developed some years ago, primarily for technical +documentation. It therefore bears some resemblance, in broad +outlines, to Texinfo. See http://www.docbook.org. If you want +to convert from Docbook to Texinfo, please see +http://docbook2X.sourceforge.net. + +
+ +

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

Man pages still have their place, and if you wish to support them, you +may find the program help2man to be useful; it generates a +traditional man page from the --help 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 ftp://ftp.gnu.org/gnu/help2man/. + +

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 makeinfo to generate the new format. + +

+


+Next: , +Previous: Output Formats, +Up: Overview +
+
+ +

1.4 Info Files

+ +

+An Info file is a Texinfo file formatted so that the Info documentation +reading program can operate on it. (makeinfo +and texinfo-format-buffer are two commands that convert a Texinfo file +into an Info file.) + +

Info files are divided into pieces called nodes, 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. + +

See Top (GNU Info), for more information about using Info. + +

Each node of an Info file may have any number of child nodes that +describe subtopics of the node's topic. The names of child +nodes are listed in a menu 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. + +

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

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

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

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

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 Top (Info)). + +

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 g *. (see Advanced Info commands.) + + + + + + + +

The dir file in the info 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. + +

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: +

     info:///usr/info/emacs#Dissociated%20Press
+     info:emacs#Dissociated%20Press
+     info://localhost/usr/info/emacs#Dissociated%20Press
+
+

The info program itself does not follow URI's of any kind. + +

+


+Next: , +Previous: Info Files, +Up: Overview +
+
+ +

1.5 Printed Books

+ +

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

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

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

TeX is a general purpose typesetting program. Texinfo provides a +file texinfo.tex that contains information (definitions or +macros) that TeX uses when it typesets a Texinfo file. +(texinfo.tex tells TeX how to convert the Texinfo @-commands +to TeX commands, which TeX can then process to create the typeset +document.) texinfo.tex contains the specifications for printing +a document. You can get the latest version of texinfo.tex from +ftp://ftp.gnu.org/gnu/texinfo/texinfo.tex. + +

In the United States, documents are most often printed on 8.5 inch by 11 +inch pages (216mm by 280mm); this is the default size. But +you can also print for 7 inch by 9.25 inch pages (178mm by +235mm, the @smallbook size; or on A4 or A5 size paper +(@afourpaper, @afivepaper). (See Printing “Small” Books. Also, see Printing on A4 Paper.) + +

By changing the parameters in texinfo.tex, 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. + +

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 TeX Mode (The GNU Emacs Manual), for information +about TeX.) + +

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

To get a copy of TeX, see +How to Obtain TeX. + +

+


+Next: , +Previous: Printed Books, +Up: Overview +
+
+ +

1.6 @-commands

+ +

+In a Texinfo file, the commands that tell TeX how to typeset the +printed manual and tell makeinfo and +texinfo-format-buffer how to create an Info file are preceded +by @; they are called @-commands. For example, +@node is the command to indicate a node and @chapter +is the command to indicate the start of a chapter. + +

+Note: Almost all @ command names are entirely lower case. +
+ +

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

Depending on what they do or what arguments4 they take, you +need to write @-commands on lines of their own or as part of +sentences: + +

+ +

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 @:, are exceptions to the rule; +they do not need braces. + +

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 @-Command Syntax, for all the details. + +

+


+Next: , +Previous: Formatting Commands, +Up: Overview +
+
+ +

1.7 General Syntactic Conventions

+ +

+This section describes the general conventions used in all Texinfo documents. + +

+ +
+


+Next: , +Previous: Conventions, +Up: Overview +
+
+ +

1.8 Comments

+ +

+You can write comments in a Texinfo file that will not appear in +either the Info file or the printed manual by using the +@comment command (which may be abbreviated to @c). +Such comments are for the person who revises the Texinfo file. All the +text on a line that follows either @comment or @c is a +comment; the rest of the line does not appear in either the Info file +or the printed manual. + +

Often, you can write the @comment or @c in the middle of +a line, and only the text that follows after the @comment or +@c command does not appear; but some commands, such as +@settitle and @setfilename, work on a whole line. You +cannot use @comment or @c in a line beginning with such +a command. + +

You can write long stretches of text that will not appear in either +the Info file or the printed manual by using the @ignore and +@end ignore 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 @ignore and @end ignore for writing +comments. + +

Text enclosed by @ignore or by failing @ifset or +@ifclear 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 stop +ignoring text from the source file; that means that you may still get +error messages if you have invalid Texinfo commands within ignored text. + +

+


+Next: , +Previous: Comments, +Up: Overview +
+
+ +

1.9 What a Texinfo File Must Have

+ +

+By convention, the namea of a Texinfo file ends with (in order of +preference) one of the extensions .texinfo, .texi, +.txi, or .tex. 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. + +

In order to be made into a printed manual and an Info file, a Texinfo +file must begin with lines like this: + +

     \input texinfo
+     @setfilename info-file-name
+     @settitle name-of-manual
+
+

The contents of the file follow this beginning, and then you +must end a Texinfo file with a line like this: + +

     @bye
+
+

Here's an explanation: + +

+ +

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: + +

     \input texinfo   @c -*-texinfo-*-
+     @c %**start of header
+     @setfilename info-file-name
+     @settitle name-of-manual
+     @c %**end of header
+
+

In the first line, -*-texinfo-*- causes Emacs to switch into +Texinfo mode when you edit the file. + +

The @c lines which surround the @setfilename and +@settitle lines are optional, but you need them in order to +run TeX or Info on just part of the file. (See Start of Header.) + +

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

+


+Next: , +Previous: Minimum, +Up: Overview +
+
+ +

1.10 Six Parts of a Texinfo File

+ +

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

+
1. Header
The Header names the file, tells TeX which definitions file to +use, and other such housekeeping tasks. + +
2. Summary and Copyright
The Summary and Copyright segment describes the document and +contains the copyright notice and copying permissions. This is done +with the @copying command. + +
3. Title and Copyright
The Title and Copyright segment contains the title and copyright +pages for the printed manual. The segment must be enclosed between +@titlepage and @end titlepage commands. The title and +copyright page appear only in the printed manual. + +
4. `Top' Node and Master Menu
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 Master Menu listing all the +nodes in the entire document. + +
5. Body
The Body of the document is typically structured like a +traditional book or encyclopedia, but it may be free form. + +
6. End
The End segment contains commands for printing indices and +generating the table of contents, and the @bye command on a line +of its own. +
+ +
+


+Next: , +Previous: Six Parts, +Up: Overview +
+
+ +

1.11 A Short Sample Texinfo File

+ +

+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 +\input texinfo through to @end titlepage, look more +intimidating than they are: most of the material is standard +boilerplate; when writing a manual, you simply change the names as +appropriate. + +

See Beginning a File, for full documentation on the commands listed +here. See GNU Sample Texts, for the full texts to be used in GNU +manuals. + +

In the following, the sample text is indented; comments on it are +not. The complete file, without interspersed comments, is shown in +Short Sample Texinfo File. + +

Part 1: Header

+ +

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

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

Part 2: Summary Description and Copyright

+ +

A real manual includes more text here, according to the license under +which it is distributed. See GNU Sample Texts. + +

     @copying
+     This is a short example of a complete Texinfo file, version 1.0.
+     
+     Copyright @copyright{} 2004 Free Software Foundation, Inc.
+     @end copying
+
+

Part 3: Titlepage, Contents, Copyright

+ +

The titlepage segment does not appear in the online output, only in the +printed manual. We use the @insertcopying 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 +@contents command generates a table of contents. + +

     @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
+
+

Part 4: `Top' Node and Master Menu

+ +

The `Top' node contains the master menu for the Info file. Since the +printed manual uses a table of contents rather than a menu, it +excludes the `Top' node. We also include the copying text again for +the benefit of online readers. Since the copying text begins with +a brief description of the manual, no other text is needed in this +case. The @top command itself helps makeinfo +determine the relationships between nodes. + +

     @ifnottex
+     @node Top
+     @top Short Sample
+     
+     @insertcopying
+     @end ifnottex
+     
+     @menu
+     * First Chapter::    The first chapter is the
+                            only chapter in this sample.
+     * Index::            Complete index.
+     @end menu
+
+

Part 5: The Body of the Document

+ +

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

     @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
+
+

Part 6: The End of the Document

+ +

The end segment contains commands for generating an index in a node and +unnumbered chapter of its own, and the @bye command that marks +the end of the document. + +

     @node Index
+     @unnumbered Index
+     
+     @printindex cp
+     
+     @bye
+
+

Some Results

+ +

Here is what the contents of the first chapter of the sample look like: + +

+
+
+
+This is the first chapter. + +

Here is a numbered list. + +

    +
  1. This is the first item. + +
  2. This is the second item. +
+
+ +
+


+Previous: Short Sample, +Up: Overview +
+
+ +

1.12 History

+ +

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 makeinfo and +info programs. Karl Berry has continued maintenance since +Texinfo 3.8 (manual edition 2.22). + +

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 +texinfo.tex. 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 ChangeLog file. Our mistakes are our own. + +

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 +@ character to introduce commands, as Texinfo does. Much more +consequentially, it strived to describe document contents rather than +formatting, an idea wholeheartedly adopted by Texinfo. + +

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

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

+


+Next: , +Previous: Overview, +Up: Top +
+
+ +

2 Using Texinfo Mode

+ +

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

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

+ +
+


+Next: , +Up: Texinfo Mode +
+
+ +

2.1 Texinfo Mode Overview

+ +

Texinfo mode provides special features for working with Texinfo files. +You can: + +

+ +

Perhaps the two most helpful features are those for inserting frequently +used @-commands and for creating node pointers and menus. + +

+


+Next: , +Previous: Texinfo Mode Overview, +Up: Texinfo Mode +
+
+ +

2.2 The Usual GNU Emacs Editing Commands

+ +

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 M-q (fill-paragraph) +command will refill a paragraph but not mix an indexing command on a +line adjacent to it into the paragraph. + +

In addition, Texinfo mode sets the page-delimiter variable to +the value of texinfo-chapter-level-regexp; 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 +C-x ] (forward-page) and C-x [ +(backward-page) commands and narrow to a chapter with the +C-x p (narrow-to-page) command. (See Pages (The GNU Emacs Manual), for details about the page commands.) + +

You may name a Texinfo file however you wish, but the convention is to +end a Texinfo file name with one of the extensions +.texinfo, .texi, .txi, or .tex. 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 .texinfo, .texi or .txi +extension. Also, Emacs switches to Texinfo mode +when you visit a +file that has -*-texinfo-*- in its first line. If ever you are +in another mode and wish to switch to Texinfo mode, type M-x +texinfo-mode. + +

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

+


+Next: , +Previous: Emacs Editing, +Up: Texinfo Mode +
+
+ + +

2.3 Inserting Frequently Used Commands

+ +

+Texinfo mode provides commands to insert various frequently used +@-commands into the buffer. You can use these commands to save +keystrokes. + +

The insert commands are invoked by typing C-c twice and then the +first letter of the @-command: + +

+
C-c C-c c
M-x texinfo-insert-@code
Insert @code{} and put the +cursor between the braces. + +
C-c C-c d
M-x texinfo-insert-@dfn
Insert @dfn{} and put the +cursor between the braces. + +
C-c C-c e
M-x texinfo-insert-@end
Insert @end and attempt to insert the correct following word, +such as example or table. (This command does not handle +nested lists correctly, but inserts the word appropriate to the +immediately preceding list.) + +
C-c C-c i
M-x texinfo-insert-@item
Insert @item and put the +cursor at the beginning of the next line. + +
C-c C-c k
M-x texinfo-insert-@kbd
Insert @kbd{} and put the +cursor between the braces. + +
C-c C-c n
M-x texinfo-insert-@node
Insert @node and a comment line +listing the sequence for the `Next', +`Previous', and `Up' nodes. +Leave point after the @node. + +
C-c C-c o
M-x texinfo-insert-@noindent
Insert @noindent and put the +cursor at the beginning of the next line. + +
C-c C-c s
M-x texinfo-insert-@samp
Insert @samp{} and put the +cursor between the braces. + +
C-c C-c t
M-x texinfo-insert-@table
Insert @table followed by a <SPC> +and leave the cursor after the <SPC>. + +
C-c C-c v
M-x texinfo-insert-@var
Insert @var{} and put the +cursor between the braces. + +
C-c C-c x
M-x texinfo-insert-@example
Insert @example and put the +cursor at the beginning of the next line. + + + +
C-c C-c {
M-x texinfo-insert-braces
Insert {} and put the cursor between the braces. + +
C-c C-c }
C-c C-c ]
M-x up-list
Move from between a pair of braces forward past the closing brace. +Typing C-c C-c ] is easier than typing C-c C-c }, which +is, however, more mnemonic; hence the two keybindings. (Also, you can +move out from between braces by typing C-f.) +
+ +

To put a command such as @code{...} around an +existing word, position the cursor in front of the word and type +C-u 1 C-c C-c c. 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—1 for one word, 2 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 @kbd and @var. + +

This set of insert commands was created after analyzing the frequency +with which different @-commands are used in the GNU Emacs +Manual and the GDB Manual. 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 texinfo.el. + +

C-c C-c C-d (texinfo-start-menu-description) 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 The Parts of a Menu.) + +

To use texinfo-start-menu-description, position point in a menu +entry line and type C-c C-c C-d. 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. + +

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

+


+Next: , +Previous: Inserting, +Up: Texinfo Mode +
+
+ + +

2.4 Showing the Section Structure of a File

+ +

+You can show the section structure of a Texinfo file by using the +C-c C-s command (texinfo-show-structure). This command +shows the section structure of a Texinfo file by listing the lines +that begin with the @-commands for @chapter, +@section, and the like. It constructs what amounts +to a table of contents. These lines are displayed in another buffer +called the *Occur* buffer. In that buffer, you can position +the cursor over one of the lines and use the C-c C-c command +(occur-mode-goto-occurrence), to jump to the corresponding spot +in the Texinfo file. + +

+
C-c C-s
M-x texinfo-show-structure
Show the @chapter, @section, and such lines of a +Texinfo file. + +
C-c C-c
M-x occur-mode-goto-occurrence
Go to the line in the Texinfo file corresponding to the line under the +cursor in the *Occur* buffer. +
+ +

If you call texinfo-show-structure with a prefix argument by +typing C-u C-c C-s, it will list not only those lines with the +@-commands for @chapter, @section, and the like, but +also the @node lines. You can use texinfo-show-structure +with a prefix argument to check whether the `Next', `Previous', and `Up' +pointers of an @node line are correct. + +

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 +C-x n n (narrow-to-region) command and +texinfo-show-structure will work on only that region. To see +the whole buffer again, use C-x n w (widen). +(See Narrowing (The GNU Emacs Manual), for more +information about the narrowing commands.) + +

In addition to providing the texinfo-show-structure command, +Texinfo mode sets the value of the page delimiter variable to match +the chapter-level @-commands. This enables you to use the C-x +] (forward-page) and C-x [ (backward-page) +commands to move forward and backward by chapter, and to use the +C-x p (narrow-to-page) command to narrow to a chapter. +See Pages (The GNU Emacs Manual), for more information +about the page commands. + +

+


+Next: , +Previous: Showing the Structure, +Up: Texinfo Mode +
+
+ + +

2.5 Updating Nodes and Menus

+ +

+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 @node line that has none +and to create menus in a file that has none. + +

If you do not use the updating commands, you need to write menus and +node pointers by hand, which is a tedious task. + +

+ +
+


+Next: , +Up: Updating Nodes and Menus +
+
+ +

2.5.1 The Updating Commands

+ +

You can use the updating commands to: + +

+ +

You can also use the commands to update all the nodes and menus in a +region or in a whole Texinfo file. + +

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 @node line, except +for the `Top' @node line. (A structuring command line is +a line beginning with @chapter, @section, or other +similar command.) + +

You can write the structuring command line on the line that follows +immediately after an @node line or else on the line that +follows after a single @comment line or a single +@ifinfo line. You cannot interpose more than one line between +the @node line and the structuring command line; and you may +interpose only an @comment line or an @ifinfo line. + +

Commands which work on a whole buffer require that the `Top' node be +followed by a node with an @chapter or equivalent-level command. +The menu updating commands will not create a main or master menu for a +Texinfo file that has only @chapter-level nodes! The menu +updating commands only create menus within nodes for lower level +nodes. To create a menu of chapters, you must provide a `Top' +node. + +

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

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 texinfo-master-menu command, is for creating a +master menu for a complete file, and optionally, for updating every +node and menu in the whole Texinfo file. + +

The texinfo-master-menu command is the primary command: + +

+
C-c C-u m
M-x texinfo-master-menu
Create or update a master menu that includes all the other menus +(incorporating the descriptions from pre-existing menus, if +any). + +

With an argument (prefix argument, C-u, if interactive), first create or +update all the nodes and all the regular menus in the buffer before +constructing the master menu. (See The Top Node and Master Menu, for more about a master menu.) + +

For texinfo-master-menu to work, the Texinfo file must have a +`Top' node and at least one subsequent node. + +

After extensively editing a Texinfo file, you can type the following: + +

          C-u M-x texinfo-master-menu
+     
or
+ C-u C-c C-u m +
+

This updates all the nodes and menus completely and all at once. +

+ +

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

The commands are: + +

+
C-c C-u C-n
M-x texinfo-update-node
Insert the `Next', `Previous', and `Up' pointers for the node that point is +within (i.e., for the @node line preceding point). If the +@node 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, C-u, if interactive), this command +updates all @node lines in the region (which is the text +between point and mark). + +
C-c C-u C-m
M-x texinfo-make-menu
Create or update the menu in the node that point is within. +With an argument (C-u as prefix argument, if +interactive), the command makes or updates menus for the +nodes which are either within or a part of the +region. + +

Whenever texinfo-make-menu 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. + +

C-c C-u C-e
M-x texinfo-every-node-update
Insert or update the `Next', `Previous', and `Up' pointers for every +node in the buffer. + +
C-c C-u C-a
M-x texinfo-all-menus-update
Create or update all the menus in the buffer. With an argument +(C-u as prefix argument, if interactive), first insert +or update all the node +pointers before working on the menus. + +

If a master menu exists, the texinfo-all-menus-update command +updates it; but the command does not create a new master menu if none +already exists. (Use the texinfo-master-menu command for +that.) + +

When working on a document that does not merit a master menu, you can +type the following: + +

          C-u C-c C-u C-a
+     
or
+ C-u M-x texinfo-all-menus-update +
+

This updates all the nodes and menus. +

+ +

The texinfo-column-for-description variable specifies the +column to which menu descriptions are indented. By default, the value +is 32 although it is often useful to reduce it to as low as 24. You +can set the variable via customization (see Changing an Option (The GNU Emacs Manual)) or with the M-x set-variable +command (see Examining and Setting Variables (The GNU Emacs Manual)). + +

Also, the texinfo-indent-menu-description command may be used to +indent existing menu descriptions to a specified column. Finally, if +you wish, you can use the texinfo-insert-node-lines command to +insert missing @node lines into a file. (See Other Updating Commands, for more information.) + +

+


+Next: , +Previous: Updating Commands, +Up: Updating Nodes and Menus +
+
+ +

2.5.2 Updating Requirements

+ +

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

Each @node line, with the exception of the line for the `Top' +node, must be followed by a line with a structuring command such as +@chapter, @section, or +@unnumberedsubsec. + +

Each @node line/structuring-command line combination +must look either like this: + +

     @node     Comments,  Minimum, Conventions, Overview
+     @comment  node-name, next,    previous,    up
+     @section Comments
+
+

or like this (without the @comment line): + +

     @node Comments, Minimum, Conventions, Overview
+     @section Comments
+
+

or like this (without the explicit node pointers): + +

     @node Comments
+     @section Comments
+
+

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 +@comment line, you may also write an @ifinfo line.) + +

If a file has a `Top' node, it must be called top or Top +and be the first node in the file. + +

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

Incidentally, the makeinfo 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 makeinfo, you have no need for the update node +commands. (See Creating an Info File, for more information about +makeinfo.) However, both makeinfo and the +texinfo-format-... commands require that you insert menus in +the file. + +

+


+Previous: Updating Requirements, +Up: Updating Nodes and Menus +
+
+ +

2.5.3 Other Updating Commands

+ +

In addition to the five major updating commands, Texinfo mode +possesses several less frequently used updating commands: + +

+
M-x texinfo-insert-node-lines
Insert @node lines before the @chapter, +@section, and other sectioning commands wherever they are +missing throughout a region in a Texinfo file. + +

With an argument (C-u as prefix argument, if interactive), the +texinfo-insert-node-lines command not only inserts +@node 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 @node lines that lack +names. Since node names should be more concise than section or +chapter titles, you must manually edit node names so inserted. + +

For example, the following marks a whole buffer as a region and inserts +@node lines and titles throughout: + +

          C-x h C-u M-x texinfo-insert-node-lines
+     
+

This command inserts titles as node names in @node lines; the +texinfo-start-menu-description command (see Inserting Frequently Used Commands) inserts titles as descriptions in +menu entries, a different action. However, in both cases, you need to +edit the inserted text. + +

M-x texinfo-multiple-files-update
Update nodes and menus in a document built from several separate files. +With C-u as a prefix argument, create and insert a master menu in +the outer file. With a numeric prefix argument, such as C-u 2, 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 texinfo-multiple-files-update command is +described in the appendix on @include files. +See texinfo-multiple-files-update. + +
M-x texinfo-indent-menu-description
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 (C-u as prefix argument, if +interactive), the texinfo-indent-menu-description 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. + +
M-x texinfo-sequential-node-update
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 g * command lets +you look through the file sequentially, so sequentially ordered nodes +are not strictly necessary.) With an argument (prefix argument, if +interactive), the texinfo-sequential-node-update command +sequentially updates all the nodes in the region. +
+ +
+


+Next: , +Previous: Updating Nodes and Menus, +Up: Texinfo Mode +
+
+ + +

2.6 Formatting for Info

+ +

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

You can use either the texinfo-format-region or the +makeinfo-region command to format a region: + + + +

C-c C-e C-r
M-x texinfo-format-region
C-c C-m C-r
M-x makeinfo-region
Format the current region for Info. +
+ +

You can use either the texinfo-format-buffer or the +makeinfo-buffer command to format a whole buffer: + + + +

C-c C-e C-b
M-x texinfo-format-buffer
C-c C-m C-b
M-x makeinfo-buffer
Format the current buffer for Info. +
+ +

For example, after writing a Texinfo file, you can type the following: + +

     C-u C-c C-u m
+
or
+ C-u M-x texinfo-master-menu +
+

This updates all the nodes and menus. Then type the following to create +an Info file: + +

     C-c C-m C-b
+
or
+ M-x makeinfo-buffer +
+

For TeX or the Info formatting commands to work, the file must +include a line that has @setfilename in its header. + +

See Creating an Info File, for details about Info formatting. + +

+


+Next: , +Previous: Info Formatting, +Up: Texinfo Mode +
+
+ + +

2.7 Printing

+ +

+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 texindex command after first running the +tex typesetting command; and then you must run the tex +command again. Or else run the texi2dvi command which +automatically creates indices as needed (see Format with texi2dvi). + +

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 +texinfo-tex-region and related commands for this purpose. Use +the texinfo-tex-buffer command to format all of a +buffer. + +

+
C-c C-t C-b
M-x texinfo-tex-buffer
Run texi2dvi on the buffer. In addition to running TeX on the +buffer, this command automatically creates or updates indices as +needed. + +
C-c C-t C-r
M-x texinfo-tex-region
Run TeX on the region. + +
C-c C-t C-i
M-x texinfo-texindex
Run texindex to sort the indices of a Texinfo file formatted with +texinfo-tex-region. The texinfo-tex-region command does +not run texindex automatically; it only runs the tex +typesetting command. You must run the texinfo-tex-region command +a second time after sorting the raw index files with the texindex +command. (Usually, you do not format an index when you format a region, +only when you format a buffer. Now that the texi2dvi command +exists, there is little or no need for this command.) + +
C-c C-t C-p
M-x texinfo-tex-print
Print the file (or the part of the file) previously formatted with +texinfo-tex-buffer or texinfo-tex-region. +
+ +

For texinfo-tex-region or texinfo-tex-buffer to work, the +file must start with a \input texinfo line and must +include an @settitle line. The file must end with @bye +on a line by itself. (When you use texinfo-tex-region, you must +surround the @settitle line with start-of-header and +end-of-header lines.) + +

See Hardcopy, for a description of the other TeX related +commands, such as tex-show-print-queue. + +

+


+Previous: Printing, +Up: Texinfo Mode +
+
+ + +

2.8 Texinfo Mode Summary

+ +

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 C-c. The keys are somewhat +mnemonic. + +

Insert Commands

+ +

The insert commands are invoked by typing C-c twice and then the +first letter of the @-command to be inserted. (It might make more +sense mnemonically to use C-c C-i, for `custom insert', but +C-c C-c is quick to type.) + +

     C-c C-c c       Insert @code.
+     C-c C-c d       Insert @dfn.
+     C-c C-c e       Insert @end.
+     C-c C-c i       Insert @item.
+     C-c C-c n       Insert @node.
+     C-c C-c s       Insert @samp.
+     C-c C-c v       Insert @var.
+     C-c C-c {       Insert braces.
+     C-c C-c ]
+     C-c C-c }       Move out of enclosing braces.
+     
+     C-c C-c C-d     Insert a node's section title
+                    in the space for the description
+                    in a menu entry line.
+
+

Show Structure

+ +

The texinfo-show-structure command is often used within a +narrowed region. + +

     C-c C-s         List all the headings.
+
+

The Master Update Command

+ +

The texinfo-master-menu command creates a master menu; and can +be used to update every node and menu in a file as well. + + +

     C-c C-u m
+     M-x texinfo-master-menu
+                    Create or update a master menu.
+     
+     C-u C-c C-u m   With C-u as a prefix argument, first
+                    create or update all nodes and regular
+                    menus, and then create a master menu.
+
+

Update Pointers

+ +

The update pointer commands are invoked by typing C-c C-u and +then either C-n for texinfo-update-node or C-e for +texinfo-every-node-update. + +

     C-c C-u C-n     Update a node.
+     C-c C-u C-e     Update every node in the buffer.
+
+

Update Menus

+ +

Invoke the update menu commands by typing C-c C-u +and then either C-m for texinfo-make-menu or +C-a for texinfo-all-menus-update. To update +both nodes and menus at the same time, precede C-c C-u +C-a with C-u. + +

     C-c C-u C-m     Make or update a menu.
+     
+     C-c C-u C-a     Make or update all
+                    menus in a buffer.
+     
+     C-u C-c C-u C-a With C-u as a prefix argument,
+                    first create or update all nodes and
+                    then create or update all menus.
+
+

Format for Info

+ +

The Info formatting commands that are written in Emacs Lisp are +invoked by typing C-c C-e and then either C-r for a region +or C-b for the whole buffer. + +

The Info formatting commands that are written in C and based on the +makeinfo program are invoked by typing C-c C-m and then +either C-r for a region or C-b for the whole buffer. + +

Use the texinfo-format... commands: + +

     C-c C-e C-r     Format the region.
+     C-c C-e C-b     Format the buffer.
+
+

Use makeinfo: + +

     C-c C-m C-r     Format the region.
+     C-c C-m C-b     Format the buffer.
+     C-c C-m C-l     Recenter the makeinfo output buffer.
+     C-c C-m C-k     Kill the makeinfo formatting job.
+
+

Typeset and Print

+ +

The TeX typesetting and printing commands are invoked by typing +C-c C-t and then another control command: C-r for +texinfo-tex-region, C-b for texinfo-tex-buffer, +and so on. + +

     C-c C-t C-r     Run TeX on the region.
+     C-c C-t C-b     Run texi2dvi on the buffer.
+     C-c C-t C-i     Run texindex.
+     C-c C-t C-p     Print the DVI file.
+     C-c C-t C-q     Show the print queue.
+     C-c C-t C-d     Delete a job from the print queue.
+     C-c C-t C-k     Kill the current TeX formatting job.
+     C-c C-t C-x     Quit a currently stopped TeX formatting job.
+     C-c C-t C-l     Recenter the output buffer.
+
+

Other Updating Commands

+ +

The remaining updating commands do not have standard keybindings because +they are rarely used. + +

     M-x texinfo-insert-node-lines
+                    Insert missing @node lines in region.
+                    With C-u as a prefix argument,
+                    use section titles as node names.
+     
+     M-x texinfo-multiple-files-update
+                    Update a multi-file document.
+                    With C-u 2 as a prefix argument,
+                    create or update all nodes and menus
+                    in all included files first.
+     
+     M-x texinfo-indent-menu-description
+                    Indent descriptions.
+     
+     M-x texinfo-sequential-node-update
+                    Insert node pointers in strict sequence.
+
+
+


+Next: , +Previous: Texinfo Mode, +Up: Top +
+
+ +

3 Beginning a Texinfo File

+ +

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

This chapter expands on the minimal complete Texinfo source file +previously given (see Six Parts). It describes the numerous +commands for handling the traditional frontmatter items in Texinfo. + +

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

+ +
+


+Next: , +Up: Beginning a File +
+
+ +

3.1 Sample Texinfo File Beginning

+ +

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

See GNU Sample Texts, for the full texts to be used in GNU manuals. + +

     \input texinfo   @c -*-texinfo-*-
+     @c %**start of header
+     @setfilename infoname.info
+     @settitle name-of-manual version
+     @c %**end of header
+     
+     @copying
+     This manual is for program, version version.
+     
+     Copyright @copyright{} years copyright-owner.
+     
+     @quotation
+     Permission is granted to ...
+     @end quotation
+     @end copying
+     
+     @titlepage
+     @title name-of-manual-when-printed
+     @subtitle subtitle-if-any
+     @subtitle second-subtitle
+     @author author
+     
+     @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 title
+     
+     @insertcopying
+     @end ifnottex
+     
+     @menu
+     * First Chapter::    Getting started ...
+     * Second Chapter::          ...
+      ...
+     * Copying::          Your rights and freedoms.
+     @end menu
+     
+     @node First Chapter
+     @chapter First Chapter
+     
+     @cindex first chapter
+     @cindex chapter, first
+     ...
+
+
+


+Next: , +Previous: Sample Beginning, +Up: Beginning a File +
+
+ +

3.2 Texinfo File Header

+ +

+Texinfo files start with at least three lines that provide Info and +TeX with necessary information. These are the \input texinfo +line, the @settitle line, and the @setfilename line. + +

Also, if you want to format just part of the Texinfo file, you must +write the @settitle and @setfilename 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. + +

Any command that affects document formatting as a whole makes sense to +include in the header. @synindex (see synindex), for +instance, is another command often included in the header. See GNU Sample Texts, for complete sample texts. + +

Thus, the beginning of a Texinfo file generally looks like this: + +

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


+Next: , +Up: Texinfo File Header +
+
+ +

3.2.1 The First Line of a Texinfo File

+ +

+Every Texinfo file that is to be the top-level input to TeX must begin +with a line that looks like this: + +

     \input texinfo   @c -*-texinfo-*-
+
+

This line serves two functions: + +

    +
  1. When the file is processed by TeX, the \input texinfo command +tells TeX to load the macros needed for processing a Texinfo file. +These are in a file called texinfo.tex, which should have been +installed on your system along with either the TeX or Texinfo +software. TeX uses the backslash, \, to mark the beginning of +a command, exactly as Texinfo uses @. The texinfo.tex +file causes the switch from \ to @; before the switch +occurs, TeX requires \, which is why it appears at the +beginning of the file. + +
  2. When the file is edited in GNU Emacs, the -*-texinfo-*- mode +specification tells Emacs to use Texinfo mode. +
+ +
+


+Next: , +Previous: First Line, +Up: Texinfo File Header +
+
+ +

3.2.2 Start of Header

+ +

+A start-of-header line is a Texinfo comment that looks like this: + +

     @c %**start of header
+
+

Write the start-of-header line on the second line of a Texinfo file. +Follow the start-of-header line with @setfilename and +@settitle lines and, optionally, with other commands that +globally affect the document formatting, such as @synindex or +@footnotestyle; and then by an end-of-header line (see End of Header). + +

The start- and end-of-header lines allow you to format only part of a +Texinfo file for Info or printing. See texinfo-format commands. + +

The odd string of characters, %**, 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 tex-start-of-header and/or +tex-end-of-header Emacs variables. See Texinfo Mode Printing. + +

+


+Next: , +Previous: Start of Header, +Up: Texinfo File Header +
+
+ +

3.2.3 @setfilename: Set the output file name

+ +

+In order to serve as the primary input file for either makeinfo +or TeX, a Texinfo file must contain a line that looks like this: + +

     @setfilename info-file-name
+
+

Write the @setfilename 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. + +

The Info formatting commands ignore everything written before the +@setfilename line, which is why the very first line of +the file (the \input line) does not show up in the output. + +

The @setfilename 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 .texi) entirely from the input file +name, or, preferably, replace it with the .info extension. + +

Although an explicit .info 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 -1, +-2, ..., -10, -11, and so on, to the original +file name. (See Tag and Split Files.) The subfile name +texinfo.info-10, for example, is too long for old systems with a +14-character limit on filenames; so the Info file name for this document +is texinfo rather than texinfo.info. When makeinfo +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 texin-10, gcc.i12, etc. + +

When producing HTML output, makeinfo will replace any extension +with html, or add .html if the given name has no +extension. + +

The @setfilename 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 texinfo.cnf if that file is present on your system +(see Preparing for TeX). + +

+


+Next: , +Previous: setfilename, +Up: Texinfo File Header +
+
+ +

3.2.4 @settitle: Set the document title

+ +

+In order to be made into a printed manual, a Texinfo file must contain +a line that looks like this: + +

     @settitle title
+
+

Write the @settitle command at the beginning of a line and +follow it on the same line by the title. This tells TeX the title to +use in a header or footer. Do not write anything else on the line; +anything on the line after the command is considered part of the title, +including what would otherwise be a comment. + +

The @settitle command should precede everything that generates +actual output. The best place for it is right after the +@setfilename command (see the previous section). + +

In the HTML file produced by makeinfo, title serves as +the document <title>. It also becomes the default document +description in the <head> part (see documentdescription). + +

The title in the @settitle command does not affect the title as +it appears on the title page. Thus, the two do not need not match +exactly. A practice we recommend is to include the version or edition +number of the manual in the @settitle title; on the title page, +the version number generally appears as a @subtitle so it would +be omitted from the @title. See titlepage. + +

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 @chapter command.) By default, no page footer is +printed. + +

Even if you are printing in a single-sided style, TeX looks for an +@settitle command line, in case you include the manual title +in the heading. + +

TeX prints page headings only for that text that comes after the +@end titlepage command in the Texinfo file, or that comes +after an @headings command that turns on headings. +(See The @headings Command, for more +information.) + +

You may, if you wish, create your own, customized headings and footings. +See Headings, for a detailed discussion of this. + +

+


+Previous: settitle, +Up: Texinfo File Header +
+
+ +

3.2.5 End of Header

+ +

+Follow the header lines with an end-of-header line, which is a +Texinfo comment that looks like this: + +

     @c %**end of header
+
+

See Start of Header. + +

+


+Next: , +Previous: Texinfo File Header, +Up: Beginning a File +
+
+ +

3.3 Document Permissions

+ +

+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 (@copying) to declare +this text once, and another command (@insertcopying) to +insert the text at appropriate points. + +

+ +
+


+Next: , +Up: Document Permissions +
+
+ +

3.3.1 @copying: Declare Copying Permissions

+ +

+The @copying command should be given very early in the document; +the recommended location is right after the header material +(see Texinfo File Header). 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: + +

     @copying
+     This manual is for program (version version, updated
+     date), which ...
+     
+     Copyright @copyright{} years copyright-owner.
+     
+     @quotation
+     Permission is granted to ...
+     @end quotation
+     @end copying
+
+

The @quotation has no legal significance; it's there to improve +readability in some contexts. + +

See GNU Sample Texts, for the full text to be used in GNU manuals. +See GNU Free Documentation License, 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. + +

The text of @copying is output as a comment at the beginning of +Info, HTML, and XML output files. It is not output implicitly in +plain text or TeX; it's up to you to use @insertcopying to +emit the copying information. See the next section for details. + +

The @copyright{} command generates a c inside a circle +in output formats that support this (print and HTML). In the other +formats (Info and plain text), it generates (C). The copyright +notice itself has the following legally defined sequence: + +

     Copyright © years copyright-owner.
+
+

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

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

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.'. + +

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

See Copyright Notices (GNU Maintenance Instructions), for +additional information. + +

+


+Previous: copying, +Up: Document Permissions +
+
+ +

3.3.2 @insertcopying: Include Permissions Text

+ +

+The @insertcopying command is simply written on a line by +itself, like this: + +

     @insertcopying
+
+

This inserts the text previously defined by @copying. To meet +legal requirements, it must be used on the copyright page in the printed +manual (see Copyright). + +

We also strongly recommend using @insertcopying in the Top node +of your manual (see The Top Node), although it is not required +legally. Here's why: + +

The @copying command itself causes the permissions text to +appear in an Info file before 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 not see this text (except when using the advanced Info +command g *). Therefore, an explicit @insertcopying +in the Top node makes it apparent to readers that the manual is free. + +

Similarly, the @copying text is automatically included at the +beginning of each HTML output file, as an HTML comment. Again, this +text is not visible (unless the reader views the HTML source). And +therefore again, the @insertcopying in the Top node is valuable +because it makes the copying permissions visible and thus promotes +freedom. + +

The permissions text defined by @copying also appears +automatically at the beginning of the XML output file. + +

+


+Next: , +Previous: Document Permissions, +Up: Beginning a File +
+
+ +

3.4 Title and Copyright Pages

+ +

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

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

You may wish to include titlepage-like information for plain text +output. Simply place any such leading material between +@ifplaintext and @end ifplaintext; makeinfo +includes this when writing plain text (--no-headers), along with +an @insertcopying. + +

+ +
+


+Next: , +Up: Titlepage & Copyright Page +
+
+ +

3.4.1 @titlepage

+ +

+Start the material for the title page and following copyright page +with @titlepage on a line by itself and end it with +@end titlepage on a line by itself. + +

The @end titlepage command starts a new page and turns on page +numbering. (See Page Headings, for details about how to +generate page headings.) All the material that you want to appear on +unnumbered pages should be put between the @titlepage and +@end titlepage commands. You can force the table of contents to +appear there with the @setcontentsaftertitlepage command +(see Contents). + +

By using the @page command you can force a page break within the +region delineated by the @titlepage and @end titlepage +commands and thereby create more than one unnumbered page. This is how +the copyright page is produced. (The @titlepage command might +perhaps have been better named the @titleandadditionalpages +command, but that would have been rather long!) + +

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 number5 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 +The Top Node.) + +

Texinfo provides two main methods for creating a title page. One method +uses the @titlefont, @sp, and @center commands +to generate a title page in which the words on the page are +centered. + +

The second method uses the @title, @subtitle, and +@author 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. + +

You may use either method, or you may combine them; see the examples in +the sections below. + +

For extremely simple documents, and for the bastard title page in +traditional book frontmatter, Texinfo also provides a command +@shorttitlepage which takes the rest of the line as the title. +The argument is typeset on a page by itself and followed by a blank +page. + +

+


+Next: , +Previous: titlepage, +Up: Titlepage & Copyright Page +
+
+ +

3.4.2 @titlefont, @center, and @sp

+ +

+You can use the @titlefont, @sp, and @center +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.) + +

Use the @titlefont command to select a large font suitable for +the title itself. You can use @titlefont more than once if you +have an especially long title. + +

For HTML output, each @titlefont command produces an +<h1> heading, but the HTML document <title> is not +affected. For that, you must put an @settitle command before +the @titlefont command (see settitle). + +

For example: + +

     @titlefont{Texinfo}
+
+

Use the @center command at the beginning of a line to center +the remaining text on that line. Thus, + +

     @center @titlefont{Texinfo}
+
+

centers the title, which in this example is “Texinfo” printed +in the title font. + +

Use the @sp command to insert vertical space. For example: + +

     @sp 2
+
+

This inserts two blank lines on the printed page. (See @sp, for more information about the @sp +command.) + +

A template for this method looks like this: + +

     @titlepage
+     @sp 10
+     @center @titlefont{name-of-manual-when-printed}
+     @sp 2
+     @center subtitle-if-any
+     @sp 2
+     @center author
+     ...
+     @end titlepage
+
+

The spacing of the example fits an 8.5 by 11 inch manual. + +

You can in fact use these commands anywhere, not just on a title page, +but since they are not logical markup commands, we don't recommend +them. + +

+


+Next: , +Previous: titlefont center sp, +Up: Titlepage & Copyright Page +
+
+ +

3.4.3 @title, @subtitle, and @author

+ +

+You can use the @title, @subtitle, and @author +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 @sp command is +needed to adjust vertical spacing. + +

Write the @title, @subtitle, or @author +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 @titlepage. + +

The @title command produces a line in which the title is set +flush to the left-hand side of the page in a larger than normal font. +The title is underlined with a black rule. Only a single line is +allowed; the @* 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 @title and @titlefont; see the final example in +this section. + +

The @subtitle command sets subtitles in a normal-sized font +flush to the right-hand side of the page. + +

The @author 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 @author command line is +followed by an @page command line.) + +

There are two ways to use the @author command: you can write +the name or names on the remaining part of the line that starts with +an @author command: + +

     @author by Jane Smith and John Doe
+
+

or you can write the names one above each other by using two (or more) +@author commands: + +

     @author Jane Smith
+     @author John Doe
+
+

(Only the bottom name is underlined with a black rule.) + +

A template for this method looks like this: + +

     @titlepage
+     @title name-of-manual-when-printed
+     @subtitle subtitle-if-any
+     @subtitle second-subtitle
+     @author author
+     @page
+     ...
+     @end titlepage
+
+

You may also combine the @titlefont method described in the +previous section and @title method described in this one. This +may be useful if you have a very long title. Here is a real-life 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
+
+

(The use of @value here is explained in value Example. + +

+


+Next: , +Previous: title subtitle author, +Up: Titlepage & Copyright Page +
+
+ +

3.4.4 Copyright Page

+ +

+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 @titlepage and @end titlepage +commands. + +

Use the @page command to cause a page break. To push the +copyright notice and the other text on the copyright page towards the +bottom of the page, use the following incantantion after @page: + +

     @vskip 0pt plus 1filll
+
+

This is a TeX command that is not supported by the Info formatting +commands. The @vskip command inserts whitespace. The 0pt +plus 1filll 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 ls in the word +filll; this is correct. + +

To insert the copyright text itself, write @insertcopying +next (see Document Permissions): + +

     @insertcopying
+
+

Follow the copying text by the publisher, ISBN numbers, cover art +credits, and other such information. + +

Here is an example putting all this together: + +

     @titlepage
+     ...
+     @page
+     @vskip 0pt plus 1filll
+     @insertcopying
+     
+     Published by ...
+     
+     Cover art by ...
+     @end titlepage
+
+
+


+Next: , +Previous: Copyright, +Up: Titlepage & Copyright Page +
+
+ +

3.4.5 Heading Generation

+ +

+The @end titlepage command must be written on a line by itself. +It not only marks the end of the title and copyright pages, but also +causes TeX to start generating page headings and page numbers. + +

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: + +

+ +

Most documents are formatted with the standard single-sided or +double-sided format, using @setchapternewpage odd for +double-sided printing and no @setchapternewpage command for +single-sided printing. + +

+


+Previous: end titlepage, +Up: Titlepage & Copyright Page +
+
+ +

3.4.6 The @headings Command

+ +

+The @headings command is rarely used. It specifies what kind of +page headings and footings to print on each page. Usually, this is +controlled by the @setchapternewpage command. You need the +@headings command only if the @setchapternewpage command +does not do what you want, or if you want to turn off pre-defined page +headings prior to defining your own. Write an @headings command +immediately after the @end titlepage command. + +

You can use @headings as follows: + +

+
@headings off
Turn off printing of page headings. + +
@headings single
Turn on page headings appropriate for single-sided printing. + +
@headings double
@headings on
Turn on page headings appropriate for double-sided printing. The two +commands, @headings on and @headings double, are +synonymous. + +
@headings singleafter
@headings doubleafter
Turn on single or double headings, respectively, after the +current page is output. + +
@headings on
Turn on page headings: single if @setchapternewpage +on, double otherwise. +
+ +

For example, suppose you write @setchapternewpage off before the +@titlepage 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 @headings +double after the @end titlepage command. + +

You can stop TeX from generating any page headings at all by +writing @headings off on a line of its own immediately after the +line containing the @end titlepage command, like this: + +

     @end titlepage
+     @headings off
+
+

The @headings off command overrides the @end titlepage +command, which would otherwise cause TeX to print page +headings. + +

You can also specify your own style of page heading and footing. +See Page Headings, for more information. + +

+


+Next: , +Previous: Titlepage & Copyright Page, +Up: Beginning a File +
+
+ +

3.5 Generating a Table of Contents

+ +

+The @chapter, @section, and other structuring commands +(see Structuring) 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 @contents and/or +@summarycontents command(s). + +

+
@contents
Generates a table of contents in a printed manual, including all +chapters, sections, subsections, etc., as well as appendices and +unnumbered chapters. Headings generated by @majorheading, +@chapheading, and the other @...heading commands +do not appear in the table of contents (see Structuring Command Types). + +
@shortcontents
@summarycontents
(@summarycontents is a synonym for @shortcontents.) + +

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

+ +

Both contents commands should be written on a line by themselves, and +are best placed near the beginning of the file, after the @end +titlepage (see titlepage). 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 +@unnumbered before them. + +

Since an Info file uses menus instead of tables of contents, the Info +formatting commands ignore the contents commands. But the contents are +included in plain text output (generated by makeinfo +--no-headers), unless makeinfo is writing its output to standard +output. + +

When makeinfo writes a short table of contents while producing +html output, the links in the short table of contents point to +corresponding entries in the full table of contents rather than the text +of the document. The links in the full table of contents point to the +main text of the document. + +

In the past, the contents commands were sometimes placed at the end of +the file, after any indices and just before the @bye, but we +no longer recommend this. + +

However, since many existing Texinfo documents still do have the +@contents 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 +@setcontentsaftertitlepage and/or +@setshortcontentsaftertitlepage. The first prints only the +main contents after the @end titlepage; the second prints both +the short contents and the main contents. In either case, any +subsequent @contents or @shortcontents is ignored +(unless, erroneously, no @end titlepage is ever encountered). + +

You need to include the @set...contentsaftertitlepage +commands early in the document (just after @setfilename, for +example). We recommend using texi2dvi (see Format with texi2dvi) to specify this without altering the source file at all. For +example: +

     texi2dvi --texinfo=@setcontentsaftertitlepage foo.texi
+
+
+


+Next: , +Previous: Contents, +Up: Beginning a File +
+
+ +

3.6 The `Top' Node and Master Menu

+ +

+The `Top' node is the node in which a reader enters an Info manual. As +such, it should begin with the @insertcopying command +(see Document Permissions) to provide a brief description of the +manual (including the version number) and copying permissions, and end +with a master menu for the whole manual. Of course you should include +any other general information you feel a reader would find helpful. + +

It is also conventional to write an @top sectioning command line +containing the title of the document immediately after the @node +Top line (see The @top Sectioning Command). + +

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 +@ifnottex and @end ifnottex commands. (TeX does not +print either an @node line or a menu; they appear only in Info; +strictly speaking, you are not required to enclose these parts between +@ifnottex and @end ifnottext, but it is simplest to do +so. See Conditionally Visible Text.) + +

+ +
+


+Next: , +Up: The Top Node +
+
+ +

3.6.1 Top Node Example

+ +

+Here is an example of a Top node. + +

     @ifnottex
+     @node Top
+     @top Sample Title
+     
+     @insertcopying
+     
+     Additional general information.
+     
+     @menu
+     * First Chapter::
+     * Second Chapter::
+     ...
+     * Index::
+     @end menu
+
+
+


+Previous: Top Node Example, +Up: The Top Node +
+
+ +

3.6.2 Parts of a Master Menu

+ +

+A master menu is a detailed main menu listing all the nodes in a +file. + +

A master menu is enclosed in @menu and @end menu +commands and does not appear in the printed document. + +

Generally, a master menu is divided into parts. + +

+ +

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 Writing a Menu, for more +information.) + +

For example, the master menu for this manual looks like the following +(but has many more entries): + +

     @menu
+     * Copying Conditions::  Your rights.
+     * Overview::            Texinfo in brief.
+     ...
+     * Command and Variable Index::
+     * Concept Index::
+     
+     @detailmenu
+     --- The Detailed Node Listing ---
+     
+     Overview of Texinfo
+     
+     * Reporting Bugs:: ...
+     ...
+     
+     Beginning a Texinfo File
+     
+     * Sample Beginning:: ...
+     ...
+     @end detailmenu
+     @end menu
+
+
+


+Next: , +Previous: The Top Node, +Up: Beginning a File +
+
+ +

3.7 Global Document Commands

+ +

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

+ +
+


+Next: , +Up: Global Document Commands +
+
+ +

3.7.1 @documentdescription: Summary Text

+ +

+When producing HTML output for a document, makeinfo writes a +<meta> element in the <head> to give some idea of the +content of the document. By default, this description is the title +of the document, taken from the @settitle command +(see settitle). To change this, use the @documentdescription +environment, as in: + +

     @documentdescription
+     descriptive text.
+     @end documentdescription
+
+

This will produce the following output in the <head> of the HTML: + +

     <meta name=description content="descriptive text.">
+
+

@documentdescription must be specified before the first node of +the document. + +

+


+Next: , +Previous: documentdescription, +Up: Global Document Commands +
+
+ +

3.7.2 @setchapternewpage:

+ +

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

You can use the @setchapternewpage command with various +arguments to specify how TeX should start chapters and whether it +should format headers for printing on one or both sides of the paper +(single-sided or double-sided printing). + +

Write the @setchapternewpage command at the beginning of a +line followed by its argument. + +

For example, you would write the following to cause each chapter to +start on a fresh odd-numbered page: + +

     @setchapternewpage odd
+
+

You can specify one of three alternatives with the +@setchapternewpage command: + +

+
@setchapternewpage off
Cause TeX to typeset a new chapter on the same page as the last +chapter, after skipping some vertical whitespace. Also, cause TeX to +format page headers for single-sided printing. + +
@setchapternewpage on
Cause TeX to start new chapters on new pages and to format page +headers for single-sided printing. This is the form most often used for +short reports or personal printing. This is the default. + +
@setchapternewpage odd
Cause TeX to start new chapters on new, odd-numbered pages +(right-handed pages) and to typeset for double-sided printing. This is +the form most often used for books and manuals. +
+ +

Texinfo does not have an @setchapternewpage even command, +because there is no printing tradition of starting chapters or books on +an even-numbered page. + +

If you don't like the default headers that @setchapternewpage +sets, you can explicit control them with the @headings command. +See The @headings Command. + +

At the beginning of a manual or book, pages are not numbered—for +example, the title and copyright pages of a book are not numbered. By +convention, table of contents and frontmatter pages are numbered with +roman numerals and not in sequence with the rest of the document. + +

Since an Info file does not have pages, the @setchapternewpage +command has no effect on it. + +

We recommend not including any @setchapternewpage 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 +--texinfo option to texi2dvi to specify the output +you want. + +

+


+Next: , +Previous: setchapternewpage, +Up: Global Document Commands +
+
+ +

3.7.3 @paragraphindent: Paragraph Indenting

+ +

+The Texinfo processors may insert whitespace at the beginning of the +first line of each paragraph, thereby indenting that paragraph. You can +use the @paragraphindent command to specify this indentation. +Write an @paragraphindent command at the beginning of a line +followed by either asis or a number: + +

     @paragraphindent indent
+
+

The indentation is according to the value of indent: + +

+
asis
Do not change the existing indentation (not implemented in TeX). + +
none
0
Omit all indentation. + +
n
Indent by n space characters in Info output, by n ems in +TeX. + +
+ +

The default value of indent is 3. @paragraphindent is +ignored for HTML output. + +

It is best to write the @paragraphindent command before the +end-of-header line at the beginning of a Texinfo file, so the region +formatting commands indent paragraphs as specified. See Start of Header. + +

A peculiarity of the texinfo-format-buffer and +texinfo-format-region commands is that they do not indent (nor +fill) paragraphs that contain @w or @* commands. + +

+


+Next: , +Previous: paragraphindent, +Up: Global Document Commands +
+
+ +

3.7.4 @firstparagraphindent: Indenting After Headings

+ +

+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 +@firstparagraphindent command: + +

     @firstparagraphindent word
+
+

The first paragraph after a heading is indented according to the value +of word: + +

+
none
Prevents the first paragraph from being indented (default). +This option is ignored by makeinfo if +@paragraphindent asis is in effect. + +
insert
Include normal paragraph indentation. This respects the paragraph +indentation set by a @paragraphindent command +(see paragraphindent). +
+ +

For HTML and XML output, the @firstparagraphindent setting is +ignored. + +

It is best to write the @paragraphindent command before the +end-of-header line at the beginning of a Texinfo file, so the region +formatting commands indent paragraphs as specified. See Start of Header. + +

+


+Previous: firstparagraphindent, +Up: Global Document Commands +
+
+ +

3.7.5 @exampleindent: Environment Indenting

+ +

+The Texinfo processors indent each line of @example and similar +environments. You can use the @exampleindent command to specify +this indentation. Write an @exampleindent command at the +beginning of a line followed by either asis or a number: + +

     @exampleindent indent
+
+

The indentation is according to the value of indent: + +

+
asis
Do not change the existing indentation (not implemented in TeX). + +
0
Omit all indentation. + +
n
Indent environments by n space characters in Info output, by +n ems in TeX. + +
+ +

The default value of indent is 5. @exampleindent is +ignored for HTML output. + +

It is best to write the @exampleindent command before the +end-of-header line at the beginning of a Texinfo file, so the region +formatting commands indent paragraphs as specified. See Start of Header. + +

+


+Previous: Global Document Commands, +Up: Beginning a File +
+
+ +

3.8 Software Copying Permissions

+ +

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

The copying and distribution information and the disclaimer are followed +by an introduction or else by the first chapter of the manual. + +

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

+


+Next: , +Previous: Beginning a File, +Up: Top +
+
+ +

4 Ending a Texinfo File

+ +

+The end of a Texinfo file should include commands to create indices, +and the @bye command to mark the last line to be processed. + +

For example: + +

     @node Index
+     @unnumbered Index
+     
+     @printindex cp
+     
+     @bye
+
+ + +
+


+Next: , +Up: Ending a File +
+
+ +

4.1 Printing Indices and Menus

+ +

+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 @cindex +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 @printindex 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 +texindex (see Hardcopy) to sort the raw data to produce a +sorted index file. The sorted index file is what is actually used to +print the index. + +

Texinfo offers six separate types of predefined index, which suffice +in most cases. See Indices, for information on this, as well +defining your own new indices, combining indices, and, most +importantly advice on writing the actual index entries. This section +focuses on printing indices, which is done with the +@printindex command. + +

@printindex takes one argument, a two-letter index +abbreviation. It reads the corresponding sorted index file (for +printed output), and formats it appropriately into an index. + +

The @printindex command does not generate a chapter heading +for the index, since different manuals have different needs. +Consequently, you should precede the @printindex command with +a suitable section or chapter command (usually @appendix or +@unnumbered) to supply the chapter heading and put the index +into the table of contents. Precede the chapter heading with an +@node line as usual. + +

For example: + +

     @node Variable Index
+     @unnumbered Variable Index
+     
+     @printindex vr
+     
+     @node Concept Index
+     @unnumbered Concept Index
+     
+     @printindex cp
+
+

If you have more than one index, we recommend placing the concept index last. + +

+ +

It's not possible to generate an index when writing to standard +output; makeinfo generates a warning in this case. + +

+


+Previous: Printing Indices & Menus, +Up: Ending a File +
+
+ +

4.2 @bye File Ending

+ +

+An @bye command terminates Texinfo processing. None of the +formatters read anything following @bye. The @bye +command should be on a line by itself. + +

If you wish, you may follow the @bye 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 @bye were within +@ignore ... @end ignore. Also, you may follow the +@bye line with a local variables list for Emacs. +See Using Local Variables and the Compile Command, +for more information. + +

+


+Next: , +Previous: Ending a File, +Up: Top +
+
+ +

5 Chapter Structuring

+ +

+The chapter structuring 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 Generating a Table of Contents). + +

The chapter structuring commands do not create an Info node structure, +so normally you should put an @node command immediately before +each chapter structuring command (see Nodes). 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. + +

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

+ +
+


+Next: , +Up: Structuring +
+
+ +

5.1 Tree Structure of Sections

+ +

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

Here is a diagram that shows a Texinfo file with three chapters, +each of which has two sections. + +

                              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
+
+

In a Texinfo file that has this structure, the beginning of Chapter 2 +looks like this: + +

     @node    Chapter 2,  Chapter 3, Chapter 1, top
+     @chapter Chapter 2
+
+

The chapter structuring commands are described in the sections that +follow; the @node and @menu commands are described in +following chapters. (See Nodes, and see Menus.) + +

+


+Next: , +Previous: Tree Structuring, +Up: Structuring +
+
+ +

5.2 Structuring Command Types

+ +

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

The four groups are the @chapter series, the +@unnumbered series, the @appendix series, and the +@heading series. + +

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

+ +

Here are the four groups of chapter structuring commands: + +

No new page +
Numbered Unnumbered Lettered/numbered Unnumbered +
In contents In contents In contents Not in contents +
@top @majorheading +
@chapter @unnumbered @appendix @chapheading +
@section @unnumberedsec @appendixsec @heading +
@subsection @unnumberedsubsec @appendixsubsec @subheading +
@subsubsection @unnumberedsubsubsec @appendixsubsubsec @subsubheading +
+ +

+


+Next: , +Previous: Structuring Command Types, +Up: Structuring +
+
+ +

5.3 @top

+ +

The @top command is a special sectioning command that you use +only after an @node Top line at the beginning of a Texinfo file. +The @top command tells the makeinfo formatter which node +is the `Top' node, so it can use it as the root of the node tree if your +manual uses implicit node pointers. It has the same typesetting effect as +@unnumbered (see @unnumbered and @appendix). For detailed information, see The @top Command. + +

The @top node and its menu (if any) is conventionally wrapped in +an @ifnottex conditional so that it will appear only in Info and +HTML output, not TeX. + +

+


+Next: , +Previous: makeinfo top, +Up: Structuring +
+
+ + +

5.4 @chapter

+ +

+@chapter 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. + +

For example, this chapter in this manual is entitled “Chapter +Structuring”; the @chapter line looks like this: + +

     @chapter Chapter Structuring
+
+

In TeX, the @chapter command creates a chapter in the +document, specifying the chapter title. The chapter is numbered +automatically. + +

In Info, the @chapter 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: + +

     Chapter Structuring
+     *******************
+
+

Texinfo also provides a command @centerchap, which is analogous +to @unnumbered, but centers its argument in the printed output. +This kind of stylistic choice is not usually offered by Texinfo. + + +

+


+Next: , +Previous: chapter, +Up: Structuring +
+
+ +

5.5 @unnumbered and @appendix

+ +

+Use the @unnumbered command to create a chapter that appears +in a printed manual without chapter numbers of any kind. Use the +@appendix command to create an appendix in a printed manual +that is labelled by letter instead of by number. + +

For Info file output, the @unnumbered and @appendix +commands are equivalent to @chapter: the title is printed on a +line by itself with a line of asterisks underneath. (See @chapter.) + +

To create an appendix or an unnumbered chapter, write an +@appendix or @unnumbered 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. + +

+


+Next: , +Previous: unnumbered & appendix, +Up: Structuring +
+
+ +

5.6 @majorheading, @chapheading

+ +

+The @majorheading and @chapheading commands put +chapter-like headings in the body of a document. + +

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

In TeX, an @majorheading command generates a larger vertical +whitespace before the heading than an @chapheading command but +is otherwise the same. + +

In Info, +the @majorheading and +@chapheading commands are equivalent to +@chapter: the title is printed on a line by itself with a line +of asterisks underneath. (See @chapter.) + +

+


+Next: , +Previous: majorheading & chapheading, +Up: Structuring +
+
+ + +

5.7 @section

+ +

+In a printed manual, an @section command identifies a +numbered section within a chapter. The section title appears in the +table of contents. In Info, an @section command provides a +title for a segment of text, underlined with =. + +

This section is headed with an @section command and looks like +this in the Texinfo file: + +

     @section @code{@@section}
+
+

To create a section, write the @section command at the +beginning of a line and follow it on the same line by the section +title. + +

Thus, + +

     @section This is a section
+
+

produces + +

     This is a section
+     =================
+
+

in Info. + +

+


+Next: , +Previous: section, +Up: Structuring +
+
+ + +

5.8 @unnumberedsec, @appendixsec, @heading

+ +

+The @unnumberedsec, @appendixsec, and @heading +commands are, respectively, the unnumbered, appendix-like, and +heading-like equivalents of the @section command. +(See @section.) + +

+
@unnumberedsec
The @unnumberedsec command may be used within an +unnumbered chapter or within a regular chapter or appendix to +provide an unnumbered section. + +
@appendixsec
@appendixsection
@appendixsection is a longer spelling of the +@appendixsec command; the two are synonymous. + +Conventionally, the @appendixsec or @appendixsection +command is used only within appendices. + +
@heading
You may use the @heading command anywhere you wish for a +section-style heading that will not appear in the table of contents. +
+ +
+


+Next: , +Previous: unnumberedsec appendixsec heading, +Up: Structuring +
+
+ + +

5.9 The @subsection Command

+ +

+Subsections are to sections as sections are to chapters. +(See @section.) In Info, subsection titles are +underlined with -. For example, + +

     @subsection This is a subsection
+
+

produces + +

     This is a subsection
+     --------------------
+
+

In a printed manual, subsections are listed in the table of contents +and are numbered three levels deep. + +

+


+Next: , +Previous: subsection, +Up: Structuring +
+
+ + +

5.10 The @subsection-like Commands

+ +

+The @unnumberedsubsec, @appendixsubsec, and +@subheading commands are, respectively, the unnumbered, +appendix-like, and heading-like equivalents of the @subsection +command. (See @subsection.) + +

In Info, the @subsection-like commands generate a title +underlined with hyphens. In a printed manual, an @subheading +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 @unnumberedsubsec command produces an unnumbered heading like +that of a subsection and an @appendixsubsec 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. + +

+


+Next: , +Previous: unnumberedsubsec appendixsubsec subheading, +Up: Structuring +
+
+ +

5.11 The `subsub' Commands

+ +

+The fourth and lowest level sectioning commands in Texinfo are the +`subsub' commands. They are: + +

+
@subsubsection
Subsubsections are to subsections as subsections are to sections. +(See @subsection.) In a printed manual, +subsubsection titles appear in the table of contents and are numbered +four levels deep. + +
@unnumberedsubsubsec
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. + +
@appendixsubsubsec
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. + +
@subsubheading
The @subsubheading 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. +
+ +

In Info, `subsub' titles are underlined with periods. +For example, + +

     @subsubsection This is a subsubsection
+
+

produces + +

     This is a subsubsection
+     .......................
+
+
+


+Previous: subsubsection, +Up: Structuring +
+
+ +

5.12 @raisesections and @lowersections

+ +

+The @raisesections and @lowersections commands +implicitly raise and lower the hierarchical level of following +chapters, sections and the other sectioning commands. + +

That is, the @raisesections command changes sections to +chapters, subsections to sections, and so on. Conversely, the +@lowersections command changes chapters to sections, sections +to subsections, and so on. Thus, an @lowersections command +cancels an @raisesections command, and vice versa. + +

You can use @lowersections to include text written as an outer +or standalone Texinfo file in another Texinfo file as an inner, +included file. Typical usage looks like this: + +

     @lowersections
+     @include somefile.texi
+     @raisesections
+
+

(Without the @raisesections, all the subsequent +sections in the document would be lowered.) + +

If the included file being lowered has a @top node, you'll +need to conditionalize its inclusion with a flag (see set value). + +

Another difficulty can arise with documents that use the (recommended) +feature of makeinfo for implicitly determining node +pointers. Since makeinfo must assume a hierarchically +organized document to determine the pointers, you cannot just +arbitrarily sprinkle @raisesections and @lowersections +commands in the document. The final result has to have menus that +take the raising and lowering into account. Therefore, as a practical +matter, you generally only want to raise or lower large chunks, +usually in external files as shown above. + +

Repeated use of the commands continue to raise or lower the +hierarchical level a step at a time. An attempt to raise above +`chapter' reproduces chapter commands; an attempt to lower below +`subsubsection' reproduces subsubsection commands. Also, lowered +subsubsections and raised chapters will not work with +makeinfo's feature of implicitly determining node pointers, +since the menu structure won't be correct. + +

Write each @raisesections and @lowersections command +on a line of its own. + +

+


+Next: , +Previous: Structuring, +Up: Top +
+
+ +

6 Nodes

+ +

Nodes 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 node pointers that name +other nodes, and can contain menus which are lists of nodes. In +Info, the movement commands can carry you to a pointed-to node or to a +node listed in a menu. + +

Node pointers and menus provide structure for Info files just as +chapters, sections, subsections, and the like, provide structure for +printed books. + +

Because node names are used in cross-references, it is not desirable +to casually change them. Such name changes invalidate references from +other manuals, from mail archives, and so on. + +

+ +
+


+Next: , +Up: Nodes +
+
+ +

6.1 Two Paths

+ +

The node and menu commands and the chapter structuring commands are +technically independent of each other: + +

+ +

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

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

+


+Next: , +Previous: Two Paths, +Up: Nodes +
+
+ +

6.2 Node and Menu Illustration

+ +

Here is a copy of the diagram shown earlier that illustrates a Texinfo +file with three chapters, each of which contains two sections. + +

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

                              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
+
+

The fully-written command to start Chapter 2 would be this: + +

     @node     Chapter 2,  Chapter 3, Chapter 1, Top
+     @comment  node-name,  next,      previous,  up
+
+

This @node 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 makeinfo Pointer Creation), but the +pointer relationships still obtain. + +

+Note: Please Note: `Next' refers to the next node at the same +hierarchical level in the manual, not necessarily to the next node +within the Texinfo file. In the Texinfo file, the subsequent node may +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 same 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.) +
+ +

To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter +2. (See Menus.) You would write the menu just +before the beginning of Section 2.1, like this: + +

        @menu
+        * Sect. 2.1::    Description of this section.
+        * Sect. 2.2::
+        @end menu
+
+

Write the node for Sect. 2.1 like this: + +

        @node     Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
+        @comment  node-name, next,      previous,  up
+
+

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 Cross References.) + +

Usually, an @node command and a chapter structuring command are +used in sequence, along with indexing commands. (You may follow the +@node line with a comment line that reminds you which pointer is +which.) + +

Here is the beginning of the chapter in this manual called “Ending a +Texinfo File”. This shows an @node line followed by a comment +line, an @chapter line, and then by indexing lines. + +

     @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
+
+
+


+Next: , +Previous: Node Menu Illustration, +Up: Nodes +
+
+ +

6.3 The @node Command

+ +

+A node is a segment of text that begins at an @node +command and continues until the next @node 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 @node command in the file. A node usually +contains only one chapter structuring command, the one that follows +the @node 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. + +

To create a node, write an @node command at the beginning of a +line, and follow it with up to four arguments, separated by commas, on +the rest of the same line. The first argument is required; it is the +name of this node. The subsequent arguments are the names of the +`Next', `Previous', and `Up' pointers, in that order, and may be omitted +if your Texinfo document is hierarchically organized (see makeinfo Pointer Creation). + +

You may insert spaces before each name if you wish; the spaces are +ignored. You must write the name of the node and (if present) the names +of the `Next', `Previous', and `Up' pointers all on the same line. +Otherwise, the formatters fail. (see info, for more +information about nodes in Info.) + +

Usually, you write one of the chapter-structuring command lines +immediately after an @node line—for example, an +@section or @subsection line. (See Structuring Command Types.) + +

+Note: The GNU Emacs Texinfo mode updating commands work +only with Texinfo files in which @node lines are followed by chapter +structuring lines. See Updating Requirements. +
+ +

TeX uses @node lines to identify the names to use for cross +references. For this reason, you must write @node 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 @xref and related commands; +see Cross References.) + +

+ +
+


+Next: , +Up: node +
+
+ +

6.3.1 Choosing Node and Pointer Names

+ +

The name of a node identifies the node. The pointers enable +you to reach other nodes and consist simply of the names of those nodes. + +

Normally, a node's `Up' pointer contains the name of the node whose menu +mentions that node. The node's `Next' pointer contains the name of the +node that follows that node in that menu and its `Previous' pointer +contains the name of the node that precedes it in that menu. When a +node's `Previous' node is the same as its `Up' node, both node pointers +name the same node. + +

Usually, the first node of a Texinfo file is the `Top' node, and its +`Up' and `Previous' pointers point to the dir file, which +contains the main menu for all of Info. + +

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 First Node, for information on how to write the +first node of a Texinfo file. + +

Even when you explicitly specify all pointers, that does not mean you +can write the nodes in the Texinfo source file in an arbitrary order! +Because TeX processes the file sequentially, irrespective of node +pointers, you must write the nodes in the order you wish them to appear +in the printed output. + +

+


+Next: , +Previous: Node Names, +Up: node +
+
+ +

6.3.2 How to Write an @node Line

+ +

+The easiest way to write an @node line is to write @node +at the beginning of a line and then the name of the node, like +this: + +

     @node node-name
+
+

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 makeinfo +insert node pointers into the Info file it creates. (See Texinfo Mode, and makeinfo Pointer Creation.) + +

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 C-c C-c n. This command inserts +@node 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. + +

The template for a fully-written-out node line with `Next', `Previous', +and `Up' pointers looks like this: + +

     @node node-name, next, previous, up
+
+

If you wish, you can ignore @node lines altogether in your first +draft and then use the texinfo-insert-node-lines command to +create @node 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. + +

After you have inserted an @node 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. + +

+


+Next: , +Previous: Writing a Node, +Up: node +
+
+ +

6.3.3 @node Line Tips

+ +

Here are three suggestions: + +

+ +
+


+Next: , +Previous: Node Line Tips, +Up: node +
+
+ +

6.3.4 @node Line Requirements

+ +

Here are several requirements for @node lines: + + + + +

+ +
+


+Next: , +Previous: Node Line Requirements, +Up: node +
+
+ +

6.3.5 The First Node

+ +

+The first node of a Texinfo file is the Top node, except in an +included file (see Include Files). The Top node should contain a +short summary, copying permissions, and a master menu. See The Top Node, for more information on the Top node contents and examples. + +

Here is a description of the node pointers to be used in the Top node: + +

+ +

See Installing an Info File, for more information about installing +an Info file in the info directory. + +

For concreteness, here is an example with explicit pointers (which you +can maintain automatically with the texinfo mode commands): + +

Or you can leave the pointers off entirely and let the tools implicitly +define them. This is recommended. Thus: + +

     @node Top
+
+
+


+Previous: First Node, +Up: node +
+
+ +

6.3.6 The @top Sectioning Command

+ +

+A special sectioning command, @top should be used with the +@node Top line. The @top sectioning command tells +makeinfo that it marks the `Top' node in the file. It provides +the information that makeinfo needs to insert node pointers +automatically. Write the @top command at the beginning of the +line immediately following the @node Top line. Write the title +on the remaining part of the same line as the @top command. + +

In Info, the @top sectioning command causes the title to appear +on a line by itself, with a line of asterisks inserted underneath, as +other sectioning commands do. + +

In TeX and texinfo-format-buffer, the @top +sectioning command is merely a synonym for @unnumbered. +Neither of these formatters require an @top command, and do +nothing special with it. You can use @chapter or +@unnumbered after the @node Top line when you use +these formatters. Also, you can use @chapter or +@unnumbered when you use the Texinfo updating commands to +create or update pointers and menus. + +

Thus, in practice, a Top node starts like this: + +

     @node Top
+     @top Your Manual Title
+
+
+


+Next: , +Previous: node, +Up: Nodes +
+
+ +

6.4 Creating Pointers with makeinfo

+ +

+The makeinfo program has a feature for automatically determining +node pointers for a hierarchically organized document. + +

When you take advantage of this feature, you do not need to write the +`Next', `Previous', and `Up' pointers after the name of a node. +However, you must write a sectioning command, such as @chapter +or @section, on the line immediately following each truncated +@node line (except that comment lines may intervene). + +

In addition, you must follow the `Top' @node line with a line +beginning with @top to mark the `Top' node in the +file. See @top. + +

Finally, you must write the name of each node (except for the `Top' +node) in a menu that is one or more hierarchical levels above the +node's hierarchical level. + +

This implicit node pointer insertion feature in makeinfo +relieves you from the need to update menus and pointers manually or +with Texinfo mode commands. (See Updating Nodes and Menus.) + +

In most cases, you will want to take advantage of this feature and not +redundantly specify node pointers. However, Texinfo documents are not +required to be organized hierarchically or in fact 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 Menus) also disables this +feature, for that group of nodes. In those cases, you will need to +explicitly specify the pointers. + +

+


+Previous: makeinfo Pointer Creation, +Up: Nodes +
+
+ +

6.5 @anchor: Defining Arbitrary Cross-reference Targets

+ +

+An anchor 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 @anchor command, and give the label as a +normal brace-delimited argument. For example: + +

     This marks the @anchor{x-spot}spot.
+     ...
+     @xref{x-spot,,the spot}.
+
+

produces: + +

     This marks the spot.
+     ...
+     See [the spot], page 1.
+
+

As you can see, the @anchor 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 @xref or other cross-reference +command, as shown. See Cross References, for details on the +cross-reference commands. + +

It is best to put @anchor 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 @anchor +command on a line by itself if that helps readability of the source. +Spaces are always ignored after @anchor. + +

Anchor names and node names may not conflict. Anchors and nodes are +given similar treatment in some ways; for example, the goto-node +command in standalone Info takes either an anchor name or a node name as +an argument. (See goto-node (GNU Info).) + +

+


+Next: , +Previous: Nodes, +Up: Top +
+
+ +

7 Menus

+ +

+Menus contain pointers to subordinate nodes. In online output, +you use menus to go to such nodes. Menus have no effect in printed +manuals and do not appear in them. + +

A node with a menu should not contain much text. If you find yourself +writing a lot of before a menu, we generally recommend moving most of +the text into a new subnode—all but a paragraph or two. Otherwise, +a reader with a terminal that displays only a few lines may miss the +menu and its associated text. As a practical matter, it is best to +locate a menu within 20 or so lines of the beginning of the node. + +

+ +
+


+Next: , +Up: Menus +
+
+ +

7.1 Menu Location

+ +

+A menu must be located at the end of a node, without any regular text +or additional commands between the @end menu and the beginning +of the next node. (As a consequence, there may be at most one menu in +a node.) + +

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

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 +makeinfo implicit pointer creation feature (see makeinfo Pointer Creation) and GNU Emacs Texinfo mode updating commands work +only to create menus of subordinate nodes in a hierarchically +structured document. Instead, use cross references to refer to +arbitrary nodes. + +

In the past, we recommended using a @heading command within an +@ifinfo conditional instead of the normal sectioning commands +after a very short node with a menu. This had the advantage of making +the printed output look better, because there was no very short text +between two headings on the page. But aside from not working with +makeinfo's implicit pointer creation, it also makes the XML +output incorrect, since it does not reflect the true document +structure. So, unfortunately we can no longer recommend this. + +

+


+Next: , +Previous: Menu Location, +Up: Menus +
+
+ +

7.2 Writing a Menu

+ +

+A menu consists of an @menu command on a line by itself +followed by menu entry lines or menu comment lines and then by an +@end menu command on a line by itself. + +

A menu looks like this: + +

     @menu
+     Larger Units of Text
+     
+     * Files::                       All about handling files.
+     * Multiples: Buffers.           Multiple buffers; editing
+                                      several files at once.
+     @end menu
+
+

In a menu, every line that begins with an is a menu +entry. (Note the space after the asterisk.) A line that does not +start with an 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 Larger Units of Text is a +menu comment line; the two lines starting with are menu +entries. Space characters in a menu are preserved as-is; this allows +you to format the menu as you wish. + +

+


+Next: , +Previous: Writing a Menu, +Up: Menus +
+
+ +

7.3 The Parts of a Menu

+ +

+A menu entry has three parts, only the second of which is required: + +

    +
  1. The menu entry name (optional). + +
  2. The name of the node (required). + +
  3. A description of the item (optional). +
+ +

The template for a menu entry looks like this: + +

     * menu-entry-name: node-name.   description
+
+

Follow the menu entry name with a single colon and follow the node name +with tab, comma, period, or newline. + +

In Info, a user selects a node with the m (Info-menu) +command. The menu entry name is what the user types after the m +command. + +

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

+


+Next: , +Previous: Menu Parts, +Up: Menus +
+
+ + +

7.4 Less Cluttered Menu Entry

+ +

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

For example, write + +

     * Name::                                    description
+
+

instead of + +

     * Name: Name.                               description
+
+

You should use the node name for the menu entry name whenever possible, +since it reduces visual clutter in the menu. + +

+


+Next: , +Previous: Less Cluttered Menu Entry, +Up: Menus +
+
+ + +

7.5 A Menu Example

+ +

+A menu looks like this in Texinfo: + +

     @menu
+     * menu entry name: Node name.   A short description.
+     * Node name::                   This form is preferred.
+     @end menu
+
+

This produces: + +

     * menu:
+     
+     * menu entry name: Node name.   A short description.
+     * Node name::                   This form is preferred.
+
+

Here is an example as you might see it in a Texinfo file: + +

     @menu
+     Larger Units of Text
+     
+     * Files::                       All about handling files.
+     * Multiples: Buffers.           Multiple buffers; editing
+                                      several files at once.
+     @end menu
+
+

This produces: + +

     * menu:
+     Larger Units of Text
+     
+     * Files::                       All about handling files.
+     * Multiples: Buffers.           Multiple buffers; editing
+                                      several files at once.
+
+

In this example, the menu has two entries. Files is both a menu +entry name and the name of the node referred to by that name. +Multiples is the menu entry name; it refers to the node named +Buffers. The line Larger Units of Text is a comment; it +appears in the menu, but is not an entry. + +

Since no file name is specified with either Files or +Buffers, they must be the names of nodes in the same Info file +(see Referring to Other Info Files). + +

+


+Previous: Menu Example, +Up: Menus +
+
+ + +

7.6 Referring to Other Info Files

+ +

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

The format looks like this: + +

     @menu
+     * first-entry-name:(filename)nodename.     description
+     * second-entry-name:(filename)second-node. description
+     @end menu
+
+

For example, to refer directly to the Outlining and +Rebinding nodes in the Emacs Manual, you would write a +menu like this: + +

     @menu
+     * Outlining: (emacs)Outline Mode. The major mode for
+                                      editing outlines.
+     * Rebinding: (emacs)Rebinding.    How to redefine the
+                                      meaning of a key.
+     @end menu
+
+

If you do not list the node name, but only name the file, then Info +presumes that you are referring to the `Top' node. + +

The dir file that contains the main menu for Info has menu +entries that list only file names. These take you directly to the `Top' +nodes of each Info document. (See Installing an Info File.) + +

For example: + +

     * Info: (info).         Documentation browsing system.
+     * Emacs: (emacs).       The extensible, self-documenting
+                            text editor.
+
+

(The dir 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.) + +

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

+


+Next: , +Previous: Menus, +Up: Top +
+
+ +

8 Cross References

+ +

+Cross references 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. + +

+ +
+


+Next: , +Up: Cross References +
+
+ +

8.1 What References Are For

+ +

Often, but not always, a printed document should be designed so that +it can be read sequentially. People tire of flipping back and forth +to find information that should be presented to them as they need +it. + +

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

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

In Info, a cross reference results in an entry that you can follow +using the Info f command. (see Following cross-references.) + +

The various cross reference commands use nodes (or anchors, +see @anchor) 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 +@node lines to name the places to which you make cross +references. + +

+


+Next: , +Previous: References, +Up: Cross References +
+
+ + +

8.2 Different Cross Reference Commands

+ +

+There are four different cross reference commands: + +

+
@xref
Used to start a sentence in the printed manual saying `See ...' +or an Info cross-reference saying *Note name: node.. + +
@ref
Used within or, more often, at the end of a sentence; same as +@xref for Info; produces just the reference in the printed +manual without a preceding `See'. + +
@pxref
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. (p is for `parenthesis'.) + +
@inforef
Used to make a reference to an Info file for which there is no printed +manual. +
+ +

(The @cite 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 @cite.) + +

+


+Next: , +Previous: Cross Reference Commands, +Up: Cross References +
+
+ + +

8.3 Parts of a Cross Reference

+ +

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

Here is a simple cross reference example: + +

     @xref{Node name}.
+
+

which produces + +

     *Note Node name::.
+
+

and + +

+See Section nnn [Node name], page ppp. +
+ +

Here is an example of a full five-part cross reference: + +

     @xref{Node name, Cross Reference Name, Particular Topic,
+     info-file-name, A Printed Manual}, for details.
+
+

which produces + +

     *Note Cross Reference Name: (info-file-name)Node name,
+     for details.
+
+

in Info and + +

+See section “Particular Topic” in A Printed Manual, for details. +
+ +

in a printed book. + +

The five possible arguments for a cross reference are: + +

    +
  1. 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. + +
  2. The cross reference name for the Info reference, if it is to be different +from the node name. If you include this argument, it becomes +the first part of the cross reference. It is usually omitted. + +
  3. 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. + +
  4. 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 .info +suffix on the file name, since Info readers try appending it +automatically. + +
  5. The name of a printed manual from a different Texinfo file. +
+ +

The template for a full five argument cross reference looks like +this: + +

     @xref{node-name, cross-reference-name, title-or-topic,
+     info-file-name, printed-manual-title}.
+
+

Cross references with one, two, three, four, and five arguments are +described separately following the description of @xref. + +

Write a node name in a cross reference in exactly the same way as in +the @node line, including the same capitalization; otherwise, the +formatters may not find the reference. + +

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 @xref at the beginning of a sentence; write +@pxref only within parentheses, and so on. + +

+


+Next: , +Previous: Cross Reference Parts, +Up: Cross References +
+
+ + +

8.4 @xref

+ +

+The @xref 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 f 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. + +

+ +
+


+Next: , +Up: xref +
+
+ +

8.4.1 What a Reference Looks Like and Requires

+ +

Most often, an Info cross reference looks like this: + +

     *Note node-name::.
+
+

or like this + +

     *Note cross-reference-name: node-name.
+
+

In TeX, a cross reference looks like this: + +

+See Section section-number [node-name], page page. +
+ +

or like this + +

+See Section section-number [title-or-topic], page page. +
+ +

The @xref 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 @pxref command works +differently. See @pxref.) + +

+Caution: A period or comma must follow the closing +brace of an @xref. It is required to terminate the cross +reference. This period or comma will appear in the output, both in +the Info file and in the printed manual. +
+ +

@xref must refer to an Info node by name. Use @node +to define the node (see Writing a Node). + +

@xref is followed by several arguments inside braces, separated by +commas. Whitespace before and after these commas is ignored. + +

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

+Note: Commas separate arguments in a cross reference; +avoid including them in the title or other part lest the formatters +mistake them for separators. +
+ +
+


+Next: , +Previous: Reference Syntax, +Up: xref +
+
+ +

8.4.2 @xref with One Argument

+ +

The simplest form of @xref 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. + +

For example, + +

     @xref{Tropical Storms}.
+
+

produces + +

     *Note Tropical Storms::.
+
+

and + +

+See Section 3.1 [Tropical Storms], page 24. +
+ +

(Note that in the preceding example the closing brace is followed by a +period.) + +

You can write a clause after the cross reference, like this: + +

     @xref{Tropical Storms}, for more info.
+
+

which produces + +

     *Note Tropical Storms::, for more info.
+
+

and + +

+See Section 3.1 [Tropical Storms], page 24, for more info. +
+ +

(Note that in the preceding example the closing brace is followed by a +comma, and then by the clause, which is followed by a period.) + +

+


+Next: , +Previous: One Argument, +Up: xref +
+
+ +

8.4.3 @xref with Two Arguments

+ +

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

The template is like this: + +

     @xref{node-name, cross-reference-name}.
+
+

For example, + +

     @xref{Electrical Effects, Lightning}.
+
+

produces: + +

     *Note Lightning: Electrical Effects.
+
+

and + +

+See Section 5.2 [Electrical Effects], page 57. +
+ +

(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.) + +

You can write a clause after the cross reference, like this: + +

     @xref{Electrical Effects, Lightning}, for more info.
+
+

which produces +

     *Note Lightning: Electrical Effects, for more info.
+
+

and + +

+See Section 5.2 [Electrical Effects], page 57, for more info. +
+ +

(Note that in the preceding example the closing brace is followed by a +comma, and then by the clause, which is followed by a period.) + +

+


+Next: , +Previous: Two Arguments, +Up: xref +
+
+ +

8.4.4 @xref with Three Arguments

+ +

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

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

Also, remember to write a comma or period after the closing brace of an +@xref to terminate the cross reference. In the following +examples, a clause follows a terminating comma. + +

The template is like this: + +

     @xref{node-name, cross-reference-name, title-or-topic}.
+
+

For example, + +

     @xref{Electrical Effects, Lightning, Thunder and Lightning},
+     for details.
+
+

produces + +

     *Note Lightning: Electrical Effects, for details.
+
+

and + +

+See Section 5.2 [Thunder and Lightning], page 57, for details. +
+ +

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

     @xref{Electrical Effects, , Thunder and Lightning},
+     for details.
+
+

produces + +

     *Note Thunder and Lightning: Electrical Effects, for details.
+
+

and + +

+See Section 5.2 [Thunder and Lightning], page 57, for details. +
+ +

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

Here are several examples from The GNU Awk User's Guide: + +

     @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}.
+
+
+


+Previous: Three Arguments, +Up: xref +
+
+ +

8.4.5 @xref with Four and Five Arguments

+ +

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

Remember that a comma or period must follow the closing brace of an +@xref command to terminate the cross reference. In the +following examples, a clause follows a terminating comma. + +

The template is: + +

     @xref{node-name, cross-reference-name, title-or-topic,
+     info-file-name, printed-manual-title}.
+
+

For example, + +

     @xref{Electrical Effects, Lightning, Thunder and Lightning,
+     weather, An Introduction to Meteorology}, for details.
+
+

produces + +

     *Note Lightning: (weather)Electrical Effects, for details.
+
+

The name of the Info file is enclosed in parentheses and precedes +the name of the node. + +

In a printed manual, the reference looks like this: + +

+See section “Thunder and Lightning” in An Introduction to +Meteorology, for details. +
+ +

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

Often, you will leave out the second argument when you use the long +version of @xref. In this case, the third argument, the topic +description, will be used as the cross reference name in Info. + +

The template looks like this: + +

     @xref{node-name, , title-or-topic, info-file-name,
+     printed-manual-title}, for details.
+
+

which produces + +

     *Note title-or-topic: (info-file-name)node-name, for details.
+
+

and + +

+See section title-or-topic in printed-manual-title, for details. +
+ +

For example, + +

     @xref{Electrical Effects, , Thunder and Lightning,
+     weather, An Introduction to Meteorology}, for details.
+
+

produces + +

     *Note Thunder and Lightning: (weather)Electrical Effects,
+     for details.
+
+

and + +

+See section “Thunder and Lightning” in An Introduction to +Meteorology, for details. +
+ +

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

+


+Next: , +Previous: xref, +Up: Cross References +
+
+ +

8.5 Naming a `Top' Node

+ +

+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 @xref command. (This +is different from the way you write a menu entry; see Referring to Other Info Files.) 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 @xref command. + +

Thus, to make a cross reference to The GNU Make Manual, +write: + +

     @xref{Top, , Overview, make, The GNU Make Manual}.
+
+

which produces + +

     *Note Overview: (make)Top.
+
+

and + +

+See section “Overview” in The GNU Make Manual. +
+ +

In this example, Top is the name of the first node, and +Overview is the name of the first section of the manual. + +

+


+Next: , +Previous: Top Node Naming, +Up: Cross References +
+
+ +

8.6 @ref

+ +

+@ref is nearly the same as @xref except that it does +not generate a `See' in the printed output, just the reference itself. +This makes it useful as the last part of a sentence. + +

For example, + +

+

     For more information, see @ref{Hurricanes}.
+
+

produces (in Info): + +

     For more information, see *Note Hurricanes::.
+
+

and (in printed output): + +

+For more information, see Section 8.2 [Hurricanes], page 123. +
+ +

The @ref command sometimes tempts writers to express +themselves in a manner that is suitable for a printed manual but looks +awkward in the Info format. Bear in mind that your audience will be +using both the printed and the Info format. For example: + +

+

     Sea surges are described in @ref{Hurricanes}.
+
+

looks ok in the printed output: + +

+Sea surges are described in Section 6.7 [Hurricanes], page 72. +
+ +

but is awkward to read in Info: + +

     Sea surges are described in *Note Hurricanes::.
+
+
+Caution: You should write a period or comma immediately after an @ref +command with two or more arguments. Otherwise, Info will generate a +(grammatically incorrect) period, just so the cross-reference doesn't +fail completely. +
+ +

As a general rule, you should write a period or comma after every +@ref command. This works best in both the printed and the +Info output. + +

+


+Next: , +Previous: ref, +Up: Cross References +
+
+ +

8.7 @pxref

+ +

+The parenthetical reference command, @pxref, is nearly the +same as @xref, but you use it only inside parentheses +and you do not type a comma or period after the command's +closing brace. The command differs from @xref in two +ways: + +

    +
  1. TeX typesets the reference for the printed manual with a lower case +`see' rather than an upper case `See'. + +
  2. The Info formatting commands automatically end the reference with a +closing colon or period. +
+ +

Because one type of formatting automatically inserts closing +punctuation and the other does not, you should use @pxref +only inside parentheses as part of another sentence. Also, you +yourself should not insert punctuation after the reference, as you do +with @xref. + +

@pxref is designed so that the output looks right and works +right between parentheses both in printed output and in an Info file. +In a printed manual, a closing comma or period should not follow a +cross reference within parentheses; such punctuation is wrong. But in +an Info file, suitable closing punctuation must follow the cross +reference so Info can recognize its end. @pxref spares you +the need to use complicated methods to put a terminator into one form +of the output and not the other. + +

With one argument, a parenthetical cross reference looks like +this: + +

+

     ... storms cause flooding (@pxref{Hurricanes}) ...
+
+

which produces + +

     ... storms cause flooding (*Note Hurricanes::) ...
+
+

and + +

+... storms cause flooding (see Section 6.7 [Hurricanes], page 72) ... +
+ +

With two arguments, a parenthetical cross reference has this +template: + +

     ... (@pxref{node-name, cross-reference-name}) ...
+
+

which produces + +

     ... (*Note cross-reference-name: node-name.) ...
+
+

and + +

+... (see Section nnn [node-name], page ppp) ... +
+ +

@pxref can be used with up to five arguments just like +@xref (see @xref). + +

+Caution: Use @pxref only as a parenthetical +reference. Do not try to use @pxref as a clause in a sentence. +It will look bad in either the Info file, the printed output, or +both. +
+ +

Parenthetical cross references look best at the ends of sentences. +Although they technically work in the middle of a sentence, that +location breaks up the flow of reading. + +

+


+Next: , +Previous: pxref, +Up: Cross References +
+
+ +

8.8 @inforef

+ +

+@inforef is used for cross references to Info files for which +there are no printed manuals. Even in a printed manual, +@inforef generates a reference directing the user to look in +an Info file. + +

The command takes either two or three arguments, in the following +order: + +

    +
  1. The node name. + +
  2. The cross reference name (optional). + +
  3. The Info file name. +
+ +

Separate the arguments with commas, as with @xref. Also, you +must terminate the reference with a comma or period after the +}, as you do with @xref. + +

The template is: + +

     @inforef{node-name, cross-reference-name, info-file-name},
+
+

Thus, + +

     @inforef{Advanced, Advanced Info commands, info},
+     for more information.
+
+

produces + +

     *Note Advanced Info commands: (info)Advanced,
+     for more information.
+
+

and + +

+See Info file info, node Advanced, for more information. +
+ +

Similarly, + +

     @inforef{Advanced, , info}, for more information.
+
+

produces + +

     *Note (info)Advanced::, for more information.
+
+

and + +

+See Info file info, node Advanced, for more information. +
+ +

The converse of @inforef is @cite, which is used to +refer to printed works for which no Info form exists. See @cite. + +

+


+Previous: inforef, +Up: Cross References +
+
+ +

8.9 @url, @uref{url[, text][, replacement]}

+ +

+@uref 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, @uref +produces a link you can follow. + +

@url is a synonym for @uref. Originally, @url +had the meaning of @indicateurl +(see @indicateurl), but in actual practice it +was misused the vast majority of the time. So we've changed the +definitions. + +

The second argument, if specified, is the text to display (the default +is the url itself); in Info and DVI output, but not in HTML output, the +url is also output. + +

The third argument, if specified, is the text to display, but in this +case the url is not 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. + +

If the url is long enough to cause problems with line breaking, you +may find it useful to insert @/ at places where a line break +would be acceptable (after / characters, for instance). This +tells TeX to allow (but not force) a line break at those places. +See Line Breaks. + +

Here is an example of the simple one argument form, where the url is +both the target and the text of the link: + +

     The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}.
+
+

produces: +

     The official GNU ftp site is ftp://ftp.gnu.org/gnu.
+
+

An example of the two-argument form: +

     The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site}
+     holds programs and texts.
+
+

produces: +

     The official GNU ftp site
+     holds programs and texts.
+
+

that is, the Info output is this: +

     The official GNU ftp site (ftp://ftp.gnu.org/gnu)
+     holds programs and texts.
+
+

and the HTML output is this: +

     The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a>
+     holds programs and texts.
+
+

An example of the three-argument form: +

     The @uref{/man.cgi/1/ls,,ls(1)} program ...
+
+

produces: +

     The ls(1) program ...
+
+

but with HTML: +

     The <a href="/man.cgi/1/ls">ls(1)</a> program ...
+
+

To merely indicate a url without creating a link people can follow, use +@indicateurl (see @indicateurl). + +

Some people prefer to display url's in the unambiguous format: + +

     <URL:http://host/path>
+
+

You can use this form in the input file if you wish. We feel it's not +necessary to include the <URL: and > in the output, +since any software that tries to detect url's in text already has to +detect them without the <URL: to be useful. + +

+


+Next: , +Previous: Cross References, +Up: Top +
+
+ +

9 Marking Words and Phrases

+ +

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

+ +
+


+Next: , +Up: Marking Text +
+
+ +

9.1 Indicating Definitions, Commands, etc.

+ +

+Texinfo has commands for indicating just what kind of object a piece of +text refers to. For example, metasyntactic variables are marked by +@var, and code by @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 intentional formatting language rather than a typesetting +formatting language.) + +

For example, in a printed manual, +code is usually illustrated in a typewriter font; +@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. + +

+ +
+


+Next: , +Up: Indicating +
+
+ +

9.1.1 Highlighting Commands are Useful

+ +

The highlighting commands can be used to extract useful information +from the file, such as lists of functions or file names. It is +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. + +

The commands serve a variety of purposes: + +

+
@code{sample-code}
Indicate text that is a literal example of a piece of a program. + +
@kbd{keyboard-characters}
Indicate keyboard input. + +
@key{key-name}
Indicate the conventional name for a key on a keyboard. + +
@samp{text}
Indicate text that is a literal example of a sequence of characters. + +
@var{metasyntactic-variable}
Indicate a metasyntactic variable. + +
@env{environment-variable}
Indicate an environment variable. + +
@file{file-name}
Indicate the name of a file. + +
@command{command-name}
Indicate the name of a command. + +
@option{option}
Indicate a command-line option. + +
@dfn{term}
Indicate the introductory or defining use of a term. + +
@cite{reference}
Indicate the name of a book. + +
@acronym{acronym}
Indicate an acronym. + +
@indicateurl{uniform-resource-locator}
Indicate a uniform resource locator for the World Wide Web. + +
@email{email-address[, displayed-text]}
Indicate an electronic mail address. + +
+ +
+


+Next: , +Previous: Useful Highlighting, +Up: Indicating +
+
+ +

9.1.2 @code{sample-code}

+ +

+Use the @code command to indicate text that is a piece of a +program and which consists of entire syntactic tokens. Enclose the +text in braces. + +

Thus, you should use @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. + +

Use @code for command names in languages that resemble +programming languages, such as Texinfo. For example, @code and +@samp are produced by writing @code{@@code} and +@code{@@samp} in the Texinfo source, respectively. + +

It is incorrect to alter the case of a word inside an @code +command when it appears at the beginning of a sentence. Most computer +languages are case sensitive. In C, for example, Printf is +different from the identifier printf, 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. + +

In the printed manual, @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, + +

     The function returns @code{nil}.
+
+

produces this in the printed manual: + +

+The function returns nil. +
+ +

Here are some cases for which it is preferable not to use @code: + +

+ +

Since @command, @option, and @env were +introduced relatively recently, it is acceptable to use @code or +@samp 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. + +

+


+Next: , +Previous: code, +Up: Indicating +
+
+ +

9.1.3 @kbd{keyboard-characters}

+ +

+Use the @kbd command for characters of input to be typed by +users. For example, to refer to the characters M-a, write: + +

     @kbd{M-a}
+
+

and to refer to the characters M-x shell, write: + +

     @kbd{M-x shell}
+
+

By default, the @kbd command produces a different font +(slanted typewriter instead of normal typewriter) in the printed +manual, so users can distinguish the characters that they are supposed +to type from those that the computer outputs. + +

In Info output, @kbd is usually the same as @code, +producing `quotes' around its argument. However, in typewriter-like +contexts such as the @example environment (see example) +and @code command itself, the quotes are omitted, since Info +format cannot use distinguishing fonts. + +

Since the usage of @kbd varies from manual to manual, you can +control the font switching with the @kbdinputstyle command. +This command has no effect on Info output. Write this command at the +beginning of a line with a single word as an argument, one of the +following: + +

+

+
code
Always use the same font for @kbd as @code. +
example
Use the distinguishing font for @kbd only in @example +and similar environments. +
distinct
(the default) Always use the distinguishing font for @kbd. +
+ +

You can embed another @-command inside the braces of an @kbd +command. Here, for example, is the way to describe a command that +would be described more verbosely as “press the r key and then +press the <RETURN> key”: + +

     @kbd{r @key{RET}}
+
+

This produces: r <RET>. (The present manual accepts the +default for @kbdinputstyle.) + +

You also use the @kbd command if you are spelling out the letters +you type; for example: + +

     To give the @code{logout} command,
+     type the characters @kbd{l o g o u t @key{RET}}.
+
+

This produces: + +

+To give the logout command, +type the characters l o g o u t <RET>. +
+ +

(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 @key{SPC} for it.) + +

+


+Next: , +Previous: kbd, +Up: Indicating +
+
+ + +

9.1.4 @key{key-name}

+ +

+Use the @key command for the conventional name for a key on a +keyboard, as in: + +

     @key{RET}
+
+

You can use the @key command within the argument of an +@kbd command when the sequence of characters to be typed +includes one or more keys that are described by name. + +

For example, to produce C-x <ESC> you would type: + +

     @kbd{C-x @key{ESC}}
+
+

Here is a list of the recommended names for keys: + +

+
+
SPC
Space +
RET
Return +
LFD
Linefeed (however, since most keyboards nowadays do not have a Linefeed key, +it might be better to call this character C-j. +
TAB
Tab +
BS
Backspace +
ESC
Escape +
DEL
Delete +
SHIFT
Shift +
CTRL
Control +
META
Meta +
+
+ +

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 Meta-a, use the @kbd command +alone; do not use the @key command; but when you are referring +to the modifier key in isolation, use the @key command. For +example, write @kbd{Meta-a} to produce Meta-a and +@key{META} to produce <META>. + + + + + + + +

+


+Next: , +Previous: key, +Up: Indicating +
+
+ +

9.1.5 @samp{text}

+ +

+Use the @samp 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. + +

     To match @samp{foo} at the end of the line,
+     use the regexp @samp{foo$}.
+
+

produces + +

+To match foo at the end of the line, use the regexp +foo$. +
+ +

Any time you are referring to single characters, you should use +@samp unless @kbd or @key is more appropriate. +Also, you may use @samp for entire statements in C and for entire +shell commands—in this case, @samp often looks better than +@code. Basically, @samp is a catchall for whatever is +not covered by @code, @kbd, or @key. + +

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: + +

     In English, the vowels are @samp{a}, @samp{e},
+     @samp{i}, @samp{o}, @samp{u}, and sometimes
+     @samp{y}.
+
+

This produces: + +

+In English, the vowels are a, e, +i, o, u, and sometimes +y. +
+ +
+


+Next: , +Previous: samp, +Up: Indicating +
+
+ +

9.1.6 @verb{<char>text<char>}

+ +

+Use the @verb command to print a verbatim sequence of +characters. + +

Like LaTeX's \verb command, the verbatim text can be quoted using +any unique delimiter character. Enclose the verbatim text, including the +delimiters, in braces. Text is printed in a fixed-width font: + +

     How many @verb{|@|}-escapes does one need to print this
+     @verb{.@a @b @c.} string or @verb{+@'e?`!`{}\+} this?
+
+

produces + +

     How many @-escapes does one need to print this
+     @a @b @c string or these @'e?`{}!`\ this?
+
+

This is in contrast to @samp (see the previous section), +@code, and similar commands; in those cases, the argument is +normal Texinfo text, where the three characters @{} are +special. With @verb, nothing is special except the delimiter +character you choose. + +

It is not reliable to use @verb inside other Texinfo constructs. + +

+


+Next: , +Previous: verb, +Up: Indicating +
+
+ +

9.1.7 @var{metasyntactic-variable}

+ +

+Use the @var command to indicate metasyntactic variables. A +metasyntactic variable 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. + +

Do not use @var for the names of particular variables in +programming languages. These are specific names from a program, so +@code is correct for them (see code). For example, the +Emacs Lisp variable texinfo-tex-command is not a metasyntactic +variable; it is properly formatted using @code. + +

Do not use @var for environment variables either; @env +is correct for them (see the next section). + +

The effect of @var 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. + +

For example, + +

     To delete file @var{filename},
+     type @samp{rm @var{filename}}.
+
+

produces + +

+To delete file filename, type rm filename. +
+ +

(Note that @var may appear inside @code, +@samp, @file, etc.) + +

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: + +

     \input texinfo
+     @@setfilename @var{info-file-name}
+     @@settitle @var{name-of-manual}
+
+

This produces: + +

     \input texinfo
+     @setfilename info-file-name
+     @settitle name-of-manual
+
+

In some documentation styles, metasyntactic variables are shown with +angle brackets, for example: + +

     ..., type rm <filename>
+
+

However, that is not the style that Texinfo uses. (You can, of +course, modify the sources to texinfo.tex and the Info formatting commands +to output the <...> format if you wish.) + +

+


+Next: , +Previous: var, +Up: Indicating +
+
+ +

9.1.8 @env{environment-variable}

+ +

+Use the @env command to indicate environment variables, as used +by many operating systems, including GNU. Do not use it for +metasyntactic variables; use @var instead (see the previous +section). + +

@env is equivalent to @code in its effects. +For example: + +

     The @env{PATH} environment variable ...
+
+

produces +

+The PATH environment variable ... +
+ +
+


+Next: , +Previous: env, +Up: Indicating +
+
+ +

9.1.9 @file{file-name}

+ +

+Use the @file 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 @file +for symbols in a programming language; use @code. + +

Currently, @file is equivalent to @samp in its effects. +For example, + +

     The @file{.el} files are in
+     the @file{/usr/local/emacs/lisp} directory.
+
+

produces + +

+The .el files are in +the /usr/local/emacs/lisp directory. +
+ +
+


+Next: , +Previous: file, +Up: Indicating +
+
+ +

9.1.10 @command{command-name}

+ +

+Use the @command command to indicate command names, such as +ls or cc. + +

@command is equivalent to @code in its effects. +For example: + +

     The command @command{ls} lists directory contents.
+
+

produces +

+The command ls lists directory contents. +
+ +

You should write the name of a program in the ordinary text font, rather +than using @command, if you regard it as a new English word, +such as `Emacs' or `Bison'. + +

When writing an entire shell command invocation, as in ls -l, +you should use either @samp or @code at your discretion. + +

+


+Next: , +Previous: command, +Up: Indicating +
+
+ +

9.1.11 @option{option-name}

+ +

+Use the @option command to indicate a command-line option; for +example, -l or --version or +--output=filename. + +

@option is equivalent to @samp in its effects. +For example: + +

     The option @option{-l} produces a long listing.
+
+

produces +

+The option -l produces a long listing. +
+ +

In tables, putting options inside @code produces a +more pleasing effect. + +

+


+Next: , +Previous: option, +Up: Indicating +
+
+ + +

9.1.12 @dfn{term}

+ +

+Use the @dfn 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 @dfn. The command generates italics in +the printed manual, and double quotation marks in the Info file. For +example: + +

     Getting rid of a file is called @dfn{deleting} it.
+
+

produces + +

+Getting rid of a file is called deleting it. +
+ +

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

+


+Next: , +Previous: dfn, +Up: Indicating +
+
+ +

9.1.13 @cite{reference}

+ +

+Use the @cite 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. + +

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 @xref. + +

+


+Next: , +Previous: cite, +Up: Indicating +
+
+ +

9.1.14 @acronym{acronym[, meaning]}

+ +

+Use the @acronym command for abbreviations written in all +capital letters, such as `NASA'. The abbreviation is given as +the single argument in braces, as in @acronym{NASA}. As +a matter of style, or for particular abbreviations, you may prefer to +use periods, as in @acronym{F.B.I.}. + +

If the acronym is at the end of a sentence, remember to use the +special @. and similar commands (see Ending a Sentence). + +

In TeX, the acronym is printed in slightly smaller font. In the +Info output, the argument is printed as-is. In HTML, Docbook, and +XML, the <acronym> tag is used. + +

@acronym accepts an optional second argument, intended to be +used for the meaning of the acronym. If present, it is printed in +parentheses after the acronym. For instance (since GNU is a recursive +acronym, we use @acronym recursively): + +

     @acronym{GNU, @acronym{GNU}'s Not Unix}
+
+

produces: + +

     GNU (@acronym{GNU}'s Not Unix)
+
+

In some circumstances, it is conventional to print family names in all +capitals. Don't use @acronym for this, since a name is not an +acronym. Use @sc instead (see Smallcaps). + +

+


+Next: , +Previous: acronym, +Up: Indicating +
+
+ +

9.1.15 @indicateurl{uniform-resource-locator}

+ +

+Use the @indicateurl command to indicate a uniform resource +locator on the World Wide Web. This is analogous to @file, +@var, etc., and is purely for markup purposes. It does not +produce a link you can follow in HTML output (use the @uref +command for that, see @uref). It is useful for +url's which do not actually exist. For example: + +

     For example, the url might be @indicateurl{http://example.org/path}.
+
+

which produces: + +

     For example, the url might be <http://example.org/path>.
+
+
+


+Previous: indicateurl, +Up: Indicating +
+
+ +

9.1.16 @email{email-address[, displayed-text]}

+ +

+Use the @email command to indicate an electronic mail address. +It takes one mandatory argument, the address, and one optional argument, the +text to display (the default is the address itself). + +

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, @email produces a mailto link that usually +brings up a mail composition window. For example: + +

     Send bug reports to @email{bug-texinfo@@gnu.org},
+     suggestions to the @email{bug-texinfo@@gnu.org, same place}.
+
+

produces +

     Send bug reports to bug-texinfo@gnu.org,
+     suggestions to the same place.
+
+
+


+Previous: Indicating, +Up: Marking Text +
+
+ + +

9.2 Emphasizing Text

+ +

+Usually, Texinfo changes the font to mark words in the text according to +what category the words belong to; an example is the @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 @r command, has any regular use. + +

+ +
+


+Next: , +Up: Emphasis +
+
+ +

9.2.1 @emph{text} and @strong{text}

+ +

+The @emph and @strong commands are for emphasis; +@strong is stronger. In printed output, @emph produces +italics and @strong produces bold. + +

For example, + +

     @strong{Caution:} @samp{rm * .[^.]*}
+     removes @emph{all} files in the directory.
+
+

produces the following in printed output and HTML: + +

+Caution: rm * .[^.]* +removes all files in the directory. +
+ +

and the following in Info: + +

     *Caution:* `rm * .[^.]*' removes _all_
+     files in the directory.
+
+

The @strong command is seldom used except to mark what is, in +effect, a typographical element, such as the word `Caution' in the +preceding example. + +

In the Info output, @emph surrounds the text with underscores +(_), and @strong puts asterisks around the text. + +

+Caution: Do not use @strong with the word Note; Info will +mistake the combination for a cross reference. (It's usually +redundant, anyway.) Use a phrase such as Please notice or +Caution instead, or the optional argument to +@quotationNote is allowable there. +
+ +
+


+Next: , +Previous: emph & strong, +Up: Emphasis +
+
+ +

9.2.2 @sc{text}: The Small Caps Font

+ +

+Use the @sc command to set text in a small caps font +(where possible). Write the text you want to be in small caps between +braces in lower case, like this: + +

     Richard @sc{Stallman} founded @acronym{GNU}.
+
+

This produces: + +

     Richard Stallman founded GNU.
+
+

As shown here, we recommend using @acronym for actual +abbreviations (see acronym), and reserving @sc for special +cases where you want small caps. The output is not the same +(@acronym prints in a smaller text font, not the small caps +font), but more importantly it describes the actual text more +accurately. + +

Family names are one case where small capitals are sometimes desirable, +also as shown here. + +

TeX typesets any uppercase letters between the braces of an +@sc command in full-size capitals; only lowercase letters are +printed in the small caps font. In the Info output, the argument to +@sc is printed in all upper case. In HTML, the argument is +uppercased and the output marked with the <small> tag to reduce +the font size. + +

Since it's redundant to mark all-uppercase text with @sc, +makeinfo warns about such usage. + +

We recommend using regular mixed case wherever possible. + +

+


+Previous: Smallcaps, +Up: Emphasis +
+
+ +

9.2.3 Fonts for Printing, Not Info

+ +

+Texinfo provides four font commands that specify font changes in the +printed manual and (where possible) in the HTML output, but have no +effect in the Info file. All four commands apply to an argument that +follows, surrounded by braces. + +

+
@i
selects an italic font; + +
@b
selects bold face; + +
@t
selects the fixed-width, typewriter-style font used by @code; + +
@r
selects a roman font, which is the usual font in which text is printed. + +
+ +

Only the @r command has much use: in example-like +environments, you can use the @r command to write comments in +the standard roman font instead of the fixed-width font. This looks +better in printed output, and produces a <lineannotation> tag +in Docbook output. + +

For example, + +

     @lisp
+     (+ 2 2)    ; @r{Add two plus two.}
+     @end lisp
+
+

produces + +

     (+ 2 2)    ; Add two plus two.
+
+

In general, you should avoid using the other three font commands. If +you need to use one, it probably indicates a gap in the Texinfo +language. + +

+


+Next: , +Previous: Marking Text, +Up: Top +
+
+ +

10 Quotations and Examples

+ +

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 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 @end command that is also at the beginning of a line by +itself. For instance, you begin an example by writing @example +by itself at the beginning of a line and end the example by writing +@end example on a line by itself, at the beginning of that +line. + + +

+ +
+


+Next: , +Up: Quotations and Examples +
+
+ +

10.1 Block Enclosing Commands

+ +

Here are commands for quotations and examples, explained further in the +following sections: + +

+
@quotation
Indicate text that is quoted. The text is filled, indented (from both +margins), and printed in a roman font by default. + +
@example
Illustrate code, commands, and the like. The text is printed +in a fixed-width font, and indented but not filled. + +
@verbatim
Mark a piece of text that is to be printed verbatim; no character +substitutions are made and all commands are ignored, until the next +@end verbatim. The text is printed in a fixed-width font, +and not indented or filled. Extra spaces and blank lines are +significant, and tabs are expanded. + +
@smallexample
Same as @example, except that in TeX this command typesets +text in a smaller font. + +
@lisp
Like @example, but specifically for illustrating Lisp code. The +text is printed in a fixed-width font, and indented but not filled. + +
@smalllisp
Is to @lisp as @smallexample is to @example. + +
@display
Display illustrative text. The text is indented but not filled, and +no font is selected (so, by default, the font is roman). + +
@smalldisplay
Is to @display as @smallexample is to @example. + +
@format
Like @display (the text is not filled and no font is selected), +but the text is not indented. + +
@smallformat
Is to @format as @smallexample is to @example. +
+ +

The @exdent command is used within the above constructs to +undo the indentation of a line. + +

The @flushleft and @flushright commands are used to line +up the left or right margins of unfilled text. + +

The @noindent command may be used after one of the above +constructs to prevent the following text from being indented as a new +paragraph. + +

You can use the @cartouche environment around one of the above +constructs to highlight the example or quotation by drawing a box with +rounded corners around it. See Drawing Cartouches Around Examples. + +

+


+Next: , +Previous: Block Enclosing Commands, +Up: Quotations and Examples +
+
+ +

10.2 @quotation: Block quotations

+ +

+The text of a quotation is processed normally (regular font, text is +filled) except that: + +

+ +
+This is an example of text written between an @quotation +command and an @end quotation command. An @quotation +command is most often used to indicate text that is excerpted from +another (real or hypothetical) printed work. +
+ +

Write an @quotation command as text on a line by itself. This +line will disappear from the output. Mark the end of the quotation +with a line beginning with and containing only @end quotation. +The @end quotation line will likewise disappear from the +output. + +

@quotation takes one optional argument, given on the remainder +of the line. This text, if present, is included at the beginning of +the quotation in bold or otherwise emphasized, and followed with a +:. For example: + +

     @quotation Note
+     This is
+     a foo.
+     @end quotation
+
+

produces + +

+Note: This is +a foo. +
+ +

If the @quotation argument is exactly one of these words: + +

     Caution  Important  Note  Tip  Warning
+
+

then the Docbook output uses corresponding special tags +(<note>, etc.) instead of the default <blockquote>. +HTML output always uses <blockquote>. + +

+


+Next: , +Previous: quotation, +Up: Quotations and Examples +
+
+ +

10.3 @example: Example Text

+ +

+The @example environment is used to indicate an example that +is not part of the running text, such as computer input or output. +Write an @example command at the beginning of a line by +itself. Mark the end of the example with an @end example +command, also written at the beginning of a line by itself. + +

An @example environment has the following characteristics: + +

+ +

For example, + +

     @example
+     cp foo @var{dest1}; \
+      cp foo @var{dest2}
+     @end example
+
+

produces + +

     cp foo dest1; \
+      cp foo dest2
+
+

The lines containing @example and @end example will +disappear from the output. To make the output look good, you should +put a blank line before the @example and another blank line +after the @end example. Blank lines inside the beginning +@example and the ending @end example, on the other +hand, do appear in the output. + +

+Caution: Do not use tabs in the lines of an example! (Or anywhere else in +Texinfo, except in verbatim environments.) TeX treats tabs as +single spaces, and that is not what they look like. In Emacs, you can +use M-x untabify to convert tabs in a region to multiple spaces. +
+ +

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 @noindent command +prevents a piece of text from being indented as if it were a new +paragraph (see @noindent. + +

If you want to embed code fragments within sentences, instead of +displaying them, use the @code command or its relatives +(see @code). + +

If you wish to write a “comment” on a line of an example in the +normal roman font, you can use the @r command (see Fonts). + +

+


+Next: , +Previous: example, +Up: Quotations and Examples +
+
+ +

10.4 @verbatim: Literal Text

+ +

+Use the @verbatim environment for printing of text that may +contain special characters or commands that should not be interpreted, +such as computer input or output (@example interprets its text +as regular Texinfo commands). This is especially useful for including +automatically generated output in a Texinfo manual. Here is an example; +the output you see is just the same as the input, with a line +@verbatim before and a line @end verbatim after. + +

+This is an example of text written in a @verbatim
+block.  No character substitutions are made.  All commands
+are ignored, until `<at>end verbatim'.
+
+In the printed manual, the text is typeset in a
+fixed-width font, and not indented or filled.  All
+spaces and blank lines are significant, including tabs.
+
+ +

Write a @verbatim command at the beginning of a line by itself. +This line will disappear from the output. Mark the end of the verbatim +block with a @end verbatim command, also written at the +beginning of a line by itself. The @end verbatim will also +disappear from the output. + +

For example: + + +


@verbatim
+
{
+
<TAB>@command with strange characters: @'e
+
expand<TAB>me
+
}
+
@end verbatim
+
+

produces + +

+{
+        @command with strange characters: @'e
+expand	me
+}
+
+ +

Since the lines containing @verbatim and @end verbatim +produce no output, typically you should put a blank line before the +@verbatim and another blank line after the @end +verbatim. Blank lines between the beginning @verbatim and +the ending @end verbatim will appear in the output. + +

It is not reliable to use @verbatim inside other Texinfo constructs. + +

+


+Next: , +Previous: verbatim, +Up: Quotations and Examples +
+
+ +

10.5 @verbatiminclude file: Include a File Verbatim

+ +

+You can include the exact contents of a file in the document with the +@verbatiminclude command: + +

     @verbatiminclude filename
+
+

The contents of filename is printed in a verbatim environment +(see @verbatim). 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 @verbatiminclude within @example +(see @example). + +

The name of the file is taken literally, with a single exception: +@value{var} references are expanded. This makes it +possible to reliably include files in other directories in a +distribution, for instance: + +

     @include @value{top_srcdir}/NEWS
+
+

(You still have to get top_srcdir defined in the +first place.) + +

+


+Next: , +Previous: verbatiminclude, +Up: Quotations and Examples +
+
+ +

10.6 @lisp: Marking a Lisp Example

+ +

+The @lisp command is used for Lisp code. It is synonymous +with the @example command. + +

     This is an example of text written between an
+     @lisp command and an @end lisp command.
+
+

Use @lisp instead of @example 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.6 + +

Mark the end of @lisp with @end lisp on a line by +itself. + +

+


+Next: , +Previous: lisp, +Up: Quotations and Examples +
+
+ +

10.7 @small... Block Commands

+ +

+In addition to the regular @example and @lisp commands, +Texinfo has “small” example-style commands. These are +@smalldisplay, @smallexample, @smallformat, and +@smalllisp. + +

In Info, the @small... commands are equivalent to their +non-small companion commands. + +

In TeX, however, the @small... 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. + +

Mark the end of an @small... block with a corresponding +@end small.... For example, pair @smallexample with +@end smallexample. + +

Here is an example of the font used by the @small... +commands (in Info, the output will be the same as usual): + +

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

The @small... commands make it easier to prepare manuals +without forcing you to edit examples by hand to fit them onto narrower +pages. + +

As a general rule, a printed document looks much better if you use +only one of (for instance) @example or @smallexample +consistently within a chapter. + +

+


+Next: , +Previous: small, +Up: Quotations and Examples +
+
+ +

10.8 @display and @smalldisplay

+ +

+The @display command begins a kind of example. It is like the +@example command +except that, in +a printed manual, @display does not select the fixed-width +font. In fact, it does not specify the font at all, so that the text +appears in the same font it would have appeared in without the +@display command. + +

     This is an example of text written between an @display command
+     and an @end display command.  The @display command
+     indents the text, but does not fill it.
+
+

Texinfo also provides a command @smalldisplay, which is like +@display but uses a smaller font in @smallbook format. +See small. + +

+


+Next: , +Previous: display, +Up: Quotations and Examples +
+
+ +

10.9 @format and @smallformat

+ +

+The @format command is similar to @example except +that, in the printed manual, @format does not select the +fixed-width font and does not narrow the margins. + +

This is an example of text written between an @format command
+and an @end format command.  As you can see
+from this example,
+the @format command does not fill the text.
+
+

Texinfo also provides a command @smallformat, which is like +@format but uses a smaller font in @smallbook format. +See small. + +

+


+Next: , +Previous: format, +Up: Quotations and Examples +
+
+ +

10.10 @exdent: Undoing a Line's Indentation

+ +

+The @exdent 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 +@exdent line is printed in the roman font. + +

@exdent is usually used within examples. Thus, + +

     @example
+     This line follows an @@example command.
+     @exdent This line is exdented.
+     This line follows the exdented line.
+     The @@end example comes on the next line.
+     @end group
+
+

produces + +

     This line follows an @example command.
+
This line is exdented.
+ This line follows the exdented line. + The @end example comes on the next line. +
+

In practice, the @exdent command is rarely used. +Usually, you un-indent text by ending the example and +returning the page to its normal width. + +

+


+Next: , +Previous: exdent, +Up: Quotations and Examples +
+
+ +

10.11 @flushleft and @flushright

+ +

+The @flushleft and @flushright 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 @flushleft and @flushright +commands are ended by @end flushleft and @end +flushright commands on lines of their own. + +

For example, + +

     @flushleft
+     This text is
+     written flushleft.
+     @end flushleft
+
+

produces + +

+
This text is + written flushleft. +
+
+ +

@flushright produces the type of indentation often used in the +return address of letters. For 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
+
+

produces + +

Here is an example of text written +

flushright. The @flushright command +

right justifies every line but leaves the +

left end ragged. +

+ +
+


+Next: , +Previous: flushleft & flushright, +Up: Quotations and Examples +
+
+ +

10.12 @noindent: Omitting Indentation

+ +

+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 +@noindent at the beginning of a line, preceding the continuation +text. You can also disable indentation for all paragraphs globally with +@paragraphindent (see Paragraph Indenting). + +

It is best to write @noindent 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. + +

For 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}.)
+
+

produces: + +

+     
          This is an example
+     
+ +

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 + @display and @end display.) + +

+

To adjust the number of blank lines properly in the Info file output, +remember that the line containing @noindent does not generate a +blank line, and neither does the @end example line. + +

In the Texinfo source file for this manual, each line that says +`produces' is preceded by @noindent. + +

Do not put braces after an @noindent command; they are not +necessary, since @noindent is a command used outside of +paragraphs (see Command Syntax). + +

+


+Next: , +Previous: noindent, +Up: Quotations and Examples +
+
+ +

10.13 @indent: Forcing Indentation

+ +

+ + To complement the @noindent command (see the previous +section), Texinfo provides the @indent command that forces a +paragraph to be indented. This paragraph, for instance, is indented +using an @indent command. The first paragraph of a section is +the most likely place to use @indent, to override the normal +behavior of no indentation there (see paragraphindent). + +

It is best to write @indent on a line by itself, since in most +environments, spaces following the command will not be ignored. The +@indent line will not generate a blank line in the Info output +within an environment. + +

However, it is ok to use it at the beginning of a line, with text +following, outside of any environment. + +

Do not put braces after an @indent command; they are not +necessary, since @indent is a command used outside of +paragraphs (see Command Syntax). + +

+


+Previous: indent, +Up: Quotations and Examples +
+
+ +

10.14 @cartouche: Rounded Rectangles Around Examples

+ +

+In a printed manual, the @cartouche command draws a box with +rounded corners around its contents. In HTML, a normal rectangle is +drawn (that's the best HTML can do). @cartouche has no effect +in Info output. + +

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

For example, + +

     @cartouche
+     @example
+     % pwd
+     /usr/local/share/emacs
+     @end example
+     @end cartouche
+
+

surrounds the two-line example with a box with rounded corners, in the +printed manual. + +

The output from the example looks like this (if you're reading this in +Info, you'll see the @cartouche had no effect): + +

+
     % pwd
+     /usr/local/info
+
+
+ +

For proper output in HTML, it's necessary to put the +@cartouche around the @example, and not the other way +around. This limitation of makeinfo may be removed one day. + +

@cartouche also implies @group (see group). + +

+


+Next: , +Previous: Quotations and Examples, +Up: Top +
+
+ +

11 Lists and Tables

+ +

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

+ +
+


+Next: , +Up: Lists and Tables +
+
+ +

11.1 Introducing Lists

+ +

Texinfo automatically indents the text in lists or tables, and numbers +an enumerated list. This last feature is useful if you modify the +list, since you do not need to renumber it yourself. + +

Numbered lists and tables begin with the appropriate @-command at the +beginning of a line, and end with the corresponding @end +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. + +

Begin an enumerated list, for example, with an @enumerate +command and end the list with an @end enumerate command. +Begin an itemized list with an @itemize command, followed on +the same line by a formatting command such as @bullet, and end +the list with an @end itemize command. + +Precede each element of a list with an @item or @itemx +command. + +

+
+
+Here is an itemized list of the different kinds of table and lists: + + + +
+
+
+Here is an enumerated list with the same items: + +
    +
  1. Itemized lists with and without bullets. + +
  2. Enumerated lists, using numbers or letters. + +
  3. Two-column tables with highlighting. +
+ +
+
+
+And here is a two-column table with the same items and their +@-commands: + +
+
@itemize
Itemized lists with and without bullets. + +
@enumerate
Enumerated lists, using numbers or letters. + +
@table
@ftable
@vtable
Two-column tables, optionally with indexing. +
+ +
+


+Next: , +Previous: Introducing Lists, +Up: Lists and Tables +
+
+ +

11.2 @itemize: Making an Itemized List

+ +

+The @itemize 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. + +

Begin an itemized list by writing @itemize 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 +@bullet after @itemize, but you can use +@minus, 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 +@w. (When you write the mark command such as +@bullet after an @itemize command, you may omit the +{}.) If you don't specify a mark command, the default is +@bullet. + +

Write the text of the indented paragraphs themselves after the +@itemize, up to another line that says @end +itemize. + +

At the beginning of each paragraph for which a mark in the margin is +desired, write a line that starts with @item. It is ok to +have text following the @item. + +

Usually, you should put a blank line before an @item. 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. + +

Here is an example of the use of @itemize, followed by the +output it produces. @bullet produces an * in Info and a +round dot in TeX. + +

     @itemize @bullet
+     @item
+     Some text for foo.
+     
+     @item
+     Some text
+     for bar.
+     @end itemize
+
+

This produces: + +

+ +
+ +

Itemized lists may be embedded within other itemized lists. Here is a +list marked with dashes embedded in a list marked with bullets: + +

     @itemize @bullet
+     @item
+     First item.
+     
+     @itemize @minus
+     @item
+     Inner item.
+     
+     @item
+     Second inner item.
+     @end itemize
+     
+     @item
+     Second outer item.
+     @end itemize
+
+

This produces: + +

+ +
+ +
+


+Next: , +Previous: itemize, +Up: Lists and Tables +
+
+ +

11.3 @enumerate: Making a Numbered or Lettered List

+ +

+@enumerate is like @itemize (see @itemize), except that the labels on the items are +successive integers or letters instead of bullets. + +

Write the @enumerate 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, @enumerate starts the +list with the number 1. With a numeric argument, such as +3, the command starts the list with that number. With an upper +or lower case letter, such as a or A, the command starts +the list with that letter. + +

Write the text of the enumerated list in the same way as an itemized +list: write a line starting with @item at the beginning of +each paragraph that you want enumerated. It is ok to have text +following the @item. + +

You should put a blank line between entries in the list. +This generally makes it easier to read the Info file. + +

Here is an example of @enumerate without an argument: + +

     @enumerate
+     @item
+     Underlying causes.
+     
+     @item
+     Proximate causes.
+     @end enumerate
+
+

This produces: + +

    +
  1. Underlying causes. + +
  2. Proximate causes. +
+
+
+
+Here is an example with an argument of 3: +
+
+
+
     @enumerate 3
+     @item
+     Predisposing causes.
+     
+     @item
+     Precipitating causes.
+     
+     @item
+     Perpetuating causes.
+     @end enumerate
+
+

This produces: + +

    +
  1. Predisposing causes. + +
  2. Precipitating causes. + +
  3. Perpetuating causes. +
+
+
+
+Here is a brief summary of the alternatives. The summary is constructed +using @enumerate with an argument of a. +
+
+
+
    +
  1. @enumerate + +

    Without an argument, produce a numbered list, starting with the number +1. + +

  2. @enumerate positive-integer + +

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

  3. @enumerate upper-case-letter + +

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

  4. @enumerate lower-case-letter + +

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

+ +

You can also nest enumerated lists, as in an outline. + +

+


+Next: , +Previous: enumerate, +Up: Lists and Tables +
+
+ +

11.4 Making a Two-column Table

+ +

+@table is similar to @itemize (see @itemize), but allows you to specify a name or heading line for +each item. The @table command is used to produce two-column +tables, and is especially useful for glossaries, explanatory +exhibits, and command-line option summaries. + +

+ +
+


+Next: , +Up: Two-column Tables +
+
+ +

11.4.1 Using the @table Command

+ +

Use the @table 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. + +

Write the @table 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, @samp, +@var, @option, or @kbd (see Indicating). + +

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, @table @code will cause the text in the first +column to be output as if it @code command. + +

You may also use the @asis command as an argument to +@table. @asis is a command that does nothing; if you +use this command after @table, the first column entries are +output without added highlighting (“as is”). + +

The @table 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 +@item's will supply the argument.) + +

Begin each table entry with an @item command at the beginning +of a line. Write the first column text on the same line as the +@item command. Write the second column text on the line +following the @item 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 @item +will be placed in the first column (including any footnotes). + +

Normally, you should put a blank line before an @item line. +This puts a blank line in the Info file. Except when the entries are +very brief, a blank line looks better. + +

End the table with a line consisting of @end table, 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. + +

The following table, for example, highlights the text in the first +column with an @samp command: + +

     @table @samp
+     @item foo
+     This is the text for
+     @samp{foo}.
+     
+     @item bar
+     Text for @samp{bar}.
+     @end table
+
+

This produces: + +

+
foo
This is the text for +foo. +
bar
Text for bar. +
+ +

If you want to list two or more named items with a single block of +text, use the @itemx command. (See @itemx.) + +

+


+Next: , +Previous: table, +Up: Two-column Tables +
+
+ +

11.4.2 @ftable and @vtable

+ +

+The @ftable and @vtable commands are the same as the +@table command except that @ftable automatically enters +each of the items in the first column of the table into the index of +functions and @vtable 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 @item commands are indexed, and they are indexed in +exactly the form that they appear on that line. See Indices, +for more information about indices. + +

Begin a two-column table using @ftable or @vtable 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, +exactly as you would for an @table command; and end the table +with an @end ftable or @end vtable command on a line by +itself. + +

See the example for @table in the previous section. + +

+


+Previous: ftable vtable, +Up: Two-column Tables +
+
+ +

11.4.3 @itemx

+ +

+Use the @itemx command inside a table when you have two or more +first column entries for the same item, each of which should appear on a +line of its own. + +

Use @item for the first entry, and @itemx for all +subsequent entries; @itemx must always follow an @item +command, with no blank line intervening. + +

The @itemx command works exactly like @item except +that it does not generate extra vertical space above the first column +text. If you have multiple consecutive @itemx commands, do +not insert any blank lines between them. + +

For 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
+
+

This produces: + +

+
upcase
downcase
These two functions accept a character or a string as +argument, and return the corresponding upper case (lower +case) character or string. +
+ +

(Note also that this example illustrates multi-line supporting text in +a two-column table.) + +

+


+Previous: Two-column Tables, +Up: Lists and Tables +
+
+ +

11.5 @multitable: Multi-column Tables

+ +

+@multitable allows you to construct tables with any number of +columns, with each column having any width you like. + +

You define the column widths on the @multitable line itself, and +write each row of the actual table following an @item command, +with columns separated by an @tab command. Finally, @end +multitable completes the table. Details in the sections below. + +

+ +
+


+Next: , +Up: Multi-column Tables +
+
+ +

11.5.1 Multitable Column Widths

+ +

+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 @multitable command. + +

    +
  1. To specify column widths as fractions of the line length, write +@columnfractions and the decimal numbers (presumably less than +1; a leading zero is allowed and ignored) after the +@multitable command, as in: + +
              @multitable @columnfractions .33 .33 .33
    +     
    +

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

  2. To specify a prototype row, write the longest entry for each column +enclosed in braces after the @multitable command. For example: + +
              @multitable {some text for column one} {for column two}
    +     
    +

    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'. + +

    The prototype entries need not appear in the table itself. + +

    Although we used simple text in this example, the prototype entries can +contain Texinfo commands; markup commands such as @code are +particularly likely to be useful. + +

+ +
+


+Previous: Multitable Column Widths, +Up: Multi-column Tables +
+
+ +

11.5.2 Multitable Rows

+ +

+After the @multitable command defining the column widths (see +the previous section), you begin each row in the body of a multitable +with @item, and separate the column entries with @tab. +Line breaks are not special within the table body, and you may break +input lines in your source file as necessary. + +

You can also use @headitem instead of @item to produce +a heading row. The TeX output for such a row is in bold, and +the HTML, XML, and Docbook output uses the <thead> tag. + +

Here is a complete example of a multi-column table (the text is from +The GNU Emacs Manual, see Splitting Windows (The GNU Emacs Manual)): + +

     @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
+
+

produces: + +

Key Command Description +
C-x 2 +split-window-vertically +Split the selected window into two windows, +with one above the other. +
C-x 3 +split-window-horizontally +Split the selected window into two windows +positioned side by side. +
C-Mouse-2 + +In the mode line or scroll bar of a window, +split that window. +
+ +

+


+Next: , +Previous: Lists and Tables, +Up: Top +
+
+ +

12 Special Displays

+ +

+The commands in this chapter allow you to write text that is specially +displayed (output format permitting), outside of the normal document +flow. + +

One set of such commands is for creating “floats”, that is, figures, +tables, and the like, set off from the main text, possibly numbered, +captioned, and/or referred to from elsewhere in the document. Images +are often included in these displays. + +

Another group of commands is for creating footnotes in Texinfo. + +

+ +
+


+Next: , +Up: Special Displays +
+
+ +

12.1 Floats

+ +

+A float is a display which is set off from the main text. It is +typically labelled as being a “Figure”, “Table”, “Example”, or +some similar type. + +

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 @group (see @group). + +

+ +
+


+Next: , +Up: Floats +
+
+ +

12.1.1 @float [type][,label]: Floating material

+ +

+To produce floating material, enclose the material you want to be +displayed separate between @float and @end float +commands, on lines by themselves. + +

Floating material uses @image to display an already-existing +graphic (see Images), or @multitable to display a table +(see Multi-column Tables). However, the contents of the float can +be anything. Here's an example with simple text: + +

     @float Figure,fig:ex1
+     This is an example float.
+     @end float
+
+

And the output: + +

+This is an example float. +

Figure 12.1

+ +

As shown in the example, @float takes two arguments (separated +by a comma), type and label. Both are optional. + +

+
type
Specifies the sort of float this is; typically a word such as +“Figure”, “Table”, etc. If not given, and label is, any +cross-referencing will simply use a bare number. + +
label
Specifies a cross-reference label for this float. If given, this +float is automatically given a number, and will appear in any +@listofloats output (see listoffloats). Cross-references +to label are allowed. + +

On the other hand, if label is not given, then the float will +not be numbered and consequently will not appear in the +@listoffloats output or be cross-referenceable. +

+ +

Normally, you specify both type and label, to get a +labeled and numbered float. + +

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, ..., and is reset at each chapter. Each +float type is counted independently. + +

Floats within an @unnumbered are numbered, or outside of any +chapter, are simply numbered consecutively from 1. + +

These numbering conventions are not, at present, changeable. + +

+


+Next: , +Previous: float, +Up: Floats +
+
+ +

12.1.2 @caption & @shortcaption

+ +

+You may write an @caption anywhere within a @float +environment, to define a caption for the float. It is not allowed in +any other context. @caption takes a single argument, enclosed +in braces. Here's an example: + +

     @float
+     An example float, with caption.
+     @caption{Caption for example float.}
+     @end float
+
+

The output is: + +

+An example float, with caption. + +

Caption for example float.

+ +

@caption can appear anywhere within the float; it is not +processed until the @end float. The caption text is usually a +sentence or two, but may consist of several paragraphs if necessary. + +

In the output, the caption always appears below the float; this is not +currently changeable. It is preceded by the float type and/or number, +as specified to the @float command (see the previous section). + +

The @shortcaption command likewise may be used only within +@float, and takes a single argument in braces. The short +caption text is used instead of the caption text in a list of floats +(see the next section). Thus, you can write a long caption for the +main document, and a short title to appear in the list of floats. + +

+


+Previous: caption shortcaption, +Up: Floats +
+
+ +

12.1.3 @listoffloats: Tables of contents for floats

+ +

+You can write a @listoffloats command to generate a list of +floats for a given float type (see float), analogous to the +document's overall table of contents. Typically, it is written in its +own @unnumbered node to provide a heading and structure, +rather like @printindex (see Printing Indices & Menus). + +

@listoffloats takes one optional argument, the float type. +Here's an example: + +

     @node List of Figures
+     @unnumbered List of Figures
+     @listoffloats Figure
+
+

And the output from @listoffloats: + +

+
+
+
+  
+

Without any argument, @listoffloats generates a list of +floats for which no float type was specified, i.e., no first argument +to the @float command (see float). + +

Each line in the list of floats contains the float type (if any), +the float number, and the caption, if any—the @shortcaption +argument, if it was specified, else the @caption argument. +In Info, the result is a menu where each float can be selected. In +HTML, each line is a link to the float. In printed output, the page +number is included. + +

Unnumbered floats (those without cross-reference labels) are omitted +from the list of floats. + +

+


+Next: , +Previous: Floats, +Up: Special Displays +
+
+ +

12.2 Inserting Images

+ +

+You can insert an image given in an external file with the +@image command. Although images can be used anywhere, +including the middle of a paragraph, we describe them in this chapter +since they are most often part of a displayed figure or example. + +

+ +
+


+Next: , +Up: Images +
+
+ +

12.2.1 Image Syntax

+ +

Here is the basic synopsis of the @image command: + +

     @image{filename[, width[, height[, alttext[, extension]]]]}
+
+

The filename argument is mandatory, and must not have an +extension, because the different processors support different formats: + +

+ +

The width and height arguments are described in the next +section. + +

When producing html, makeinfo sets the alt attribute for +inline images to the optional alttext (fourth) argument to +@image, if supplied. If not supplied, makeinfo uses +the full file name of the image being displayed. If you want an empty +alt string, use @-. The alttext is taken as +Texinfo text, so special characters such as " and < and +& are escaped in the HTML and XML output. + +

If you do not supply the optional extension (fifth) argument, +makeinfo first tries filename.png; if that does +not exist, it tries filename.jpg. If that does not exist +either, it complains. (We cannot support GIF format directly due to +software patents.) + +

In Info output, makeinfo writes a reference to the binary image +file (trying filename suffixed with extension, +.extension, .png, or .jpg, in that order) +if one exists. It also literally includes the .txt file if one +exists. This way, Info readers which can display images (such as the +Emacs Info browser, running under X) can do so, whereas Info readers +which can only use text (such as the standalone Info reader) can +display the textual version. + +

The implementation of this is to put the following construct into the +Info output: + +

     ^@^H[image src="binaryfile" text="txtfile"
+                alt="alttext ... ^@^H]
+
+

where ^@ and ^H stand for the actual null and +backspace control characters. If one of the files is not present, the +corresponding argument is omitted. + +

The reason for mentioning this here is that older Info browsers (this +feature was introduced in Texinfo version 4.6) will display the above +literally, which, although not pretty, should not be harmful. + +

+


+Previous: Image Syntax, +Up: Images +
+
+ +

12.2.2 Image Scaling

+ +

The optional width and height arguments to the +@image command (see the previous section) specify the size to +scale the image to. They are ignored for Info output. If neither is +specified, the image is presented in its natural size (given in the +file); if only one is specified, the other is scaled proportionately; +and if both are specified, both are respected, thus possibly distorting +the original image by changing its aspect ratio. + +

The width and height may be specified using any valid TeX +dimension, namely: + +

+
pt
point (72.27pt = 1in) +
pc
pica (1pc = 12pt) +
bp
big point (72bp = 1in) +
in
inch +
cm
centimeter (2.54cm = 1in) +
mm
millimeter (10mm = 1cm) +
dd
didôt point (1157dd = 1238pt) +
cc
cicero (1cc = 12dd) +
sp
scaled point (65536sp = 1pt) +
+ +

For example, the following will scale a file ridt.eps to one +inch vertically, with the width scaled proportionately: + +

     @image{ridt,,1in}
+
+

For @image to work with TeX, the file epsf.tex must be +installed somewhere that TeX can find it. (The standard location is +texmf/tex/generic/dvips/epsf.tex, where texmf is a +root of your TeX directory tree.) This file is included in the +Texinfo distribution and is also available from +ftp://tug.org/tex/epsf.tex, among other places. + +

@image can be used within a line as well as for displayed +figures. Therefore, if you intend it to be displayed, be sure to leave +a blank line before the command, or the output will run into the +preceding text. + +

Image scaling is presently implemented only in TeX, not in HTML or +any other sort of output. + +

+


+Previous: Images, +Up: Special Displays +
+
+ +

12.3 Footnotes

+ +

+A footnote is for a reference that documents or elucidates the +primary text.7 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. + +

+ +
+


+Next: , +Up: Footnotes +
+
+ +

12.3.1 Footnote Commands

+ +

In Texinfo, footnotes are created with the @footnote command. +This command is followed immediately by a left brace, then by the text +of the footnote, and then by a terminating right brace. Footnotes may +be of any length (they will be broken across pages if necessary), but +are usually short. The template is: + +

     ordinary text@footnote{text of footnote}
+
+

As shown here, the @footnote command should come right after the +text being footnoted, with no intervening space; otherwise, the footnote +marker might end up starting a line. + +

For example, this clause is followed by a sample footnote8; in the Texinfo source, it looks like +this: + +

     ...a sample footnote@footnote{Here is the sample
+     footnote.}; in the Texinfo source...
+
+

As you can see, the source includes two punctuation marks next to each +other; in this case, .}; is the sequence. This is normal (the +first ends the footnote and the second belongs to the sentence being +footnoted), so don't worry that it looks odd. + +

In a printed manual or book, the reference mark for a footnote is a +small, superscripted number; the text of the footnote appears at the +bottom of the page, below a horizontal line. + +

In Info, the reference mark for a footnote is a pair of parentheses +with the footnote number between them, like this: (1). The +reference mark is followed by a cross-reference link to the footnote's +text. + +

In the HTML output, footnote references are marked with a small, +superscripted number which is rendered as a hypertext link to the +footnote text. + +

By the way, footnotes in the argument of an @item command for a +@table must be on the same line as the @item +(as usual). See Two-column Tables. + +

+


+Previous: Footnote Commands, +Up: Footnotes +
+
+ +

12.3.2 Footnote Styles

+ +

Info has two footnote styles, which determine where the text of the +footnote is located: + + + +

+ +

Unless your document has long and important footnotes (as in, say, +Gibbon's Decline and Fall ...), we recommend the end +style, as it is simpler for readers to follow. + +

Use the @footnotestyle command to specify an Info file's +footnote style. Write this command at the beginning of a line followed +by an argument, either end for the end node style or +separate for the separate node style. + +

For example, + +

     @footnotestyle end
+
+

or +

     @footnotestyle separate
+
+

Write an @footnotestyle command before or shortly after the +end-of-header line at the beginning of a Texinfo file. (If you +include the @footnotestyle command between the start-of-header +and end-of-header lines, the region formatting commands will format +footnotes as specified.) + +

If you do not specify a footnote style, the formatting commands use +their default style. Currently, texinfo-format-buffer and +texinfo-format-region use the `separate' style and +makeinfo uses the `end' style. + +

+


+Next: , +Previous: Special Displays, +Up: Top +
+
+ +

13 Indices

+ +

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

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

See Printing Indices & Menus, for information on how to print +indices. + +

+ +
+


+Next: , +Up: Indices +
+
+ +

13.1 Making Index Entries

+ +

+When you are making index entries, it is good practice to think of the +different ways people may look for something. Different people +do not 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. + +

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

See Printing Indices & Menus, for information about printing an index +at the end of a book or creating an index menu in an Info file. + +

+


+Next: , +Previous: Index Entries, +Up: Indices +
+
+ +

13.2 Predefined Indices

+ +

Texinfo provides six predefined indices. Here are their nominal +meanings, abbreviations, and the corresponding index entry commands: + +

+
cp
(@cindex) concept index, for general concepts. +
fn
(@findex) function index, for function and function-like +names (such as entry points of libraries). +
ky
(@kindex) keystroke index, for keyboard commands. +
pg
(@pindex) program index, for names of programs. +
tp
(@tindex) data type index, for type names (such as structures +defined in header files). +
vr
(@vindex) variable index, for variable names (such as global +variables of libraries). +
+ +

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

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 @findex commands for +them; then, when you print the “Function Index” as an unnumbered +chapter, you could give it the title `Function and Macro Index' and +all will be consistent for the reader. + +

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 New Indices). + +

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 @synindex or +@syncodeindex commands (see Combining Indices). + +

+


+Next: , +Previous: Predefined Indices, +Up: Indices +
+
+ +

13.3 Defining the Entries of an Index

+ +

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

An index entry consists of an indexing command at the beginning of a +line followed, on the rest of the line, by the entry. + +

For example, this section begins with the following five entries for +the concept index: + +

     @cindex Defining indexing entries
+     @cindex Index entries, defining
+     @cindex Entries for an index
+     @cindex Specifying index entries
+     @cindex Creating index entries
+
+

Each predefined index has its own indexing command—@cindex +for the concept index, @findex for the function index, and so +on, as listed in the previous section. + +

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

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

Whichever case convention you use, please use it consistently! + +

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

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 font. You may change the way part of an entry is +printed with the usual Texinfo commands, such as @file for +file names (see Marking Text), and @r for the normal roman +font (see Fonts). + +

+Caution: Do not use a colon in an index entry. In Info, a colon separates the +menu entry name from the node name, so a colon in the entry itself +confuses Info. See Menu Parts, for more information about the +structure of a menu entry. +
+ +
+


+Next: , +Previous: Indexing Commands, +Up: Indices +
+
+ +

13.4 Combining Indices

+ +

+Sometimes you will want to combine two disparate indices such as +functions and concepts, perhaps because you have few enough entries +that a separate index would look silly. + +

You could put functions into the concept index by writing +@cindex commands for them instead of @findex commands, +and produce a consistent manual by printing the concept index with the +title `Function and Concept Index' and not printing the `Function +Index' at all; but this is not a robust procedure. It works only if +your document is never included as part of another document that is +designed to have a separate function index; if your document were to +be included with such a document, the functions from your document and +those from the other would not end up together. Also, to make your +function names appear in the right font in the concept index, you +would need to enclose every one of them between the braces of +@code. + +

+ +
+


+Next: , +Up: Combining Indices +
+
+ +

13.4.1 @syncodeindex

+ +

+When you want to combine functions and concepts into one index, you +should index the functions with @findex and index the concepts +with @cindex, and use the @syncodeindex command to +redirect the function index entries into the concept index. + +

The @syncodeindex 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: + +

     @syncodeindex from to
+
+

For this purpose, the indices are given two-letter names: + +

+
cp
concept index +
fn
function index +
vr
variable index +
ky
key index +
pg
program index +
tp
data type index +
+ +

Write an @syncodeindex 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: + +

     @syncodeindex fn cp
+
+

This will cause all entries designated for the function index to merge +in with the concept index instead. + +

To merge both a variables index and a function index into a concept +index, write the following: + +

     @syncodeindex vr cp
+     @syncodeindex fn cp
+
+

The @syncodeindex command puts all the entries from the `from' +index (the redirected index) into the @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 font as you would expect. + +

+


+Previous: syncodeindex, +Up: Combining Indices +
+
+ +

13.4.2 @synindex

+ +

+The @synindex command is nearly the same as the +@syncodeindex command, except that it does not put the +`from' index entries into the @code font; rather it puts +them in the roman font. Thus, you use @synindex when you +merge a concept index into a function index. + +

See Printing Indices & Menus, for information about printing an index +at the end of a book or creating an index menu in an Info file. + +

+


+Previous: Combining Indices, +Up: Indices +
+
+ +

13.5 Defining New Indices

+ +

+In addition to the predefined indices, you may use the +@defindex and @defcodeindex commands to define new +indices. These commands create new indexing @-commands with which +you mark index entries. The @defindex command is used like +this: + +

     @defindex name
+
+

The name of an index should be a two letter word, such as au. +For example: + +

     @defindex au
+
+

This defines a new index, called the au index. At the same +time, it creates a new indexing command, @auindex, that you +can use to make index entries. Use this new indexing command just as +you would use a predefined indexing command. + +

For example, here is a section heading followed by a concept index +entry and two au index entries. + +

     @section Cognitive Semantics
+     @cindex kinesthetic image schemas
+     @auindex Johnson, Mark
+     @auindex Lakoff, George
+
+

(Evidently, au serves here as an abbreviation for “author”.) + +

In general, Texinfo constructs the new indexing command by +concatenating the name of the index with index; thus, defining +an xy index leads to the automatic creation of an +@xyindex command. + +

Use the @printindex command to print the index, as you do with +the predefined indices. For example: + +

     @node Author Index
+     @unnumbered Author Index
+     
+     @printindex au
+
+

The @defcodeindex is like the @defindex command, +except that, in the printed output, it prints entries in an +@code font by default instead of a roman font. + +

You should define new indices before the end-of-header line of a +Texinfo file, and (of course) before any @synindex or +@syncodeindex commands (see Texinfo File Header). + +

+


+Next: , +Previous: Indices, +Up: Top +
+
+ +

14 Special Insertions

+ +

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

+ +
+


+Next: , +Up: Insertions +
+
+ +

14.1 Inserting @ and {} and ,

+ +

+@ and curly braces are special characters in Texinfo. To insert +these characters so they appear in text, you must put an @ in +front of these characters to prevent Texinfo from misinterpreting +them. + +

The comma `,' is a special character only in one uncommon context: +it separates arguments to commands that take multiple arguments. + +

+ +
+


+Next: , +Up: Atsign Braces Comma +
+
+ +

14.1.1 Inserting `@' with @@

+ +

+@@ stands for a single @ in either printed or Info +output. + +

Do not put braces after an @@ command. + +

+


+Next: , +Previous: Inserting an Atsign, +Up: Atsign Braces Comma +
+
+ +

14.1.2 Inserting `{' and `}' with @{ and @}

+ +

+@{ stands for a single { in either printed or Info +output. + +

@} stands for a single } in either printed or Info +output. + +

Do not put braces after either an @{ or an @} +command.ppp + +

+


+Previous: Inserting Braces, +Up: Atsign Braces Comma +
+
+ +

14.1.3 Inserting `,' with @comma{}

+ +

+Ordinarily, a comma `,' is a normal character that can be simply typed +in your input where you need it. + +

However, Texinfo uses the comma as a special character in one uncommon +context: some commands, such as @acronym (see acronym) and +@xref (see Cross References), as well as user-defined +macros (see Defining Macros), can take more than one argument. In +these cases, the comma character is used to separate arguments. + +

Since a comma chacter would confuse Texinfo's parsing for these +commands, you must use the command , instead if you want +to have an actual comma in the output. Here are some examples: + +

     @acronym{ABC, A Bizarre @comma{}}
+     @xref{Comma,, The @comma{} symbol}
+     @mymac{One argument@comma{} containing a comma}
+
+

Although , can be used anywhere, there is no need for it +anywhere except in this unusual case. + +

+


+Next: , +Previous: Atsign Braces Comma, +Up: Insertions +
+
+ +

14.2 Inserting Space

+ +

The following sections describe commands that control spacing of various +kinds within and after sentences. + +

+ +
+


+Next: , +Up: Inserting Space +
+
+ +

14.2.1 Not Ending a Sentence

+ +

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

Use the @: command after a period, question mark, +exclamation mark, or colon that should not be followed by extra space. +For example, use @: after periods that end abbreviations +which are not at the ends of sentences. + +

For example, + +

     The s.o.p.@: has three parts ...
+     The s.o.p. has three parts ...
+
+

produces + +

+The s.o.p. has three parts ...
+The s.o.p. has three parts ... +
+ +

(Incidentally, s.o.p. is an abbreviation for “Standard Operating +Procedure”.) + +

@: 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: &period; &quest; &excl; +&colon;. This gives further processors a chance to notice and not +add the usual extra space. + +

Do not put braces after @: (or any non-alphabetic command). + +

+


+Next: , +Previous: Not Ending a Sentence, +Up: Inserting Space +
+
+ +

14.2.2 Ending a Sentence

+ +

+Use @. instead of a period, @! instead of an +exclamation point, and @? 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: + +

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

produces + +

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

In the Info file output, @. is equivalent to a simple +.; likewise for @! and @?. + +

The meanings of @: and @. in Texinfo are designed to +work well with the Emacs sentence motion commands (see Sentences (The GNU Emacs Manual)). + +

Do not put braces after any of these commands. + +

+


+Next: , +Previous: Ending a Sentence, +Up: Inserting Space +
+
+ +

14.2.3 Multiple Spaces

+ +

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

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: +@SPACE, @TAB, and @NL, all of +which insert a single space into the output. (Here, +@SPACE represents an @ character followed by a +space, i.e., @ , and TAB and NL represent the tab +character and end-of-line, i.e., when @ is the last character on +a line.) + +

For example, +

     Spacey@ @ @ @
+     example.
+
+

produces + +

     Spacey    example.
+
+

Other possible uses of @SPACE have been subsumed by +@multitable (see Multi-column Tables). + +

Do not follow any of these commands with braces. + +

To produce a non-breakable space, see @tie. + +

+


+Previous: Multiple Spaces, +Up: Inserting Space +
+
+ +

14.2.4 @dmn{dimension}: Format a Dimension

+ +

+At times, you may want to write 12pt or +8.5in with little or no space between the number and the +abbreviation for the dimension. You can use the @dmn 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. + +

To use the @dmn command, write the number and then follow it +immediately, with no intervening space, by @dmn, and then by +the dimension within braces. For example, + +

     A4 paper is 8.27@dmn{in} wide.
+
+

produces + +

+A4 paper is 8.27in wide. +
+ +

Not everyone uses this style. Some people prefer 8.27 in.@: +or 8.27 inches to 8.27@dmn{in} in the Texinfo file. +In these cases, however, the formatters may insert a line break between +the number and the dimension, so use @w (see w). Also, if +you write a period after an abbreviation within a sentence, you should +write @: after the period to prevent TeX from inserting extra +whitespace, as shown here. See Not Ending a Sentence. + +

+


+Next: , +Previous: Inserting Space, +Up: Insertions +
+
+ +

14.3 Inserting Accents

+ +

+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: @, does 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. + +

To get the true accented characters output in Info, and not just the +ASCII transliterations, you can use the --enable-encoding +option to makeinfo (see makeinfo options). + +

+

Command Output What +
@"o ö umlaut accent +
@'o ó acute accent +
@,{c} ç cedilla accent +
@=o macron/overbar accent +
@^o ô circumflex accent +
@`o ò grave accent +
@~o õ tilde accent +
@dotaccent{o} o. overdot accent +
@H{o} o'' long Hungarian umlaut +
@ringaccent{o} o* ring accent +
@tieaccent{oo} oo[ tie-after accent +
@u{o} o( breve accent +
@ubaraccent{o} o_ underbar accent +
@udotaccent{o} .o underdot accent +
@v{o} o< hacek/check/caron accent +
+ +

This table lists the Texinfo commands for inserting other characters +commonly used in languages other than English. + +

+

@exclamdown{} ¡ upside-down ! +
@questiondown{} ¿ upside-down ? +
@aa{} @AA{} å Å a,A with circle +
@ae{} @AE{} æ Æ ae,AE ligatures +
@dotless{i} i dotless i +
@dotless{j} j dotless j +
@l{} @L{} /l /L suppressed-L,l +
@o{} @O{} ø Ø O,o with slash +
@oe{} @OE{} œ Œ oe,OE ligatures +
@ordf{} @ordm{} ª º Spanish ordinals +
@ss{} ß es-zet or sharp S +
+ +

+


+Next: , +Previous: Inserting Accents, +Up: Insertions +
+
+ +

14.4 Inserting Ellipsis and Bullets

+ +

+An ellipsis (a line of dots) is not typeset as a string of +periods, so a special command is used for ellipsis in Texinfo. The +@bullet command is special, too. Each of these commands is +followed by a pair of braces, {}, 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 @-Command Syntax, for further information.) + +

+ +
+


+Next: , +Up: Dots Bullets +
+
+ +

14.4.1 @dots{} (...) and @enddots{} (....)

+ +

+Use the @dots{} command to generate an ellipsis, which is +three dots in a row, appropriately spaced ... like so. Do +not simply write three periods in the input file; that would work for +the Info file output, but would produce the wrong amount of space +between the periods in the printed manual. + +

Similarly, the @enddots{} command generates an +end-of-sentence ellipsis, which has different spacing afterwards, +.... Look closely to see the difference. + +

+


+Previous: dots, +Up: Dots Bullets +
+
+ +

14.4.2 @bullet{} (•)

+ +

+Use the @bullet{} command to generate a large round dot, or +the closest possible thing to one. In Info, an asterisk is used. + +

Here is a bullet: • + +

When you use @bullet in @itemize, you do not need to +type the braces, because @itemize supplies them. +(See @itemize.) + +

+


+Next: , +Previous: Dots Bullets, +Up: Insertions +
+
+ +

14.5 Inserting TeX and Legal Symbols: ©, ®

+ +

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, {}, without any whitespace +between the name of the command and the braces. + +

+ +
+


+Next: , +Up: TeX and copyright +
+
+ +

14.5.1 @TeX{} (TeX) and @LaTeX{} (LaTeX)

+ +

+Use the @TeX{} command to generate `TeX'. In a printed +manual, this is a special logo that is different from three ordinary +letters. In Info, it just looks like TeX. + +

Similarly, use the @LaTeX{} command to generate `LaTeX', +which is even more special in printed manuals (and different from the +incorrect La@TeX{}. In Info, the result is just +LaTeX. (LaTeX is another macro package built on top of +TeX, very loosely analogous to Texinfo in that it emphasizes +logical structure, but much (much) larger.) + +

The spelling of these commands are unusual among Texinfo commands in +that they use both uppercase and lowercase letters. + +

+


+Next: , +Previous: tex, +Up: TeX and copyright +
+
+ +

14.5.2 @copyright{} (©)

+ +

+Use the @copyright{} command to generate the copyright +symbol, `©'. Where possible, this is a c +inside a circle; in Info, this is (C). + +

+


+Previous: copyright symbol, +Up: TeX and copyright +
+
+ +

14.5.3 @registeredsymbol{} (®)

+ +

+Use the @registeredsymbol{} command to generate the +registered symbol, `®'. Where possible, this is an +R inside a circle; in Info, this is (R). + +

+


+Next: , +Previous: TeX and copyright, +Up: Insertions +
+
+ +

14.6 @pounds{} (£): Pounds Sterling

+ +

+Use the @pounds{} command to generate `£'. In a +printed manual, this is the symbol for the currency pounds sterling. +In Info, it is a #. Other currency symbols are unfortunately not +available. + +

+


+Next: , +Previous: pounds, +Up: Insertions +
+
+ +

14.7 @minus{} (−): Inserting a Minus Sign

+ +

+Use the @minus{} command to generate a minus sign. In a +fixed-width font, this is a single hyphen, but in a proportional font, +the symbol is the customary length for a minus sign—a little longer +than a hyphen, shorter than an em-dash: + +

      is a minus sign generated with @minus{},
+     
+     `-' is a hyphen generated with the character -,
+     
+     `—' is an em-dash for text.
+
+

In the fixed-width font used by Info, @minus{} is the same +as a hyphen. + +

You should not use @minus{} inside @code or +@example because the width distinction is not made in the +fixed-width font they use. + +

When you use @minus to specify the mark beginning each entry in +an itemized list, you do not need to type the braces +(see @itemize). + +

+


+Next: , +Previous: minus, +Up: Insertions +
+
+ +

14.8 @math: Inserting Mathematical Expressions

+ +

+You can write a short mathematical expression with the @math +command. Write the mathematical expression between braces, like this: + +

     @math{(a + b)(a + b) = a^2 + 2ab + b^2}
+
+

This produces the following in Info and HTML: + +

     (a + b)(a + b) = a^2 + 2ab + b^2
+
+

Thus, the @math command has no effect on the Info and HTML +output; makeinfo just reproduces the input, it does not try +to interpret the mathematics in any way. + +

@math implies @tex. This not only makes it possible to +write superscripts and subscripts (as in the above example), but also +allows you to use any of the plain TeX math control sequences. It's +conventional to use \ instead of @ for these commands. +As in: +

     @math{\sin 2\pi \equiv \cos 3\pi}
+
+

which looks like the input in Info and HTML: +

     \sin 2\pi \equiv \cos 3\pi
+
+

Since \ is an escape character inside @math, you can use +@\ to get a literal backslash (\\ will work in TeX, +but you'll get the literal \\ in Info). @\ is not +defined outside of @math, since a \ ordinarily produces a +literal \. + +

For displayed equations, you must at present use TeX directly +(see Raw Formatter Commands). + +

+


+Previous: math, +Up: Insertions +
+
+ +

14.9 Glyphs for Examples

+ +

+In Texinfo, code is often illustrated in examples that are delimited +by @example and @end example, or by @lisp and +@end lisp. In such examples, you can indicate the results of +evaluation or an expansion using => or +==>. Likewise, there are commands to insert glyphs +to indicate +printed output, error messages, equivalence of expressions, and the +location of point. + +

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

+ +
+


+Next: , +Up: Glyphs +
+
+ +

14.9.1 Glyphs Summary

+ +

Here are the different glyph commands: + +

+
=>
@result{} points to the result of an expression. + +
==>
@expansion{} shows the results of a macro expansion. + +
-|
@print{} indicates printed output. + +
error-->
@error{} indicates that the following text is an error +message. + +
==
@equiv{} indicates the exact equivalence of two forms. + +
-!-
@point{} shows the location of point. +
+ + + +
+


+Next: , +Previous: Glyphs Summary, +Up: Glyphs +
+
+ +

14.9.2 @result{} (=>): Indicating Evaluation

+ +

+Use the @result{} command to indicate the result of +evaluating an expression. + +

The @result{} command is displayed as => in +Info and HTML and as a true double stemmed arrow in the printed output. + +

Thus, the following, + +

     (cdr '(1 2 3))
+         => (2 3)
+
+

may be read as “(cdr '(1 2 3)) evaluates to (2 3)”. + +

+


+Next: , +Previous: result, +Up: Glyphs +
+
+ +

14.9.3 @expansion{} (==>): Indicating an Expansion

+ +

+When an expression is a macro call, it expands into a new expression. +You can indicate the result of the expansion with the +@expansion{} command. + +

The @expansion{} command is displayed as ==> +in Info and HTML, and as a long arrow with a flat base in the printed +output. + +

For example, the following + +

     @lisp
+     (third '(a b c))
+         @expansion{} (car (cdr (cdr '(a b c))))
+         @result{} c
+     @end lisp
+
+

produces + +

     (third '(a b c))
+         ==> (car (cdr (cdr '(a b c))))
+         => c
+
+

which may be read as: + +

+(third '(a b c)) expands to (car (cdr (cdr '(a b c)))); +the result of evaluating the expression is c. +
+ +

Often, as in this case, an example looks better if the +@expansion{} and @result{} commands are indented. + +

+


+Next: , +Previous: expansion, +Up: Glyphs +
+
+ +

14.9.4 @print{} (-|): Indicating Printed Output

+ +

+Sometimes an expression will print output during its execution. You +can indicate the printed output with the @print{} command. + +

The @print{} command is displayed as -| in Info +and HTML and (similarly) as a horizontal dash butting against a +vertical bar in the printed output. + +

In the following example, the printed text is indicated with +-|, and the value of the expression follows on the +last line. + +

     (progn (print 'foo) (print 'bar))
+         -| foo
+         -| bar
+         => bar
+
+

In a Texinfo source file, this example is written as follows: + +

     @lisp
+     (progn (print 'foo) (print 'bar))
+         @print{} foo
+         @print{} bar
+         @result{} bar
+     @end lisp
+
+
+


+Next: , +Previous: Print Glyph, +Up: Glyphs +
+
+ +

14.9.5 @error{} (error-->): Indicating an Error Message

+ +

+A piece of code may cause an error when you evaluate it. You can +designate the error message with the @error{} command. + +

The @error{} command is displayed as error--> in Info +and HTML and as the word `error' in a box in the printed output. + +

Thus, + +

     @lisp
+     (+ 23 'x)
+     @error{} Wrong type argument: integer-or-marker-p, x
+     @end lisp
+
+

produces + +

     (+ 23 'x)
+     error--> Wrong type argument: integer-or-marker-p, x
+
+

This indicates that the following error message is printed +when you evaluate the expression: + +

     Wrong type argument: integer-or-marker-p, x
+
+

error--> itself is not part of the error message. + +

+


+Next: , +Previous: Error Glyph, +Up: Glyphs +
+
+ +

14.9.6 @equiv{} (==): Indicating Equivalence

+ +

+Sometimes two expressions produce identical results. You can indicate the +exact equivalence of two forms with the @equiv{} command. + +

The @equiv{} command is displayed as == in Info +and HTML and as a standard mathematical equivalence sign (three +parallel horizontal lines) in the printed output. + +

Thus, + +

     @lisp
+     (make-sparse-keymap) @equiv{} (list 'keymap)
+     @end lisp
+
+

produces + +

     (make-sparse-keymap) == (list 'keymap)
+
+

This indicates that evaluating (make-sparse-keymap) produces +identical results to evaluating (list 'keymap). + +

+


+Previous: Equivalence, +Up: Glyphs +
+
+ +

14.9.7 @point{} (-!-): Indicating Point in a Buffer

+ +

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

You can use the @point{} 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 between +two characters where point is located.) + +

The @point{} command is displayed as -!- in Info +and HTML and as a small five pointed star in the printed +output. + +

The following example shows the contents of buffer foo before +and after evaluating a Lisp command to insert the word changed. + +

     ---------- Buffer: foo ----------
+     This is the -!-contents of foo.
+     ---------- Buffer: foo ----------
+
+
     (insert "changed ")
+         => nil
+     ---------- Buffer: foo ----------
+     This is the changed -!-contents of foo.
+     ---------- Buffer: foo ----------
+
+

In a Texinfo source file, the example is written like this: + +

     @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
+
+
+


+Next: , +Previous: Insertions, +Up: Top +
+
+ +

15 Forcing and Preventing Breaks

+ +

+Usually, a Texinfo file is processed both by TeX and by one of the +Info formatting commands. Line, paragraph, or page breaks sometimes +occur in the `wrong' place in one or other form of output. You must +ensure that text looks right both in the printed manual and in the +Info file. + +

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

+ +
+


+Next: , +Up: Breaks +
+
+ +

15.1 Break Commands

+ +

The break commands create or allow line and paragraph breaks: + +

+
@*
Force a line break. + +
@sp n
Skip n blank lines. + +
@-
Insert a discretionary hyphen. + +
@hyphenation{hy-phen-a-ted words}
Define hyphen points in hy-phen-a-ted words. +
+ +

These commands hold text together on a single line: + +

+
@w{text}
Prevent text from being split and hyphenated across two lines. +
@tie{}
Insert a normal interword space at which a line break may not occur. +
+ +

The pagination commands apply only to printed output, since Info +files do not have pages. + +

+
@page
Start a new page in the printed manual. + +
@group
Hold text together that must appear on one printed page. + +
@need mils
Start a new printed page if not enough space on this one. +
+ +
+


+Next: , +Previous: Break Commands, +Up: Breaks +
+
+ +

15.2 @* and @/: Generate and Allow Line Breaks

+ +

+The @* command forces a line break in both the printed manual and +in Info. The @/ command allows a line break (printed manual only). + +

Here is an example with @*: + +

     This line @* is broken @*in two places.
+
+

produces + +

     This line
+     is broken
+     in two places.
+
+

The @/ command can be useful within a url +(see @uref), which tend to be long and are otherwise +unbreakable. For example: + +

     The official Texinfo home page is on the GNU web site:
+     @uref{http://www.gnu.org/@/software/@/gnu/@/texinfo}.
+
+

produces + +

     The official Texinfo home page is on the GNU web site:
+     http://www.gnu.org/software/gnu/texinfo.
+
+

Without the @/ commands, TeX would have nowhere to +break the line. @/ has no effect in the online output. + +

+


+Next: , +Previous: Line Breaks, +Up: Breaks +
+
+ +

15.3 @- and @hyphenation: Helping TeX Hyphenate

+ +

+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: + +

+
@-
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 Overfull hboxes). TeX will not insert any hyphenation points itself into a +word containing @-. + +
@hyphenation{hy-phen-a-ted words}
Tell TeX how to hyphenate hy-phen-a-ted words. As shown, you +put a - at each hyphenation point. For example: +
          @hyphenation{man-u-script man-u-scripts}
+     
+

TeX only uses the specified hyphenation points when the +words match exactly, so give all necessary variants. +

+ +

Info output is not hyphenated, so these commands have no effect there. + +

+


+Next: , +Previous: - and hyphenation, +Up: Breaks +
+
+ +

15.4 @w{text}: Prevent Line Breaks

+ +

+@w{text} outputs text and prohibits line breaks +within text, for both TeX and makeinfo. + +

Thus, you can use @w to produce a non-breakable space, fixed at +the width of a normal interword space: + +

     @w{ } @w{ } @w{ } indentation.
+
+

produces: + +

           indentation.
+
+

The space from @w{ }, as well as being non-breakable, +also will not stretch or shrink. Sometimes that is what you want, for +instance if you're doing indenting manual. However, usually you want +a normal interword space that does stretch and shrink (in the printed +output); see the @tie command in the next section. + +

You can also use the @w command to prevent TeX from +automatically hyphenating a long name or phrase that happens to fall +near the end of a line. makeinfo does not ever hyphenate +words. + +

You can also use @w to avoid unwanted keyword expansion in +source control systems. For example, to literally write $Id$ +in your document, use @w{$}Id$. + +

+


+Next: , +Previous: w, +Up: Breaks +
+
+ +

15.5 @tie{}: Inserting an Unbreakable Space

+ +

+The @tie{} 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: + +

     @TeX{} was written by Donald E.@tie{}Knuth.
+
+

produces: + +

     TeX was written by Donald E. Knuth.
+
+

There are two important differences between @tie{} and +@w{ }: + +

+ +
+


+Next: , +Previous: tie, +Up: Breaks +
+
+ +

15.6 @sp n: Insert Blank Lines

+ +

+A line beginning with and containing only @sp n +generates n blank lines of space in both the printed manual and +the Info file. @sp also forces a paragraph break. For +example, + +

     @sp 2
+
+

generates two blank lines. + +

The @sp command is most often used in the title page. + +

+


+Next: , +Previous: sp, +Up: Breaks +
+
+ +

15.7 @page: Start a New Page

+ +

+A line containing only @page starts a new page in a printed +manual. The command has no effect on Info files since they are not +paginated. An @page command is often used in the @titlepage +section of a Texinfo file to start the copyright page. + +

+


+Next: , +Previous: page, +Up: Breaks +
+
+ + +

15.8 @group: Prevent Page Breaks

+ +

+The @group command (on a line by itself) is used inside an +@example 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 @end group. +These two lines produce no output of their own, and in the Info file +output they have no effect at all. + + + + +

Although @group would make sense conceptually in a wide +variety of contexts, its current implementation works reliably only +within @example and variants, and within @display, +@format, @flushleft and @flushright. +See Quotations and Examples. (What all these commands have in +common is that each line of input produces a line of output.) In +other contexts, @group can cause anomalous vertical +spacing. + +

This formatting requirement means that you should write: + +

     @example
+     @group
+     ...
+     @end group
+     @end example
+
+

with the @group and @end group commands inside the +@example and @end example commands. + +

The @group 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 @group and @end +group. + +

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 +@end group if you get incomprehensible error messages in +TeX. + +

+


+Previous: group, +Up: Breaks +
+
+ + +

15.9 @need mils: Prevent Page Breaks

+ +

+A line containing only @need n starts +a new page in a printed manual if fewer than n mils (thousandths +of an inch) remain on the current page. Do not use +braces around the argument n. The @need command has no +effect on Info files since they are not paginated. + +

This paragraph is preceded by an @need 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: + +

     @need 800
+     This paragraph is preceded by ...
+
+

The @need command is useful for preventing orphans (single +lines at the bottoms of printed pages). + +

+


+Next: , +Previous: Breaks, +Up: Top +
+
+ +

16 Definition Commands

+ +

+The @deffn command and the other definition commands +enable you to describe functions, variables, macros, commands, user +options, special forms and other such artifacts in a uniform +format. + +

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: +@deffn enters the name into the index of functions, +@defvr enters it into the index of variables, and so +on (see Predefined Indices). + +

A manual need not and should not contain more than one definition for +a given name. An appendix containing a summary should use +@table rather than the definition commands. + +

+ +
+


+Next: , +Up: Definition Commands +
+
+ +

16.1 The Template for a Definition

+ +

+The @deffn command is used for definitions of entities that +resemble functions. To write a definition using the @deffn +command, write the @deffn 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 @end deffn command +written on a line of its own. + +

The other definition commands follow the same format: a line with the +@def... command and whatever arguments are appropriate for +that command; the body of the definition; and a corresponding +@end line. + +

The template for a definition looks like this: + +

     @deffn category name arguments...
+     body-of-definition
+     @end deffn
+
+

For example, + +

     @deffn Command forward-word count
+     This command moves point forward @var{count} words
+     (or backward if @var{count} is negative). ...
+     @end deffn
+
+

produces + +

+ +
+— Command: forward-word count
+

This function moves point forward count words +(or backward if count is negative). ... +

+
+ +

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: + +

     @deffn {Interactive Command} isearch-forward
+     ...
+     @end deffn
+
+

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 except the last one are more than one word, you need to +enclose them in braces. + +

Some of the definition commands are more general than others. The +@deffn command, for example, is the general definition command +for functions and the like—for entities that may take arguments. +When you use this command, you specify the category to which the +entity belongs. Three predefined, specialized variations +(@defun, @defmac, and @defspec) specify the +category for you: “Function”, “Macro”, and “Special Form” +respectively. (In Lisp, a special form is an entity much like a +function.) Similarly, the general @defvr command is +accompanied by several specialized variations for describing +particular kinds of variables. + +

See Sample Function Definition, for a detailed example of a +function definition, including the use of @example inside the +definition. + +

Unfortunately, due to implementation difficulties, macros are not expanded +in @deffn and all the other definition commands. + +

+


+Next: , +Previous: Def Cmd Template, +Up: Definition Commands +
+
+ +

16.2 Definition Command Continuation Lines

+ +

+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 @ at the end of +each line to be continued. Here's an example: + +

     @defun fn-name @
+       arg1 arg2 arg3
+     This is the basic continued defun.
+     @end defun
+
+

produces: + +

+— Function: fn-name arg1 arg2 arg3
+

This is the basic continued defun. +

+ +

As you can see, the continued lines are combined, as if they had been +typed on one source line. + +

Although this example only shows a one-line continuation, +continuations may extend over any number of lines; simply put an +@ at the end of each line to be continued. + +

The @ character does not have to be the last character on the +physical line: whitespace is allowed (and ignored) afterwards. + +

In general, any number of spaces or tabs around the @ +continuation character, both on the line with the @ 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: + +

     @deffn {Category @
+       Name} ...
+
+

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 @ outside braces. + +

@ does not (currently) function as a continuation character in +any other context. Ordinarily, @ followed by a +whitespace character (space, tab, newline) produces a normal interword +space (see Multiple Spaces). + +

+


+Next: , +Previous: Def Cmd Continuation Lines, +Up: Definition Commands +
+
+ +

16.3 Optional and Repeated Arguments

+ +

+Some entities take optional or repeated arguments, which may be +specified by a distinctive glyph that uses square brackets and +ellipses. For example, a special form often breaks its argument list +into separate arguments in more complicated ways than a +straightforward function. + + +

An argument enclosed within square brackets is optional. +Thus, [optional-arg] means that optional-arg is optional. +An argument followed by an ellipsis is optional +and may be repeated more than once. + +Thus, repeated-args... stands for zero or more +arguments. Parentheses are used when several arguments are grouped +into additional levels of list structure in Lisp. + +

Here is the @defspec line of an example of an imaginary +special form: + +

+ +
+— Special Form: foobar (var [from to [inc]]) body...
+
+
+ +

In this example, the arguments from and to are optional, +but must both be present or both absent. If they are present, +inc may optionally be specified as well. These arguments are +grouped with the argument var into a list, to distinguish them +from body, which includes all remaining elements of the +form. + +

In a Texinfo source file, this @defspec line is written like +this (except it would not be split over two lines, as it is in this +example). + +

     @defspec foobar (@var{var} [@var{from} @var{to}
+         [@var{inc}]]) @var{body}@dots{}
+
+

The function is listed in the Command and Variable Index under +foobar. + +

+


+Next: , +Previous: Optional Arguments, +Up: Definition Commands +
+
+ +

16.4 Two or More `First' Lines

+ +

+To create two or more `first' or header lines for a definition, follow +the first @deffn line by a line beginning with @deffnx. +The @deffnx command works exactly like @deffn +except that it does not generate extra vertical white space between it +and the preceding line. + +

For example, + +

     @deffn {Interactive Command} isearch-forward
+     @deffnx {Interactive Command} isearch-backward
+     These two search commands are similar except ...
+     @end deffn
+
+

produces + +

+— Interactive Command: isearch-forward
+— Interactive Command: isearch-backward
+

These two search commands are similar except ... +

+ +

Each definition command has an `x' form: @defunx, +@defvrx, @deftypefunx, etc. + +

The `x' forms work similarly to @itemx (see itemx). + +

+


+Next: , +Previous: deffnx, +Up: Definition Commands +
+
+ +

16.5 The Definition Commands

+ +

Texinfo provides more than a dozen definition commands, all of which +are described in this section. + +

The definition commands automatically enter the name of the entity in +the appropriate index: for example, @deffn, @defun, +and @defmac enter function names in the index of functions; +@defvr and @defvar enter variable names in the index +of variables. + +

Although the examples that follow mostly illustrate Lisp, the commands +can be used for other programming languages. + +

+ +
+


+Next: , +Up: Def Cmds in Detail +
+
+ +

16.5.1 Functions and Similar Entities

+ +

This section describes the commands for describing functions and similar +entities: + + + +

@deffn category name arguments...
The @deffn 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 @deffn 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 @end deffn on a line of its +own. + +

For example, here is a definition: + +

          @deffn Command forward-char nchars
+          Move point forward @var{nchars} characters.
+          @end deffn
+     
+

This shows a rather terse definition for a “command” named +forward-char with one argument, nchars. + +

@deffn and prints argument names such as nchars in slanted +type in the printed output, because we think of these names as +metasyntactic variables—they stand for the actual argument values. +Within the text of the description, however, write an argument name +explicitly with @var to refer to the value of the argument. +In the example above, we used @var{nchars} in this way. + +

In the unusual case when an argument name contains --, or +another character sequence which is treated specially +(see Conventions), use @var around the argument. This +causes the name to be printed in slanted typewriter, instead of the +regular slanted font, exactly as input. + + +

The template for @deffn is: + +

          @deffn category name arguments...
+          body-of-definition
+          @end deffn
+     
+


@defun name arguments...
The @defun command is the definition command for functions. +@defun is equivalent to @deffn Function .... +Terminate the definition with @end defun on a line of its own. +Thus, the template is: + +
          @defun function-name arguments...
+          body-of-definition
+          @end defun
+     
+


@defmac name arguments...
The @defmac command is the definition command for macros. +@defmac is equivalent to @deffn Macro ... and +works like @defun. + +


@defspec name arguments...
The @defspec command is the definition command for special +forms. (In Lisp, a special form is an entity much like a function, +see Special Forms (GNU Emacs Lisp Reference Manual).) +@defspec is equivalent to @deffn {Special Form} +... and works like @defun. +
+ +

All these commands create entries in the index of functions. + +

+


+Next: , +Previous: Functions Commands, +Up: Def Cmds in Detail +
+
+ +

16.5.2 Variables and Similar Entities

+ +

Here are the commands for defining variables and similar +entities: + + + +

@defvr category name
The @defvr 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 @defvr 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. + +

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, + +

          @defvr {User Option} fill-column
+          This buffer-local variable specifies
+          the maximum width of filled lines.
+          ...
+          @end defvr
+     
+

Terminate the definition with @end defvr on a line of its +own. + +

The template is: + +

          @defvr category name
+          body-of-definition
+          @end defvr
+     
+

@defvr creates an entry in the index of variables for name. + +


@defvar name
The @defvar command is the definition command for variables. +@defvar is equivalent to @defvr Variable +.... + +

For example: + +

          @defvar kill-ring
+          ...
+          @end defvar
+     
+

The template is: + +

          @defvar name
+          body-of-definition
+          @end defvar
+     
+

@defvar creates an entry in the index of variables for +name. + +


@defopt name
The @defopt command is the definition command for user +options, i.e., variables intended for users to change according to +taste; Emacs has many such (see Variables (The GNU Emacs Manual)). @defopt is equivalent to @defvr {User +Option} ... and works like @defvar. It creates an entry +in the index of variables. +
+ +
+


+Next: , +Previous: Variables Commands, +Up: Def Cmds in Detail +
+
+ +

16.5.3 Functions in Typed Languages

+ +

The @deftypefn 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++. + + + +

@deftypefn category data-type name arguments...
The @deftypefn command is the general definition command for +functions and similar entities that may take arguments and that are +typed. The @deftypefn 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. + +

For example, + +

          @deftypefn {Library Function} int foobar
+            (int @var{foo}, float @var{bar})
+          ...
+          @end deftypefn
+     
+

(where the text before the “...”, shown above as two lines, would +actually be a single line in a real Texinfo file) produces the following +in Info: + +

          -- Library Function: int foobar (int FOO, float BAR)
+          ...
+     
+

This means that foobar is a “library function” that returns an +int, and its arguments are foo (an int) and +bar (a float). + +

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 +@var for the variable names, which will uppercase the +variable names in Info and use the slanted typewriter font in printed +output; (c) use @var for the variable names and +@code for the type names and keywords, which will be dutifully +obeyed. + +

The template for @deftypefn is: + +

          @deftypefn category data-type name arguments ...
+          body-of-description
+          @end deftypefn
+     
+

Note that if the category or data type is more than one +word then it must be enclosed in braces to make it a single argument. + +

If you are describing a procedure in a language that has packages, +such as Ada, you might consider using @deftypefn in a manner +somewhat contrary to the convention described in the preceding +paragraphs. For example: + +

          @deftypefn stacks private push @
+                 (@var{s}:in out stack; @
+                 @var{n}:in integer)
+          ...
+          @end deftypefn
+     
+

(The @deftypefn arguments are shown using continuations +(see Def Cmd Continuation Lines), but could be on a single line in +a real Texinfo file.) + +

In this instance, the procedure is classified as belonging to the +package stacks rather than classified as a `procedure' and its +data type is described as private. (The name of the procedure +is push, and its arguments are s and n.) + +

@deftypefn creates an entry in the index of functions for +name. + +

@deftypefun data-type name arguments...
The @deftypefun command is the specialized definition command +for functions in typed languages. The command is equivalent to +@deftypefn Function .... The template is: + +
          @deftypefun type name arguments...
+          body-of-description
+          @end deftypefun
+     
+

@deftypefun creates an entry in the index of functions for +name. + +

+ +
+


+Next: , +Previous: Typed Functions, +Up: Def Cmds in Detail +
+
+ +

16.5.4 Variables in Typed Languages

+ +

Variables in typed languages are handled in a manner similar to +functions in typed languages. See Typed Functions. The general +definition command @deftypevr corresponds to +@deftypefn and the specialized definition command +@deftypevar corresponds to @deftypefun. + + + +

@deftypevr category data-type name
The @deftypevr 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. + +

The @deftypevr 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. + +

For example: + +

          @deftypevr {Global Flag} int enable
+          ...
+          @end deftypevr
+     
+

produces the following in Info: + +

          -- Global Flag: int enable
+          ...
+     
+

The template is: + +

          @deftypevr category data-type name
+          body-of-description
+          @end deftypevr
+     
+


@deftypevar data-type name
The @deftypevar command is the specialized definition command +for variables in typed languages. @deftypevar is equivalent +to @deftypevr Variable .... The template is: + +
          @deftypevar data-type name
+          body-of-description
+          @end deftypevar
+     
+
+ +

These commands create entries in the index of variables. + +

+


+Next: , +Previous: Typed Variables, +Up: Def Cmds in Detail +
+
+ +

16.5.5 Data Types

+ +

Here is the command for data types: + + + +

@deftp category name attributes...
The @deftp command is the generic definition command for data +types. The command is written at the beginning of a line and is +followed on the same line by the category, by the name of the type +(which is a word like int or float), and then by names of +attributes of objects of that type. Thus, you could use this command +for describing int or float, in which case you could use +data type as the category. (A data type is a category of +certain objects for purposes of deciding which operations can be +performed on them.) + +

In Lisp, for example, pair names a particular data +type, and an object of that type has two slots called the +car and the cdr. Here is how you would write the first line +of a definition of pair. + +

          @deftp {Data type} pair car cdr
+          ...
+          @end deftp
+     
+

The template is: + +

          @deftp category name-of-type attributes...
+          body-of-definition
+          @end deftp
+     
+

@deftp creates an entry in the index of data types. +

+ +
+


+Previous: Data Types, +Up: Def Cmds in Detail +
+
+ +

16.5.6 Object-Oriented Programming

+ +

+Here are the commands for formatting descriptions about abstract +objects, such as are used in object-oriented programming. A class is +a defined type of abstract object. An instance of a class is a +particular object that has the type of the class. An instance +variable is a variable that belongs to the class but for which each +instance has its own value. + +

+ +
+


+Next: , +Up: Abstract Objects +
+
+ +
16.5.6.1 Object-Oriented Variables
+ +

+These commands allow you to define different sorts of variables in +object-oriented programming languages. + +

+
@defcv category class name
The @defcv command is the general definition command for +variables associated with classes in object-oriented programming. The +@defcv command is followed by three arguments: the category of +thing being defined, the class to which it belongs, and its +name. For instance: + +
          @defcv {Class Option} Window border-pattern
+          ...
+          @end defcv
+     
+

produces: + +

+— Class Option of Window: border-pattern
+
... +
+ +

@defcv creates an entry in the index of variables. + +

@deftypecv category class data-type name
The @deftypecv command is the definition command for typed +class variables in object-oriented programming. It is analogous to +@defcv with the addition of the data-type parameter to +specify the type of the instance variable. Ordinarily, the data type +is a programming language construct that should be marked with +@code. For instance: + +
          @deftypecv {Class Option} Window @code{int} border-pattern
+          ...
+          @end deftypecv
+     
+

produces: + +

+— Class Option of Window: int border-pattern
+
... +
+ +

@deftypecv creates an entry in the index of variables. + +

@defivar class name
The @defivar command is the definition command for instance +variables in object-oriented programming. @defivar is +equivalent to @defcv {Instance Variable} .... For +instance: + +
          @defivar Window border-pattern
+          ...
+          @end defivar
+     
+

produces: + +

+— Instance Variable of Window: border-pattern
+
... +
+ +

@defivar creates an entry in the index of variables. + +

@deftypeivar class data-type name
The @deftypeivar command is the definition command for typed +instance variables in object-oriented programming. It is analogous to +@defivar with the addition of the data-type parameter to +specify the type of the instance variable. Ordinarily, the data type +is a programming language construct that should be marked with +@code. For instance: + +
          @deftypeivar Window @code{int} border-pattern
+          ...
+          @end deftypeivar
+     
+

produces: + +

+— Instance Variable of Window: int border-pattern
+
... +
+ +

@deftypeivar creates an entry in the index of variables. + +

+ +
+


+Previous: Object-Oriented Variables, +Up: Abstract Objects +
+
+ +
16.5.6.2 Object-Oriented Methods
+ +

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

@defop category class name arguments...
The @defop command is the general definition command for these +method-like entities. + +

For example, some systems have constructs called wrappers that +are associated with classes as methods are, but that act more like +macros than like functions. You could use @defop Wrapper to +describe one of these. + +

Sometimes it is useful to distinguish methods and operations. +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 expose; we would say that this window system +defines an expose 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. + +

Often it makes more sense to document operations than methods. For +example, window application developers need to know about the +expose 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: + +

          @defop Operation windows expose
+     
+

The @defop 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. + +

The template is: +

          @defop category class name arguments...
+          body-of-definition
+          @end defop
+     
+

@defop creates an entry, such as `expose on +windows', in the index of functions. + +


@deftypeop category class data-type name arguments...
The @deftypeop command is the definition command for typed +operations in object-oriented programming. It is similar to +@defop with the addition of the data-type parameter to +specify the return type of the method. @deftypeop creates an +entry in the index of functions. + +
@defmethod class name arguments...
The @defmethod 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. + +

@defmethod is equivalent to @defop Method .... +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. + +

For example: +

          @defmethod bar-class bar-method argument
+          ...
+          @end defmethod
+     
+

illustrates the definition for a method called bar-method of +the class bar-class. The method takes an argument. + +

@defmethod creates an entry in the index of functions. + +

@deftypemethod class data-type name arguments...
The @deftypemethod command is the definition command for methods +in object-oriented typed languages, such as C++ and Java. It is similar +to the @defmethod command with the addition of the +data-type parameter to specify the return type of the method. +@deftypemethod creates an entry in the index of functions. + +
+ +
+


+Next: , +Previous: Def Cmds in Detail, +Up: Definition Commands +
+
+ +

16.6 Conventions for Writing Definitions

+ +

+When you write a definition using @deffn, @defun, or +one of the other definition commands, please take care to use +arguments that indicate the meaning, as with the count argument +to the forward-word function. Also, if the name of an argument +contains the name of a type, such as integer, take care that the +argument actually is of that type. + +

+


+Previous: Def Cmd Conventions, +Up: Definition Commands +
+
+ +

16.7 A Sample Function Definition

+ +

+A function definition uses the @defun and @end defun +commands. The name of the function follows immediately after the +@defun command and it is followed, on the same line, by the +parameter list. + +

Here is a definition from Calling Functions (The GNU Emacs Lisp Reference Manual). + +

+ +
+— Function: apply function &rest arguments
+

apply calls function with arguments, just +like funcall but with one difference: the last of +arguments is a list of arguments to give to +function, rather than a single argument. We also say +that this list is appended to the other arguments. + +

apply returns the result of calling function. +As with funcall, function must either be a Lisp +function or a primitive function; special forms and macros +do not make sense in apply. + +

               (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)
+          
+

An interesting example of using apply is found in the description +of mapcar. +

+
+ +

In the Texinfo source file, this example looks like this: + +

     @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
+
+

In this manual, this function is listed in the Command and Variable +Index under apply. + +

Ordinary variables and user options are described using a format like +that for functions except that variables do not take arguments. + +

+


+Next: , +Previous: Definition Commands, +Up: Top +
+
+ +

17 Conditionally Visible Text

+ +

+The conditional commands allow you to use different text for +different output formats, or for general conditions that you define. +For example, you can use them to specify different text for the +printed manual and the Info output. + +

The conditional commands comprise the following categories. + +

+ + + +
+


+Next: , +Up: Conditionals +
+
+ +

17.1 Conditional Commands

+ +

Texinfo has an @ifformat environment for each output +format, to allow conditional inclusion of text for a particular output +format. + +

@ifinfo begins segments of text that should be ignored by +TeX when it typesets the printed manual, and by makeinfo +when not producing Info output. The segment of text appears only in +the Info file and, for historical compatibility, the plain text +output. + +

The environments for the other formats are analogous: + +

+
@ifdocbook ... @end ifdocbook
Text to appear only in the Docbook output. + +
@ifhtml ... @end ifhtml
Text to appear only in the HTML output. + +
@ifplaintext ... @end ifplaintext
Text to appear only in the plain text output. + +
@iftex ... @end iftex
Text to appear only in the printed manual. + +
@ifxml ... @end ifxml
Text to appear only in the XML output. +
+ +

The @if... and @end if... commands must appear +on lines by themselves in your source file. + +

Here is an example showing all these conditionals: + +

     @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
+
+

The preceding example produces the following line: + +

And this text will only appear in HTML. + +

Notice that you only see one of the input lines, depending on which +version of the manual you are reading. + +

+


+Next: , +Previous: Conditional Commands, +Up: Conditionals +
+
+ +

17.2 Conditional Not Commands

+ +

+You can specify text to be included in any output format other +than a given one with the @ifnot... environments: + +

     @ifnotdocbook ... @end ifnotdocbook
+     @ifnothtml ... @end ifnothtml
+     @ifnotinfo ... @end ifnotinfo
+     @ifnotplaintext ... @end ifnotplaintext
+     @ifnottex ... @end ifnottex
+     @ifnotxml ... @end ifnotxml
+
+

The @ifnot... command and the @end command must +appear on lines by themselves in your actual source file. + +

If the output file is being made in the given format, the +region is ignored. Otherwise, it is included. + +

There is one exception (for historical compatibility): +@ifnotinfo text is omitted for both Info and plain text +output, not just Info. To specify text which appears only in Info and +not in plain text, use @ifnotplaintext, like this: + +

     @ifinfo
+     @ifnotplaintext
+     This will be in Info, but not plain text.
+     @end ifnotplaintext
+     @end ifinfo
+
+

The regions delimited by these commands are ordinary Texinfo source as +with @iftex, not raw formatter source as with @tex +(see Raw Formatter Commands). + +

+


+Next: , +Previous: Conditional Not Commands, +Up: Conditionals +
+
+ +

17.3 Raw Formatter Commands

+ +

+Inside a region delineated by @iftex and @end iftex, +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 \ used by TeX with an +@. For example, in the @titlepage section of a +Texinfo file, you can use the TeX command @vskip to format +the copyright page. (The @titlepage command causes Info to +ignore the region automatically, as it does with the @iftex +command.) + +

However, most features of plain TeX will not work within +@iftex, as they are overridden by Texinfo features. The +purpose of @iftex is to provide conditional processing for the +Texinfo source, not provide access to underlying formatting features. + +

You can enter plain TeX completely, and use \ in the TeX +commands, by delineating a region with the @tex and @end +tex commands. All plain TeX commands and category codes are +restored within an @tex region. The sole exception is that the +@ character still introduces a command, so that @end tex +can be recognized properly. As with @iftex, Texinfo +processors will ignore such a region unless TeX output is being produced. + +

In complex cases, you may wish to define new TeX macros within +@tex. You must use \gdef to do this, not \def, +because @tex regions are processed in a TeX group. + +

As an example, here is a mathematical expression written in plain TeX: + +

     @tex
+     $$ \chi^2 = \sum_{i=1}^N
+              \left (y_i - (a + b x_i)
+              \over \sigma_i\right)^2 $$
+     @end tex
+
+

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

Analogously, you can use @ifhtml ... @end ifhtml to delimit +a region to be included in HTML output only, and @html ... +@end html for a region of raw HTML. + +

Likewise, you can use @ifxml ... @end ifxml to delimit +a region to be included in XML output only, and @xml ... +@end xml for a region of raw XML. + +

Again likewise, you can use @ifdocbook ... @end ifdocbook +to delimit a region to be included in Docbook output only, and +@docbook ... @end docbook for a region of raw Docbook. + +

In all cases, the exception to the raw processing is that @ is +still an escape character, so the @end command can be +recognized. + +

+


+Next: , +Previous: Raw Formatter Commands, +Up: Conditionals +
+
+ +

17.4 @set, @clear, and @value

+ +

You can direct the Texinfo formatting commands to format or ignore parts +of a Texinfo file with the @set, @clear, @ifset, +and @ifclear commands. + +

Here are brief descriptions of these commands, see the following +sections for more details: + +

+
@set flag [value]
Set the variable flag, to the optional value if specifed. + +
@clear flag
Undefine the variable flag, whether or not it was previously defined. + +
@ifset flag
If flag is set, text through the next @end ifset command +is formatted. If flag is clear, text through the following +@end ifset command is ignored. + +
@ifclear flag
If flag is set, text through the next @end ifclear command +is ignored. If flag is clear, text through the following +@end ifclear command is formatted. +
+ + + +
+


+Next: , +Up: set clear value +
+
+ +

17.4.1 @set and @value

+ +

+You use the @set command to specify a value for a flag, which +is later expanded by the @value command. + +

A flag (aka variable) is an identifier. It is best to use +only letters and numerals in a flag name, not - or +_—they will work in some contexts, but not all, due to +limitations in TeX. + +

The value is the remainder of the input line, and can contain anything. + +

Write the @set command like this: + +

     @set foo This is a string.
+
+

This sets the value of the flag foo to “This is a string.”. + +

The Texinfo formatters then replace an @value{flag} +command with the string to which flag is set. Thus, when +foo is set as shown above, the Texinfo formatters convert this: + +

     @value{foo}
+
to this:
+ This is a string. +
+

You can write an @value command within a paragraph; but you +must write an @set command on a line of its own. + +

If you write the @set command like this: + +

     @set foo
+
+

without specifying a string, the value of foo is the empty string. + +

If you clear a previously set flag with @clear flag, a +subsequent @value{flag} command will report an error. + +

For example, if you set foo as follows: + +

     @set howmuch very, very, very
+
+

then the formatters transform + +

     It is a @value{howmuch} wet day.
+
into
+ It is a very, very, very wet day. +
+

If you write + +

     @clear howmuch
+
+

then the formatters transform + +

     It is a @value{howmuch} wet day.
+
into
+ It is a {No value for "howmuch"} wet day. +
+
+


+Next: , +Previous: set value, +Up: set clear value +
+
+ +

17.4.2 @ifset and @ifclear

+ +

When a flag is set, the Texinfo formatting commands format text +between subsequent pairs of @ifset flag and @end +ifset commands. When the flag is cleared, the Texinfo formatting +commands do not format the text. @ifclear operates +analogously. + +

Write the conditionally formatted text between @ifset flag +and @end ifset commands, like this: + +

     @ifset flag
+     conditional-text
+     @end ifset
+
+

For example, you can create one document that has two variants, such as +a manual for a `large' and `small' model: + +

+

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

In the example, the formatting commands will format the text between +@ifset large and @end ifset because the large +flag is set. + +

When flag is cleared, the Texinfo formatting commands do +not format the text between @ifset flag and +@end ifset; that text is ignored and does not appear in either +printed or Info output. + +

For example, if you clear the flag of the preceding example by writing +an @clear large command after the @set large command +(but before the conditional text), then the Texinfo formatting commands +ignore the text between the @ifset large and @end ifset +commands. In the formatted output, that text does not appear; in both +printed and Info output, you see only the lines that say, “You can use +this machine to dig up shrubs without hurting them. Remember to replant +promptly ...”. + +

If a flag is cleared with an @clear flag command, then +the formatting commands format text between subsequent pairs of +@ifclear and @end ifclear commands. But if the flag +is set with @set flag, then the formatting commands do +not format text between an @ifclear and an @end +ifclear command; rather, they ignore that text. An @ifclear +command looks like this: + +

     @ifclear flag
+
+
+


+Previous: ifset ifclear, +Up: set clear value +
+
+ +

17.4.3 @value Example

+ +

You can use the @value command to minimize the number of +places you need to change when you record an update to a manual. +See GNU Sample Texts, for the full text of an example of using this +to work with Automake distributions. + +

This example is adapted from Overview (The GNU Make Manual). + +

    +
  1. Set the flags: + +
              @set EDITION 0.35 Beta
    +          @set VERSION 3.63 Beta
    +          @set UPDATED 14 August 1992
    +          @set UPDATE-MONTH August 1992
    +     
    +
  2. Write text for the @copying section (see copying): + +
              @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
    +     
    +
  3. Write text for the title page, for people reading the printed manual: + +
              @titlepage
    +          @title GNU Make
    +          @subtitle A Program for Directing Recompilation
    +          @subtitle Edition @value{EDITION}, ...
    +          @subtitle @value{UPDATE-MONTH}
    +          @page
    +          @insertcopying
    +          ...
    +          @end titlepage
    +     
    +

    (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.) + +

  4. Write text for the Top node, for people reading the Info file: + +
              @ifnottex
    +          @node Top
    +          @top Make
    +          
    +          @insertcopying
    +          ...
    +          @end ifnottex
    +     
    +

    After you format the manual, the @value constructs have been +expanded, so the output contains text like this: + +

              This is Edition 0.35 Beta, last updated 14 August 1992,
    +          of `The GNU Make Manual', for `make', Version 3.63 Beta.
    +     
    +
+ +

When you update the manual, you change only the values of the flags; you +do not need to edit the three sections. + +

+


+Previous: set clear value, +Up: Conditionals +
+
+ +

17.5 Conditional Nesting

+ +

+Conditionals can be nested; however, the details are a little tricky. +The difficulty comes with failing conditionals, such as +@ifhtml when HTML is not being produced, where the included +text is to be ignored. However, it is not to be completely +ignored, since it is useful to have one @ifset inside another, +for example—that is a way to include text only if two conditions are +met. Here's an 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
+
+

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 +all conditionals are properly nested, because then the +processors could have to fully interpret the ignored text, which +defeats the purpose of the command. Here's an example illustrating +these rules: + +

     @ifset a
+     @ifset b
+     @ifclear ok  - ok, ignored
+     @end junky   - ok, ignored
+     @end ifset
+     @c WRONG - missing @end ifset.
+
+

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

+


+Next: , +Previous: Conditionals, +Up: Top +
+
+ +

18 Internationalization

+ +

Texinfo has some support for writing in languages other than English, +although this area still needs considerable work. + +

For a list of the various accented and special characters Texinfo +supports, see Inserting Accents. + +

+ +
+


+Next: , +Up: Internationalization +
+
+ +

18.1 @documentlanguage cc: Set the Document Language

+ +

+The @documentlanguage command declares the current document +language. Write it on a line by itself, with a two-letter ISO-639 +language code following (list is included below). If you have a +multilingual document, the intent is to be able to use this command +multiple times, to declare each language change. If the command is not +used at all, the default is en for English. + +

At present, this command is ignored in Info and HTML output. For +TeX, it causes the file txi-cc.tex to be read (if it +exists). Such a file appropriately redefines the various English words +used in TeX output, such as `Chapter', `See', and so on. + +

It would be good if this command also changed TeX's ideas of the +current hyphenation patterns (via the TeX primitive +\language), but this is unfortunately not currently implemented. + +

Hereare the valid language codes, from ISO-639. + +

aa Afar +ab Abkhazian +af Afrikaans +
am Amharic +ar Arabic +as Assamese +
ay Aymara +az Azerbaijani +ba Bashkir +
be Byelorussian +bg Bulgarian +bh Bihari +
bi Bislama +bn Bengali; Bangla +bo Tibetan +
br Breton +ca Catalan +co Corsican +
cs Czech +cy Welsh +da Danish +
de German +dz Bhutani +el Greek +
en English +eo Esperanto +es Spanish +
et Estonian +eu Basque +fa Persian +
fi Finnish +fj Fiji +fo Faroese +
fr French +fy Frisian +ga Irish +
gd Scots Gaelic +gl Galician +gn Guarani +
gu Gujarati +ha Hausa +he Hebrew +
hi Hindi +hr Croatian +hu Hungarian +
hy Armenian +ia Interlingua +id Indonesian +
ie Interlingue +ik Inupiak +is Icelandic +
it Italian +iu Inuktitut +ja Japanese +
jw Javanese +ka Georgian +kk Kazakh +
kl Greenlandic +km Cambodian +kn Kannada +
ks Kashmiri +ko Korean +ku Kurdish +
ky Kirghiz +la Latin +ln Lingala +
lt Lithuanian +lo Laothian +lv Latvian, Lettish +
mg Malagasy +mi Maori +mk Macedonian +
ml Malayalam +mn Mongolian +mo Moldavian +
mr Marathi +ms Malay +mt Maltese +
my Burmese +na Nauru +ne Nepali +
nl Dutch +no Norwegian +oc Occitan +
om (Afan) Oromo +or Oriya +pa Punjabi +
pl Polish +ps Pashto, Pushto +pt Portuguese +
qu Quechua +rm Rhaeto-Romance +rn Kirundi +
ro Romanian +ru Russian +rw Kinyarwanda +
sa Sanskrit +sd Sindhi +sg Sangro +
sh Serbo-Croatian +si Sinhalese +sk Slovak +
sl Slovenian +sm Samoan +sn Shona +
so Somali +sq Albanian +sr Serbian +
ss Siswati +st Sesotho +su Sundanese +
sv Swedish +sw Swahili +ta Tamil +
te Telugu +tg Tajik +th Thai +
ti Tigrinya +tk Turkmen +tl Tagalog +
tn Setswana +to Tonga +tr Turkish +
ts Tsonga +tt Tatar +tw Twi +
ug Uighur +uk Ukrainian +ur Urdu +
uz Uzbek +vi Vietnamese +vo Volapuk +
wo Wolof +xh Xhosa +yi Yiddish +
yo Yoruba +za Zhuang +zh Chinese +
zu Zulu +
+ +

+


+Previous: documentlanguage, +Up: Internationalization +
+
+ +

18.2 @documentencoding enc: Set Input Encoding

+ +

+The @documentencoding command declares the input document +encoding. Write it on a line by itself, with a valid encoding +specification following. + +

At present, Texinfo supports only three encodings: + +

+
US-ASCII
This has no particular effect, but it's included for completeness. +
ISO-8859-1
ISO-8859-2
These specify the standard encodings for Western European and +Eastern European languages, respectively. A full description of the +encodings is beyond our scope here; +http://czyborra.com/charsets/iso8859.html is one of many useful +references. +
+ +

Specifying an encoding enc has the following effects: + +

In Info output, if the option --enable-encoding is also given +to makeinfo, a so-called `Local Variables' section +(see File Variables (The GNU Emacs Manual)) is output +including enc. This allows Info readers to set the encoding +appropriately: + +

     Local Variables:
+     coding: enc
+     End:
+
+

In HTML output, a <meta> tag is output, in the <head> +section of the HTML, that specifies enc. Web servers and +browsers cooperate to use this information so the correct encoding is +used to display the page. + +

     <meta http-equiv="Content-Type" content="text/html;
+          charset=enc">
+
+

In all other cases, it is recognized but ignored. + +

+


+Next: , +Previous: Internationalization, +Up: Top +
+
+ +

19 Defining New Texinfo Commands

+ +

+Texinfo provides several ways to define new commands: + +

+ + + +
+


+Next: , +Up: Defining New Texinfo Commands +
+
+ +

19.1 Defining Macros

+ +

+You use the Texinfo @macro command to define a macro, like this: + +

     @macro macroname{param1, param2, ...}
+     text ... \param1\ ...
+     @end macro
+
+

The parameters param1, param2, ... correspond to +arguments supplied when the macro is subsequently used in the document +(described in the next section). + +

For a macro to work consistently with TeX, macroname must +consist entirely of letters: no digits, hyphens, underscores, or other +special characters. So, we recommend using only letters. However, +makeinfo will accept anything except {}_^=; +_ and ^ are excluded so that macros can be called in +@math mode without a following space +(see @math). + +

If a macro needs no parameters, you can define it either with an empty +list (@macro foo {}) or with no braces at all (@macro +foo). + +

The definition or body 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 +@macro. + +

In the macro body, instances of a parameter name surrounded by +backslashes, as in \param1\ 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. + +

To get a single \ in the macro expansion, use \\. Any +other use of \ in the body yields a warning. + +

The newlines after the @macro line and before the @end +macro line are ignored, that is, not included in the macro body. All +other whitespace is treated according to the usual Texinfo rules. + +

To allow a macro to be used recursively, that is, in an argument to a +call to itself, you must define it with @rmacro, like this: + +

     @rmacro rmac {arg}
+     a\arg\b
+     @end rmacro
+     ...
+     @rmac{1@rmac{text}2}
+
+

This produces the output `a1atextb2b'. With @macro instead of +@rmacro, an error message is given. + +

You can undefine a macro foo with @unmacro foo. +It is not an error to undefine a macro that is already undefined. +For example: + +

     @unmacro foo
+
+
+


+Next: , +Previous: Defining Macros, +Up: Defining New Texinfo Commands +
+
+ +

19.2 Invoking Macros

+ +

+After a macro is defined (see the previous section), you can use +(invoke) it in your document like this: + +

     @macroname {arg1, arg2, ...}
+
+

and the result will be just as if you typed the body of +macroname at that spot. For example: + +

     @macro foo {p, q}
+     Together: \p\ & \q\.
+     @end macro
+     @foo{a, b}
+
+

produces: + +

     Together: a & b.
+
+

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: + +

     @macro argless {}
+     No arguments here.
+     @end macro
+     @argless{}
+
+

produces: + +

     No arguments here.
+
+

To insert a comma, brace, or backslash in an argument, prepend a +backslash, as in + +

     @macname {\\\{\}\,}
+
+

which will pass the (almost certainly error-producing) argument +\{}, to macname. However, commas in parameters, even +if escaped by a backslash, might cause trouble in TeX. + +

If the macro is defined to take a single argument, and is invoked +without any braces, the entire rest of the line after the macro name is +supplied as the argument. For example: + +

     @macro bar {p}
+     Twice: \p\ & \p\.
+     @end macro
+     @bar aah
+
+

produces: + + +

     Twice: aah & aah.
+
+

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: + +

     @macro bar {p}
+     Twice: \p\ & \p\.
+     @end macro
+     @bar{a,b}
+
+

produces: + +

     Twice: a,b & a,b.
+
+
+


+Next: , +Previous: Invoking Macros, +Up: Defining New Texinfo Commands +
+
+ +

19.3 Macro Details

+ +

+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 +makeinfo by invoking texi2dvi with the -E +option (see Format with texi2dvi). + +

+ +

The makeinfo implementation also has limitations: + +

+ +

One more limitation is common to both implementations: white space is +ignored at the beginnings of lines. + +

Future major revisions of Texinfo may ease some of these limitations +(by introducing a new macro syntax). + +

+


+Next: , +Previous: Macro Details, +Up: Defining New Texinfo Commands +
+
+ +

19.4 @alias new=existing

+ +

+The @alias 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. + +

Write the @alias 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: +

     @alias new = existing
+
+

For example, if your document contains citations for both books and +some other media (movies, for example), you might like to define a +macro @moviecite{} that does the same thing as an ordinary +@cite{} but conveys the extra semantic information as well. +You'd do this as follows: + +

     @alias moviecite = cite
+
+

Macros do not always have the same effect as aliases, due to vagaries +of argument parsing. Also, aliases are much simpler to define than +macros. So the command is not redundant. (It was also heavily used +in the Jargon File!) + +

Aliases must not be recursive, directly or indirectly. + +

It is not advisable to redefine any TeX primitive, plain, or +Texinfo command name as an alias. Unfortunately this is a very large +set of names, and the possible resulting errors are completely random. + +

+


+Previous: alias, +Up: Defining New Texinfo Commands +
+
+ +

19.5 definfoenclose: Customized Highlighting

+ +

+A @definfoenclose command may be used to define a highlighting +command for Info, but not for TeX. A command defined using +@definfoenclose marks text by enclosing it in strings that +precede and follow the text. You can use this to get closer control of +your Info output. + +

Presumably, if you define a command with @definfoenclose for Info, +you will create a corresponding command for TeX, either in +texinfo.tex, texinfo.cnf, or within an @iftex in +your document. + +

Write a @definfoenclose command on a line and follow it with +three arguments separated by commas. The first argument to +@definfoenclose is the @-command name (without the @); +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. + +

If you do a @definfoenclose on the name of a pre-defined macro +(such as @emph, @strong, @t, or @i), the +enclosure definition will override the built-in definition. + +

An enclosure command defined this way takes one argument in braces; this +is intended for new markup commands (see Marking Text). + +

For example, you can write: + +

     @definfoenclose phoo,//,\\
+
+

near the beginning of a Texinfo file to define @phoo as an Info +formatting command that inserts `//' before and `\\' after the argument +to @phoo. You can then write @phoo{bar} wherever you +want `//bar\\' highlighted in Info. + +

Also, for TeX formatting, you could write + +

     @iftex
+     @global@let@phoo=@i
+     @end iftex
+
+

to define @phoo as a command that causes TeX to typeset the +argument to @phoo in italics. + +

Each definition applies to its own formatter: one for TeX, the other +for texinfo-format-buffer or texinfo-format-region. The +@definfoenclose command need not be within @ifinfo, but +the raw TeX commands do need to be in @iftex. + +

Here is another example: write + +

     @definfoenclose headword, , :
+
+

near the beginning of the file, to define @headword as an Info +formatting command that inserts nothing before and a colon after the +argument to @headword. + +

@definfoenclose definitions must not be recursive, directly or +indirectly. + +

+


+Next: , +Previous: Defining New Texinfo Commands, +Up: Top +
+
+ +

20 Formatting and Printing Hardcopy

+ +

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

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

+ +
+


+Next: , +Up: Hardcopy +
+
+ +

20.1 Use TeX

+ +

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 How to Obtain TeX, for information on how to obtain TeX.) + +

The standalone makeinfo program and Emacs functions +texinfo-format-region and texinfo-format-buffer commands +read the very same @-commands in the Texinfo file as does TeX, but +process them differently to make an Info file (see Creating an Info File). + +

+


+Next: , +Previous: Use TeX, +Up: Hardcopy +
+
+ +

20.2 Format with tex and texindex

+ +

+You can format the Texinfo file with the shell command tex +followed by the name of the Texinfo file. For example: + +

     tex foo.texi
+
+

TeX will produce a DVI file as well as several auxiliary +files containing information for indices, cross references, etc. The +DVI file (for DeVice Independent file) can be printed on virtually +any device (see the following sections). + +

The tex formatting command itself does not sort the indices; it +writes an output file of unsorted index data. (The texi2dvi +command automatically generates indices; see Format with texi2dvi.) To generate a printed index after +running the tex command, you first need a sorted index to work +from. The texindex command sorts indices. (The source file +texindex.c comes as part of the standard Texinfo distribution, +among other places.) + +

The tex formatting command outputs unsorted index files under +names that obey a standard convention: the name of your main input file +with any .tex (or similar, see tex invocation (Web2c)) extension removed, followed by the two letter names of indices. +For example, the raw index output files for the input file +foo.texinfo would be foo.cp, foo.vr, foo.fn, +foo.tp, foo.pg and foo.ky. Those are exactly the +arguments to give to texindex. + +

Instead of specifying all the unsorted index file names explicitly, you +can use ?? as shell wildcards and give the command in this +form: + +

     texindex foo.??
+
+

This command will run texindex on all the unsorted index files, +including any that you have defined yourself using @defindex +or @defcodeindex. (You may execute texindex foo.?? +even if there are similarly named files with two letter extensions +that are not index files, such as foo.el. The texindex +command reports but otherwise ignores such files.) + +

For each file specified, texindex generates a sorted index file +whose name is made by appending s to the input file name. The +@printindex command looks for a file with that name +(see Printing Indices & Menus). texindex does not alter the +raw index output file. + +

After you have sorted the indices, you need to rerun tex on the +Texinfo file. This regenerates the DVI file, this time with +up-to-date index entries. + +

Finally, you may need to run tex one more time, to get the page +numbers in the cross-references correct. + +

To summarize, this is a five step process: + +

    +
  1. Run tex 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). + +
  2. Run texindex on the raw index files. This creates the +corresponding sorted index files (with three letter extensions). + +
  3. Run tex 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. + +
  4. Sort the indices again, with texindex. + +
  5. Run tex one last time. This time the correct page numbers are +written for the cross-references. +
+ +

Alternatively, it's a one-step process: run texi2dvi +(see Format with texi2dvi). + +

You need not run texindex each time after you run tex. If +you do not, on the next run, the tex formatting command will use +whatever sorted index files happen to exist from the previous use of +texindex. This is usually ok while you are debugging. + +

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 @novalidate command, which you must give +before the @setfilename command +(see @setfilename). Thus, the beginning of +your file would look approximately like this: + +

     \input texinfo
+     @novalidate
+     @setfilename myfile.info
+     ...
+
+

@novalidate also turns off validation in +makeinfo, just like its --no-validate option +(see Pointer Validation). + +

+


+Next: , +Previous: Format with tex/texindex, +Up: Hardcopy +
+
+ +

20.3 Format with texi2dvi

+ +

+The texi2dvi command automatically runs both TeX and +texindex as many times as necessary to produce a DVI file +with sorted indices and all cross-references resolved. It is +therefore simpler than manually executing the +textexindextextex sequence +described in the previous section. + +

To run texi2dvi on an input file foo.texi, do this (where +prompt$ is your shell prompt): + +

     prompt$ texi2dvi foo.texi
+
+

As shown in this example, the input filenames to texi2dvi must +include any extension (.texi, .texinfo, etc.). Under +MS-DOS and perhaps in other circumstances, you may need to run sh +texi2dvi foo.texi instead of relying on the operating system to invoke +the shell on the texi2dvi script. + +

Perhaps the most useful option to texi2dvi is +--command=cmd. This inserts cmd on a line by itself +after the @setfilename in a temporary copy of the input file +before running TeX. With this, you can specify different printing +formats, such as @smallbook (see smallbook), +@afourpaper (see A4 Paper), or @pagesizes +(see pagesizes), without actually changing the document source. +(You can also do this on a site-wide basis with texinfo.cnf; +see Preparing for TeX). + +

texi2dvi can also be used to process LaTeX files; simply +run texi2dvi filename.ext. + +

For a list of other options, run texi2dvi --help. + +

+


+Next: , +Previous: Format with texi2dvi, +Up: Hardcopy +
+
+ +

20.4 Shell Print Using lpr -d

+ +

+The precise command to print a DVI file depends on your system +installation. Two common ones are dvips foo.dvi -o and lpr +-d foo.dvi. + +

For example, the following commands will (perhaps) suffice to sort the +indices, format, and print the Bison Manual: + +

     tex bison.texinfo
+     texindex bison.??
+     tex bison.texinfo
+     lpr -d bison.dvi
+
+

(Remember that the shell commands may be different at your site; but +these are commonly used versions.) + +

Using the texi2dvi shell script (see the previous section): + +

     texi2dvi bison.texinfo
+     lpr -d bison.dvi
+     # or perhaps dvips bison.dvi -o
+
+

lpr 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 lpr, but these are usually limited to sending files +to a print server over the network, and generally don't support the +-d option. If you are unfortunate enough to work on one of these +systems, you have several alternative ways of printing DVI files: + +

+ +
+


+Next: , +Previous: Print with lpr, +Up: Hardcopy +
+
+ +

20.5 From an Emacs Shell

+ +

+You can give formatting and printing commands from a shell within GNU +Emacs. To create a shell within Emacs, type M-x shell. In this +shell, you can format and print the document. See Format and Print Hardcopy, for details. + +

You can switch to and from the shell buffer while tex is +running and do other editing. If you are formatting a long document +on a slow machine, this can be very convenient. + +

You can also use texi2dvi from an Emacs shell. For example, +here is how to use texi2dvi to format and print Using and +Porting GNU CC from a shell within Emacs: + +

     texi2dvi gcc.texinfo
+     lpr -d gcc.dvi
+
+

See the next section for more information about formatting +and printing in Texinfo mode. + +

+


+Next: , +Previous: Within Emacs, +Up: Hardcopy +
+
+ +

20.6 Formatting and Printing in Texinfo Mode

+ +

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

+
C-c C-t C-b
M-x texinfo-tex-buffer
Run texi2dvi on the current buffer. + +
C-c C-t C-r
M-x texinfo-tex-region
Run TeX on the current region. + +
C-c C-t C-i
M-x texinfo-texindex
Sort the indices of a Texinfo file formatted with +texinfo-tex-region. + +
C-c C-t C-p
M-x texinfo-tex-print
Print a DVI file that was made with texinfo-tex-region or +texinfo-tex-buffer. + +
C-c C-t C-q
M-x tex-show-print-queue
Show the print queue. + +
C-c C-t C-d
M-x texinfo-delete-from-print-queue
Delete a job from the print queue; you will be prompted for the job +number shown by a preceding C-c C-t C-q command +(texinfo-show-tex-print-queue). + +
C-c C-t C-k
M-x tex-kill-job
Kill the currently running TeX job started by either +texinfo-tex-region or texinfo-tex-buffer, or any other +process running in the Texinfo shell buffer. + +
C-c C-t C-x
M-x texinfo-quit-job
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 .log file. + +
C-c C-t C-l
M-x tex-recenter-output-buffer
Redisplay the shell buffer in which the TeX printing and formatting +commands are run to show its most recent output. +
+ +

Thus, the usual sequence of commands for formatting a buffer is as +follows (with comments to the right): + +

     C-c C-t C-b             Run texi2dvi on the buffer.
+     C-c C-t C-p             Print the DVI file.
+     C-c C-t C-q             Display the printer queue.
+
+

The Texinfo mode TeX formatting commands start a subshell in Emacs +called the *tex-shell*. The texinfo-tex-command, +texinfo-texindex-command, and tex-dvi-print-command +commands are all run in this shell. + +

You can watch the commands operate in the *tex-shell* buffer, +and you can switch to and from and use the *tex-shell* buffer +as you would any other shell buffer. + +

The formatting and print commands depend on the values of several variables. +The default values are: + +

         Variable                              Default value
+     
+     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"
+
+

You can change the values of these variables with the M-x +set-variable command (see Examining and Setting Variables (The GNU Emacs Manual)), or with your .emacs +initialization file (see Init File (The GNU Emacs Manual)). + +

Beginning with version 20, GNU Emacs offers a user-friendly interface, +called Customize, for changing values of user-definable variables. +See Easy Customization Interface (The GNU Emacs Manual), for more details about this. The Texinfo variables can +be found in the Development/Docs/Texinfo group, once you invoke +the M-x customize command. + +

+


+Next: , +Previous: Texinfo Mode Printing, +Up: Hardcopy +
+
+ +

20.7 Using the Local Variables List

+ +

+Yet another way to apply the TeX formatting command to a Texinfo file +is to put that command in a local variables list at the end of the +Texinfo file. You can then specify the tex or texi2dvi +commands as a compile-command and have Emacs run it by typing +M-x compile. This creates a special shell called the +*compilation* buffer in which Emacs runs the compile command. +For example, at the end of the gdb.texinfo file, after the +@bye, you could put the following: + +

     Local Variables:
+     compile-command: "texi2dvi gdb.texinfo"
+     End:
+
+

This technique is most often used by programmers who also compile programs +this way; see Compilation (The GNU Emacs Manual). + +

+


+Next: , +Previous: Compile-Command, +Up: Hardcopy +
+
+ +

20.8 TeX Formatting Requirements Summary

+ +

+Every Texinfo file that is to be input to TeX must begin with a +\input command and must contain an @setfilename command: + +

     \input texinfo
+     @setfilename arg-not-used-by-TeX
+
+

The first command instructs TeX to load the macros it needs to +process a Texinfo file and the second command opens auxiliary files. + +

Every Texinfo file must end with a line that terminates TeX's +processing and forces out unfinished pages: + +

     @bye
+
+

Strictly speaking, these lines are all a Texinfo file needs to be +processed successfully by TeX. + +

Usually, however, the beginning includes an @settitle command to +define the title of the printed manual, an @setchapternewpage +command, a title page, a copyright page, and permissions. Besides an +@bye, 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.) + +

For more information, see: + +

+ +
+


+Next: , +Previous: Requirements Summary, +Up: Hardcopy +
+
+ +

20.9 Preparing for TeX

+ +

+TeX needs to know where to find the texinfo.tex file that the +\input texinfo command on the first line reads. The +texinfo.tex 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: +

     http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/doc/texinfo.tex?rev=HEAD
+
+

+Usually, the installer has put the texinfo.tex file in the +default directory that contains TeX macros when GNU Texinfo, Emacs or +other GNU software is installed. In this case, TeX will find the +file and you do not need to do anything special. If this has not been +done, you can put texinfo.tex in the current directory when you +run TeX, and TeX will find it there. + +

Also, you should install epsf.tex, if it is not already installed +from another distribution. More details are at the end of the description +of the @image command (see Images). + +

Likewise for pdfcolor.tex, if it is not already installed and you +use pdftex. + +

Optionally, you may create an additional texinfo.cnf, and install +it as well. This file is read by TeX when the @setfilename +command is executed (see @setfilename). 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 texinfo.cnf contains the line @afourpaper +(see A4 Paper), then all Texinfo documents will be processed with +that page size in effect. If you have nothing to put in +texinfo.cnf, you do not need to create it. + +

If neither of the above locations for these system files suffice for +you, you can specify the directories explicitly. For +texinfo.tex, you can do this by writing the complete path for the +file after the \input command. Another way, that works for both +texinfo.tex and texinfo.cnf (and any other file TeX +might read), is to set the TEXINPUTS environment variable in your +.cshrc or .profile file. + +

Which you use of .cshrc or .profile depends on +whether you use a Bourne shell-compatible (sh, bash, +ksh, ...) or C shell-compatible (csh, tcsh) +command interpreter. The latter read the .cshrc file for +initialization information, and the former read .profile. + +

In a .cshrc file, you could use the following csh command +sequence: + +

     setenv TEXINPUTS .:/home/me/mylib:
+
+

In a .profile file, you could use the following sh command +sequence: + +

     TEXINPUTS=.:/home/me/mylib:
+     export TEXINPUTS
+
+

On MS-DOS/MS-Windows, you would say it like this9: + +

     set TEXINPUTS=.;d:/home/me/mylib;c:
+
+

It is customary for DOS/Windows users to put such commands in the +autoexec.bat file, or in the Windows Registry. + +

These settings would cause TeX to look for \input file first +in the current directory, indicated by the ., then in a +hypothetical user me's mylib directory, and finally in +the system directories. (A leading, trailing, or doubled : +indicates searching the system directories at that point.) + +

Finally, you may wish to dump a .fmt file (see Memory dumps (Web2c)) so that TeX can load Texinfo faster. (The +disadvantage is that then updating texinfo.tex requires +redumping.) You can do this by running this command, assuming +epsf.tex is findable by TeX: + +

     initex texinfo @dump
+
+

(dump is a TeX primitive.) Then, move texinfo.fmt to +wherever your .fmt files are found; typically, this will be in the +subdirectory web2c of your TeX installation. + +

+


+Next: , +Previous: Preparing for TeX, +Up: Hardcopy +
+
+ +

20.10 Overfull “hboxes”

+ +

+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: + +

     Overfull @hbox (20.76302pt too wide)
+
+

(In TeX, lines are in “horizontal boxes”, hence the term, “hbox”. +@hbox is a TeX primitive not needed in the Texinfo language.) + +

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 Catching Errors with TeX Formatting, +for more information about typesetting errors. + +

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

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: + +

+

     @tex
+     \global\emergencystretch = .9\hsize
+     @end tex
+
+

(You should adjust the fraction as needed.) This huge value for +\emergencystretch cannot be the default, since then the typeset +output would generally be of noticeably lower quality; the default +is .15\hsize. \hsize is the TeX dimension +containing the current line width. + +

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

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 @titlepage command: + +

     @finalout
+
+
+


+Next: , +Previous: Overfull hboxes, +Up: Hardcopy +
+
+ +

20.11 Printing “Small” Books

+ +

+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: + +

     @smallbook
+
+

(Since many books are about 7 by 9.25 inches, this command might better +have been called the @regularbooksize command, but it came to be +called the @smallbook command by comparison to the 8.5 by 11 +inch format.) + +

If you write the @smallbook command between the +start-of-header and end-of-header lines, the Texinfo mode TeX +region formatting command, texinfo-tex-region, will format the +region in “small” book size (see Start of Header). + +

See small, for information about +commands that make it easier to produce examples for a smaller manual. + +

See Format with texi2dvi, and Preparing for TeX, for other ways to format with @smallbook that do not +require changing the source file. + +

+


+Next: , +Previous: smallbook, +Up: Hardcopy +
+
+ +

20.12 Printing on A4 Paper

+ +

+You can tell TeX to format a document for printing on European size +A4 paper (or A5) with the @afourpaper (or @afivepaper) +command. Write the command on a line by itself near the beginning of +the Texinfo file, before the title page. For example, this is how you +would write the header for this manual: + +

     \input texinfo    @c -*-texinfo-*-
+     @c %**start of header
+     @setfilename texinfo
+     @settitle Texinfo
+     @afourpaper
+     @c %**end of header
+
+

See Format with texi2dvi, and Preparing for TeX, for other ways to format for different paper sizes that do not +require changing the source file. + +

You may or may not prefer the formatting that results from the command +@afourlatex. There's also @afourwide for A4 paper in +wide format. + +

+


+Next: , +Previous: A4 Paper, +Up: Hardcopy +
+
+ +

20.13 @pagesizes [width][, height]: Custom Page Sizes

+ +

+You can explicitly specify the height and (optionally) width of the main +text area on the page with the @pagesizes 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: + +

     @pagesizes 200mm,150mm  
+
+

and +

     @pagesizes 11.5in      
+
+

This would be reasonable for printing on B5-size paper. To emphasize, +this command specifies the size of the text area, not the size of +the paper (which is 250mm by 177mm for B5, 14in by +8.5in for legal). + +

To make more elaborate changes, such as changing any of the page +margins, you must define a new command in texinfo.tex (or +texinfo.cnf, see Preparing for TeX). + +

See Format with texi2dvi, and Preparing for TeX, for other ways to specify @pagesizes that do not +require changing the source file. + +

@pagesizes is ignored by makeinfo. + +

+


+Next: , +Previous: pagesizes, +Up: Hardcopy +
+
+ +

20.14 Cropmarks and Magnification

+ +

You can (attempt to) direct TeX to print cropmarks at the corners of +pages with the @cropmarks command. Write the @cropmarks +command on a line by itself between @iftex and @end +iftex lines near the beginning of the Texinfo file, before the title +page, like this: + +

     @iftex
+     @cropmarks
+     @end iftex
+
+

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 @smallbook 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 +texinfo.tex. + +

You can attempt to direct TeX to typeset pages larger or smaller than +usual with the \mag TeX command. Everything that is typeset +is scaled proportionally larger or smaller. (\mag stands for +“magnification”.) This is not a Texinfo @-command, but is a +plain TeX command that is prefixed with a backslash. You have to +write this command between @tex and @end tex +(see Raw Formatter Commands). + +

Follow the \mag command with an = 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: + +

     @tex
+     \mag=1200
+     @end tex
+
+

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

Depending on your system, DVI files prepared with a +nonstandard-\mag may not print or may print only with certain +magnifications. Be prepared to experiment. + +

+


+Next: , +Previous: Cropmarks and Magnification, +Up: Hardcopy +
+
+ +

20.15 PDF Output

+ +

+You can generate a PDF output file from Texinfo source by using the +pdftex program to process your file instead of plain +tex. That is, run pdftex foo.texi instead of tex +foo.texi, or give the --pdf option to texi2dvi. + +

PDF stands for `Portable Document Format'. It was invented by +Adobe Systems some years ago for document interchange, based on their +PostScript language. A PDF reader for the X window system is freely available, as is the +definition of the file format. At present, there are no @ifpdf or +@pdf commands as with the other output formats. + +

Despite the `portable' in the name, PDF files are nowhere near as +portable in practice as the plain ASCII formats (Info, HTML) that +Texinfo supports (DVI portability is arguable). They also tend to be +much larger. Nevertheless, a PDF file does preserve an actual printed +document on a screen as faithfully as possible, so it has its place. + +

+


+Previous: PDF Output, +Up: Hardcopy +
+
+ +

20.16 How to Obtain TeX

+ +

+ + + + + + +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 (http://tug.org/web2c). + +

Instructions for retrieval by anonymous ftp and information on other +available distributions: +http://tug.org/unixtex.ftp. + +

The Free Software Foundation provides a core distribution on its Source +Code CD-ROM suitable for printing Texinfo manuals. To order it, contact: + +

     Free Software Foundation, Inc.
+     59 Temple Place Suite 330
+     Boston, MA   02111-1307
+     USA
+     Telephone: +1-617-542-5942
+     Fax: (including Japan) +1-617-542-2652
+     Free Dial Fax (in Japan):
+           0031-13-2473 (KDD)
+           0066-3382-0158 (IDC)
+     Electronic mail: gnu@gnu.org
+
+

Many other TeX distributions are available; see +http://tug.org/. + +

+


+Next: , +Previous: Hardcopy, +Up: Top +
+
+ +

21 Creating and Installing Info Files

+ +

This chapter describes how to create and install Info files. See Info Files, for general information about the file format itself. + +

+ +
+


+Next: , +Up: Creating and Installing Info Files +
+
+ +

21.1 Creating an Info File

+ +

+makeinfo is a program that converts a Texinfo file into an Info +file, HTML file, or plain text. texinfo-format-region and +texinfo-format-buffer are GNU Emacs functions that convert +Texinfo to Info. + +

For information on installing the Info file in the Info system, +see Installing an Info File. + +

+ +
+


+Next: , +Up: Creating an Info File +
+
+ +

21.1.1 makeinfo Preferred

+ +

The makeinfo 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. makeinfo is a +C program that is independent of Emacs. You do not need to run Emacs to +use makeinfo, which means you can use makeinfo on machines +that are too small to run Emacs. You can run makeinfo in any one +of three ways: from an operating system shell, from a shell inside +Emacs, or by typing the C-c C-m C-r or the C-c C-m C-b +command in Texinfo mode in Emacs. + +

The texinfo-format-region and the texinfo-format-buffer +commands are useful if you cannot run makeinfo. Also, in some +circumstances, they format short regions or buffers more quickly than +makeinfo. + +

+


+Next: , +Previous: makeinfo advantages, +Up: Creating an Info File +
+
+ +

21.1.2 Running makeinfo from a Shell

+ +

+To create an Info file from a Texinfo file, invoke makeinfo +followed by the name of the Texinfo file. Thus, to create the Info +file for Bison, type the following to the shell: + +

     makeinfo bison.texinfo
+
+

(You can run a shell inside Emacs by typing M-x shell.) + +

makeinfo has many options to control its actions and output; +see the next section. + +

+


+Next: , +Previous: Invoking makeinfo, +Up: Creating an Info File +
+
+ +

21.1.3 Options for makeinfo

+ +

+The makeinfo program accepts many options. Perhaps the most +commonly needed are those that change the output format. By default, +makeinfo outputs Info files. + +

Each command line option is a word preceded by -- or a letter +preceded by -. You can use abbreviations for the long option +names as long as they are unique. + +

For example, you could use the following shell command to create an Info +file for bison.texinfo in which each line is filled to only 68 +columns: + +

     makeinfo --fill-column=68 bison.texinfo
+
+

You can write two or more options in sequence, like this: + +

     makeinfo --no-split --fill-column=70 ...
+
+

This would keep the Info file together as one possibly very long +file and would also set the fill column to 70. + +

The options are: + +

+
-D var
Cause the variable var to be defined. This is equivalent to +@set var in the Texinfo file (see set clear value). + +
--commands-in-node-names
Allow @-commands in node names. This is not recommended, as it +can probably never be implemented in TeX. It also makes +makeinfo much slower. Also, this option is ignored when +--no-validate is used. See Pointer Validation, for more +details. + +
--css-include=file
Include the contents of file, which should contain cascading +style sheets specifications, in the <style> block of the HTML +output. See HTML CSS. If file is -, read standard +input. + +
--docbook
Generate Docbook output rather than Info. + +
--enable-encoding
Output accented and special characters in Info or plain text output +based on @documentencoding. +See documentencoding, and Inserting Accents. + +
--error-limit=limit
-e limit
Set the maximum number of errors that makeinfo will report +before exiting (on the assumption that continuing would be useless); +default 100. + +
--fill-column=width
-f width
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 --html. + +
--footnote-style=style
-s style
Set the footnote style to style, either end for the end +node style (the default) or separate for the separate node style. +The value set by this option overrides the value set in a Texinfo file +by an @footnotestyle command (see Footnotes). When the +footnote style is separate, makeinfo makes a new node +containing the footnotes found in the current node. When the footnote +style is end, makeinfo places the footnote references at +the end of the current node. Ignored with --html. + +
--force
-F
Ordinarily, if the input file has errors, the output files are not +created. With this option, they are preserved. + +
--help
-h
Print a usage message listing all available options, then exit successfully. + +
--html
Generate HTML output rather than Info. See Generating HTML. 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. + +
-I dir
Append dir to the directory search list for finding files that +are included using the @include command. By default, +makeinfo searches only the current directory. If dir is +not given, the current directory . is appended. Note that +dir can actually be a list of several directories separated by the +usual path separator character (: on Unix, ; on +MS-DOS/MS-Windows). + +
--ifdocbook
--ifhtml
--ifinfo
--ifplaintext
--iftex
--ifxml
For the specified format, process @ifformat and +@format commands even if not generating the given output +format. For instance, if --iftex is specified, then +@iftex and @tex blocks will be read. This can be useful +when postprocessing the output. + +
--macro-expand=file
-E file
Output the Texinfo source with all the macros expanded to the named +file. Normally, the results of macro expansion are used internally by +makeinfo and then discarded. This option is used by +texi2dvi. + +
--no-headers
For Info output, do not include menus or node separator lines in the +output, and implicitly --enable-encoding (see above). This +results in a simple plain text file that you can (for example) send in +email without complications, or include in a distribution (as in an +INSTALL file). + +

For HTML output, likewise omit menus. And if --no-split 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 Generating HTML. + +

In both cases, ignore @setfilename and write to standard +output by default—can be overridden with -o. + +

--no-ifdocbook
--no-ifhtml
--no-ifinfo
--no-ifplaintext
--no-iftex
--no-ifxml
Do not process @ifformat and @format +commands even if generating the given format. For instance, if +--no-ifhtml is specified, then @ifhtml and +@html blocks will not be read. + +
--no-split
Suppress the splitting stage of makeinfo. 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 Generating HTML). + +
--no-pointer-validate
--no-validate
Suppress the pointer-validation phase of makeinfo. This can also +be done with the @novalidate command (see Use TeX). Normally, after a Texinfo file is processed, some consistency +checks are made to ensure that cross references can be resolved, etc. +See Pointer Validation. + +
--no-warn
Suppress warning messages (but not error messages). You might +want this if the file you are creating has examples of Texinfo cross +references within it, and the nodes that are referenced do not actually +exist. + +
--number-sections
Output chapter, section, and appendix numbers as in printed manuals. + +
--no-number-footnotes
Suppress automatic footnote numbering. By default, makeinfo +numbers each footnote sequentially in a single node, resetting the +current footnote number to 1 at the start of each node. + +
--output=file
-o file
Specify that the output should be directed to file and not to the +file name specified in the @setfilename command found in the +Texinfo source (see setfilename). If file is -, output +goes to standard output and --no-split is implied. For split +HTML output, file is the name for the directory into which all +HTML nodes are written (see Generating HTML). + +
-P dir
Prepend dir to the directory search list for @include. +If dir is not given, the current directory . is prepended. +See -I for more details. + +
--paragraph-indent=indent
-p indent
Set the paragraph indentation style to indent. The value set by +this option overrides the value set in a Texinfo file by an +@paragraphindent command (see paragraphindent). The value +of indent is interpreted as follows: + +
+
asis
Preserve any existing indentation at the starts of paragraphs. + +
0 or none
Delete any existing indentation. + +
num
Indent each paragraph by num spaces. +
+ +
--reference-limit=limit
-r limit
Set the value of the number of references to a node that +makeinfo will make without reporting a warning. If a node has more +than this number of references in it, makeinfo will make the +references but also report a warning. The default is 1000. + +
--split-size=num
Keep Info files to at most num characters; default is 300,000. + +
-U var
Cause var to be undefined. This is equivalent to +@clear var in the Texinfo file (see set clear value). + +
--verbose
Cause makeinfo to display messages saying what it is doing. +Normally, makeinfo only outputs messages if there are errors or +warnings. + +
--version
-V
Print the version number, then exit successfully. + +
--xml
Generate XML output rather than Info. + +
+ +

makeinfo also reads the environment variable +TEXINFO_OUTPUT_FORMAT to determine the output format, if not +overridden by a command line option. The possible values are: + +

     docbook  html  info  plaintext  xml
+
+

If not set, Info output is the default. + +

+


+Next: , +Previous: makeinfo options, +Up: Creating an Info File +
+
+ +

21.1.4 Pointer Validation

+ +

+If you do not suppress pointer validation with the --no-validate +option or the @novalidate command in the source file (see Use TeX), makeinfo 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: + +

    +
  1. 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 +(dir), then the referenced node must exist. + +
  2. 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. + +
  3. Every node except the `Top' node must have an `Up' pointer. + +
  4. 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 `(file)'. + +
  5. 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. + +
  6. 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. +
+ +

Some Texinfo documents might fail during the validation phase because +they use commands like @value and @definfoenclose in +node definitions and cross-references inconsistently. Consider the +following 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.
+
+

Here, the node “Node 1” was referenced both verbatim and through +@value. + +

By default, makeinfo 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 @node line should have also used @value. +However, if, for some reason, you must reference node names +inconsistently, and makeinfo fails to validate the file, you can +use the --commands-in-node-names option to force makeinfo +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. + +

The support for @-commands in @node directives is not +general enough to be freely used. For example, if the example above +redefined nodename somewhere in the document, makeinfo +will fail to convert it, even if invoked with the +--commands-in-node-names option. + +

--commands-in-node-names has no effect if the --no-validate +option is given. + +

+


+Next: , +Previous: Pointer Validation, +Up: Creating an Info File +
+
+ +

21.1.5 Running makeinfo Within Emacs

+ +

+You can run makeinfo in GNU Emacs Texinfo mode by using either the +makeinfo-region or the makeinfo-buffer commands. In +Texinfo mode, the commands are bound to C-c C-m C-r and C-c +C-m C-b by default. + +

+
C-c C-m C-r
M-x makeinfo-region
Format the current region for Info. + +
C-c C-m C-b
M-x makeinfo-buffer
Format the current buffer for Info. +
+ +

When you invoke makeinfo-region the output goes to a temporary +buffer. When you invoke makeinfo-buffer output goes to the +file set with @setfilename (see setfilename). + +

The Emacs makeinfo-region and makeinfo-buffer commands +run the makeinfo program in a temporary shell buffer. If +makeinfo finds any errors, Emacs displays the error messages in +the temporary buffer. + +

You can parse the error messages by typing C-x ` +(next-error). This causes Emacs to go to and position the +cursor on the line in the Texinfo source that makeinfo thinks +caused the error. See Running make or Compilers Generally (The GNU Emacs Manual), for more +information about using the next-error command. + +

In addition, you can kill the shell in which the makeinfo +command is running or make the shell buffer display its most recent +output. + +

+
C-c C-m C-k
M-x makeinfo-kill-job
Kill the current running makeinfo job +(from makeinfo-region or makeinfo-buffer). + +
C-c C-m C-l
M-x makeinfo-recenter-output-buffer
Redisplay the makeinfo shell buffer to display its most recent +output. +
+ +

(Note that the parallel commands for killing and recentering a TeX +job are C-c C-t C-k and C-c C-t C-l. See Texinfo Mode Printing.) + +

You can specify options for makeinfo by setting the +makeinfo-options variable with either the M-x +customize or the M-x set-variable command, or by setting the +variable in your .emacs initialization file. + +

For example, you could write the following in your .emacs file: + +

     (setq makeinfo-options
+          "--paragraph-indent=0 --no-split
+           --fill-column=70 --verbose")
+
+

+ +For more information, see
+Easy Customization Interface (The GNU Emacs Manual),
+Examining and Setting Variables (The GNU Emacs Manual),
+Init File (The GNU Emacs Manual), and
+Options for makeinfo. + +

+


+Next: , +Previous: makeinfo in Emacs, +Up: Creating an Info File +
+
+ +

21.1.6 The texinfo-format... Commands

+ +

In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo +file with the texinfo-format-region command. This formats the +current region and displays the formatted text in a temporary buffer +called *Info Region*. + +

Similarly, you can format a buffer with the +texinfo-format-buffer command. This command creates a new +buffer and generates the Info file in it. Typing C-x C-s will +save the Info file under the name specified by the +@setfilename line which must be near the beginning of the +Texinfo file. + +

+
C-c C-e C-r
texinfo-format-region
Format the current region for Info. + +
C-c C-e C-b
texinfo-format-buffer
Format the current buffer for Info. +
+ +

The texinfo-format-region and texinfo-format-buffer +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 Catching Mistakes. +However, the makeinfo program is often faster and +provides better error checking (see makeinfo in Emacs). + +

+


+Next: , +Previous: texinfo-format commands, +Up: Creating an Info File +
+
+ + +

21.1.7 Batch Formatting

+ +

+You can format Texinfo files for Info using batch-texinfo-format +and Emacs Batch mode. You can run Emacs in Batch mode from any shell, +including a shell inside of Emacs. (See Command Arguments (The GNU Emacs Manual).) + +

Here is a shell command to format all the files that end in +.texinfo in the current directory: + +

     emacs -batch -funcall batch-texinfo-format *.texinfo
+
+

Emacs processes all the files listed on the command line, even if an +error occurs while attempting to format some of them. + +

Run batch-texinfo-format only with Emacs in Batch mode as shown; +it is not interactive. It kills the Batch mode Emacs on completion. + +

batch-texinfo-format is convenient if you lack makeinfo +and want to format several Texinfo files at once. When you use Batch +mode, you create a new Emacs process. This frees your current Emacs, so +you can continue working in it. (When you run +texinfo-format-region or texinfo-format-buffer, you cannot +use that Emacs for anything else until the command finishes.) + +

+


+Previous: Batch Formatting, +Up: Creating an Info File +
+
+ + +

21.1.8 Tag Files and Split Files

+ +

+If a Texinfo file has more than 30,000 bytes, +texinfo-format-buffer automatically creates a tag table +for its Info file; makeinfo always creates a tag table. With +a tag table, Info can jump to new nodes more quickly than it can +otherwise. + +

In addition, if the Texinfo file contains more than about 300,000 +bytes, texinfo-format-buffer and makeinfo split the +large Info file into shorter indirect subfiles of about 300,000 +bytes each. Big files are split into smaller files so that Emacs does +not need to make a large buffer to hold the whole of a large Info +file; instead, Emacs allocates just enough memory for the small, split-off +file that is needed at the time. This way, Emacs avoids wasting +memory when you run Info. (Before splitting was implemented, Info +files were always kept short and include files were designed as +a way to create a single, large printed manual out of the smaller Info +files. See Include Files, for more information. Include files are +still used for very large documents, such as The Emacs Lisp +Reference Manual, in which each chapter is a separate file.) + +

When a file is split, Info itself makes use of a shortened version of +the original file that contains just the tag table and references to +the files that were split off. The split-off files are called +indirect files. + +

The split-off files have names that are created by appending -1, +-2, -3 and so on to the file name specified by the +@setfilename command. The shortened version of the original file +continues to have the name specified by @setfilename. + +

At one stage in writing this document, for example, the Info file was saved +as the file test-texinfo and that file looked like this: + +

     Info file: test-texinfo,    -*-Text-*-
+     produced by texinfo-format-buffer
+     from file: new-texinfo-manual.texinfo
+     
+     ^_
+     Indirect:
+     test-texinfo-1: 102
+     test-texinfo-2: 50422
+     test-texinfo-3: 101300
+     ^_^L
+     Tag table:
+     (Indirect)
+     Node: overview^?104
+     Node: info file^?1271
+     Node: printed manual^?4853
+     Node: conventions^?6855
+     ...
+
+

(But test-texinfo had far more nodes than are shown here.) Each of +the split-off, indirect files, test-texinfo-1, +test-texinfo-2, and test-texinfo-3, is listed in this file +after the line that says Indirect:. The tag table is listed after +the line that says Tag table:. + +

In the list of indirect files, the number following the file name +records the cumulative number of bytes in the preceding indirect files, +not counting the file list itself, the tag table, or 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. + +

If you are using texinfo-format-buffer to create Info files, +you may want to run the Info-validate command. (The +makeinfo command does such a good job on its own, you do not +need Info-validate.) However, you cannot run the M-x +Info-validate node-checking command on indirect files. For +information on how to prevent files from being split and how to +validate the structure of the nodes, see Using Info-validate. + +

+


+Previous: Creating an Info File, +Up: Creating and Installing Info Files +
+
+ +

21.2 Installing an Info File

+ +

+Info files are usually kept in the info directory. You can read +Info files using the standalone Info program or the Info reader built +into Emacs. (see info, for an introduction to Info.) + +

+ +
+


+Next: , +Up: Installing an Info File +
+
+ +

21.2.1 The Directory File dir

+ +

For Info to work, the info directory must contain a file that +serves as a top level directory for the Info system. By convention, +this file is called dir. (You can find the location of this file +within Emacs by typing C-h i to enter Info and then typing +C-x C-f to see the pathname to the info directory.) + +

The dir file is itself an Info file. It contains the top level +menu for all the Info files in the system. The menu looks like +this: + +

     * Menu:
+     * Info:    (info).     Documentation browsing system.
+     * Emacs:   (emacs).    The extensible, self-documenting
+                           text editor.
+     * Texinfo: (texinfo).  With one source file, make
+                           either a printed manual using
+                           @TeX{} or an Info file.
+     ...
+
+

Each of these menu entries points to the `Top' node of the Info file +that is named in parentheses. (The menu entry does not need to +specify the `Top' node, since Info goes to the `Top' node if no node +name is mentioned. See Nodes in Other Info Files.) + +

Thus, the Info entry points to the `Top' node of the +info file and the Emacs entry points to the `Top' node +of the emacs file. + +

In each of the Info files, the `Up' pointer of the `Top' node refers +back to the dir file. For example, the line for the `Top' +node of the Emacs manual looks like this in Info: + +

     File: emacs  Node: Top, Up: (DIR), Next: Distrib
+
+

In this case, the dir file name is written in 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 dir. + +

+


+Next: , +Previous: Directory File, +Up: Installing an Info File +
+
+ +

21.2.2 Listing a New Info File

+ +

+To add a new Info file to your system, you must write a menu entry to +add to the menu in the dir file in the info directory. +For example, if you were adding documentation for GDB, you would write +the following new entry: + +

     * GDB: (gdb).           The source-level C debugger.
+
+

The first part of the menu entry is the menu entry name, followed by a +colon. The second part is the name of the Info file, in parentheses, +followed by a period. The third part is the description. + +

The name of an Info file often has a .info extension. Thus, the +Info file for GDB might be called either gdb or gdb.info. +The Info reader programs automatically try the file name both with and +without .info10; so it is better to avoid +clutter and not to write .info explicitly in the menu entry. For +example, the GDB menu entry should use just gdb for the file +name, not gdb.info. + +

+


+Next: , +Previous: New Info File, +Up: Installing an Info File +
+
+ +

21.2.3 Info Files in Other Directories

+ +

+If an Info file is not in the info directory, there are three +ways to specify its location: + +

    +
  1. Write the pathname in the dir file as the second part of the menu. + +
  2. If you are using Emacs, list the name of the file in a second dir +file, in its directory; and then add the name of that directory to the +Info-directory-list variable in your personal or site +initialization file. + +

    This variable tells Emacs where to look for dir files (the files +must be named dir). Emacs merges the files named dir from +each of the listed directories. (In Emacs version 18, you can set the +Info-directory variable to the name of only one +directory.) + +

  3. Specify the Info directory name in the INFOPATH environment +variable in your .profile or .cshrc initialization file. +(Only you and others who set this environment variable will be able to +find Info files whose location is specified this way.) +
+ +

For example, to reach a test file in the /home/bob/info +directory, you could add an entry like this to the menu in the +standard dir file: + +

     * Test: (/home/bob/info/info-test).  Bob's own test file.
+
+

In this case, the absolute file name of the info-test file is +written as the second part of the menu entry. + +

Alternatively, you could write the following in your .emacs file: + +

+

     (require 'info)
+     (setq Info-directory-list
+      (cons (expand-file-name "/home/bob/info")
+            Info-directory-list))
+
+

This tells Emacs to merge the system dir file with the dir +file in /home/bob/info. Thus, Info will list the +/home/bob/info/info-test file as a menu entry in the +/home/bob/info/dir file. Emacs does the merging only when +M-x info is first run, so if you want to set +Info-directory-list in an Emacs session where you've already run +info, you must (setq Info-dir-contents nil) to force Emacs +to recompose the dir file. + +

Finally, you can tell Info where to look by setting the INFOPATH +environment variable in your shell startup file, such as .cshrc, +.profile or autoexec.bat. If you use a Bourne-compatible +shell such as sh or bash for your shell command +interpreter, you set the INFOPATH environment variable in the +.profile initialization file; but if you use csh or +tcsh, you set the variable in the .cshrc initialization +file. On MS-DOS/MS-Windows systems, you must set INFOPATH in +your autoexec.bat file or in the Registry. Each type of shell +uses a different syntax. + +

+ +

The . indicates the current directory as usual. Emacs uses the +INFOPATH environment variable to initialize the value of Emacs's +own Info-directory-list variable. The stand-alone Info reader +merges any files named dir in any directory listed in the +INFOPATH variable into a single menu presented to you in the node +called (dir)Top. + +

However you set INFOPATH, if its last character is a +colon12, this +is replaced by the default (compiled-in) path. This gives you a way to +augment the default path with new directories without having to list all +the standard places. For example (using sh syntax): + +

     INFOPATH=/local/info:
+     export INFOPATH
+
+

will search /local/info first, then the standard directories. +Leading or doubled colons are not treated specially. + +

When you create your own dir file for use with +Info-directory-list or INFOPATH, it's easiest to start by +copying an existing dir file and replace all the text after the +* Menu: with your desired entries. That way, the punctuation and +special CTRL-_ characters that Info needs will be present. + +

+


+Next: , +Previous: Other Info Directories, +Up: Installing an Info File +
+
+ +

21.2.4 Installing Info Directory Files

+ +

When you install an Info file onto your system, you can use the program +install-info to update the Info directory file dir. +Normally the makefile for the package runs install-info, just +after copying the Info file into its proper installed location. + +

In order for the Info file to work with install-info, you include +the commands @dircategory and +@direntry...@end direntry in the Texinfo source +file. Use @direntry to specify the menu entries to add to the +Info directory file, and use @dircategory to specify which part +of the Info directory to put it in. Here is how these commands are used +in this manual: + +

     @dircategory Texinfo documentation system
+     @direntry
+     * Texinfo: (texinfo).           The GNU documentation format.
+     * install-info: (texinfo)Invoking install-info. ...
+     ...
+     @end direntry
+
+

Here's what this produces in the Info file: + +

     INFO-DIR-SECTION Texinfo documentation system
+     START-INFO-DIR-ENTRY
+     * Texinfo: (texinfo).           The GNU documentation format.
+     * install-info: (texinfo)Invoking install-info. ...
+     ...
+     END-INFO-DIR-ENTRY
+
+

The install-info program sees these lines in the Info file, and +that is how it knows what to do. + +

Always use the @direntry and @dircategory commands near +the beginning of the Texinfo input, before the first @node +command. If you use them later on in the input, install-info +will not notice them. + +

If you use @dircategory more than once in the Texinfo source, +each usage specifies the `current' category; any subsequent +@direntry commands will add to that category. + +

When choosing a category name for the @dircategory command, we +recommend consulting the Free Software Directory. If your program is not listed there, +or listed incorrectly or incompletely, please report the situation to +the directory maintainers (bug-directory@gnu.org) so that the +category names can be kept in sync. + +

Here are a few examples (see the util/dir-example file in the +Texinfo distribution for large sample dir file): + +

     Emacs
+     Localization
+     Printing
+     Software development
+     Software libraries
+     Text creation and manipulation
+
+

Each `Invoking' node for every program installed should have a +corresponding @direntry. This lets users easily find the +documentation for the different programs they can run, as with the +traditional man system. + +

+


+Previous: Installing Dir Entries, +Up: Installing an Info File +
+
+ +

21.2.5 Invoking install-info

+ +

+install-info inserts menu entries from an Info file into the +top-level dir file in the Info system (see the previous sections +for an explanation of how the dir file works). It's most often +run as part of software installation, or when constructing a dir file +for all manuals on a system. Synopsis: + +

     install-info [option]... [info-file [dir-file]]
+
+

If info-file or dir-file are not specified, the options +(described below) that define them must be. There are no compile-time +defaults, and standard input is never used. install-info can +read only one Info file and write only one dir file per invocation. + +

If dir-file (however specified) does not exist, +install-info creates it if possible (with no entries). + +

If any input file is compressed with gzip (see Invoking gzip (Gzip)), install-info automatically uncompresses it +for reading. And if dir-file is compressed, install-info +also automatically leaves it compressed after writing any changes. +If dir-file itself does not exist, install-info tries to +open dir-file.gz. + +

Options: + +

+
--delete
Delete the entries in info-file from dir-file. The file +name in the entry in dir-file must be info-file (except for +an optional .info in either one). Don't insert any new entries. + +
--dir-file=name
-d name
Specify file name of the Info directory file. This is equivalent to +using the dir-file argument. + +
--entry=text
-e text
Insert text as an Info directory entry; text should have the +form of an Info menu item line plus zero or more extra lines starting +with whitespace. If you specify more than one entry, they are all +added. If you don't specify any entries, they are determined from +information in the Info file itself. + +
--help
-h
Display a usage message listing basic usage and all available options, +then exit successfully. + +
--info-file=file
-i file
Specify Info file to install in the directory. +Equivalent to using the info-file argument. + +
--info-dir=dir
-D dir
Specify the directory where the directory file dir resides. +Equivalent to --dir-file=dir/dir. + +
--item=text
Same as --entry=text. An Info directory entry is actually +a menu item. + +
--quiet
Suppress warnings. + +
--remove
-r
Same as --delete. + +
--section=sec
-s sec
Put this file's entries in section sec of the directory. If you +specify more than one section, all the entries are added in each of the +sections. If you don't specify any sections, they are determined from +information in the Info file itself. + +
--version
-V
Display version information and exit successfully. + +
+ +
+


+Next: , +Previous: Creating and Installing Info Files, +Up: Top +
+
+ +

22 Generating HTML

+ +

+makeinfo generates Info output by default, but given the +--html option, it will generate HTML, for web browsers and +other programs. This chapter gives some details on such HTML output. + +

makeinfo can also write in XML and Docbook format, but we do +not as yet describe these further. See Output Formats, for a brief +overview of all the output formats. + +

+ +
+


+Next: , +Up: Generating HTML +
+
+ +

22.1 HTML Translation

+ +

makeinfo will include segments of Texinfo source between +@ifhtml and @end ifhtml in the HTML output (but not +any of the other conditionals, by default). Source between +@html and @end html is passed without change to the +output (i.e., suppressing the normal escaping of input <, +> and & characters which have special significance in +HTML). See Conditional Commands. + +

The --footnote-style option is currently ignored for HTML output; +footnotes are always linked to the end of the output file. + +

By default, a navigation bar is inserted at the start of each node, +analogous to Info output. The --no-headers option suppresses +this if used with --no-split. Header <link> elements in +split output can support info-like navigation with browsers like Lynx +and Emacs W3 which implement this HTML 1.0 feature. + +

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 +@multitable command, but tagged to degrade as well as possible +in browsers without table support. The HTML 4 lang +attribute on the <html> attribute is also used. (Please report +output from an error-free run of makeinfo which has browser +portability problems as a bug.) + +

+


+Next: , +Previous: HTML Translation, +Up: Generating HTML +
+
+ +

22.2 HTML Splitting

+ +

+When splitting output (which is the default), makeinfo +writes HTML output into (generally) one output file per Texinfo source +@node. + +

The output file name is the node name with special characters replaced +by -'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 makeinfo is run on a +system which does not distinguish case in filenames, nodes which are +the same except for case will also be folded into the same output +file. + +

When splitting, the HTML output files are written into a subdirectory, +with the name chosen as follows: +

    +
  1. makeinfo first tries the subdirectory with the base name +from @setfilename (that is, any extension is removed). For +example, HTML output for @setfilename gcc.info would be +written into a subdirectory named gcc. + +
  2. If that directory cannot be created for any reason, then +makeinfo tries appending .html to the directory name. +For example, output for @setfilename texinfo would be written +to texinfo.html. + +
  3. If the name.html directory can't be +created either, makeinfo gives up. + +
+ +

In any case, the top-level output file within the directory +is always named index.html. + +

Monolithic output (--no-split) is named according to +@setfilename (with any .info extension is replaced with +.html) or --output (the argument is used literally). + +

+


+Next: , +Previous: HTML Splitting, +Up: Generating HTML +
+
+ +

22.3 HTML CSS

+ +

+Cascading Style Sheets (CSS for short) is an Internet standard for +influencing the display of HTML documents: see +http://www.w3.org/Style/CSS/. + +

By default, makeinfo includes a few simple CSS commands to +better implement the appearance of some of the environments. Here +are two of them, as an example: + +

     pre.display { font-family:inherit }
+     pre.smalldisplay { font-family:inherit; font-size:smaller }
+
+

A full explanation of CSS is (far) beyond this manual; please see the +reference above. In brief, however, this specification tells the web +browser to use a `smaller' font size for @smalldisplay text, +and to use the `inherited' font (generally a regular roman typeface) +for both @smalldisplay and @display. By default, the +HTML <pre> command uses a monospaced font. + +

You can influence the CSS in the HTML output with the +--css-include=file option to makeinfo. This +includes the contents file in the HTML output, as you might +expect. However, the details are somewhat tricky, as described in the +following, to provide maximum flexibility. + +

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

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

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

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

+ +

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

+


+Previous: HTML CSS, +Up: Generating HTML +
+
+ +

22.4 HTML Cross-references

+ +

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

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

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

Acknowledgement: this algorithm was primarily devised by Patrice Dumas +in 2003–04. + +

+ +
+


+Next: , +Up: HTML Xref +
+
+ +

22.4.1 HTML Cross-reference Link Basics

+ +

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

     http://host/dir/file.html#target
+
+

The information to construct a link comes from the node name and +manual name in the cross-reference command in the Texinfo source +(see Cross References), and from external information, which +is currently simply hardwired. In the future, it may come from an +external data file. + +

We now consider each part in turn. + +

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

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

+ +

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

Finally, the target part is always the expanded node name. + +

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

Whether the referent manual is split or mono is another bit of the +external information. For now, makeinfo simply assumes the +referent manual is the same as the present manual. + +

There can be a mismatch between the format of the referent manual that +the generating software assumes, and the format it's actually present +in. See HTML Xref Mismatch. + +

+


+Next: , +Previous: HTML Xref Link Basics, +Up: HTML Xref +
+
+ +

22.4.2 HTML Cross-reference Node Name Expansion

+ +

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

Cross-references in Texinfo can actually refer either to nodes or +anchors (see anchor), but anchors are treated identically to nodes +in this context, so we'll continue to say “node” names for +simplicity. + +

(@-commands and 8-bit characters are not presently handled by +makeinfo for HTML cross-references. See the next section.) + +

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

     @xref{Top, Introduction,, emacs, The GNU Emacs Manual}.
+     => <a href="emacs/index.html#Top">
+
+
    +
  1. The standard ASCII letters (a-z and A-z), and numbers (0-9) are not +modified. All other characters are changed as specified below. + +
  2. 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.) + +
  3. Leading and trailing spaces are removed. + +
  4. After the above has been applied, each remaining space character is +converted into a - character. + +
  5. Other ASCII 7-bit characters are transformed into _00xx, +where xx is the ASCII character code in (lowercase) hexadecimal. +This includes _, which is mapped to _005f. + +
+ +

For example: + +

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

Notice in particular: + +

+ +

On case-folding computer systems, nodes differing only by case will be +mapped to the same file. + +

In particular, as mentioned above, Top always maps to the file +index.html. Thus, on a case-folding system, Top and a node +named `Index' will both be written to index.html. + +

Fortunately, the targets serve to distinguish these cases, since HTML +target names are always case-sensitive, independent of operating +system. + +

+


+Next: , +Previous: HTML Xref Node Name Expansion, +Up: HTML Xref +
+
+ +

22.4.3 HTML Cross-reference Command Expansion

+ +

+In standard Texinfo, node names may not contain @-commands. +makeinfo has an option --commands-in-node-names +which partially supports it (see Invoking makeinfo), but it is not +robust and not recommended. + +

Thus, makeinfo also does not fully implement this part of +the HTML cross-reference algorithm, but it is documented here for the +sake of completeness. + +

First, comments are removed. + +

Next, any @value commands (see set value) and macro invocations +(see Invoking Macros) are fully expanded. + +

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

     @asis @b @cite @code @command @dfn @dmn @dotless
+     @emph @env @file @indicateurl @kbd @key
+     @samp @sc @strong @t @var @w
+
+

For @sc, any letters are capitalized. + +

The following commands are replaced by constant text, as shown. If +any of these commands have non-empty arguments, as in +@TeX{bad}, it is an error, and the result is unspecified. +`(space)' means a space character, `(nothing)' means the empty string, +etc. The notation `U+xxxx' means Unicode code point xxxx. +There are further transformations of many of these expansions for the +final file or target name, such as space characters to -, etc., +according to the other rules. + +

@(newline) (space) +
@(space) (space) +
@(tab) (space) +
@! ! +
@* (space) +
@- (nothing) +
@. . +
@: (nothing) +
@? ? +
@@ @ +
@{ { +
@} } +
@LaTeX LaTeX +
@TeX TeX +
@bullet U+2022 +
@comma , +
@copyright U+00A9 +
@dots U+2026 +
@enddots ... +
@equiv U+2261 +
@error error--> +
@exclamdown U+00A1 +
@expansion U+2192 +
@minus U+2212 +
@ordf U+00AA +
@ordm U+00BA +
@point U+2217 +
@pounds U+00A3 +
@print -| +
@questiondown U+00BF +
@registeredsymbol U+00AE +
@result U+21D2 +
@tie (space) +
+ +

An @acronym command is replaced by the first argument, +followed by the second argument in parentheses, if present. +See acronym. + +

An @email command is replaced by the text argument if +present, else the address. See email. + +

An @image command is replaced by the filename (first) +argument. See Images. + +

A @verb command is replaced by its transformed argument. +See verb. + +

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

+


+Next: , +Previous: HTML Xref Command Expansion, +Up: HTML Xref +
+
+ +

22.4.4 HTML Cross-reference 8-bit Character Expansion

+ +

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

These will then be further transformed by the rules above into the +string _xxxx, where xxxx is the code point in hex. + +

For example, combining this rule and the previous section: + +

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

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

For the definition of Unicode Normalization Form C, see Unicode report +UAX#15, http://www.unicode.org/reports/tr15/. Many related +documents and implementations are available elsewhere on the web. + +

+


+Previous: HTML Xref 8-bit Character Expansion, +Up: HTML Xref +
+
+ +

22.4.5 HTML Cross-reference Mismatch

+ +

+As mentioned earlier (see HTML Xref Link Basics), the generating +software has to guess whether a given manual being cross-referenced is +available in split or monolithic form—and, inevitably, it might +guess wrong. However, it is possible when the referent manual itself +is generated, it is possible to handle at least some mismatches. + +

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

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

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

Then, in the <body> tag of manual.html: + +

     <body onLoad="redirect();">
+
+

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

Ultimately, we hope to allow for an external configuration file to +control which manuals are available from where, and how. + +

+


+Next: , +Previous: Generating HTML, +Up: Top +
+
+ +

Appendix A @-Command List

+ +

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

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

+ +
+
+
+
+
@whitespace
An @ followed by a space, tab, or newline produces a normal, +stretchable, interword space. See Multiple Spaces. + +
@!
Generate an exclamation point that really does end a sentence (usually +after an end-of-sentence capital letter). See Ending a Sentence. + +
@"
@'
Generate an umlaut or acute accent, respectively, over the next +character, as in ö and ó. See Inserting Accents. + +
@*
Force a line break. See Line Breaks. + +
@,{c}
Generate a cedilla accent under c, as in ç. See Inserting Accents. + +
@-
Insert a discretionary hyphenation point. See - and hyphenation. + +
@.
Produce a period that really does end a sentence (usually after an +end-of-sentence capital letter). See Ending a Sentence. + +
@/
Produces no output, but allows a line break. See Line Breaks. + +
@:
Indicate to TeX that an immediately preceding period, question +mark, exclamation mark, or colon does not end a sentence. Prevent +TeX from inserting extra whitespace as it does at the end of a +sentence. The command has no effect on the Info file output. +See Not Ending a Sentence. + +
@=
Generate a macron (bar) accent over the next character, as in o¯. +See Inserting Accents. + +
@?
Generate a question mark that really does end a sentence (usually after +an end-of-sentence capital letter). See Ending a Sentence. + +
@@
Stands for an at sign, @. +See Inserting @ and {} and ,. + +
@\
Stands for a backslash (\) inside @math. +See math. + +
@^
@`
Generate a circumflex (hat) or grave accent, respectively, over the next +character, as in ô and è. +See Inserting Accents. + +
@{
Stands for a left brace, {. +See Inserting @ and {} and ,. + +
@}
Stands for a right-hand brace, }.
+See Inserting @ and {} and ,. + +
@~
Generate a tilde accent over the next character, as in Ñ. +See Inserting Accents. + +
@AA{}
@aa{}
Generate the uppercase and lowercase Scandinavian A-ring letters, +respectively: Å, å. See Inserting Accents. + +
@acronym{abbrev}
Tag abbrev as an acronym, that is, an abbreviation written in all +capital letters, such as `NASA'. See acronym. + +
@AE{}
@ae{}
Generate the uppercase and lowercase AE ligatures, respectively: +Æ, æ. See Inserting Accents. + +
@afivepaper
Change page dimensions for the A5 paper size. See A4 Paper. + +
@afourlatex
@afourpaper
@afourwide
Change page dimensions for the A4 paper size. See A4 Paper. + +
@alias new=existing
Make the command @new an alias for the existing command +@existing. See alias. + +
@anchor{name}
Define name as the current location for use as a cross-reference +target. See @anchor. + +
@appendix title
Begin an appendix. The title appears in the table +of contents of a printed manual. In Info, the title is +underlined with asterisks. See The @unnumbered and @appendix Commands. + +
@appendixsec title
@appendixsection title
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. @appendixsection is a longer +spelling of the @appendixsec command. See Section Commands. + +
@appendixsubsec title
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 Subsection Commands. + +
@appendixsubsubsec title
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 The `subsub' Commands. + +
@asis
Used following @table, @ftable, and @vtable to +print the table's first column without highlighting (“as is”). +See Making a Two-column Table. + +
@author author
Typeset author flushleft and underline it. See The @title and @author Commands. + +
@b{text}
Print text in bold font. No effect in Info. See Fonts. + +
@bullet{}
Generate a large round dot, or the closest possible +thing to one. See @bullet. + +
@bye
Stop formatting a file. The formatters do not see the contents of a +file following an @bye command. See Ending a File. + +
@c comment
Begin a comment in Texinfo. The rest of the line does not appear in +either the Info file or the printed manual. A synonym for +@comment. See Comments. + +
@caption
Define the full caption for a @float. See caption shortcaption. + +
@cartouche
Highlight an example or quotation by drawing a box with rounded +corners around it. Pair with @end cartouche. No effect in +Info. See Drawing Cartouches Around Examples.) + +
@center line-of-text
Center the line of text following the command. +See @center. + +
@centerchap line-of-text
Like @chapter, but centers the chapter title. See @chapter. + +
@chapheading title
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 @majorheading and @chapheading. + +
@chapter title
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 @chapter. + +
@cindex entry
Add entry to the index of concepts. See Defining the Entries of an Index. + +
@cite{reference}
Highlight the name of a book or other reference that lacks a +companion Info file. See @cite. + +
@clear flag
Unset flag, preventing the Texinfo formatting commands from +formatting text between subsequent pairs of @ifset flag +and @end ifset commands, and preventing +@value{flag} from expanding to the value to which +flag is set. +See @set @clear @value. + +
@code{sample-code}
Highlight text that is an expression, a syntactically complete token +of a program, or a program name. See @code. + +
@comma{}
Insert a comma `,' character; only needed when a literal comma would +be taken as an argument separator. See Inserting a Comma. + +
@command{command-name}
Indicate a command name, such as ls. +See @command. + +
@comment comment
Begin a comment in Texinfo. The rest of the line does not appear in +either the Info file or the printed manual. A synonym for @c. +See Comments. + +
@contents
Print a complete table of contents. Has no effect in Info, which uses +menus instead. See Generating a Table of Contents. + +
@copyright{}
Generate the copyright symbol ©. See @copyright{}. + +
@defcodeindex index-name
Define a new index and its indexing command. Print entries in an +@code font. See Defining New Indices. + +
@defcv category class name
@defcvx category class name
Format a description for a variable associated with a class in +object-oriented programming. Takes three arguments: the category of +thing being defined, the class to which it belongs, and its name. +See Definition Commands, and Def Cmds in Detail. + +
@deffn category name arguments...
@deffnx category name arguments...
Format a description for a function, interactive command, or similar +entity that may take arguments. @deffn takes as arguments the +category of entity being described, the name of this particular +entity, and its arguments, if any. See Definition Commands. + +
@defindex index-name
Define a new index and its indexing command. Print entries in a roman +font. See Defining New Indices. + +
@definfoenclose newcmd, before, after,
Create new @-command newcmd for Info that marks text by enclosing +it in strings that precede and follow the text. See definfoenclose. + +
@defivar class instance-variable-name
@defivarx class instance-variable-name
This command formats a description for an instance variable in +object-oriented programming. The command is equivalent to @defcv +{Instance Variable} .... See Definition Commands, and +Def Cmds in Detail. + +
@defmac macroname arguments...
@defmacx macroname arguments...
Format a description for a macro. The command is equivalent to +@deffn Macro .... See Definition Commands, and +Def Cmds in Detail. + +
@defmethod class method-name arguments...
@defmethodx class method-name arguments...
Format a description for a method in object-oriented programming. The +command is equivalent to @defop Method .... Takes as +arguments the name of the class of the method, the name of the +method, and its arguments, if any. See Definition Commands, and +Def Cmds in Detail. + +
@defop category class name arguments...
@defopx category class name arguments...
Format a description for an operation in object-oriented programming. +@defop takes as arguments the 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 Definition Commands, and Abstract Objects. + +
@defopt option-name
@defoptx option-name
Format a description for a user option. The command is equivalent to +@defvr {User Option} .... See Definition Commands, and +Def Cmds in Detail. + +
@defspec special-form-name arguments...
@defspecx special-form-name arguments...
Format a description for a special form. The command is equivalent to +@deffn {Special Form} .... See Definition Commands, +and Def Cmds in Detail. + +
@deftp category name-of-type attributes...
@deftpx category name-of-type attributes...
Format a description for a data type. @deftp takes as arguments +the category, the name of the type (which is a word like int or +float), and then the names of attributes of objects of that type. +See Definition Commands, and Data Types. + +
@deftypecv category class data-type name
@deftypecvx category class data-type name
Format a description for a typed class variable in object-oriented programming. +See Definition Commands, and Abstract Objects. + +
@deftypefn classification data-type name arguments...
@deftypefnx classification data-type name arguments...
Format a description for a function or similar entity that may take +arguments and that is typed. @deftypefn takes as arguments the +classification of entity being described, the type, the name of the +entity, and its arguments, if any. See Definition Commands, and +Def Cmds in Detail. + +
@deftypefun data-type function-name arguments...
@deftypefunx data-type function-name arguments...
Format a description for a function in a typed language. +The command is equivalent to @deftypefn Function .... +See Definition Commands, and Def Cmds in Detail. + +
@deftypeivar class data-type variable-name
@deftypeivarx class data-type variable-name
Format a description for a typed instance variable in object-oriented +programming. See Definition Commands, and Abstract Objects. + +
@deftypemethod class data-type method-name arguments...
@deftypemethodx class data-type method-name arguments...
Format a description for a typed method in object-oriented programming. +See Definition Commands, and Def Cmds in Detail. + +
@deftypeop category class data-type name arguments...
@deftypeopx category class data-type name arguments...
Format a description for a typed operation in object-oriented programming. +See Definition Commands, and Abstract Objects. + +
@deftypevar data-type variable-name
@deftypevarx data-type variable-name
Format a description for a variable in a typed language. The command is +equivalent to @deftypevr Variable .... See Definition Commands, and Def Cmds in Detail. + +
@deftypevr classification data-type name
@deftypevrx classification data-type name
Format a description for something like a variable in a typed +language—an entity that records a value. Takes as arguments the +classification of entity being described, the type, and the name of the +entity. See Definition Commands, and Def Cmds in Detail. + +
@defun function-name arguments...
@defunx function-name arguments...
Format a description for functions. The command is equivalent to +@deffn Function .... See Definition Commands, and +Def Cmds in Detail. + +
@defvar variable-name
@defvarx variable-name
Format a description for variables. The command is equivalent to +@defvr Variable .... See Definition Commands, and +Def Cmds in Detail. + +
@defvr category name
@defvrx category name
Format a description for any kind of variable. @defvr takes +as arguments the category of the entity and the name of the entity. +See Definition Commands, +and Def Cmds in Detail. + +
@detailmenu
Avoid makeinfo confusion stemming from the detailed node listing +in a master menu. See Master Menu Parts. + +
@dfn{term}
Highlight the introductory or defining use of a term. +See @dfn. + +
@dircategory dirpart
Specify a part of the Info directory menu where this file's entry should +go. See Installing Dir Entries. + +
@direntry
Begin the Info directory menu entry for this file. Pair with +@end direntry. See Installing Dir Entries. + +
@display
Begin a kind of example. Like @example (indent text, do not +fill), but do not select a new font. Pair with @end display. +See @display. + +
@dmn{dimension}
Format a unit of measure, as in 12pt. Causes TeX to insert a +thin space before dimension. No effect in Info. +See @dmn. + +
@docbook
Enter Docbook completely. Pair with @end docbook. See Raw Formatter Commands. + +
@documentdescription
Set the document description text, included in the HTML output. Pair +with @end documentdescription. See @documentdescription. + +
@documentencoding enc
Declare the input encoding to be enc. +See @documentencoding. + +
@documentlanguage CC
Declare the document language as the two-character ISO-639 abbreviation +CC. See @documentlanguage. + +
@dotaccent{c}
Generate a dot accent over the character c, as in o.. +See Inserting Accents. + +
@dots{}
Insert an ellipsis: .... +See @dots. + +
@email{address[, displayed-text]}
Indicate an electronic mail address. +See @email. + +
@emph{text}
Highlight text; text is displayed in italics in printed +output, and surrounded by asterisks in Info. See Emphasizing Text. + +
@end environment
Ends environment, as in @end example. See @-commands. + +
@env{environment-variable}
Indicate an environment variable name, such as PATH. +See @env. + +
@enddots{}
Generate an end-of-sentence of ellipsis, like this .... +See @dots{}. + +
@enumerate [number-or-letter]
Begin a numbered list, using @item for each entry. +Optionally, start list with number-or-letter. Pair with +@end enumerate. See @enumerate. + +
@equiv{}
Indicate to the reader the exact equivalence of two forms with a +glyph: ==. See Equivalence. + +
@error{}
Indicate to the reader with a glyph that the following text is +an error message: error-->. See Error Glyph. + +
@evenfooting [left] @| [center] @| [right]
@evenheading [left] @| [center] @| [right]
Specify page footings resp. headings for even-numbered (left-hand) +pages. See How to Make Your Own Headings. + +
@everyfooting [left] @| [center] @| [right]
@everyheading [left] @| [center] @| [right]
Specify page footings resp. headings for every page. Not relevant to +Info. See How to Make Your Own Headings. + +
@example
Begin an example. Indent text, do not fill, and select fixed-width font. +Pair with @end example. See @example. + +
@exampleindent indent
Indent example-like environments by indent number of spaces +(perhaps 0). See Paragraph Indenting. + +
@exclamdown{}
Produce an upside-down exclamation point. See Inserting Accents. + +
@exdent line-of-text
Remove any indentation a line might have. See Undoing the Indentation of a Line. + +
@expansion{}
Indicate the result of a macro expansion to the reader with a special +glyph: ==>. +See ==> Indicating an Expansion. + +
@file{filename}
Highlight the name of a file, buffer, node, or directory. See @file. + +
@finalout
Prevent TeX from printing large black warning rectangles beside +over-wide lines. See Overfull hboxes. + +
@findex entry
Add entry to the index of functions. See Defining the Entries of an Index. + +
@float
Environment to define floating material. Pair with @end float. +See Floats. + +
@flushleft
@flushright
Left justify every line but leave the right end ragged. +Leave font as is. Pair with @end flushleft. +@flushright analogous. +See @flushleft and @flushright. + +
@footnote{text-of-footnote}
Enter a footnote. Footnote text is printed at the bottom of the page +by TeX; Info may format in either `End' node or `Separate' node style. +See Footnotes. + +
@footnotestyle style
Specify an Info file's footnote style, either end for the end +node style or separate for the separate node style. +See Footnotes. + +
@format
Begin a kind of example. Like @display, but do not narrow the +margins. Pair with @end format. See @example. + +
@ftable formatting-command
Begin a two-column table, using @item for each entry. +Automatically enter each of the items in the first column into the +index of functions. Pair with @end ftable. The same as +@table, except for indexing. See @ftable and @vtable. + +
@group
Hold text together that must appear on one printed page. Pair with +@end group. Not relevant to Info. See @group. + +
@H{c}
Generate the long Hungarian umlaut accent over c, as in o''. + +
@heading title
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 Section Commands. + +
@headings on-off-single-double
Turn page headings on or off, and/or specify single-sided or double-sided +page headings for printing. See The @headings Command. + +
@html
Enter HTML completely. Pair with @end html. See Raw Formatter Commands. + +
@hyphenation{hy-phen-a-ted words}
Explicitly define hyphenation points. See @- and @hyphenation. + +
@i{text}
Print text in italic font. No effect in Info. See Fonts. + +
@ifclear flag
If flag is cleared, the Texinfo formatting commands format text +between @ifclear flag and the following @end +ifclear command. +See @set @clear @value. + +
@ifdocbook
@ifhtml
@ifinfo
Begin text that will appear only in the given output format. +@ifinfo output appears in both Info and (for historical +compatibility) plain text output. Pair with @end ifdocbook +resp. @end ifhtml resp. @end ifinfo. +See Conditionals. + +
@ifnotdocbook
@ifnothtml
@ifnotinfo
@ifnotplaintext
@ifnottex
@ifnotxml
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: +@ifnothtml text is omitted from html output, etc. The exception +is @ifnotinfo text, which is omitted from plain text output as +well as Info output. Pair with the corresponding @end +ifnotformat. See Conditionals. + +
@ifplaintext
Begin text that will appear only in the plain text output. +Pair with @end ifplaintext. See Conditionals. + +
@ifset flag
If flag is set, the Texinfo formatting commands format text +between @ifset flag and the following @end ifset +command. +See @set @clear @value. + +
@iftex
Begin text that will not appear in the Info file or other output, but +will be processed only by TeX. Pair with @end iftex. +See Conditionally Visible Text. + +
@ifxml
Begin text that will appear only in the XML output. Pair with +@end ifxml. See Conditionals. + +
@ignore
Begin text that will not appear in any output. Pair with @end +ignore. See Comments and Ignored Text. + +
@image{filename, [width], [height], [alt], [ext]}
Include graphics image in external filename scaled to the given +width and/or height, using alt text and looking for +filename.ext in HTML. See Images. + +
@include filename
Incorporate the contents of the file filename into the Info file +or printed document. See Include Files. + +
@indicateurl{indicateurl}
Indicate text that is a uniform resource locator for the World Wide +Web. See @indicateurl. + +
@inforef{node-name, [entry-name], info-file-name}
Make a cross reference to an Info file for which there is no printed +manual. See Cross references using @inforef. + +
\input macro-definitions-file
Use the specified macro definitions file. This command is used only +in the first line of a Texinfo file to cause TeX to make use of the +texinfo macro definitions file. The backslash in \input +is used instead of an @ because TeX does not +recognize @ until after it has read the definitions file. +See Texinfo File Header. + +
@item
Indicate the beginning of a marked paragraph for @itemize and +@enumerate; indicate the beginning of the text of a first column +entry for @table, @ftable, and @vtable. +See Lists and Tables. + +
@itemize mark-generating-character-or-command
Produce a sequence of indented paragraphs, with a mark inside the left +margin at the beginning of each paragraph. Pair with @end +itemize. See @itemize. + +
@itemx
Like @item but do not generate extra vertical space above the +item text. See @itemx. + +
@kbd{keyboard-characters}
Indicate text that is characters of input to be typed by +users. See @kbd. + +
@kbdinputstyle style
Specify when @kbd should use a font distinct from @code. +See @kbd. + +
@key{key-name}
Indicate a name for a key on a keyboard. +See @key. + +
@kindex entry
Add entry to the index of keys. +See Defining the Entries of an Index. + +
@L{}
@l{}
Generate the uppercase and lowercase Polish suppressed-L letters, +respectively: /L, /l. + +
@LaTeX{}
Insert the logo LaTeX. See TeX and LaTeX. + +
@lisp
Begin an example of Lisp code. Indent text, do not fill, and select +fixed-width font. Pair with @end lisp. See @lisp. + +
@listoffloats
Produce a table-of-contents-like listing of @floats. +See listoffloats. + +
@lowersections
Change subsequent chapters to sections, sections to subsections, and so +on. See @raisesections and @lowersections. + +
@macro macroname {params}
Define a new Texinfo command @macroname{params}. +Only supported by makeinfo and texi2dvi. See Defining Macros. + +
@majorheading title
Print a chapter-like heading in the text, but not in the table of +contents of a printed manual. Generate more vertical whitespace before +the heading than the @chapheading command. See @majorheading and @chapheading. + +
@math{mathematical-expression}
Format a mathematical expression. +See @math: Inserting Mathematical Expressions. + +
@menu
Mark the beginning of a menu of nodes in Info. No effect in a printed +manual. Pair with @end menu. See Menus. + +
@minus{}
Generate a minus sign, `−'. See @minus. + +
@multitable column-width-spec
Begin a multi-column table. Pair with @end multitable. +See Multitable Column Widths. + +
@need n
Start a new page in a printed manual if fewer than n mils +(thousandths of an inch) remain on the current page. See @need. + +
@node name, next, previous, up
Define the beginning of a new node in Info, and serve as a locator for +references for TeX. See @node. + +
@noindent
Prevent text from being indented as if it were a new paragraph. +See @noindent. + +
@novalidate
Suppress validation of node references, omit creation of auxiliary files +with TeX. Use before @setfilename. See Pointer Validation. + +
@O{}
@o{}
Generate the uppercase and lowercase O-with-slash letters, respectively: +Ø, ø. + +
@oddfooting [left] @| [center] @| [right]
@oddheading [left] @| [center] @| [right]
Specify page footings resp. headings for odd-numbered (right-hand) +pages. See How to Make Your Own Headings. + +
@OE{}
@oe{}
Generate the uppercase and lowercase OE ligatures, respectively: +Œ, œ. See Inserting Accents. + +
@option{option-name}
Indicate a command-line option, such as -l or --help. +See @option. + +
@page
Start a new page in a printed manual. No effect in Info. +See @page. + +
@pagesizes [width][, height]
Change page dimensions. See pagesizes. + +
@paragraphindent indent
Indent paragraphs by indent number of spaces (perhaps 0); preserve +source file indentation if indent is asis. +See Paragraph Indenting. + +
@pindex entry
Add entry to the index of programs. See Defining the Entries of an Index. + +
@point{}
Indicate the position of point in a buffer to the reader with a +glyph: -!-. See Indicating Point in a Buffer. + +
@pounds{}
Generate the pounds sterling currency sign. +See @pounds{}. + +
@print{}
Indicate printed output to the reader with a glyph: +-|. See Print Glyph. + +
@printindex index-name
Print an alphabetized two-column index in a printed manual or generate +an alphabetized menu of index entries for Info. See Printing Indices & Menus. + +
@pxref{node-name, [entry], [topic-or-title], [info-file], [manual]}
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 @pxref. + +
@questiondown{}
Generate an upside-down question mark. See Inserting Accents. + +
@quotation
Narrow the margins to indicate text that is quoted from another real +or imaginary work. Takes optional argument of prefix text. Pair with +@end quotation. See @quotation. + +
@r{text}
Print text in roman font. No effect in Info. +See Fonts. + +
@raisesections
Change subsequent sections to chapters, subsections to sections, and so +on. See @raisesections and @lowersections. + +
@ref{node-name, [entry], [topic-or-title], [info-file], [manual]}
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 @ref. + +
@refill
This command used to refill and indent the paragraph after all the +other processing has been done. It is no longer needed, since all +formatters now automatically refill as needed, but you may still see +it in the source to some manuals, as it does no harm. + +
@registeredsymbol{}
Generate the legal symbol ®. See @registeredsymbol{}. + +
@result{}
Indicate the result of an expression to the reader with a special +glyph: =>. See @result. + +
@ringaccent{c}
Generate a ring accent over the next character, as in o*. +See Inserting Accents. + +
@samp{text}
Highlight text that is a literal example of a sequence of +characters. Used for single characters, for statements, and often for +entire shell commands. See @samp. + +
@sc{text}
Set text in a printed output in the small caps font and +set text in the Info file in uppercase letters. +See Smallcaps. + +
@section title
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 @section. + +
@set flag [string]
Make flag active, causing the Texinfo formatting commands to +format text between subsequent pairs of @ifset flag and +@end ifset commands. Optionally, set value of flag to +string. +See @set @clear @value. + +
@setchapternewpage on-off-odd
Specify whether chapters start on new pages, and if so, whether on +odd-numbered (right-hand) new pages. See @setchapternewpage. + +
@setcontentsaftertitlepage
Put the table of contents after the @end titlepage even if the +@contents command is not there. See Contents. + +
@setfilename info-file-name
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 @setfilename. + +
@setshortcontentsaftertitlepage
Place the short table of contents after the @end titlepage +command even if the @shortcontents command is not there. +See Contents. + +
@settitle title
Provide a title for page headers in a printed manual, and the default +document description for HTML <head>. +See @settitle. + +
@shortcaption
Define the short caption for a @float. See caption shortcaption. + +
@shortcontents
Print a short table of contents. Not relevant to Info, which uses +menus rather than tables of contents. A synonym for +@summarycontents. See Generating a Table of Contents. + +
@shorttitlepage title
Generate a minimal title page. See @titlepage. + +
@smallbook
Cause TeX to produce a printed manual in a 7 by 9.25 inch format +rather than the regular 8.5 by 11 inch format. See Printing Small Books. Also, see small. + +
@smalldisplay
Begin a kind of example. Like @smallexample (narrow margins, no +filling), but do not select the fixed-width font. Pair with @end +smalldisplay. See small. + +
@smallexample
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 @example. Pair with @end smallexample. +See small. + +
@smallformat
Begin a kind of example. Like @smalldisplay, but do not narrow +the margins. Pair with @end smallformat. See small. + +
@smalllisp
Begin an example of Lisp code. Same as @smallexample. Pair +with @end smalllisp. See small. + +
@sp n
Skip n blank lines. See @sp. + +
@ss{}
Generate the German sharp-S es-zet letter, ß. See Inserting Accents. + +
@strong {text}
Emphasize text by typesetting it in a bold font for the +printed manual and by surrounding it with asterisks for Info. +See Emphasizing Text. + +
@subheading title
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 @unnumberedsubsec @appendixsubsec @subheading. + +
@subsection title
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 @subsection. + +
@subsubheading title
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 The `subsub' Commands. + +
@subsubsection title
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 The `subsub' Commands. + +
@subtitle title
In a printed manual, set a subtitle in a normal sized font flush to +the right-hand side of the page. Not relevant to Info, which does not +have title pages. See @title @subtitle and @author Commands. + +
@summarycontents
Print a short table of contents. Not relevant to Info, which uses +menus rather than tables of contents. A synonym for +@shortcontents. See Generating a Table of Contents. + +
@syncodeindex from-index into-index
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 font. See Combining Indices. + +
@synindex from-index into-index
Merge the index named in the first argument into the index named in +the second argument. Do not change the font of from-index +entries. See Combining Indices. + +
@t{text}
Print text in a fixed-width, typewriter-like font. +No effect in Info. See Fonts. + +
@tab
Separate columns in a multitable. See Multitable Rows. + +
@table formatting-command
Begin a two-column table, using @item for each entry. Write +each first column entry on the same line as @item. First +column entries are printed in the font resulting from +formatting-command. Pair with @end table. +See Making a Two-column Table. +Also see @ftable and @vtable, +and @itemx. + +
@TeX{}
Insert the logo TeX. See TeX and LaTeX. + +
@tex
Enter TeX completely. Pair with @end tex. See Raw Formatter Commands. + +
@thischapter
@thischaptername
@thisfile
@thispage
@thistitle
Only allowed in a heading or footing. Stands for the number and name of +the current chapter (in the format `Chapter 1: Title'), the chapter name +only, the filename, the current page number, and the title of the +document, respectively. See How to Make Your Own Headings. + +
@tie{}
Generate a normal interword space at which a line break is not allowed. +See @tie{}. + +
@tieaccent{cc}
Generate a tie-after accent over the next two characters cc, as in +`oo['. See Inserting Accents. + +
@tindex entry
Add entry to the index of data types. See Defining the Entries of an Index. + +
@title title
In a printed manual, set a title flush to the left-hand side of the +page in a larger than normal font and underline it with a black rule. +Not relevant to Info, which does not have title pages. See The @title @subtitle and @author Commands. + +
@titlefont{text}
In a printed manual, print text in a larger than normal font. +Not relevant to Info, which does not have title pages. +See The @titlefont @center and @sp Commands. + +
@titlepage
Indicate to Texinfo the beginning of the title page. Write command on +a line of its own. Pair with @end titlepage. Nothing between +@titlepage and @end titlepage appears in Info. +See @titlepage. + +
@today{}
Insert the current date, in `1 Jan 1900' style. See How to Make Your Own Headings. + +
@top title
In a Texinfo file to be formatted with makeinfo, identify the +topmost @node in the file, which must be written on the line +immediately preceding the @top command. Used for +makeinfo's node pointer insertion feature. The title is +underlined with asterisks. Both the @node line and the @top +line normally should be enclosed by @ifnottex and @end +ifnottex. In TeX and texinfo-format-buffer, the @top +command is merely a synonym for @unnumbered. See Creating Pointers with makeinfo. + +
@u{c}
@ubaraccent{c}
@udotaccent{c}
Generate a breve, underbar, or underdot accent, respectively, over or +under the character c, as in o(, o_, +.o. See Inserting Accents. + +
@unnumbered title
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 @unnumbered and @appendix. + +
@unnumberedsec title
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 Section Commands. + +
@unnumberedsubsec title
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 @unnumberedsubsec @appendixsubsec @subheading. + +
@unnumberedsubsubsec title
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 The `subsub' Commands. + +
@uref{url[, displayed-text][, replacement}
@url{url[, displayed-text][, replacement}
Define a cross reference to an external uniform resource locator for the +World Wide Web. See @uref. + +
@v{c}
Generate check accent over the character c, as in o<. +See Inserting Accents. + +
@value{flag}
Replace flag with the value to which it is set by @set +flag. +See @set @clear @value. + +
@var{metasyntactic-variable}
Highlight a metasyntactic variable, which is something that stands for +another piece of text. See Indicating Metasyntactic Variables. + +
@verb{delim literal delim}
Output literal, delimited by the single character delim, +exactly as is (in the fixed-width font), including any whitespace or +Texinfo special characters. See verb. + +
@verbatim
Output the text of the environment exactly as is (in the fixed-width +font). Pair with @end verbatim. See verbatim. + +
@verbatiminclude filename
Output the contents of filename exactly as is (in the fixed-width font). +See verbatiminclude. + +
@vindex entry
Add entry to the index of variables. See Defining the Entries of an Index. + +
@vskip amount
In a printed manual, insert whitespace so as to push text on the +remainder of the page towards the bottom of the page. Used in +formatting the copyright page with the argument 0pt plus +1filll. (Note spelling of filll.) @vskip may be used +only in contexts ignored for Info. See Copyright. + +
@vtable formatting-command
Begin a two-column table, using @item for each entry. +Automatically enter each of the items in the first column into the +index of variables. Pair with @end vtable. The same as +@table, except for indexing. See @ftable and @vtable. + +
@w{text}
Prevent text from being split across two lines. +See @w. + +
@xml
Enter XML completely. Pair with @end xml. See Raw Formatter Commands. + +
@xref{node-name, [entry], [topic-or-title], [info-file], [manual]}
Make a reference that starts with `See' in a printed manual. Follow +command with a punctuation mark. Only the first argument is +mandatory. See @xref. +
+ +
+


+Up: Command List +
+
+ +

A.1 @-Command Syntax

+ +

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

+
1. Non-alphabetic commands.
These commands consist of an @ followed by a punctuation mark or other +character that is not part of the alphabet. Non-alphabetic commands are +almost always part of the text within a paragraph, and never take any +argument. The two characters (@ and the other one) are complete in +themselves; none is followed by braces. The non-alphabetic commands +are: @., @:, @*, @SPACE, +@TAB, @NL, @@, @{, and +@}. + +
2. Alphabetic commands that do not require arguments.
These commands start with @ followed by a word followed by left- and +right-hand braces. These commands insert special symbols in the +document; they do not require arguments. For example, +@dots{} => ..., @equiv{} +=> ==, @TeX{} => `TeX', +and @bullet{} => . + +
3. Alphabetic commands that require arguments within braces.
These commands start with @ followed by a letter or a word, followed by an +argument within braces. For example, the command @dfn indicates +the introductory or defining use of a term; it is used as follows: In +Texinfo, @@-commands are @dfn{mark-up} commands. + +
4. Alphabetic commands that occupy an entire line.
These commands occupy an entire line. The line starts with @, +followed by the name of the command (a word); for example, @center +or @cindex. If no argument is needed, the word is followed by +the end of the line. If there is an argument, it is separated from +the command name by a space. Braces are not used. +
+ +

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

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

+


+Next: , +Previous: Command List, +Up: Top +
+
+ +

Appendix B Tips and Hints

+ +

Here are some tips for writing Texinfo documentation: + +

+

+ +
Index, Index, Index!
+ +

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

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

Here are more hints we have found valuable: + +

+ +
Blank Lines
+ + + +
Complete Phrases
+ +

Complete phrases are easier to read than ... + +

+ +
Editions, Dates and Versions
+ +

Include edition numbers, version numbers, and dates in the +@copying text (for people reading the Texinfo file, and for the +legal copyright in the output files). Then use @insertcopying +in the @titlepage section (for people reading the printed +output) and the Top node (for people reading the online output). + +

It is easiest to do this using @set and @value. +See @value Example, and GNU Sample Texts. + +

Definition Commands
+ +

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

+ +
Capitalization
+ + + +
Spaces
+ +

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

For example, TeX fills the following: + +

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

so it looks like this: + +

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

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

@code, @samp, @var, and ---
+ + + +
Periods Outside of Quotes
+ +

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

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

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

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

Introducing New Terms
+ + + +
@pxref
+ + +

Absolutely never use @pxref 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. + +

Invoking from a Shell
+ +

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

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

ANSI C Syntax
+ +

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

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

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

Avoid the obsolete style that looks like this: + +

     #include <dld.h>
+     
+     dld_init (path)
+     char *path;
+
+

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

Bad Examples
+ +

Here are several examples of bad writing to avoid: + +

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

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

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

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

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

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


+Next: , +Previous: Tips, +Up: Top +
+
+ +

Appendix C Sample Texinfo Files

+ +

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

+ +
+


+Next: , +Up: Sample Texinfo Files +
+
+ +

C.1 Short Sample

+ +

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

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

+
+
+
     \input texinfo   @c -*-texinfo-*-
+     @c %**start of header
+     @setfilename sample.info
+     @settitle Sample Manual 1.0
+     @c %**end of header
+     
+     @copying
+     This is a short example of a complete Texinfo file.
+     
+     Copyright (C) 2004 Free Software Foundation, Inc.
+     @end copying
+     
+     @titlepage
+     @title Sample Title
+     @page
+     @vskip 0pt plus 1filll
+     @insertcopying
+     @end titlepage
+     
+     @c Output the table of the contents at the beginning.
+     @contents
+     
+     @ifnottex
+     @node Top
+     @top GNU Sample
+     
+     @insertcopying
+     @end ifnottex
+     
+     @menu
+     * First Chapter::    The first chapter is the
+                           only chapter in this sample.
+     * Index::            Complete index.
+     @end menu
+     
+     
+     @node First Chapter
+     @chapter First Chapter
+     
+     @cindex chapter, first
+     
+     This is the first chapter.
+     @cindex index entry, another
+     
+     Here is a numbered list.
+     
+     @enumerate
+     @item
+     This is the first item.
+     
+     @item
+     This is the second item.
+     @end enumerate
+     
+     
+     @node Index
+     @unnumbered Index
+     
+     @printindex cp
+     
+     @bye
+
+
+


+Next: , +Previous: Short Sample Texinfo File, +Up: Sample Texinfo Files +
+
+ +

C.2 GNU Sample Texts

+ +

+Following is a sample Texinfo document with the full texts that should +be used in GNU manuals. + +

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

See Short Sample, for a minimal example of a Texinfo file. +See Beginning a File, for a full explanation of that minimal +example. + +

Here are some notes on the example: + +

+ +

Here is the sample document: + +

+\input texinfo   @c -*-texinfo-*-
+@comment $Id: texinfo.txi,v 1.52 2004/04/09 21:30:07 karl Exp $
+@comment %**start of header
+@setfilename sample.info
+@include version.texi
+@settitle GNU Sample @value{VERSION}
+@syncodeindex pg cp
+@comment %**end of header
+@copying
+This manual is for GNU Sample
+(version @value{VERSION}, @value{UPDATED}),
+which is an example in the Texinfo documentation.
+
+Copyright @copyright{} 2004 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below.  A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License.''
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software.  Copies published by the Free
+Software Foundation raise funds for GNU development.''
+@end quotation
+@end copying
+
+@dircategory Texinfo documentation system
+@direntry
+* sample: (sample)Invoking sample.
+@end direntry
+
+@titlepage
+@title GNU Sample
+@subtitle for version @value{VERSION}, @value{UPDATED}
+@author A.U. Thor (@email{bug-texinfo@@gnu.org})
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top GNU Sample
+
+@insertcopying
+@end ifnottex
+
+@menu
+* Invoking sample::
+* Copying This Manual::
+* Index::
+@end menu
+
+
+@node Invoking sample
+@chapter Invoking sample
+
+@pindex sample
+@cindex invoking @command{sample}
+
+This is a sample manual.  There is no sample program to
+invoke, but if there was, you could see its basic usage
+and command line options here.
+
+
+@node Copying This Manual
+@appendix Copying This Manual
+
+@menu
+* GNU Free Documentation License::  License for copying this manual.
+@end menu
+
+@include fdl.texi
+
+
+@node Index
+@unnumbered Index
+
+@printindex cp
+
+@bye
+
+ +
+


+Next: , +Previous: GNU Sample Texts, +Up: Sample Texinfo Files +
+
+ +

C.3 Verbatim Copying License

+ +

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

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

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

+@copying
+This document is a sample for allowing verbatim copying only.
+
+Copyright @copyright{} 2004 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to make and distribute verbatim copies
+of this entire document without royalty provided the
+copyright notice and this permission notice are preserved.
+@end quotation
+@end copying
+
+ +
+


+Previous: Verbatim Copying License, +Up: Sample Texinfo Files +
+
+ +

C.4 All-permissive Copying License

+ +

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

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

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

     Copyright © 2004 Free Software Foundation, Inc.
+     
+     Copying and distribution of this file, with or without modification,
+     are permitted in any medium without royalty provided the copyright
+     notice and this notice are preserved.
+
+
+


+Next: , +Previous: Sample Texinfo Files, +Up: Top +
+
+ +

Appendix D Include Files

+ +

+When TeX or an Info formatting command sees an @include +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. + +

Include files let you keep a single large document as a collection of +conveniently small parts. + +

+ +
+


+Next: , +Up: Include Files +
+
+ +

D.1 How to Use Include Files

+ +

+To include another file within a Texinfo file, write the +@include 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: + +

     @include buffers.texi
+
+

The name of the file is taken literally, with a single exception: +@value{var} references are expanded. This makes it +possible to reliably include files in other directories in a +distribution. See @verbatiminclude, for +an example. + +

An included file should simply be a segment of text that you expect to +be included as is into the overall or outer 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 \input texinfo; if you do, that phrase is inserted +into the output file as is. Likewise, you should not end an included +file with an @bye command; nothing after @bye is +formatted. + +

In the past, you were required to write an @setfilename line at the +beginning of an included file, but no longer. Now, it does not matter +whether you write such a line. If an @setfilename line exists +in an included file, it is ignored. + +

Conventionally, an included file begins with an @node line that +is followed by an @chapter 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 @node 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, texinfo-multiple-files-update, that is +designed for @include files. + +

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 GNU Sample Texts). + +

+


+Next: , +Previous: Using Include Files, +Up: Include Files +
+
+ +

D.2 texinfo-multiple-files-update

+ +

+GNU Emacs Texinfo mode provides the texinfo-multiple-files-update +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 @node line of the +included files or all of them: + +

+
M-x texinfo-multiple-files-update
Called without any arguments: + +
    +
  • Create or update the `Next', `Previous', and `Up' pointers of the +first @node line in each file included in an outer or overall +Texinfo file. + +
  • Create or update the `Top' level node pointers of the outer or +overall file. + +
  • Create or update a main menu in the outer file. +
+ +
C-u M-x texinfo-multiple-files-update
Called with C-u as a prefix argument: + +
    +
  • Create or update pointers in the first @node line in each +included file. + +
  • Create or update the `Top' level node pointers of the outer file. + +
  • Create and insert a master menu in the outer file. The master menu +is made from all the menus in all the included files. +
+ +
C-u 8 M-x texinfo-multiple-files-update
Called with a numeric prefix argument, such as C-u 8: + +
    +
  • Create or update all the `Next', `Previous', and `Up' pointers +of all the included files. + +
  • Create or update all the menus of all the included +files. + +
  • Create or update the `Top' level node pointers of the outer or +overall file. + +
  • And then create a master menu in the outer file. This is similar to +invoking texinfo-master-menu with an argument when you are +working with just one file. +
+
+ +

Note the use of the prefix argument in interactive use: with a regular +prefix argument, just C-u, the +texinfo-multiple-files-update command inserts a master menu; +with a numeric prefix argument, such as C-u 8, the command +updates every pointer and menu in all the files and then inserts a +master menu. + +

+


+Next: , +Previous: texinfo-multiple-files-update, +Up: Include Files +
+
+ +

D.3 Include Files Requirements

+ +

+If you plan to use the texinfo-multiple-files-update 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 @include commands listing the included files. It +should not even include indices, which should be listed in an included +file of their own. + +

Moreover, each of the included files must contain exactly one highest +level node (conventionally, @chapter 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 @chapter, an @appendix, or an +@unnumbered node. Thus, normally, each included file contains +one, and only one, chapter or equivalent-level node. + +

The outer file should contain only one node, the `Top' node. It +should not contain any nodes besides the single `Top' node. The +texinfo-multiple-files-update command will not process +them. + +

+


+Next: , +Previous: Include Files Requirements, +Up: Include Files +
+
+ +

D.4 Sample File with @include

+ +

+Here is an example of an outer Texinfo file with @include files +within it before running texinfo-multiple-files-update, which +would insert a main or master menu: + +

     \input texinfo @c -*-texinfo-*-
+     
+     @setfilename include-example.info
+     @settitle Include Example
+     
+     
+     ... See Sample Texinfo Files, 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
+
+

An included file, such as foo.texinfo, might look like this: + +

     @node First
+     @chapter First Chapter
+     
+     Contents of first chapter ...
+
+

The full contents of concept-index.texinfo might be as simple as this: + +

     @node Concept Index
+     @unnumbered Concept Index
+     
+     @printindex cp
+
+

The outer Texinfo source file for The GNU Emacs Lisp Reference +Manual is named elisp.texi. This outer file contains a master +menu with 417 entries and a list of 41 @include +files. + +

+


+Previous: Sample Include File, +Up: Include Files +
+
+ +

D.5 Evolution of Include Files

+ +

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

References from one file to another were made by referring to the file +name as well as the node name. (See Referring to Other Info Files. Also, see @xref with Four and Five Arguments.) + +

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 +@setfilename line.) + +

However, because large Info files are now split automatically, it is +no longer necessary to keep them small. + +

Nowadays, multiple Texinfo files are used mostly for large documents, +such as The GNU Emacs Lisp Reference Manual, and for projects +in which several different people write different sections of a +document simultaneously. + +

In addition, the Info formatting commands have been extended to work +with the @include 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. + +

+


+Next: , +Previous: Include Files, +Up: Top +
+
+ +

Appendix E Page Headings

+ +

+Most printed manuals contain headings along the top of every page +except the title and copyright pages. Some manuals also contain +footings. (Headings and footings have no meaning to Info, which is +not paginated.) + +

+ +
+


+Next: , +Up: Headings +
+
+ +

E.1 Headings Introduced

+ +

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

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

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

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

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

+


+Next: , +Previous: Headings Introduced, +Up: Headings +
+
+ + +

E.2 Standard Heading Formats

+ +

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

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

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

A single-sided page looks like this: + +

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

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

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

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

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

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

+


+Next: , +Previous: Heading Format, +Up: Headings +
+
+ + +

E.3 Specifying the Type of Heading

+ +

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

There are four possibilities: + +

+
No @setchapternewpage command
Cause TeX to specify the single-sided heading format, with chapters +on new pages. This is the same as @setchapternewpage on. + +
@setchapternewpage on
Specify the single-sided heading format, with chapters on new pages. + +
@setchapternewpage off
Cause TeX to start a new chapter on the same page as the last page of +the preceding chapter, after skipping some vertical whitespace. Also +cause TeX to typeset for single-sided printing. (You can override +the headers format with the @headings double command; see +The @headings Command.) + +
@setchapternewpage odd
Specify the double-sided heading format, with chapters on new pages. +
+ +

Texinfo lacks an @setchapternewpage even command. + +

+


+Previous: Heading Choice, +Up: Headings +
+
+ + +

E.4 How to Make Your Own Headings

+ +

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

Texinfo provides six commands for specifying headings and +footings: +

+ +

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

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

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

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

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

Here are the six heading and footing commands: + +

+

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


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

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

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

@thispage
Expands to the current page number. + + +


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


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


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


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

You can also use the @today{} command, which expands to the +current date, in `1 Jan 1900' format. + +Other @-commands and text are printed in a header or footer just as +if they were in the body of a page. It is useful to incorporate text, +particularly when you are writing drafts: + +

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

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

+


+Next: , +Previous: Headings, +Up: Top +
+
+ +

Appendix F Formatting Mistakes

+ +

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

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

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

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

+ +
+


+Next: , +Up: Catching Mistakes +
+
+ +

F.1 makeinfo Find Errors

+ +

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

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

+


+Next: , +Previous: makeinfo Preferred, +Up: Catching Mistakes +
+
+ + +

F.2 Catching Errors with Info Formatting

+ +

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

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

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

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

     @end menus is not handled by texinfo
+
+

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

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

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

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

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

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

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

Formatting produces: +

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

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

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

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

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

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

+


+Next: , +Previous: Debugging with Info, +Up: Catching Mistakes +
+
+ + +

F.3 Catching Errors with TeX Formatting

+ +

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

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

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

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

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

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

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

     Paragraph ended before @xref was complete.
+
+

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

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

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

    +
  1. You can tell TeX to continue running and ignore just this error by +typing <RET> at the ? prompt. + +
  2. You can tell TeX to continue running and to ignore all errors as best +it can by typing r <RET> at the ? prompt. + +

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

  3. You can tell TeX to stop this run by typing x <RET> +at the ? prompt. +
+ +

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

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

     (@end occurred inside a group at level 1)
+
+

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

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

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

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

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

+


+Next: , +Previous: Debugging with TeX, +Up: Catching Mistakes +
+
+ + +

F.4 Using texinfo-show-structure

+ +

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

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

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

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

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

The first line in the *Occur* window describes the regular +expression specified by texinfo-heading-pattern. This regular +expression is the pattern that texinfo-show-structure looks for. +See Using Regular Expressions (The GNU Emacs Manual), +for more information. + +

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

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

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

+


+Next: , +Previous: Using texinfo-show-structure, +Up: Catching Mistakes +
+
+ + +

F.5 Using occur

+ +

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

     M-x occur
+
+

and then, when prompted, type a regexp, a regular expression for +the pattern you want to match. (See Regular Expressions (The GNU Emacs Manual).) The occur command works from +the current location of the cursor in the buffer to the end of the +buffer. If you want to run occur on the whole buffer, place +the cursor at the beginning of the buffer. + +

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

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

See Using Occur (The GNU Emacs Manual), +for more information. + +

+


+Previous: Using occur, +Up: Catching Mistakes +
+
+ + +

F.6 Finding Badly Referenced Nodes

+ +

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

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

+ +
+


+Next: , +Up: Running Info-Validate +
+
+ +

F.6.1 Running Info-validate

+ +

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

     M-x Info-validate
+
+

Note that the Info-validate command requires an upper case +`I'. You may also need to create a tag table before running +Info-validate. See Tagifying. + +

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

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

     In node "Overview", invalid Next: Texinfo Mode
+
+

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

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

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

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

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

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

+


+Next: , +Previous: Using Info-validate, +Up: Running Info-Validate +
+
+ + +

F.6.2 Creating an Unsplit File

+ +

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

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

     C-u M-x texinfo-format-buffer
+
+

or else + +

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

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

+


+Next: , +Previous: Unsplit, +Up: Running Info-Validate +
+
+ +

F.6.3 Tagifying a File

+ +

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

     M-x Info-tagify
+
+

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

The third step is to validate the Info file: + +

     M-x Info-validate
+
+

(Note the upper case I in Info-validate.) +In brief, the steps are: + +

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

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

+


+Previous: Tagifying, +Up: Running Info-Validate +
+
+ + +

F.6.4 Splitting a File Manually

+ +

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

The split-off files are called the indirect subfiles. + +

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

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

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

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

(Note that the I in Info is upper case.) + +

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

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

+


+Next: , +Previous: Catching Mistakes, +Up: Top +
+
+ +

Appendix G Copying This Manual

+ + + +
+


+Up: Copying This Manual +
+
+ +

G.1 GNU Free Documentation License

+ +

Version 1.2, November 2002
+ +
     Copyright © 2000,2001,2002 Free Software Foundation, Inc.
+     59 Temple Place, Suite 330, Boston, MA  02111-1307, USA
+     
+     Everyone is permitted to copy and distribute verbatim copies
+     of this license document, but changing it is not allowed.
+
+
    +
  1. PREAMBLE + +

    The purpose of this License is to make a manual, textbook, or other +functional and useful document free in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +

    This License is a kind of “copyleft”, which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +

    We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +

  2. APPLICABILITY AND DEFINITIONS + +

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

    A “Modified Version” of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +

    A “Secondary Section” is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (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. + +

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

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

    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”. + +

    Examples of suitable formats for Transparent copies include plain +ascii without markup, Texinfo input format, LaTeX input +format, SGML or XML using a publicly available +DTD, and standard-conforming simple HTML, +PostScript or PDF designed for human modification. Examples +of transparent image formats include PNG, XCF and +JPG. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, SGML or +XML for which the DTD and/or processing tools are +not generally available, and the machine-generated HTML, +PostScript or PDF produced by some word processors for +output purposes only. + +

    The “Title Page” means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, “Title Page” means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +

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

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

  3. VERBATIM COPYING + +

    You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +

    You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +

  4. COPYING IN QUANTITY + +

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

    If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +

    If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a 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. + +

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

  5. MODIFICATIONS + +

    You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +

      +
    1. 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. + +
    2. 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. + +
    3. State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +
    4. Preserve all the copyright notices of the Document. + +
    5. Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +
    6. 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. + +
    7. Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +
    8. Include an unaltered copy of this License. + +
    9. 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. + +
    10. 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. + +
    11. 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. + +
    12. 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. + +
    13. Delete any section Entitled “Endorsements”. Such a section +may not be included in the Modified Version. + +
    14. Do not retitle any existing section to be Entitled “Endorsements” or +to conflict in title with any Invariant Section. + +
    15. Preserve any Warranty Disclaimers. +
    + +

    If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +

    You may add a section Entitled “Endorsements”, provided it contains +nothing but endorsements of your Modified Version by various +parties—for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +

    You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +

    The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +

  6. COMBINING DOCUMENTS + +

    You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +

    The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +

    In the combination, you must combine any sections Entitled “History” +in the various original documents, forming one section Entitled +“History”; likewise combine any sections Entitled “Acknowledgements”, +and any sections Entitled “Dedications”. You must delete all +sections Entitled “Endorsements.” + +

  7. COLLECTIONS OF DOCUMENTS + +

    You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +

    You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +

  8. AGGREGATION WITH INDEPENDENT WORKS + +

    A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, 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. + +

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

  9. TRANSLATION + +

    Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, 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. + +

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

  10. TERMINATION + +

    You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + +

  11. FUTURE REVISIONS OF THIS LICENSE + +

    The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. + +

    Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License “or any later version” applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. +

+ +

G.1.1 ADDENDUM: How to use this License for your documents

+ +

To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +

       Copyright (C)  year  your name.
+       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''.
+
+

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the “with...Texts.” line with this: + +

         with the Invariant Sections being list their titles, with
+         the Front-Cover Texts being list, and with the Back-Cover Texts
+         being list.
+
+

If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +

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

+


+Next: , +Previous: Copying This Manual, +Up: Top +
+
+ +

Command and Variable Index

+ +

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 @. + + + +

+


+Previous: Command and Variable Index, +Up: Top +
+
+ +

Concept Index

+ + + +
+
+

Footnotes

[1] 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 X is actually the Greek letter “chi” rather than +the English letter “ex”. Pronounce TeX as if the X were the +last sound in the name `Bach'; but pronounce Texinfo as if the x +were a `k'. Spell “Texinfo” with a capital “T” and the other +letters in lower case.

+ +

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

+ +

[3] You can also use the +texi2roff program if you +do not have TeX; since Texinfo is designed for use with TeX, +texi2roff is not described here. texi2roff 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.

+ +

[4] The word +argument 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 Oxford English +Dictionary, the word derives from the Latin for to make clear, +prove; 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.

+ +

[5] 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.

+ +

[6] It would be straightforward to extend Texinfo to work +in a similar fashion for C, Fortran, or other languages.

+ +

[7] 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 The Chicago Manual of Style, which is published by the +University of Chicago Press.

+ +

[8] Here +is the sample footnote.

+ +

[9] Note the use +of the ; character, instead of :, as directory separator +on these systems.

+ +

[10] On MS-DOS/MS-Windows systems, Info will +try the .inf extension as well.

+ +

[11] Note the +use of ; as the directory separator, and a different syntax for +using values of other environment variables.

+ +

[12] On MS-DOS/MS-Windows systems, use semi-colon instead.

+ +


+ + + diff --git a/Master/texmf/doc/texinfo/texinfo.pdf b/Master/texmf/doc/texinfo/texinfo.pdf new file mode 100644 index 00000000000..74d214b6799 Binary files /dev/null and b/Master/texmf/doc/texinfo/texinfo.pdf differ -- cgit v1.2.3