diff options
27 files changed, 5 insertions, 24117 deletions
diff --git a/Master/texmf/doc/info/info-stnd.info b/Master/texmf/doc/info/info-stnd.info deleted file mode 100644 index cc941f82faa..00000000000 --- a/Master/texmf/doc/info/info-stnd.info +++ /dev/null @@ -1,2228 +0,0 @@ -This is info-stnd.info, produced by makeinfo version 4.12 from -info-stnd.texi. - -This manual is for GNU Info (version 4.12, 5 March 2008), a program for -viewing documents in Info format (usually created from Texinfo source -files). - - Copyright (C) 1992, 1993, 1996, 1997, 1998, 1999, 2001, 2002, 2003, -2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.2 or any later version published by the Free Software - Foundation; with no Invariant Sections, with the Front-Cover texts - being "A GNU Manual", and with the Back-Cover Texts as in (a) - below. A copy of the license is included in the section entitled - "GNU Free Documentation License' in the Texinfo manual. - - (a) The FSF's Back-Cover Text is: "You have the freedom to copy - and modify this GNU manual. Buying copies from the FSF supports - it in developing GNU and promoting software freedom." - - This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. - -INFO-DIR-SECTION Texinfo documentation system -START-INFO-DIR-ENTRY -* info standalone: (info-stnd). Read Info documents without Emacs. -* infokey: (info-stnd)Invoking infokey. Compile Info customizations. -END-INFO-DIR-ENTRY - - -File: info-stnd.info, Node: Top, Next: What is Info, Up: (dir) - -GNU Info -******** - -If you do not know how to use Info, but have a working Info reader, you -should read the Info manual before this one (*note Getting Started: -(info)Top.), as it includes more background information and a thorough -tutorial. This documentation describes the standalone Info reader that -is part of the Texinfo distribution, not the Info reader that is part -of GNU Emacs. - -* Menu: - -* What is Info:: What is Info? -* Invoking Info:: Options you can pass on the command line. -* Cursor Commands:: Commands which move the cursor within a node. -* Scrolling Commands:: Commands for reading the text within a node. -* Node Commands:: Commands for selecting a new node. -* Searching Commands:: Commands for searching an Info file. -* Xref Commands:: Commands for selecting cross references. -* Window Commands:: Commands which manipulate multiple windows. -* Printing Nodes:: How to print out the contents of a node. -* Miscellaneous Commands:: A few commands that defy categories. -* Variables:: How to change the default behavior of Info. -* Custom Key Bindings:: How to define your own key-to-command bindings. -* Index:: Global index with keystrokes, command names, - variable names, and general concepts. - - -File: info-stnd.info, Node: What is Info, Next: Invoking Info, Prev: Top, Up: Top - -1 What is Info? -*************** - -The "Info" program is a standalone program, part of the Texinfo -distribution, which is used to view Info files on an ASCII terminal. -"Info files" are typically the result of processing Texinfo files with -the program `makeinfo' (also in the Texinfo distribution) - - 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. - - GNU Emacs also provides an Info reader (just type `M-x info' in -Emacs). Emacs Info and standalone Info have nearly identical user -interfaces, although customization and other details are different -(this manual explains the standalone Info reader). The Emacs Info -reader supports the X Window System and other such bitmapped -interfaces, not just plain ASCII, so if you want the prettiest display -for Info files, you should try it. You can use Emacs Info without -using Emacs for anything else. (Type `C-x C-c' to exit; this also -works in the standalone Info reader.) - - -File: info-stnd.info, Node: Invoking Info, Next: Cursor Commands, Prev: 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' -`-k 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. (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 *note - 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 files(1). - 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 extensions(2). - -`--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 *note - 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 `--file'(3). - 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 (*note - 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. (*Note 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. - - Finally, Info defines many default key bindings and variables. -*Note Custom Key Bindings::, for information on how to customize these -settings. - - ---------- 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"'. - - -File: info-stnd.info, Node: Cursor Commands, Next: Scrolling Commands, Prev: 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. *Note User Input: (emacs)User -Input, if you are unfamiliar with the notation.(1) - - 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-x'(2) 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 *note -`universal-argument': Miscellaneous Commands. 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. - - ---------- Footnotes ---------- - - (1) 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. - - (2) `M-x' is also a command; it invokes `execute-extended-command'. -*Note Executing an extended command: (emacs)M-x, for more detailed -information. - - -File: info-stnd.info, Node: Scrolling Commands, Next: Node Commands, Prev: 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 (*note --vi-keys::). These key bindings are designated -with "vi-like operation". *Note Custom Key Bindings::, for information -on arbitrarily customizing key bindings and variable settings. - -<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' (*note scroll-behavior::). - - 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. - - -File: info-stnd.info, Node: Node Commands, Next: Searching Commands, Prev: 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> (*note scroll-behavior::). - -<g> (`goto-node') -`C-x <g>', vi-like operation - Read the name of a node and select it. While reading the node - name, completion (*note completion: The Echo Area.) 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 (*note --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 *note - Info command-line arguments processing: command-line menu items. - 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. - - -File: info-stnd.info, Node: Searching Commands, Next: Xref Commands, Prev: 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, either as a - regular expression (by default) or a literal string. If the - string includes upper-case characters, the Info file is searched - case-sensitively; otherwise Info ignores the letter case. With a - numeric argument of 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. - -<R> (`toggle-regexp') - Toggle between using regular expressions and literal strings for - searching. Info uses so-called `extended' regular expression - syntax, similar to Emacs (*note Using Regular Expressions: - (emacs)Regexps.). - -<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' (*note --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 *note ---apropos::. - - -File: info-stnd.info, Node: Xref Commands, Next: Window Commands, Prev: 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. - -* Menu: - -* Parts of an Xref:: What a cross reference is made of. -* Selecting Xrefs:: Commands for selecting menu or note items. - - -File: info-stnd.info, Node: Parts of an Xref, Next: Selecting Xrefs, 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: *Note Writing an Xref: (texinfo)xref, for more -information on creating your own texinfo cross references. - - -File: info-stnd.info, Node: Selecting Xrefs, Prev: 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. - *Note completion: The Echo Area. - -`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. *Note completion: The Echo Area. - - 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. - - -File: info-stnd.info, Node: Window Commands, Next: Printing Nodes, Prev: 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. - -* Menu: - -* The Mode Line:: What appears in the mode line? -* Basic Windows:: Manipulating windows in Info. -* The Echo Area:: Used for displaying errors and reading input. - - -File: info-stnd.info, Node: The Mode Line, Next: Basic Windows, 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, *note toggle-wrap: Scrolling Commands.) 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--------------------------------- - - -File: info-stnd.info, Node: Basic Windows, Next: The Echo Area, Prev: 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 (*note The Mode Line::) and history of nodes viewed in that -window (*note `history-node': Node Commands.). - -`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 (*note automatic-tiling: - Variables.). - -`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. - *Note `automatic-tiling': Variables. - - -File: info-stnd.info, Node: The Echo Area, Prev: 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" -text(1). For an in-depth discussion of killing and yanking, see *note -Killing and Deleting: (emacs)Killing. - -<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. - - ---------- Footnotes ---------- - - (1) Some people are used to calling these operations "cut" and -"paste", respectively. - - -File: info-stnd.info, Node: Printing Nodes, Next: Miscellaneous Commands, Prev: 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. - - -File: info-stnd.info, Node: Miscellaneous Commands, Next: Variables, Prev: 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' (*note --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'. *Note - `automatic-footnotes': Variables. - - -File: info-stnd.info, Node: Variables, Next: Custom Key Bindings, Prev: 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. *Note 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 (*note completion: The - Echo Area.); 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. - -`cursor-movement-scrolls' - Normally, cursor movement commands (*note Cursor Commands::) stop - when top or bottom of a node is reached. When this variable is - set to `On', cursor movement commands act as scrolling ones and - their behavior is controlled by the `scroll-behavior' variable - (see below). - -`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' -`scroll-behaviour' - 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. - - `scroll-last-node' - Control what happens when a scrolling command is issued at - the end of the last node. Possible values are: - - `Stop' - Do not scroll. Display the `No more nodes within this - document.' message. This is the default. - - `Scroll' - Scroll as usual. Since the last node is usually an - index, this means that the very first node from the menu - will be selected. - - `Top' - Go to the top node of this document. - - This variable is in effect only if `scroll-behaviour' is set - to `Continuous'. - - Notice that the default behavior has changed in version 4.12. - Previous versions behaved as if `scroll-last-node=Scroll' was - set. This behavior was counter-intuitive, therefore since - version 4.12 the default is to stop at the last node. - - `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. - - This variable normally affects only scrolling commands. *Note - cursor-movement-scrolls::, for information on how to widen its - scope. - - The two names, `scroll-behavior' and `scroll-behaviour', are a - historical accident. They are merely synonyms. - -`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, - (*note `next-index-match': Searching Commands.), 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'. - - - -File: info-stnd.info, Node: Custom Key Bindings, Next: Index, Prev: Variables, Up: Top - -12 Customizing Key Bindings and Variables -***************************************** - -GNU Info provides a way to define arbitrary key-to-command bindings and -variable settings, overriding the defaults described in this document. -(The `--vi-keys' option rebinds many keys at once; *note --vi-keys::.) - - On startup, GNU Info looks for a configuration file in the invoker's -HOME directory called `.info'(1). 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. - -* Menu: - -* Invoking infokey:: -* infokey source format:: - - ---------- Footnotes ---------- - - (1) 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. - - -File: info-stnd.info, Node: Invoking infokey, Next: infokey source format, Up: Custom Key Bindings - -12.1 Invoking `infokey' -======================= - -`infokey' compiles a source file (`$HOME/.infokey'(1) 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'. - - ---------- Footnotes ---------- - - (1) This file is named `_infokey' in the MS-DOS version, and is -looked for in the current directory if `HOME' is undefined. - - -File: info-stnd.info, Node: infokey source format, Prev: 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 (*Note 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. - - -File: info-stnd.info, Node: Index, Prev: Custom Key Bindings, Up: Top - -Appendix A Index -**************** - - -* Menu: - -* ', vi-like operation: Node Commands. (line 51) -* ,: Searching Commands. (line 67) -* -: Miscellaneous Commands. - (line 68) -* --subnodes, command line option: Invoking Info. (line 146) -* .info: Custom Key Bindings. (line 6) -* .infokey: Custom Key Bindings. (line 6) -* .infokey source format: infokey source format. - (line 6) -* /: Searching Commands. (line 12) -* 0 ... 9, vi-like operation: Miscellaneous Commands. - (line 55) -* 0, in Info windows: Selecting Xrefs. (line 22) -* 1 ... 9, in Info windows: Selecting Xrefs. (line 12) -* <: Node Commands. (line 70) -* >: Node Commands. (line 77) -* ?, in Info windows: Miscellaneous Commands. - (line 28) -* ?, in the echo area: The Echo Area. (line 132) -* ?, vi-like operation: Searching Commands. (line 20) -* [: Node Commands. (line 90) -* ]: Node Commands. (line 83) -* _info file (MS-DOS): Custom Key Bindings. (line 6) -* _infokey file (MS-DOS): Invoking infokey. (line 6) -* abort-key: Miscellaneous Commands. - (line 83) -* add-digit-to-numeric-arg: Miscellaneous Commands. - (line 55) -* ANSI escape sequences in documents: Invoking Info. (line 108) -* Apropos, in Info files: Invoking Info. (line 16) -* arguments, command line: Invoking Info. (line 6) -* arguments, negative: Miscellaneous Commands. - (line 68) -* automatic-footnotes: Variables. (line 31) -* automatic-tiling: Variables. (line 44) -* b, in Info windows: Cursor Commands. (line 63) -* b, vi-like operation: Scrolling Commands. (line 63) -* BackTab, in Info windows: Selecting Xrefs. (line 57) -* BackTab, in the echo area: The Echo Area. (line 82) -* backward-char: Cursor Commands. (line 49) -* backward-word: Cursor Commands. (line 57) -* beginning-of-line: Cursor Commands. (line 37) -* beginning-of-node: Cursor Commands. (line 63) -* BS (backspace): Scrolling Commands. (line 118) -* C-a, in Info windows: Cursor Commands. (line 37) -* C-a, in the echo area: The Echo Area. (line 27) -* C-b, in Info windows: Cursor Commands. (line 49) -* C-b, in the echo area: The Echo Area. (line 23) -* C-b, vi-like operation: Scrolling Commands. (line 63) -* C-CENTER: Node Commands. (line 51) -* C-d, in the echo area: The Echo Area. (line 48) -* C-d, vi-like operation: Scrolling Commands. (line 93) -* C-e, in Info windows: Cursor Commands. (line 41) -* C-e, in the echo area: The Echo Area. (line 31) -* C-e, vi-like operation: Scrolling Commands. (line 79) -* C-End: Cursor Commands. (line 68) -* C-f, in Info windows: Cursor Commands. (line 45) -* C-f, in the echo area: The Echo Area. (line 18) -* C-f, vi-like operation: Scrolling Commands. (line 38) -* C-g, in Info windows: Miscellaneous Commands. - (line 83) -* C-g, in the echo area: The Echo Area. (line 59) -* C-h: Miscellaneous Commands. - (line 28) -* C-Home: Cursor Commands. (line 63) -* C-k, in the echo area: The Echo Area. (line 104) -* C-k, vi-like operation: Scrolling Commands. (line 88) -* C-l: Scrolling Commands. (line 123) -* C-LEFT: Cursor Commands. (line 57) -* C-LEFT, in the echo area: The Echo Area. (line 44) -* C-n: Cursor Commands. (line 29) -* C-n, vi-like operation: Scrolling Commands. (line 79) -* C-NEXT: Node Commands. (line 22) -* C-p: Cursor Commands. (line 33) -* C-p, vi-like operation: Scrolling Commands. (line 88) -* C-PgDn: Node Commands. (line 24) -* C-PgUp: Node Commands. (line 30) -* C-PREVIOUS: Node Commands. (line 28) -* C-q, in the echo area: The Echo Area. (line 69) -* C-r: Searching Commands. (line 58) -* C-RIGHT: Cursor Commands. (line 53) -* C-RIGHT, in the echo area: The Echo Area. (line 38) -* C-s: Searching Commands. (line 53) -* C-t, in the echo area: The Echo Area. (line 86) -* C-u: Miscellaneous Commands. - (line 42) -* C-u cancels typeahead, vi-like operation: Miscellaneous Commands. - (line 83) -* C-u, in the echo area, vi-like operation: The Echo Area. (line 59) -* C-u, vi-like operation: Scrolling Commands. (line 100) -* C-UP: Node Commands. (line 35) -* C-v: Scrolling Commands. (line 38) -* C-v, in the echo area, vi-like operation: The Echo Area. (line 69) -* C-w: Scrolling Commands. (line 130) -* C-x 0: Basic Windows. (line 34) -* C-x 1: Basic Windows. (line 39) -* C-x 2: Basic Windows. (line 26) -* C-x ^: Basic Windows. (line 47) -* C-x b: Node Commands. (line 177) -* C-x C-b: Node Commands. (line 172) -* C-x C-c: Miscellaneous Commands. - (line 92) -* C-x C-f: Node Commands. (line 166) -* C-x DEL, in the echo area: The Echo Area. (line 107) -* C-x g, vi-like operation: Node Commands. (line 101) -* C-x k: Node Commands. (line 158) -* C-x N: Searching Commands. (line 47) -* C-x n: Searching Commands. (line 41) -* C-x n, vi-like operation: Node Commands. (line 22) -* C-x o: Basic Windows. (line 12) -* C-x r, vi-like operation: Selecting Xrefs. (line 39) -* C-x t: Basic Windows. (line 52) -* C-x u, vi-like operation: Node Commands. (line 35) -* C-y, in the echo area: The Echo Area. (line 110) -* C-y, vi-like operation: Scrolling Commands. (line 88) -* cancelling the current operation: Miscellaneous Commands. - (line 83) -* cancelling typeahead: Miscellaneous Commands. - (line 83) -* case-sensitive search: Searching Commands. (line 34) -* case-sensitivity, and search: Searching Commands. (line 88) -* colors in documents: Invoking Info. (line 108) -* command line options: Invoking Info. (line 6) -* command-line options, how to find: Invoking Info. (line 125) -* commands, describing: Miscellaneous Commands. - (line 9) -* completion: The Echo Area. (line 115) -* compressed Info files: Invoking Info. (line 63) -* cursor, moving: Cursor Commands. (line 6) -* customizing key bindings: Custom Key Bindings. (line 6) -* d: Node Commands. (line 63) -* d, vi-like operation: Scrolling Commands. (line 93) -* default key bindings, overriding: Custom Key Bindings. (line 6) -* DEL, in Info windows: Scrolling Commands. (line 50) -* DEL, in the echo area: The Echo Area. (line 51) -* delete-window: Basic Windows. (line 34) -* describe-command: Miscellaneous Commands. - (line 9) -* describe-key: Miscellaneous Commands. - (line 13) -* describe-variable: Variables. (line 25) -* dir-node: Node Commands. (line 63) -* directory path: Invoking Info. (line 27) -* DOWN (an arrow key): Cursor Commands. (line 29) -* DOWN, vi-like operation: Scrolling Commands. (line 79) -* down-line: Scrolling Commands. (line 79) -* e, in Info windows: Cursor Commands. (line 68) -* echo area: The Echo Area. (line 6) -* echo-area-abort: The Echo Area. (line 59) -* echo-area-backward: The Echo Area. (line 23) -* echo-area-backward-kill-line: The Echo Area. (line 107) -* echo-area-backward-kill-word: The Echo Area. (line 98) -* echo-area-backward-word: The Echo Area. (line 42) -* echo-area-beg-of-line: The Echo Area. (line 27) -* echo-area-complete: The Echo Area. (line 129) -* echo-area-delete: The Echo Area. (line 48) -* echo-area-end-of-line: The Echo Area. (line 31) -* echo-area-forward: The Echo Area. (line 18) -* echo-area-forward-word: The Echo Area. (line 36) -* echo-area-insert: The Echo Area. (line 74) -* echo-area-kill-line: The Echo Area. (line 104) -* echo-area-kill-word: The Echo Area. (line 94) -* echo-area-newline: The Echo Area. (line 65) -* echo-area-possible-completions: The Echo Area. (line 132) -* echo-area-quoted-insert: The Echo Area. (line 69) -* echo-area-rubout: The Echo Area. (line 51) -* echo-area-scroll-completions-window: The Echo Area. (line 156) -* echo-area-tab-insert: The Echo Area. (line 80) -* echo-area-transpose-chars: The Echo Area. (line 86) -* echo-area-yank: The Echo Area. (line 110) -* echo-area-yank-pop: The Echo Area. (line 113) -* End: Cursor Commands. (line 41) -* end-of-line: Cursor Commands. (line 41) -* end-of-node: Cursor Commands. (line 68) -* errors-ring-bell: Variables. (line 62) -* ESC C-f: Miscellaneous Commands. - (line 109) -* ESC C-v, in Info windows: Basic Windows. (line 42) -* ESC C-v, in the echo area: The Echo Area. (line 156) -* f: Selecting Xrefs. (line 39) -* f, vi-like operation: Scrolling Commands. (line 38) -* F1: Miscellaneous Commands. - (line 28) -* file names, relative: Invoking Info. (line 54) -* file, outputting to: Invoking Info. (line 103) -* files, compressed: Invoking Info. (line 63) -* find-menu: Selecting Xrefs. (line 30) -* finding the Invocation node: Node Commands. (line 115) -* first-node: Node Commands. (line 70) -* footnotes, displaying: Miscellaneous Commands. - (line 109) -* format of .infokey source: infokey source format. - (line 6) -* forward-char: Cursor Commands. (line 45) -* forward-word: Cursor Commands. (line 53) -* functions, describing: Miscellaneous Commands. - (line 9) -* G: Node Commands. (line 133) -* g: Node Commands. (line 101) -* G, vi-like operation: Node Commands. (line 77) -* g, vi-like operation: Node Commands. (line 70) -* gc-compressed-files: Variables. (line 66) -* get-help-window: Miscellaneous Commands. - (line 28) -* get-info-help-node: Miscellaneous Commands. - (line 34) -* global-next-node: Node Commands. (line 83) -* global-prev-node: Node Commands. (line 90) -* goto-invocation: Node Commands. (line 115) -* goto-node: Node Commands. (line 101) -* grow-window: Basic Windows. (line 47) -* h: Miscellaneous Commands. - (line 34) -* h, vi-like operation: Miscellaneous Commands. - (line 28) -* history-node: Node Commands. (line 51) -* Home: Cursor Commands. (line 37) -* i: Searching Commands. (line 63) -* I: Node Commands. (line 115) -* incremental search: Searching Commands. (line 53) -* index search, selecting from the command line: Invoking Info. - (line 79) -* index, searching: Searching Commands. (line 63) -* index-apropos: Searching Commands. (line 71) -* index-search: Searching Commands. (line 63) -* Info file, selecting: Invoking Info. (line 50) -* Info files, compressed: Invoking Info. (line 63) -* Info files, relative: Invoking Info. (line 54) -* Info files, searching all indices: Invoking Info. (line 16) -* Info manual location: Invoking Info. (line 161) -* Info, invoking: Invoking Info. (line 6) -* INFO_PRINT_COMMAND, environment variable: Printing Nodes. (line 13) -* infokey: Custom Key Bindings. (line 6) -* infokey source format: infokey source format. - (line 6) -* infokey, invoking: Invoking infokey. (line 6) -* invocation description, how to find: Invoking Info. (line 125) -* invoking Info: Invoking Info. (line 6) -* invoking infokey: Invoking infokey. (line 6) -* isearch-backward: Searching Commands. (line 58) -* isearch-forward: Searching Commands. (line 53) -* ISO Latin characters: Variables. (line 81) -* ISO-Latin: Variables. (line 81) -* k, vi-like operation: Scrolling Commands. (line 88) -* keep-one-window: Basic Windows. (line 39) -* key bindings, customizing: Custom Key Bindings. (line 6) -* keys, describing: Miscellaneous Commands. - (line 13) -* keystrokes, recording: Invoking Info. (line 43) -* kill-node: Node Commands. (line 158) -* l: Node Commands. (line 51) -* last-menu-item: Selecting Xrefs. (line 22) -* last-node: Node Commands. (line 77) -* LEFT (an arrow key): Cursor Commands. (line 49) -* LEFT, in the echo area: The Echo Area. (line 23) -* Less-like key bindings: Invoking Info. (line 155) -* LFD, vi-like operation: Scrolling Commands. (line 79) -* list-visited-nodes: Node Commands. (line 172) -* local printer device: Printing Nodes. (line 18) -* m: Selecting Xrefs. (line 25) -* M-$, vi-like operation: The Echo Area. (line 31) -* M--: Miscellaneous Commands. - (line 68) -* M-0 ... M-9: Miscellaneous Commands. - (line 55) -* M-0, in the echo area, vi-like operation: The Echo Area. (line 27) -* M-0, vi-like operation: Selecting Xrefs. (line 22) -* M-1 ... M-9, vi-like operation: Selecting Xrefs. (line 12) -* M-<: Cursor Commands. (line 63) -* M->: Cursor Commands. (line 68) -* M-b, in Info windows: Cursor Commands. (line 57) -* M-b, in the echo area: The Echo Area. (line 42) -* M-b, vi-like operation: Cursor Commands. (line 63) -* M-BS, in the echo area: The Echo Area. (line 100) -* M-d, in the echo area: The Echo Area. (line 94) -* M-d, vi-like operation: Node Commands. (line 63) -* M-DEL, in the echo area: The Echo Area. (line 98) -* M-f, in Info windows: Cursor Commands. (line 53) -* M-f, in the echo area: The Echo Area. (line 36) -* M-f, vi-like operation: Selecting Xrefs. (line 39) -* M-g, vi-like operation: Selecting Xrefs. (line 62) -* M-h, in the echo area, vi-like operation: The Echo Area. (line 18) -* M-h, vi-like operation: Miscellaneous Commands. - (line 34) -* M-l, in the echo area, vi-like operation: The Echo Area. (line 23) -* M-r: Cursor Commands. (line 71) -* M-SPC, vi-like operation: Scrolling Commands. (line 38) -* M-t, vi-like operation: Node Commands. (line 59) -* M-TAB, in Info windows: Selecting Xrefs. (line 54) -* M-TAB, in the echo area: The Echo Area. (line 80) -* M-v: Scrolling Commands. (line 63) -* M-w, in the echo area, vi-like operation: The Echo Area. (line 36) -* M-X, in the echo area, vi-like operation: The Echo Area. (line 94) -* M-x, in the echo area, vi-like operation: The Echo Area. (line 48) -* M-y, in the echo area: The Echo Area. (line 113) -* menu, following: Invoking Info. (line 168) -* menu, following, from inside Info: Node Commands. (line 133) -* menu-digit: Selecting Xrefs. (line 12) -* menu-item: Selecting Xrefs. (line 25) -* menu-sequence: Node Commands. (line 133) -* move-to-next-xref: Selecting Xrefs. (line 47) -* move-to-prev-xref: Selecting Xrefs. (line 54) -* move-to-window-line: Cursor Commands. (line 71) -* moving the cursor: Cursor Commands. (line 6) -* n: Node Commands. (line 22) -* n, vi-like operation: Searching Commands. (line 41) -* negative arguments: Miscellaneous Commands. - (line 68) -* NEXT: Scrolling Commands. (line 38) -* next-index-match: Searching Commands. (line 67) -* next-line: Cursor Commands. (line 29) -* next-node: Node Commands. (line 22) -* next-window: Basic Windows. (line 12) -* node, selecting from the command line: Invoking Info. (line 94) -* nodes, selection of: Node Commands. (line 6) -* numeric arguments: Miscellaneous Commands. - (line 42) -* numeric arguments, negative: Miscellaneous Commands. - (line 68) -* O: Node Commands. (line 115) -* online help, using Info as: Invoking Info. (line 79) -* options, command line: Invoking Info. (line 6) -* outputting to a file: Invoking Info. (line 103) -* overriding default key bindings: Custom Key Bindings. (line 6) -* p: Node Commands. (line 28) -* PageDown: Scrolling Commands. (line 42) -* PageUp: Scrolling Commands. (line 114) -* prev-line: Cursor Commands. (line 33) -* prev-node: Node Commands. (line 28) -* prev-window: Basic Windows. (line 22) -* PREVIOUS: Scrolling Commands. (line 63) -* print-node: Printing Nodes. (line 13) -* printing: Printing Nodes. (line 6) -* printing characters, in the echo area: The Echo Area. (line 74) -* printing nodes to the local printer: Printing Nodes. (line 18) -* q: Miscellaneous Commands. - (line 92) -* quit: Miscellaneous Commands. - (line 92) -* quitting: Miscellaneous Commands. - (line 92) -* r: Selecting Xrefs. (line 39) -* R: Searching Commands. (line 28) -* redraw-display: Scrolling Commands. (line 123) -* regular expression search: Searching Commands. (line 12) -* relative Info file names: Invoking Info. (line 54) -* remembering user keystrokes: Invoking Info. (line 43) -* repeated search: Searching Commands. (line 41) -* replaying recorded keystrokes: Invoking Info. (line 119) -* RET, in Info windows: Selecting Xrefs. (line 62) -* RET, in the echo area: The Echo Area. (line 65) -* RET, vi-like operation: Scrolling Commands. (line 79) -* RIGHT (an arrow key): Cursor Commands. (line 45) -* RIGHT, in the echo area: The Echo Area. (line 18) -* S: Searching Commands. (line 34) -* s: Searching Commands. (line 12) -* screen, changing the height of: Miscellaneous Commands. - (line 99) -* scroll-backward: Scrolling Commands. (line 50) -* scroll-backward-page-only: Scrolling Commands. (line 63) -* scroll-backward-page-only-set-window: Scrolling Commands. (line 70) -* scroll-behavior: Variables. (line 89) -* scroll-behaviour: Variables. (line 89) -* scroll-forward: Scrolling Commands. (line 17) -* scroll-forward-page-only: Scrolling Commands. (line 38) -* scroll-forward-page-only-set-window: Scrolling Commands. (line 45) -* scroll-half-screen-down: Scrolling Commands. (line 93) -* scroll-half-screen-up: Scrolling Commands. (line 100) -* scroll-last-node: Variables. (line 101) -* scroll-other-window: Basic Windows. (line 42) -* scroll-step: Variables. (line 140) -* scrolling: Scrolling Commands. (line 6) -* scrolling through node structure: Scrolling Commands. (line 105) -* search: Searching Commands. (line 12) -* search, and case-sensitivity: Searching Commands. (line 88) -* search, case-sensitive: Searching Commands. (line 34) -* search-backward: Searching Commands. (line 20) -* search-case-sensitively: Searching Commands. (line 34) -* search-next: Searching Commands. (line 41) -* search-previous: Searching Commands. (line 47) -* searching: Searching Commands. (line 6) -* Searching all indices: Invoking Info. (line 16) -* searching, in the indices: Searching Commands. (line 63) -* select-reference-this-line: Selecting Xrefs. (line 62) -* select-visited-node: Node Commands. (line 177) -* set-screen-height: Miscellaneous Commands. - (line 99) -* set-variable: Variables. (line 16) -* Shift-TAB, in Info windows: Selecting Xrefs. (line 57) -* Shift-TAB, in the echo area: The Echo Area. (line 80) -* show-footnotes: Miscellaneous Commands. - (line 109) -* show-index-match: Variables. (line 154) -* SPC, in Info windows: Scrolling Commands. (line 17) -* SPC, in the echo area: The Echo Area. (line 129) -* speech synthesizers: Invoking Info. (line 136) -* split-window: Basic Windows. (line 26) -* t: Node Commands. (line 59) -* TAB, in Info windows: Selecting Xrefs. (line 47) -* TAB, in the echo area: The Echo Area. (line 129) -* tile-windows: Basic Windows. (line 52) -* tiling: Basic Windows. (line 52) -* toggle-regexp: Searching Commands. (line 28) -* toggle-wrap: Scrolling Commands. (line 130) -* top-node: Node Commands. (line 59) -* u: Node Commands. (line 35) -* u, vi-like operation: Scrolling Commands. (line 100) -* universal-argument: Miscellaneous Commands. - (line 42) -* UP (an arrow key): Cursor Commands. (line 33) -* UP, vi-like operation: Scrolling Commands. (line 88) -* up-line: Scrolling Commands. (line 88) -* up-node: Node Commands. (line 35) -* variables, describing: Variables. (line 25) -* variables, setting: Variables. (line 16) -* version information: Invoking Info. (line 153) -* vi-like key bindings: Invoking Info. (line 155) -* view-file: Node Commands. (line 166) -* visible-bell: Variables. (line 163) -* w, vi-like operation: Scrolling Commands. (line 70) -* Where is an Info manual?: Invoking Info. (line 161) -* where-is: Miscellaneous Commands. - (line 21) -* windows, creating: Basic Windows. (line 26) -* windows, deleting: Basic Windows. (line 34) -* windows, manipulating: Window Commands. (line 6) -* windows, selecting: Basic Windows. (line 12) -* xref-item: Selecting Xrefs. (line 39) -* y, vi-like operation: Scrolling Commands. (line 88) -* z, vi-like operation: Scrolling Commands. (line 45) -* ZZ, vi-like operation: Miscellaneous Commands. - (line 92) - - - -Tag Table: -Node: Top1549 -Node: What is Info3022 -Node: Invoking Info4172 -Ref: --apropos4596 -Ref: --show-options9953 -Ref: --vi-keys11265 -Ref: command-line menu items11694 -Ref: Invoking Info-Footnote-112952 -Ref: Invoking Info-Footnote-213000 -Ref: Invoking Info-Footnote-313385 -Node: Cursor Commands13593 -Ref: Cursor Commands-Footnote-116367 -Ref: Cursor Commands-Footnote-216649 -Node: Scrolling Commands16801 -Node: Node Commands23248 -Ref: goto-node26989 -Ref: goto-invocation27564 -Node: Searching Commands30889 -Node: Xref Commands36116 -Node: Parts of an Xref36735 -Node: Selecting Xrefs38709 -Node: Window Commands40895 -Node: The Mode Line41837 -Node: Basic Windows43747 -Node: The Echo Area46243 -Ref: The Echo Area-Footnote-151706 -Node: Printing Nodes51796 -Node: Miscellaneous Commands52951 -Node: Variables57214 -Ref: cursor-movement-scrolls59804 -Ref: scroll-behavior61482 -Node: Custom Key Bindings65226 -Ref: Custom Key Bindings-Footnote-166295 -Node: Invoking infokey66497 -Ref: Invoking infokey-Footnote-167158 -Node: infokey source format67286 -Node: Index71715 - -End Tag Table diff --git a/Master/texmf/doc/info/info.info b/Master/texmf/doc/info/info.info deleted file mode 100644 index cd23db5383a..00000000000 --- a/Master/texmf/doc/info/info.info +++ /dev/null @@ -1,1445 +0,0 @@ -This is info.info, produced by makeinfo version 4.12 from info.texi. - -This file describes how to use Info, the on-line, menu-driven GNU -documentation system. - - Copyright (C) 1989, 1992, 1996, 1997, 1998, 1999, 2000, 2001, 2002, -2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.2 or any later version published by the Free Software - Foundation; with no Invariant Sections, with the Front-Cover texts - being "A GNU Manual," and with the Back-Cover Texts as in (a) - below. A copy of the license is included in the section entitled - "GNU Free Documentation License" in the Emacs manual. - - (a) The FSF's Back-Cover Text is: "You have freedom to copy and - modify this GNU Manual, like GNU software. Buying copies from GNU - Press supports the FSF in developing GNU and promoting software - freedom." - - This document is part of a collection distributed under the GNU - Free Documentation License. If you want to distribute this - document separately from the collection, you can do so by adding a - copy of the license to the document, as described in section 6 of - the license. - -INFO-DIR-SECTION Texinfo documentation system -START-INFO-DIR-ENTRY -* Info: (info). How to use the documentation browsing system. -END-INFO-DIR-ENTRY - - -File: info.info, Node: Top, Next: Getting Started, 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. - - There are two primary Info readers: `info', a stand-alone program -designed just to read Info files, and the `info' package in GNU Emacs, -a general-purpose editor. At present, only the Emacs reader supports -using a mouse. - - If you are new to the Info reader and want to learn how to use it, -type the command `h' now. It brings you to a programmed instruction -sequence. - - To read about advanced Info commands, type `n' twice. This brings -you to `Advanced Info Commands', skipping over the `Getting Started' -chapter. - -* Menu: - -* Getting Started:: Getting started using an Info reader. -* Advanced:: Advanced Info commands. -* Expert Info:: Info commands for experts. -* Index:: An index of topics, commands, and variables. - - -File: info.info, Node: Getting Started, Next: Advanced, Prev: Top, Up: Top - -1 Getting Started -***************** - -This first part of this Info manual describes how to get around inside -of Info. The second part of the manual describes various advanced Info -commands. The third part briefly explains how to generate Info files -from Texinfo files, and describes how to write an Info file by hand. - -* Menu: - -* Help-Small-Screen:: Starting Info on a Small Screen. -* Help:: How to use Info. -* Help-P:: Returning to the Previous node. -* Help-^L:: The Space, DEL, B and ^L commands. -* Help-Inv:: Invisible text in Emacs Info. -* Help-M:: Menus. -* Help-Xref:: Following cross-references. -* Help-Int:: Some intermediate Info commands. -* Help-Q:: Quitting Info. - - -File: info.info, Node: Help-Small-Screen, Next: Help, Up: Getting Started - -1.1 Starting Info on a Small Screen -=================================== - -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 the entire text you are looking at fits on the screen, the text -`All' will be displayed at the bottom of the screen. In the -stand-alone Info reader, it is displayed at the bottom right corner of -the screen; in Emacs, it is displayed on the modeline. If you see the -text `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'). - - Here are 40 lines of junk, so you can try <SPC> and <DEL> and see -what they do. At the end are instructions of what you should do next. - -This is line 20 -This is line 21 -This is line 22 -This is line 23 -This is line 24 -This is line 25 -This is line 26 -This is line 27 -This is line 28 -This is line 29 -This is line 30 -This is line 31 -This is line 32 -This is line 33 -This is line 34 -This is line 35 -This is line 36 -This is line 37 -This is line 38 -This is line 39 -This is line 40 -This is line 41 -This is line 42 -This is line 43 -This is line 44 -This is line 45 -This is line 46 -This is line 47 -This is line 48 -This is line 49 -This is line 50 -This is line 51 -This is line 52 -This is line 53 -This is line 54 -This is line 55 -This is line 56 -This is line 57 -This is line 58 -This is line 59 - - If you have managed to get here, go back to the beginning with `DEL' -(or <BACKSPACE>), and come back here again, then you understand the -about the `Space' and `Backspace' keys. So now type an `n'--just one -character; don't type the quotes and don't type the Return key -afterward--to get to the normal start of the course. - - -File: info.info, Node: Help, Next: Help-P, Prev: 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 displayed with a special typeface, and 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' link, or an `Up' -link, 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 left - mouse button on the `Next' link to do the same "the mouse way". - - -File: info.info, Node: Help-P, Next: Help-^L, Prev: 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 - (in Emacs) click 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 -`Previous' (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 (in Emacs) click the middle mouse button on - the `Next' link, to get to the node `Help-^L' and learn more. - - -File: info.info, Node: Help-^L, Next: Help-Inv, Prev: 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 text `Top' rather than `All' near the bottom 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. - - You have just learned a considerable number of commands. If you -want to use one but have trouble remembering which, you should type -`?', which displays a brief list of commands. When you are finished -looking at the list, make it go away by typing <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'; that's 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. - - ---------- 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'. - - -File: info.info, Node: Help-Inv, Next: Help-M, Prev: 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. - -* Menu: - -* ]: Help-]. Node telling about ]. -* stuff: Help-]. Same node. -* Help-]:: Yet again, same node. - - -File: info.info, Node: Help-], 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. - - -File: info.info, Node: Help-M, Next: Help-Xref, Prev: 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>. - - 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: - -* Menu: - -* Foo: Help-FOO. A node you can visit for fun. -* Bar: Help-FOO. We have made two ways to get to the same place. -* Help-FOO:: And yet another! - - (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 in the stand-alone -reader, 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'.) In Emacs Info, type `S-<TAB>' to move to a previous subtopic -line (press and hold the <Shift> key and then press <TAB>). - - 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. - - -File: info.info, Node: Help-FOO, 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". This puts you at the menu subtopic line pointing to the subnode -that the `u' command brought you from. (Some Info readers may put you -at the _front_ of the node instead--to get back to where you were -reading, you have to type some <SPC>s.) - - 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'. - - -File: info.info, Node: Help-Xref, Next: Help-Int, Prev: Help-M, Up: Getting Started - -1.7 Following Cross-References -============================== - -In Info documentation, you will see many "cross references". Cross -references look like this: *Note Cross: Help-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.) - - You can follow a cross reference by moving the cursor to it and -press <RET>, just as in a menu. In Emacs, you can also click `Mouse-1' -on a cross reference to follow it; you can see that the cross reference -is mouse-sensitive by moving the mouse pointer to the reference and -watching how the underlying text and the mouse pointer change in -response. - - Another way to follow a cross reference is to type `f' and then -specify the name of the cross reference (in this case, `Cross') as an -argument. For this command, 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>, `M-<TAB>' and `S-<TAB>' keys, 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: *Note Overview of Texinfo: (texinfo)Top. (After following this -link, type `l' to get back to this node.) Here the name `texinfo' -between parentheses refers to the file name. This file name appears in -cross references and node names if it differs from the current file, so -you can always know that you are going to be switching to another -manual and which one. - - However, Emacs normally hides some other text in cross-references. -If you put your mouse over the cross reference, then the information -appearing in a separate box (tool tip) or in the echo area will show -the full cross-reference including the file name and the node name of -the cross reference. If you have a mouse, just leave it over the cross -reference *Note Overview of Texinfo: (texinfo)Top, and watch what -happens. If you always like to have that information visible without -having to move your mouse over the cross reference, use `M-x -visible-mode', or set `Info-hide-note-references' to a value other than -`t' (*note Emacs Info Variables::). - ->> Now type `n' to learn more commands. - - -File: info.info, Node: Help-Int, Next: Help-Q, Prev: 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 and the name of the index node; 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. *Note Search -Index::, 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. - ->> 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'). - - You can use the `r' command (`Info-history-forward' in Emacs) to -revisit nodes in the history list in the forward direction, so that `r' -will return you to the node you came from by typing `l'. - - The `L' command (`Info-history' in Emacs) creates a virtual node -that contains a list of all nodes you visited. You can select a -previously visited node from this menu to revisit it. - - 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'. - ->> Now type `n' to see the last node of the course. - - *Note Advanced::, for more advanced Info features. - - -File: info.info, Node: Help-Q, Prev: Help-Int, Up: Getting Started - -1.9 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 *note Advanced::. - - 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. - - -File: info.info, Node: Advanced, Next: Expert Info, Prev: Getting Started, Up: Top - -2 Advanced Info Commands -************************ - -This chapter describes various advanced Info commands. (If you are -using a stand-alone Info reader, there are additional commands specific -to it, which are documented in several chapters of *note GNU Info: -(info-stnd)Top.) - - One advanced command useful with most of the others described here -is `C-q', which "quotes" the next character so that it is entered -literally (*note Inserting Text: (emacs)Inserting Text.). For example, -pressing `?' ordinarily brings up a list of completion possibilities. -If you want to (for example) search for an actual `?' character, the -simplest way is to insert it using `C-q ?'. This works the same in -Emacs and stand-alone Info. - -* Menu: - -* Search Text:: How to search Info documents. -* Search Index:: How to search the indices for specific subjects. -* Go to node:: How to go to a node by name. -* Choose menu subtopic:: How to choose a menu subtopic by its number. -* Create Info buffer:: How to create a new Info buffer in Emacs. -* Emacs Info Variables:: Variables modifying the behavior of Emacs Info. - - -File: info.info, Node: Search Text, Next: Search Index, Up: Advanced - -2.1 `s' searches Info documents -=============================== - -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 text or its indices. - - The `s' command allows you to search a whole Info file for a string. -It switches to the next node if and when that is necessary. You type -`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 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 look at the mode -line 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'. - - Instead of using `s' in Emacs Info and in the stand-alone Info, you -can use an incremental search started with `C-s' or `C-r'. It can -search through multiple Info nodes. *Note Incremental Search: -(emacs)Incremental Search. In Emacs, you can disable this behavior by -setting the variable `Info-isearch-search' to `nil' (*note Emacs Info -Variables::). - - -File: info.info, Node: Search Index, Next: Go to node, Prev: Search Text, Up: Advanced - -2.2 `i' searches the indices for specific subjects -================================================== - -Since most topics in the manual should be indexed, you should try the -index search first before the text search. 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 and subsequent `,' commands find 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 Info 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-l' key does, type `iC-l<RET>' -literally. - - If you aren't sure which manual documents the topic you are looking -for, try the `M-x info-apropos' command in Emacs, or the `M-x -index-apropos' command in the stand-alone reader. It prompts for a -string and then looks up that string in all the indices of all the Info -documents installed on your system. - - -File: info.info, Node: Go to node, Next: Choose menu subtopic, Prev: Search Index, Up: Advanced - -2.3 `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 *note Help-Int::.) `gGo to -node<RET>' would come back here. - - 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>'. - - -File: info.info, Node: Choose menu subtopic, Next: Create Info buffer, Prev: Go to node, Up: Advanced - -2.4 `1'-`9' 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. - - 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. - - -File: info.info, Node: Create Info buffer, Next: Emacs Info Variables, Prev: Choose menu subtopic, Up: Advanced - -2.5 `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 a new Emacs 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. - - Another way to produce new Info buffers in Emacs is to use a numeric -prefix argument for the `C-h i' command (`info') which switches to the -Info buffer with that number. Thus, `C-u 2 C-h i' switches to the -buffer `*info*<2>', creating it if necessary. - - -File: info.info, Node: Emacs Info Variables, Prev: Create Info buffer, Up: Advanced - -2.6 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 init file. *Note Examining and Setting Variables: -(emacs)Examining. The stand-alone Info reader program has its own set -of variables, described in *note Manipulating Variables: -(info-stnd)Variables. - -`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-mode-hook' - Hooks run when `Info-mode' is called. By default, it contains the - hook `turn-on-font-lock' which enables highlighting of Info files. - You can change how the highlighting looks by customizing the faces - `info-node', `info-xref', `info-xref-visited', `info-header-xref', - `info-header-node', `info-menu-header', `info-menu-star', and - `info-title-N' (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-fontify-maximum-menu-size' - Maximum size of menu to fontify if `font-lock-mode' is non-`nil'. - -`Info-fontify-visited-nodes' - If non-`nil', menu items and cross-references pointing to visited - nodes are displayed in the `info-xref-visited' face. - -`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-isearch-search' - If non-`nil', isearch in Info searches through multiple nodes. - -`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!") - - -File: info.info, Node: Expert Info, Next: Index, Prev: Advanced, Up: Top - -3 Info for Experts -****************** - -This chapter explains how to write an Info file by hand. However, in -most cases, writing a Texinfo file is better, since you can use it to -make a printed manual or produce other formats, such as HTML and -DocBook, as well as for generating Info files. - - The `makeinfo' command converts a Texinfo file into an Info file; -`texinfo-format-region' and `texinfo-format-buffer' are GNU Emacs -functions that do the same. - - *Note Overview of Texinfo: (texinfo)Top, for how to write a Texinfo -file. - - *Note Creating an Info File: (texinfo)Creating an Info File, for how -to create an Info file from a Texinfo file. - - *Note Installing an Info File: (texinfo)Installing an Info File, for -how to install an Info file after you have created one. - - However, if you want to edit an Info file manually and install it -manually, here is how. - -* Menu: - -* Add:: Describes how to add new nodes to the hierarchy. - Also tells what nodes look like. -* Menus:: How to add to or create menus in Info nodes. -* Cross-refs:: How to add cross-references to Info nodes. -* Tags:: How to make tags tables for Info files. -* Checking:: Checking an Info File. - - -File: info.info, Node: Add, Next: Menus, Up: Expert Info - -3.1 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. *Note Menu: Menus. - - 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.(1) - - 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. - - ---------- Footnotes ---------- - - (1) 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 `^_'. - - -File: info.info, Node: Menus, Next: Cross-refs, Prev: Add, Up: Expert Info - -3.2 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 on the node graph, -nothing terrible happens if a substructure is not pointed to, but such -a substructure is rather useless since nobody can ever find out that it -exists. - - -File: info.info, Node: Cross-refs, Next: Tags, Prev: Menus, Up: Expert Info - -3.3 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! - -* Menu: - -* Help-Cross:: Target of a cross-reference. - - -File: info.info, Node: Help-Cross, Up: Cross-refs - -3.3.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. - - -File: info.info, Node: Tags, Next: Checking, Prev: Cross-refs, Up: Expert Info - -3.4 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. - - -File: info.info, Node: Checking, Prev: Tags, Up: Expert Info - -3.5 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. - - -File: info.info, Node: Index, Prev: Expert Info, Up: Top - -Index -***** - -This is an alphabetical listing of all the commands, variables, and -topics discussed in this document. - - -* Menu: - -* 1 through 9 (Info mode): Choose menu subtopic. - (line 6) -* ? (Info mode): Help-^L. (line 74) -* abbreviating Info subnodes: Help-M. (line 90) -* b (Info mode): Help-^L. (line 65) -* BACKSPACE (Info mode): Help-^L. (line 15) -* C-l (Info mode): Help-^L. (line 59) -* C-q (Info mode): Advanced. (line 11) -* C-r (Info mode): Search Text. (line 32) -* C-s (Info mode): Search Text. (line 32) -* clone-buffer: Create Info buffer. (line 6) -* completion of Info node names: Help-M. (line 98) -* cross reference format: Cross-refs. (line 6) -* cross references in Info documents: Help-Xref. (line 6) -* d (Info mode): Help-Int. (line 49) -* DEL (Info mode): Help-^L. (line 15) -* Directory node: Add. (line 31) -* f (Info mode): Help-Xref. (line 12) -* format of node headers: Add. (line 24) -* g (Info mode): Go to node. (line 6) -* go to a node by name: Go to node. (line 6) -* go to another Info file: Go to node. (line 15) -* go to Directory node: Help-Int. (line 49) -* go to Top node: Help-Int. (line 59) -* going back in Info history: Help-Int. (line 26) -* going forward in Info history: Help-Int. (line 41) -* header of Info node: Help. (line 17) -* history list of visited nodes: Help-Int. (line 45) -* i (Info mode): Search Index. (line 6) -* index-apropos: Search Index. (line 37) -* Info document as a reference: Search Text. (line 6) -* Info documents as tutorials: Help-^L. (line 37) -* Info menus: Help-M. (line 6) -* Info-additional-directory-list: Emacs Info Variables. - (line 24) -* info-apropos: Search Index. (line 37) -* Info-directory: Help-Int. (line 49) -* Info-directory-list: Emacs Info Variables. - (line 13) -* Info-enable-active-nodes: Emacs Info Variables. - (line 72) -* Info-exit: Help-Q. (line 6) -* Info-follow-reference: Help-Xref. (line 12) -* Info-fontify-maximum-menu-size: Emacs Info Variables. - (line 39) -* Info-fontify-visited-nodes: Emacs Info Variables. - (line 42) -* Info-goto-node: Go to node. (line 6) -* Info-hide-note-references: Emacs Info Variables. - (line 51) -* Info-history: Help-Int. (line 45) -* Info-history-back: Help-Int. (line 26) -* Info-history-forward: Help-Int. (line 41) -* Info-index: Search Index. (line 6) -* Info-isearch-search: Emacs Info Variables. - (line 69) -* Info-menu: Help-M. (line 85) -* Info-mode-hook: Emacs Info Variables. - (line 29) -* Info-mouse-follow-nearest-node: Help-M. (line 171) -* Info-nth-menu-item: Choose menu subtopic. - (line 6) -* Info-scroll-down: Help-^L. (line 15) -* Info-scroll-prefer-subnodes: Emacs Info Variables. - (line 59) -* Info-scroll-up: Help-^L. (line 15) -* Info-search: Search Text. (line 16) -* Info-summary: Help-^L. (line 74) -* Info-tagify: Tags. (line 11) -* Info-top-node: Help-Int. (line 59) -* Info-up: Help-FOO. (line 13) -* Info-use-header-line: Emacs Info Variables. - (line 46) -* Info-validate: Checking. (line 17) -* invisible text in Emacs: Help-Inv. (line 10) -* isearch: Search Text. (line 32) -* L (Info mode): Help-Int. (line 45) -* l (Info mode): Help-Int. (line 26) -* m (Info mode): Help-M. (line 62) -* M-n (Info mode): Create Info buffer. (line 6) -* M-s (Info mode): Search Text. (line 28) -* menu and menu entry format: Menus. (line 10) -* menus in an Info document: Help-M. (line 6) -* mouse support in Info mode: Help-M. (line 155) -* Mouse-2 (Info mode): Help-M. (line 155) -* multiple Info buffers: Create Info buffer. (line 6) -* n (Info mode): Help. (line 28) -* node delimiters: Add. (line 12) -* node header line format: Add. (line 24) -* node name format: Add. (line 31) -* node, in Info documents: Help. (line 12) -* p (Info mode): Help-P. (line 6) -* PAGEDOWN (Info mode): Help-^L. (line 52) -* PAGEUP (Info mode): Help-^L. (line 52) -* q (Info mode): Help-Q. (line 6) -* quitting Info mode: Help-Q. (line 6) -* r (Info mode): Help-Int. (line 41) -* reading Info documents top to bottom: Help-^L. (line 37) -* s (Info mode): Search Text. (line 16) -* searching Info documents: Search Text. (line 6) -* searching Info indices: Search Index. (line 6) -* select N'th menu item: Choose menu subtopic. - (line 6) -* small screen, moving around: Help-Small-Screen. (line 6) -* SPC (Info mode): Help-^L. (line 15) -* stale tags tables: Tags. (line 16) -* t (Info mode): Help-Int. (line 59) -* tags tables in Info files: Tags. (line 6) -* u (Info mode): Help-FOO. (line 13) -* unstructured documents: Add. (line 45) -* update Info tags table: Tags. (line 16) -* visible-mode: Help-Inv. (line 17) - - - -Tag Table: -Node: Top1450 -Node: Getting Started2534 -Node: Help-Small-Screen3392 -Node: Help5351 -Node: Help-P7004 -Node: Help-^L8212 -Ref: Help-^L-Footnote-112748 -Node: Help-Inv13121 -Node: Help-]14805 -Node: Help-M16370 -Node: Help-FOO24928 -Node: Help-Xref25893 -Node: Help-Int29470 -Node: Help-Q32480 -Node: Advanced33638 -Node: Search Text34851 -Node: Search Index36855 -Node: Go to node39074 -Node: Choose menu subtopic40101 -Node: Create Info buffer41288 -Node: Emacs Info Variables42375 -Node: Expert Info46162 -Node: Add47516 -Ref: Add-Footnote-150518 -Node: Menus50771 -Node: Cross-refs53663 -Node: Help-Cross54439 -Node: Tags55108 -Node: Checking56624 -Node: Index57551 - -End Tag Table diff --git a/Master/texmf/doc/info/texinfo.info b/Master/texmf/doc/info/texinfo.info deleted file mode 100644 index 6f00c11e540..00000000000 --- a/Master/texmf/doc/info/texinfo.info +++ /dev/null @@ -1,19415 +0,0 @@ -This is texinfo, produced by makeinfo version 4.12 from texinfo.txi. - -This manual is for GNU Texinfo (version 4.12, 9 April 2008), a -documentation system that can produce both online information and a -printed manual from a single source. - - Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, 1998, -1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free -Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.2 or any later version published by the Free Software - Foundation; with no Invariant Sections, with the Front-Cover Texts - being "A GNU Manual", and with the Back-Cover Texts as in (a) - below. A copy of the license is included in the section entitled - "GNU Free Documentation License." - - (a) The FSF's Back-Cover Text is: "You are free to copy and modify - this GNU Manual. Buying copies from GNU Press supports the FSF in - developing GNU and promoting software freedom." - -INFO-DIR-SECTION Texinfo documentation system -START-INFO-DIR-ENTRY -* Texinfo: (texinfo). The GNU documentation format. -* install-info: (texinfo)Invoking install-info. Update info/dir entries. -* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents. -* texi2pdf: (texinfo)PDF Output. PDF output for Texinfo. -* pdftexi2dvi: (texinfo)PDF Output. PDF output for Texinfo. -* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files. -* makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source. -END-INFO-DIR-ENTRY - - -File: texinfo, Node: Top, Next: Copying Conditions, Up: (dir) - -Texinfo -******* - -This manual is for GNU Texinfo (version 4.12, 9 April 2008), a -documentation system that can produce both online information and a -printed manual from a single source. - - 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. - -* Menu: - -* Copying Conditions:: Your rights. -* Overview:: Texinfo in brief. -* Texinfo Mode:: Using the GNU Emacs Texinfo mode. -* Beginning a File:: What is at the beginning of a Texinfo file? -* Ending a File:: What is at the end of a Texinfo file? -* Structuring:: Creating chapters, sections, appendices, etc. -* Nodes:: Writing nodes, the basic unit of Texinfo. -* Menus:: Writing menus. -* Cross References:: Writing cross references. -* Marking Text:: Marking words and phrases as code, - keyboard input, meta-syntactic - variables, and the like. -* Quotations and Examples:: Block quotations, examples, etc. -* Lists and Tables:: Itemized or numbered lists, and tables. -* Special Displays:: Floating figures and footnotes. -* Indices:: Creating indices. -* Insertions:: Inserting @-signs, braces, etc. -* Breaks:: Forcing or preventing line and page breaks. -* Definition Commands:: Describing functions and the like uniformly. -* Conditionals:: Specifying text for only some output cases. -* Internationalization:: Supporting languages other than English. -* Defining New Texinfo Commands:: User-defined macros and aliases. -* Hardcopy:: Output for paper, with TeX. -* Creating and Installing Info Files:: Details on Info output. -* Generating HTML:: Details on HTML output. - -* Command List:: All the Texinfo @-commands. -* Tips:: Hints on how to write a Texinfo document. -* Sample Texinfo Files:: Complete examples, including full texts. -* Include Files:: How to incorporate other Texinfo files. -* Headings:: How to write page headings and footings. -* Catching Mistakes:: How to find formatting mistakes. -* GNU Free Documentation License::Copying this manual. -* Command and Variable Index:: A menu containing commands and variables. -* General Index:: A menu covering many topics. - - --- The Detailed Node Listing --- - -Overview of Texinfo - -* Reporting Bugs:: Submitting effective bug reports. -* Using Texinfo:: Create printed or online output. -* Output Formats:: Overview of the supported output formats. -* Info Files:: What is an Info file? -* Printed Books:: Characteristics of a printed book or manual. -* Formatting Commands:: @-commands are used for formatting. -* Conventions:: General rules for writing a Texinfo file. -* Comments:: Writing comments and ignored text in general. -* Minimum:: What a Texinfo file must have. -* Six Parts:: Usually, a Texinfo file has six parts. -* Short Sample:: A short sample Texinfo file. -* History:: Acknowledgements, contributors and genesis. - -Using Texinfo Mode - -* Texinfo Mode Overview:: How Texinfo mode can help you. -* Emacs Editing:: Texinfo mode adds to GNU Emacs' general - purpose editing features. -* Inserting:: How to insert frequently used @-commands. -* Showing the Structure:: How to show the structure of a file. -* Updating Nodes and Menus:: How to update or create new nodes and menus. -* Info Formatting:: How to format for Info. -* Printing:: How to format and print part or all of a file. -* Texinfo Mode Summary:: Summary of all the Texinfo mode commands. - -Updating Nodes and Menus - -* Updating Commands:: Five major updating commands. -* Updating Requirements:: How to structure a Texinfo file for - using the updating command. -* Other Updating Commands:: How to indent descriptions, insert - missing nodes lines, and update - nodes in sequence. - -Beginning a Texinfo File - -* Sample Beginning:: A sample beginning for a Texinfo file. -* Texinfo File Header:: The first lines. -* Document Permissions:: Ensuring your manual is free. -* Titlepage & Copyright Page:: Creating the title and copyright pages. -* Contents:: How to create a table of contents. -* The Top Node:: Creating the `Top' node and master menu. -* Global Document Commands:: Affecting formatting throughout. -* Software Copying Permissions:: Ensure that you and others continue to - have the right to use and share software. - -Texinfo File Header - -* First Line:: The first line of a Texinfo file. -* Start of Header:: Formatting a region requires this. -* setfilename:: Tell Info the name of the Info file. -* settitle:: Create a title for the printed work. -* End of Header:: Formatting a region requires this. - -Document Permissions - -* copying:: Declare the document's copying permissions. -* insertcopying:: Where to insert the permissions. - -Title and Copyright Pages - -* titlepage:: Create a title for the printed document. -* titlefont center sp:: The `@titlefont', `@center', - and `@sp' commands. -* title subtitle author:: The `@title', `@subtitle', - and `@author' commands. -* Copyright:: How to write the copyright notice and - include copying permissions. -* end titlepage:: Turn on page headings after the title and - copyright pages. -* headings on off:: An option for turning headings on and off - and double or single sided printing. - -The `Top' Node and Master Menu - -* Top Node Example:: -* Master Menu Parts:: - -Global Document Commands - -* documentdescription:: Document summary for the HTML output. -* setchapternewpage:: Start chapters on right-hand pages. -* paragraphindent:: Specify paragraph indentation. -* firstparagraphindent:: Suppress indentation of the first paragraph. -* exampleindent:: Specify environment indentation. - -Ending a Texinfo File - -* Printing Indices & Menus:: How to print an index in hardcopy and - generate index menus in Info. -* File End:: How to mark the end of a file. - -Chapter Structuring - -* Tree Structuring:: A manual is like an upside down tree ... -* Structuring Command Types:: How to divide a manual into parts. -* makeinfo top:: The `@top' command, part of the `Top' node. -* chapter:: -* unnumbered & appendix:: -* majorheading & chapheading:: -* section:: -* unnumberedsec appendixsec heading:: -* subsection:: -* unnumberedsubsec appendixsubsec subheading:: -* subsubsection:: Commands for the lowest level sections. -* Raise/lower sections:: How to change commands' hierarchical level. - -Nodes - -* Two Paths:: Different commands to structure - Info output and printed output. -* Node Menu Illustration:: A diagram, and sample nodes and menus. -* node:: Creating nodes, in detail. -* makeinfo Pointer Creation:: Letting makeinfo determine node pointers. -* anchor:: Defining arbitrary cross-reference targets. - -The `@node' Command - -* Node Names:: How to choose node and pointer names. -* Writing a Node:: How to write an `@node' line. -* Node Line Tips:: Keep names short. -* Node Line Requirements:: Keep names unique, without @-commands. -* First Node:: How to write a `Top' node. -* makeinfo top command:: How to use the `@top' command. - -Menus - -* Menu Location:: Menus go at the ends of short nodes. -* Writing a Menu:: What is a menu? -* Menu Parts:: A menu entry has three parts. -* Less Cluttered Menu Entry:: Two part menu entry. -* Menu Example:: Two and three part menu entries. -* Other Info Files:: How to refer to a different Info file. - -Cross References - -* References:: What cross references are for. -* Cross Reference Commands:: A summary of the different commands. -* Cross Reference Parts:: A cross reference has several parts. -* xref:: Begin a reference with `See' ... -* Top Node Naming:: How to refer to the beginning of another file. -* ref:: A reference for the last part of a sentence. -* pxref:: How to write a parenthetical cross reference. -* inforef:: How to refer to an Info-only file. -* uref:: How to refer to a uniform resource locator. - -`@xref' - -* Reference Syntax:: What a reference looks like and requires. -* One Argument:: `@xref' with one argument. -* Two Arguments:: `@xref' with two arguments. -* Three Arguments:: `@xref' with three arguments. -* Four and Five Arguments:: `@xref' with four and five arguments. - -Marking Words and Phrases - -* Indicating:: How to indicate definitions, files, etc. -* Emphasis:: How to emphasize text. - -Indicating Definitions, Commands, etc. - -* Useful Highlighting:: Highlighting provides useful information. -* code:: Indicating program code. -* kbd:: Showing keyboard input. -* key:: Specifying keys. -* samp:: A literal sequence of characters. -* verb:: A verbatim sequence of characters. -* var:: Indicating metasyntactic variables. -* env:: Indicating environment variables. -* file:: Indicating file names. -* command:: Indicating command names. -* option:: Indicating option names. -* dfn:: Specifying definitions. -* cite:: Referring to books not in the Info system. -* abbr:: Indicating abbreviations. -* acronym:: Indicating acronyms. -* indicateurl:: Indicating a World Wide Web reference. -* email:: Indicating an electronic mail address. - -Emphasizing Text - -* emph & strong:: How to emphasize text in Texinfo. -* Smallcaps:: How to use the small caps font. -* Fonts:: Various font commands for printed output. - -Quotations and Examples - -* Block Enclosing Commands:: Different constructs for different purposes. -* quotation:: Writing a quotation. -* example:: Writing an example in a fixed-width font. -* verbatim:: Writing a verbatim example. -* verbatiminclude:: Including a file verbatim. -* lisp:: Illustrating Lisp code. -* small:: Examples in a smaller font. -* display:: Writing an example in the current font. -* format:: Writing an example without narrowed margins. -* exdent:: Undo indentation on a line. -* flushleft & flushright:: Pushing text flush left or flush right. -* noindent:: Preventing paragraph indentation. -* indent:: Forcing paragraph indentation. -* cartouche:: Drawing rounded rectangles around examples. - -Lists and Tables - -* Introducing Lists:: Texinfo formats lists for you. -* itemize:: How to construct a simple list. -* enumerate:: How to construct a numbered list. -* Two-column Tables:: How to construct a two-column table. -* Multi-column Tables:: How to construct generalized tables. - -Making a Two-column Table - -* table:: How to construct a two-column table. -* ftable vtable:: Automatic indexing for two-column tables. -* itemx:: How to put more entries in the first column. - -`@multitable': Multi-column Tables - -* Multitable Column Widths:: Defining multitable column widths. -* Multitable Rows:: Defining multitable rows, with examples. - -Special Displays - -* Floats:: Figures, tables, and the like. -* Images:: Including graphics and images. -* Footnotes:: Writing footnotes. - -Floats - -* float:: Producing floating material. -* caption shortcaption:: Specifying descriptions for floats. -* listoffloats:: A table of contents for floats. - -Inserting Images - -* Image Syntax:: -* Image Scaling:: - -Footnotes - -* Footnote Commands:: How to write a footnote in Texinfo. -* Footnote Styles:: Controlling how footnotes appear in Info. - -Indices - -* Index Entries:: Choose different words for index entries. -* Predefined Indices:: Use different indices for different kinds - of entries. -* Indexing Commands:: How to make an index entry. -* Combining Indices:: How to combine indices. -* New Indices:: How to define your own indices. - -Combining Indices - -* syncodeindex:: How to merge two indices, using `@code' - font for the merged-from index. -* synindex:: How to merge two indices, using the - default font of the merged-to index. - -Special Insertions - -* Atsign Braces Comma:: Inserting @ and {} and ,. -* Inserting Quote Characters:: Inserting left and right quotes, in code. -* Inserting Space:: How to insert the right amount of space - within a sentence. -* Inserting Accents:: How to insert accents and special characters. -* Inserting Quotation Marks:: How to insert quotation marks. -* Dots Bullets:: How to insert dots and bullets. -* TeX and copyright:: How to insert the TeX logo - and the copyright symbol. -* euro:: How to insert the Euro currency symbol. -* pounds:: How to insert the pounds currency symbol. -* textdegree:: How to insert the degrees symbol. -* minus:: How to insert a minus sign. -* geq leq:: How to insert greater/less-than-or-equal signs. -* math:: How to format a mathematical expression. -* Click Sequences:: Inserting GUI usage sequences. -* Glyphs:: How to indicate results of evaluation, - expansion of macros, errors, etc. - -Inserting @ and {} and , - -* Inserting an Atsign:: -* Inserting Braces:: -* Inserting a Comma:: - -Inserting Space - -* Not Ending a Sentence:: Sometimes a . doesn't end a sentence. -* Ending a Sentence:: Sometimes it does. -* Multiple Spaces:: Inserting multiple spaces. -* frenchspacing:: Specifying end-of-sentence spacing. -* dmn:: How to format a dimension. - -Inserting Ellipsis and Bullets - -* dots:: How to insert dots ... -* bullet:: How to insert a bullet. - -Inserting TeX and Legal Symbols: (C), (R) - -* tex:: The TeX logos. -* copyright symbol:: The copyright symbol (c in a circle). -* registered symbol:: The registered symbol (R in a circle). - -Glyphs for Examples - -* Glyphs Summary:: -* result:: How to show the result of expression. -* expansion:: How to indicate an expansion. -* Print Glyph:: How to indicate printed output. -* Error Glyph:: How to indicate an error message. -* Equivalence:: How to indicate equivalence. -* Point Glyph:: How to indicate the location of point. - -Glyphs Summary - -* result:: -* expansion:: -* Print Glyph:: -* Error Glyph:: -* Equivalence:: -* Point Glyph:: - -Forcing and Preventing Breaks - -* Break Commands:: Summary of break-related commands. -* Line Breaks:: Forcing line breaks. -* - and hyphenation:: Helping TeX with hyphenation points. -* allowcodebreaks:: Controlling line breaks within @code text. -* w:: Preventing unwanted line breaks in text. -* tie:: Inserting an unbreakable but varying space. -* sp:: Inserting blank lines. -* page:: Forcing the start of a new page. -* group:: Preventing unwanted page breaks. -* need:: Another way to prevent unwanted page breaks. - -Definition Commands - -* Def Cmd Template:: Writing descriptions using definition commands. -* Def Cmd Continuation Lines:: Continuing the heading over source lines. -* Optional Arguments:: Handling optional and repeated arguments. -* deffnx:: Group two or more `first' lines. -* Def Cmds in Detail:: Reference for all the definition commands. -* Def Cmd Conventions:: Conventions for writing definitions. -* Sample Function Definition:: An example. - -The Definition Commands - -* Functions Commands:: Commands for functions and similar entities. -* Variables Commands:: Commands for variables and similar entities. -* Typed Functions:: Commands for functions in typed languages. -* Typed Variables:: Commands for variables in typed languages. -* Data Types:: The definition command for data types. -* Abstract Objects:: Commands for object-oriented programming. - -Object-Oriented Programming - -* Variables: Object-Oriented Variables. -* Methods: Object-Oriented Methods. - -Conditionally Visible Text - -* Conditional Commands:: Text for a given format. -* Conditional Not Commands:: Text for any format other than a given one. -* Raw Formatter Commands:: Using raw formatter commands. -* set clear value:: Variable tests and substitutions. -* Conditional Nesting:: Using conditionals inside conditionals. - -`@set', `@clear', and `@value' - -* set value:: Expand a flag variable to a string. -* ifset ifclear:: Format a region if a flag is set. -* value Example:: An easy way to update edition information. - -Internationalization - -* documentlanguage:: Declaring the current language. -* documentencoding:: Declaring the input encoding. - -Defining New Texinfo Commands - -* Defining Macros:: Defining and undefining new commands. -* Invoking Macros:: Using a macro, once you've defined it. -* Macro Details:: Limitations of Texinfo macros. -* alias:: Command aliases. -* definfoenclose:: Customized highlighting. - -Formatting and Printing Hardcopy - -* Use TeX:: Use TeX to format for hardcopy. -* Format with tex/texindex:: How to format with explicit shell commands. -* Format with texi2dvi:: A simpler way to format. -* Print with lpr:: How to print. -* Within Emacs:: How to format and print from an Emacs shell. -* Texinfo Mode Printing:: How to format and print in Texinfo mode. -* Compile-Command:: How to print using Emacs's compile command. -* Requirements Summary:: TeX formatting requirements summary. -* Preparing for TeX:: What to do before you use TeX. -* Overfull hboxes:: What are and what to do with overfull hboxes. -* smallbook:: How to print small format books and manuals. -* A4 Paper:: How to print on A4 or A5 paper. -* pagesizes:: How to print with customized page sizes. -* Cropmarks and Magnification:: How to print marks to indicate the size - of pages and how to print scaled up output. -* PDF Output:: Portable Document Format output. -* Obtaining TeX:: How to Obtain TeX. - -Creating and Installing Info Files - -* Creating an Info File:: -* Installing an Info File:: - -Creating an Info File - -* makeinfo advantages:: `makeinfo' provides better error checking. -* Invoking makeinfo:: How to run `makeinfo' from a shell. -* makeinfo options:: Specify fill-column and other options. -* Pointer Validation:: How to check that pointers point somewhere. -* makeinfo in Emacs:: How to run `makeinfo' from Emacs. -* texinfo-format commands:: Two Info formatting commands written - in Emacs Lisp are an alternative - to `makeinfo'. -* Batch Formatting:: How to format for Info in Emacs Batch mode. -* Tag and Split Files:: How tagged and split files help Info - to run better. - -Installing an Info File - -* Directory File:: The top level menu for all Info files. -* New Info File:: Listing a new Info file. -* Other Info Directories:: How to specify Info files that are - located in other directories. -* Installing Dir Entries:: How to specify what menu entry to add - to the Info directory. -* Invoking install-info:: `install-info' options. - -Generating HTML - -* HTML Translation:: Details of the HTML output. -* HTML Splitting:: How HTML output is split. -* HTML CSS:: Influencing HTML output with Cascading Style Sheets. -* HTML Xref:: Cross-references in HTML output. - -HTML Cross-references - -* Link Basics: HTML Xref Link Basics. -* Node Expansion: HTML Xref Node Name Expansion. -* Command Expansion: HTML Xref Command Expansion. -* 8-bit Expansion: HTML Xref 8-bit Character Expansion. -* Mismatch: HTML Xref Mismatch. - -@-Command List - -* Command Syntax:: General syntax for varieties of @-commands. - -Sample Texinfo Files - -* Short Sample Texinfo File:: -* GNU Sample Texts:: -* Verbatim Copying License:: -* All-permissive Copying License:: - -GNU Free Documentation License - -Include Files - -* Using Include Files:: How to use the `@include' command. -* texinfo-multiple-files-update:: How to create and update nodes and - menus when using included files. -* Include Files Requirements:: `texinfo-multiple-files-update' needs. -* Sample Include File:: A sample outer file with included files - within it; and a sample included file. -* Include Files Evolution:: How use of the `@include' command - has changed over time. - -Page Headings - -* Headings Introduced:: Conventions for using page headings. -* Heading Format:: Standard page heading formats. -* Heading Choice:: How to specify the type of page heading. -* Custom Headings:: How to create your own headings and footings. - -Formatting Mistakes - -* makeinfo Preferred:: `makeinfo' finds errors. -* Debugging with Info:: How to catch errors with Info formatting. -* Debugging with TeX:: How to catch errors with TeX formatting. -* Using texinfo-show-structure:: How to use `texinfo-show-structure'. -* Using occur:: How to list all lines containing a pattern. -* Running Info-Validate:: How to find badly referenced nodes. - -Finding Badly Referenced Nodes - -* Using Info-validate:: How to run `Info-validate'. -* Unsplit:: How to create an unsplit file. -* Tagifying:: How to tagify a file. -* Splitting:: How to split a file manually. - - 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 - - -File: texinfo, Node: Copying Conditions, Next: Overview, Prev: 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 (*note GNU Free Documentation -License::). - - -File: texinfo, Node: Overview, Next: Texinfo Mode, Prev: Copying Conditions, Up: Top - -1 Overview of Texinfo -********************* - -"Texinfo"(1) 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. - -* Menu: - -* Reporting Bugs:: Submitting effective bug reports. -* Using Texinfo:: Create printed or online output. -* Output Formats:: Overview of the supported output formats. -* Info Files:: What is an Info file? -* Printed Books:: Characteristics of a printed book or manual. -* Formatting Commands:: @-commands are used for formatting. -* Conventions:: General rules for writing a Texinfo file. -* Comments:: Writing comments and ignored text in general. -* Minimum:: What a Texinfo file must have. -* Six Parts:: Usually, a Texinfo file has six parts. -* Short Sample:: A short sample Texinfo file. -* History:: Acknowledgements, contributors and genesis. - - ---------- 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. - - -File: texinfo, Node: Reporting Bugs, Next: Using Texinfo, 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: - - * the version number of Texinfo and the program(s) or manual(s) - involved. - - * hardware and operating system names and versions. - - * the contents of any input files necessary to reproduce the bug. - - * a description of the problem and samples of any erroneous output. - - * any unusual options you gave to `configure'. - - * anything else that you think would be helpful. - - 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' (*note Overview: (diff)Top.) and include `ChangeLog' entries -(*note Change Log: (emacs)Change Log.), and follow the existing coding -style. - - -File: texinfo, Node: Using Texinfo, Next: Output Formats, Prev: 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 (*note 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. (*Note 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 -(http://www.gnu.org/doc/). - - -File: texinfo, Node: Output Formats, Next: Info Files, Prev: 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 (*note Info Files::) for more details on this format. The - Emacs Info subsystem (*note Getting Started: (info)Top.), and the - standalone `info' program (*note Info Standalone: - (info-stnd)Top.), among others, can read these files. *Note - 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. Also, standard output is used by default. - -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/'. *Note 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 (*note Invoking Dvips: - (dvips)Invoking Dvips.) and Xdvi for viewing on an X display - (`http://sourceforge.net/projects/xdvi/'). *Note 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' or `texi2pdf'.) This format was - developed by Adobe Systems for portable document interchange, - based on their previous PostScript language. It can represent the - exact appearance of a document, including fonts and graphics, and - supporting arbitrary scaling. It is intended to be - platform-independent and easily viewable, among other design goals; - `http://tug.org/TUGboat/Articles/tb22-3/tb72beebe-pdf.pdf' has - some background. Texinfo uses the `pdftex' program, a variant of - TeX, to output PDF; see `http://tug.org/applications/pdftex'. - *Note 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. - - -File: texinfo, Node: Info Files, Next: Printed Books, Prev: 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. - - *Note Top: (info)Top, 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.(1) - - 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 (*note Top: (info)Top.). - - 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 *'. (*note Advanced Info commands: -(info)Advanced.) - - 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 URIs of any kind. - - ---------- Footnotes ---------- - - (1) 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. - - -File: texinfo, Node: Printed Books, Next: Formatting Commands, Prev: 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.(1) - - 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 the Texinfo home page, -`http://www.gnu.org/software/texinfo/'. - - 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'). (*Note Printing "Small" Books: smallbook. Also, see -*note Printing on A4 Paper: 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. (*Note -TeX Mode: (emacs)TeX Mode, 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 *note How to Obtain TeX: Obtaining TeX. - - ---------- Footnotes ---------- - - (1) You can also use the `texi2roff' (ftp://tug.org/texi2roff.tar.gz) -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. - - -File: texinfo, Node: Formatting Commands, Next: Conventions, Prev: 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 arguments(1) they take, you need to -write @-commands on lines of their own or as part of sentences: - - * Write a command such as `@quotation' at the beginning of a line as - the only text on the line. (`@quotation' begins an indented - environment.) - - * Write a command such as `@chapter' at the beginning of a line - followed by the command's arguments, in this case the chapter - title, on the rest of the line. (`@chapter' creates chapter - titles.) - - * Write a command such as `@dots{}' wherever you wish but usually - within a sentence. (`@dots{}' creates an ellipsis ...) - - * Write a command such as `@code{SAMPLE-CODE}' wherever you wish - (but usually within a sentence) with its argument, SAMPLE-CODE in - this example, between the braces. (`@code' marks text as being - code.) - - * Write a command such as `@example' on a line of its own; write the - body-text on following lines; and write the matching `@end' - command, `@end example' in this case, on a line of its own after - the body-text. (`@example' ... `@end example' indents and typesets - body-text as an example.) It's usually ok to indent environment - commands like this, but in complicated and hard-to-define - circumstances the extra spaces cause extra space to appear in the - output, so beware. - -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. *Note @-Command Syntax: -Command Syntax, for all the details. - - ---------- Footnotes ---------- - - (1) 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. - - -File: texinfo, Node: Conventions, Next: Comments, Prev: Formatting Commands, Up: Overview - -1.7 General Syntactic Conventions -================================= - -This section describes the general conventions used in all Texinfo -documents. - - * All printable ASCII characters except `@', `{' and `}' can appear - in a Texinfo file and stand for themselves. `@' is the escape - character which introduces commands, while `{' and `}' are used to - surround arguments to certain commands. To put one of these - special characters into the document, put an `@' character in - front of it, like this: `@@', `@{', and `@}'. - - * Separate paragraphs with one or more blank lines. Currently - Texinfo only recognizes newline characters as end of line, not the - CRLF sequence used on some systems; so a "blank line" means - exactly two consecutive newlines. Sometimes blank lines are - useful or convenient in other cases as well; you can use the - `@noindent' to inhibit paragraph indentation if required (*note - `@noindent': noindent.). - - * Texinfo supports the usual quotation marks used in English, and - quotation marks used in other languages, please see *note - Inserting Quotation Marks::. - - * Use three hyphens in a row, `---', to produce a long dash--like - this (called an "em dash"), used for punctuation in sentences. - Use two hyphens, `--', to produce a medium dash (called an "en - dash"), used primarily for numeric ranges, as in "June 25-26". - Use a single hyphen, `-', to produce a standard hyphen used in - compound words. For display on the screen, Info reduces three - hyphens to two and two hyphens to one (not transitively!). Of - course, any number of hyphens in the source remain as they are in - literal contexts, such as `@code' and `@example'. - - * *Caution:* Last, do not use tab characters in a Texinfo file - (except in verbatim modes)! TeX uses variable-width fonts, which - means that it is impractical at best to define a tab to work in all - circumstances. Consequently, TeX treats tabs like single spaces, - and that is not what they look like in the source. Furthermore, - `makeinfo' does nothing special with tabs, and thus a tab - character in your input file will usually appear differently in the - output. - - To avoid this problem, Texinfo mode in GNU Emacs inserts multiple - spaces when you press the <TAB> key. Also, you can run `untabify' - in Emacs to convert tabs in a region to multiple spaces, or use - the `unexpand' command from the shell. - - - -File: texinfo, Node: Comments, Next: Minimum, Prev: 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. - - -File: texinfo, Node: Minimum, Next: Six Parts, Prev: Comments, Up: Overview - -1.9 What a Texinfo File Must Have -================================= - -By convention, the name 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: - - * The `\input texinfo' line tells TeX to use the `texinfo.tex' file, - which tells TeX how to translate the Texinfo @-commands into TeX - typesetting commands. (Note the use of the backslash, `\'; this - is correct for TeX.) - - * The `@setfilename' line provides a name for the Info file and - tells TeX to open auxiliary files. *All text before - `@setfilename' is ignored!* - - * The `@settitle' line specifies a title for the page headers (or - footers) of the printed manual, and the default document - description for the `<head>' in HTML format. Strictly speaking, - `@settitle' is optional--if you don't mind your document being - titled `Untitled'. - - * The `@bye' line at the end of the file on a line of its own tells - the formatters that the file is ended and to stop formatting. - - - 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. (*Note 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. - - -File: texinfo, Node: Six Parts, Next: Short Sample, Prev: 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 may contain commands for printing indices, and - closes with the `@bye' command on a line of its own. - - -File: texinfo, Node: Short Sample, Next: History, Prev: 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. - - *Note Beginning a File::, for full documentation on the commands -listed here. *Note 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 -*note 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. *Note GNU Sample Texts::. - - @copying - This is a short example of a complete Texinfo file, version 1.0. - - Copyright @copyright{} 2005 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 repeat the short description from the beginning of -the `@copying' text, but there's no need to repeat the copyright -information, so we don't use `@insertcopying' here. The `@top' command -itself helps `makeinfo' determine the relationships between nodes. - - @ifnottex - @node Top - @top Short Sample - - This is a short sample Texinfo file. - @end ifnottex - - @menu - * First Chapter:: The first chapter is the - only chapter in this sample. - * Index:: Complete index. - @end menu - -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. - - -File: texinfo, Node: History, Prev: 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. Franc,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 strove 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. - - -File: texinfo, Node: Texinfo Mode, Next: Beginning a File, Prev: 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. - -* Menu: - -* Texinfo Mode Overview:: How Texinfo mode can help you. -* Emacs Editing:: Texinfo mode adds to GNU Emacs' general - purpose editing features. -* Inserting:: How to insert frequently used @-commands. -* Showing the Structure:: How to show the structure of a file. -* Updating Nodes and Menus:: How to update or create new nodes and menus. -* Info Formatting:: How to format for Info. -* Printing:: How to format and print part or all of a file. -* Texinfo Mode Summary:: Summary of all the Texinfo mode commands. - - -File: texinfo, Node: Texinfo Mode Overview, Next: Emacs Editing, Up: Texinfo Mode - -2.1 Texinfo Mode Overview -========================= - -Texinfo mode provides special features for working with Texinfo files. -You can: - - * Insert frequently used @-commands. - - * Automatically create `@node' lines. - - * Show the structure of a Texinfo source file. - - * Automatically create or update the `Next', `Previous', and `Up' - pointers of a node. - - * Automatically create or update menus. - - * Automatically create a master menu. - - * Format a part or all of a file for Info. - - * Typeset and print part or all of a file. - - Perhaps the two most helpful features are those for inserting -frequently used @-commands and for creating node pointers and menus. - - -File: texinfo, Node: Emacs Editing, Next: Inserting, Prev: 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 n p' (`narrow-to-page') command. (*Note Pages: -(emacs)Pages, 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. - - -File: texinfo, Node: Inserting, Next: Showing the Structure, Prev: 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 ]' -`M-x up-list' - Move from between a pair of braces forward past the closing brace. - Typing `C-c ]' is easier than typing `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. *Note The Parts of a -Menu: Menu Parts.) - - 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. - - -File: texinfo, Node: Showing the Structure, Next: Updating Nodes and Menus, Prev: 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'). (*Note Narrowing: (emacs)Narrowing, 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 n p' (`narrow-to-page') -command to narrow to a chapter. *Note Pages: (emacs)Pages, for more -information about the page commands. - - -File: texinfo, Node: Updating Nodes and Menus, Next: Info Formatting, Prev: 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. - -* Menu: - -* Updating Commands:: Five major updating commands. -* Updating Requirements:: How to structure a Texinfo file for - using the updating command. -* Other Updating Commands:: How to indent descriptions, insert - missing nodes lines, and update - nodes in sequence. - - -File: texinfo, Node: Updating Commands, Next: Updating Requirements, Up: Updating Nodes and Menus - -2.5.1 The Updating Commands ---------------------------- - -You can use the updating commands to: - - * insert or update the `Next', `Previous', and `Up' pointers of a - node, - - * insert or update the menu for a section, and - - * create a master menu for a Texinfo source file. - - 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. (*Note The Top Node - and Master Menu: The Top Node, 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 can be useful to reduce it to as low as 24. You can set -the variable via customization (*note Changing an Option: -(emacs)Changing an Option.) or with the `M-x set-variable' command -(*note Examining and Setting Variables: (emacs)Examining.). - - 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. (*Note Other Updating Commands::, -for more information.) - - -File: texinfo, Node: Updating Requirements, Next: Other Updating Commands, Prev: 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. (*Note 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. - - -File: texinfo, Node: Other Updating Commands, Prev: 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 (*note Inserting - Frequently Used Commands: Inserting.) 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. *Note - 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. - - -File: texinfo, Node: Info Formatting, Next: Printing, Prev: 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. - - *Note Creating an Info File::, for details about Info formatting. - - -File: texinfo, Node: Printing, Next: Texinfo Mode Summary, Prev: 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 (*note 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.) - - *Note Hardcopy::, for a description of the other TeX related -commands, such as `tex-show-print-queue'. - - -File: texinfo, Node: Texinfo Mode Summary, Prev: 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 { Insert braces. - 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. - - -File: texinfo, Node: Beginning a File, Next: Ending a File, Prev: 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 (*note 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. - -* Menu: - -* Sample Beginning:: A sample beginning for a Texinfo file. -* Texinfo File Header:: The first lines. -* Document Permissions:: Ensuring your manual is free. -* Titlepage & Copyright Page:: Creating the title and copyright pages. -* Contents:: How to create a table of contents. -* The Top Node:: Creating the `Top' node and master menu. -* Global Document Commands:: Affecting formatting throughout. -* Software Copying Permissions:: Ensure that you and others continue to - have the right to use and share software. - - -File: texinfo, Node: Sample Beginning, Next: Texinfo File Header, 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. - - *Note 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 - - This manual is for PROGRAM, version VERSION. - @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 - ... - - -File: texinfo, Node: Texinfo File Header, Next: Document Permissions, Prev: 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' (*note synindex::), for instance, -is another command often included in the header. *Note 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 - -* Menu: - -* First Line:: The first line of a Texinfo file. -* Start of Header:: Formatting a region requires this. -* setfilename:: Tell Info the name of the Info file. -* settitle:: Create a title for the printed work. -* End of Header:: Formatting a region requires this. - - -File: texinfo, Node: First Line, Next: Start of Header, 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. - - -File: texinfo, Node: Start of Header, Next: setfilename, Prev: 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 (*note End of Header::). - - The start- and end-of-header lines allow you to format only part of a -Texinfo file for Info or printing. *Note 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. *Note Texinfo Mode Printing::. - - -File: texinfo, Node: setfilename, Next: settitle, Prev: 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. (*Note 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 (*note -Preparing for TeX: Preparing for TeX.). - - -File: texinfo, Node: settitle, Next: End of Header, Prev: 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 (*note 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'. *Note 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. (*Note The `@headings' -Command: headings on off, for more information.) - - You may, if you wish, create your own, customized headings and -footings. *Note Headings::, for a detailed discussion of this. - - -File: texinfo, Node: End of Header, Prev: 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 - - *Note Start of Header::. - - -File: texinfo, Node: Document Permissions, Next: Titlepage & Copyright Page, Prev: 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. - -* Menu: - -* copying:: Declare the document's copying permissions. -* insertcopying:: Where to insert the permissions. - - -File: texinfo, Node: copying, Next: insertcopying, 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 (*note 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. - - *Note GNU Sample Texts::, for the full text to be used in GNU manuals. -*Note 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 (C) 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. If you do use several lines, do not indent any of them -(or anything else in the `@copying' block) in the source file. - - *Note Copyright Notices: (maintain)Copyright Notices, for additional -information. - - -File: texinfo, Node: insertcopying, Prev: 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 (*note Copyright::). - - 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 *'), but -this does not matter for legal purposes, because the text is present. - - 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). - - The permissions text defined by `@copying' also appears automatically -at the beginning of the XML output file. - - -File: texinfo, Node: Titlepage & Copyright Page, Next: Contents, Prev: 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'. - -* Menu: - -* titlepage:: Create a title for the printed document. -* titlefont center sp:: The `@titlefont', `@center', - and `@sp' commands. -* title subtitle author:: The `@title', `@subtitle', - and `@author' commands. -* Copyright:: How to write the copyright notice and - include copying permissions. -* end titlepage:: Turn on page headings after the title and - copyright pages. -* headings on off:: An option for turning headings on and off - and double or single sided printing. - - -File: texinfo, Node: titlepage, Next: titlefont center sp, 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. (*Note Page Headings: 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 (*note 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 number(1) 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 -*note 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. - - ---------- Footnotes ---------- - - (1) 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. - - -File: texinfo, Node: titlefont center sp, Next: title subtitle author, Prev: 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 -(*note 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. (*Note `@sp': 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. - - -File: texinfo, Node: title subtitle author, Next: Copyright, Prev: 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 *note value Example::. - - -File: texinfo, Node: Copyright, Next: end titlepage, Prev: 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 incantation 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 `l's in the word `filll'; -this is correct. - - To insert the copyright text itself, write `@insertcopying' next -(*note 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 - - -File: texinfo, Node: end titlepage, Next: headings on off, Prev: Copyright, Up: Titlepage & Copyright Page - -3.4.5 Heading Generation ------------------------- - -Like all `@end' commands (*note Quotations and Examples::), the `@end -titlepage' command must be written at the beginning of a line by -itself, with only one space between the `@end' and the `titlepage'. It -not only marks the end of the title and copyright pages, but also -causes TeX to start generating page headings and page numbers. - - To repeat what is said elsewhere, Texinfo has two standard page -heading formats, one for documents which are printed on one side of -each sheet of paper (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: - - * The conventional way is to write an `@setchapternewpage' command - before the title page commands, and then have the `@end titlepage' - command start generating page headings in the manner desired. - (*Note setchapternewpage::.) - - * Alternatively, you can use the `@headings' command to prevent page - headings from being generated or to start them for either single or - double-sided printing. (Write an `@headings' command immediately - after the `@end titlepage' command. *Note The `@headings' - Command: headings on off, for more information.) - - * Or, you may specify your own page heading and footing format. - *Note Page Headings: Headings, for detailed information about page - headings and footings. - - 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. - - -File: texinfo, Node: headings on off, Prev: 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 predefined 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' - Turn on page headings appropriate for double-sided printing. - -`@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. -*Note Page Headings: Headings, for more information. - - -File: texinfo, Node: Contents, Next: The Top Node, Prev: Titlepage & Copyright Page, Up: Beginning a File - -3.5 Generating a Table of Contents -================================== - -The `@chapter', `@section', and other structuring commands (*note -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 (*note 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' (*note 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' (*note Format with texi2dvi::) to specify -this without altering the source file at all. For example: - texi2dvi --texinfo=@setcontentsaftertitlepage foo.texi - - -File: texinfo, Node: The Top Node, Next: Global Document Commands, Prev: 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 a brief description of the manual (including -the version number), and end with a master menu for the whole manual. -Of course you should include any other general information you feel a -reader would find helpful. - - It is conventional and desirable to write an `@top' sectioning -command line containing the title of the document immediately after the -`@node Top' line (*note The `@top' Sectioning Command: makeinfo top -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 ifnottex', but it is simplest to do so. *Note -Conditionally Visible Text: Conditionals.) - -* Menu: - -* Top Node Example:: -* Master Menu Parts:: - - -File: texinfo, Node: Top Node Example, Next: Master Menu Parts, 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 - @end ifnottex - - Additional general information. - - @menu - * First Chapter:: - * Second Chapter:: - ... - * Index:: - @end menu - - -File: texinfo, Node: Master Menu Parts, Prev: 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. - - * The first part contains the major nodes in the Texinfo file: the - nodes for the chapters, chapter-like sections, and the appendices. - - * The second part contains nodes for the indices. - - * The third and subsequent parts contain a listing of the other, - lower level nodes, often ordered by chapter. This way, rather - than go through an intermediary menu, an inquirer can go directly - to a particular node when searching for specific information. - These menu items are not required; add them if you think they are a - convenience. If you do use them, put `@detailmenu' before the - first one, and `@end detailmenu' after the last; otherwise, - `makeinfo' will get confused. - - 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. (*Note 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:: - * General Index:: - - @detailmenu - --- The Detailed Node Listing --- - - Overview of Texinfo - - * Reporting Bugs:: ... - ... - - Beginning a Texinfo File - - * Sample Beginning:: ... - ... - @end detailmenu - @end menu - - -File: texinfo, Node: Global Document Commands, Next: Software Copying Permissions, Prev: 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. - -* Menu: - -* documentdescription:: Document summary for the HTML output. -* setchapternewpage:: Start chapters on right-hand pages. -* paragraphindent:: Specify paragraph indentation. -* firstparagraphindent:: Suppress indentation of the first paragraph. -* exampleindent:: Specify environment indentation. - - -File: texinfo, Node: documentdescription, Next: setchapternewpage, 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 (*note 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. - - -File: texinfo, Node: setchapternewpage, Next: paragraphindent, Prev: 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. *Note The -`@headings' Command: headings on off. - - 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. - - -File: texinfo, Node: paragraphindent, Next: firstparagraphindent, Prev: 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. *Note 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. - - -File: texinfo, Node: firstparagraphindent, Next: exampleindent, Prev: 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 (*note - 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. *Note Start of -Header::. - - -File: texinfo, Node: exampleindent, Prev: 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 - - `@exampleindent' is ignored for HTML output. Otherwise, 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 spaces in Info, and 0.4in in TeX, -which is somewhat less. (The reduction is to help TeX fit more -characters onto physical lines.) - - 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. *Note Start of -Header::. - - -File: texinfo, Node: Software Copying Permissions, Prev: 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. - - -File: texinfo, Node: Ending a File, Next: Structuring, Prev: 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 - -* Menu: - -* Printing Indices & Menus:: How to print an index in hardcopy and - generate index menus in Info. -* File End:: How to mark the end of a file. - - -File: texinfo, Node: Printing Indices & Menus, Next: File End, 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' (*note 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. *Note 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. - - * In printed output, `@printindex' produces a traditional two-column - index, with dot leaders between the index terms and page numbers. - - * In Info output, `@printindex' produces a special menu containing - the line number of the entry, relative to the start of the node. - Info readers can use this to go to the exact line of an entry, not - just the containing node. (Older Info readers will just go to the - node.) Here's an example: - - * First index entry: Top. (line 7) - - The actual number of spaces is variable, to right-justify the line - number; it's been reduced here to make the line fit in the printed - manual. - - * In plain text output, `@printindex' produces the same menu, but - the line numbers are relative to the start of the file, since - that's more convenient for that format. - - * In HTML and Docbook output, `@printindex' produces links to the - index entries. - - * In XML output, it simply records the index to be printed. - - It's not possible to generate an index when writing to standard -output; `makeinfo' generates a warning in this case. - - -File: texinfo, Node: File End, Prev: 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. *Note Using Local Variables and the Compile Command: -Compile-Command, for more information. - - -File: texinfo, Node: Structuring, Next: Nodes, Prev: 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 (*note Generating a Table of Contents: -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 (*note 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. - -* Menu: - -* Tree Structuring:: A manual is like an upside down tree ... -* Structuring Command Types:: How to divide a manual into parts. -* makeinfo top:: The `@top' command, part of the `Top' node. -* chapter:: -* unnumbered & appendix:: -* majorheading & chapheading:: -* section:: -* unnumberedsec appendixsec heading:: -* subsection:: -* unnumberedsubsec appendixsubsec subheading:: -* subsubsection:: Commands for the lowest level sections. -* Raise/lower sections:: How to change commands' hierarchical level. - - -File: texinfo, Node: Tree Structuring, Next: Structuring Command Types, 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. (*Note Nodes::, and see *note Menus::.) - - -File: texinfo, Node: Structuring Command Types, Next: makeinfo top, Prev: 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. - - * The `@chapter' and `@appendix' series of commands produce numbered - or lettered entries both in the body of a printed work and in its - table of contents. - - * The `@unnumbered' series of commands produce unnumbered entries - both in the body of a printed work and in its table of contents. - The `@top' command, which has a special use, is a member of this - series (*note `@top': makeinfo top.). An `@unnumbered' section - should be associated with a node and be a normal part of the - document structure. - - * The `@heading' series of commands produce simple unnumbered - headings that do not appear in a table of contents, are not - associated with nodes, and cannot be cross-referenced. The - heading commands never start a new page. - - * The `@majorheading' command is similar to `@chapheading', except - that it generates a larger vertical whitespace before the heading. - - * When an `@setchapternewpage' command says to do so, the - `@chapter', `@unnumbered', and `@appendix' commands start new - pages in the printed manual; the `@heading' commands do not. - - 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' - - -File: texinfo, Node: makeinfo top, Next: chapter, Prev: 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' (*note `@unnumbered' and `@appendix': unnumbered & -appendix.). For detailed information, see *note The `@top' Command: -makeinfo 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. - - -File: texinfo, Node: chapter, Next: unnumbered & appendix, Prev: 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. - - -File: texinfo, Node: unnumbered & appendix, Next: majorheading & chapheading, Prev: 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 (`A', `B', ...) instead of by number. - - 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. - - -File: texinfo, Node: majorheading & chapheading, Next: section, Prev: 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. (*Note `@chapter': chapter.) - - -File: texinfo, Node: section, Next: unnumberedsec appendixsec heading, Prev: majorheading & chapheading, Up: Structuring - -5.7 `@section' -============== - -A `@section' command identifies a section within a chapter unit, -whether created with `@chapter', `@unnumbered', or `@appendix', -following the numbering scheme of the chapter-level command. Thus, -within a `@chapter' chapter numbered `1', the section is numbered like -`1.2'; within an `@appendix' "chapter" labeled `A', the section is -numbered like `A.2'; within an `@unnumbered' chapter, the section gets -no number. - - For example, 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. The output -is underlined with `=' in Info. - - Thus, - - @section This is a section - -might produce the following in Info: - - 5.7 This is a section - ===================== - - -File: texinfo, Node: unnumberedsec appendixsec heading, Next: subsection, Prev: 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, as described in the previous -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. - - `@unnumberedsec' and `@appendixsec' do not need to be used in -ordinary circumstances, because `@section' may also be used within -`@unnumbered' and `@appendix' chapters; again, see the previous section. - - -File: texinfo, Node: subsection, Next: unnumberedsubsec appendixsubsec subheading, Prev: unnumberedsec appendixsec heading, Up: Structuring - -5.9 The `@subsection' Command -============================= - -Subsections are to sections as sections are to chapters. (*Note -`@section': section.) In Info, subsection titles are underlined with -`-'. For example, - - @subsection This is a subsection - -produces - - 1.2.3 This is a subsection - -------------------------- - - In a printed manual, subsections are listed in the table of contents -and are numbered three levels deep. - - -File: texinfo, Node: unnumberedsubsec appendixsubsec subheading, Next: subsubsection, Prev: 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. (*Note `@subsection': -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. - - `@unnumberedsubsec' and `@appendixsubsec' do not need to be used in -ordinary circumstances, because `@subsection' may also be used within -sections of `@unnumbered' and `@appendix' chapters (*note `section': -section.). - - -File: texinfo, Node: subsubsection, Next: Raise/lower sections, Prev: 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. - (*Note `@subsection': 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. - - `@unnumberedsubsubsec' and `@appendixsubsubsec' do not need to be -used in ordinary circumstances, because `@subsubsection' may also be -used within subsections of `@unnumbered' and `@appendix' chapters -(*note `section': section.). - - In Info, `subsub' titles are underlined with periods. For example, - - @subsubsection This is a subsubsection - -produces - - 1.2.3.4 This is a subsubsection - ............................... - - -File: texinfo, Node: Raise/lower sections, Prev: 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 (*note 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. - - -File: texinfo, Node: Nodes, Next: Menus, Prev: 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. - -* Menu: - -* Two Paths:: Different commands to structure - Info output and printed output. -* Node Menu Illustration:: A diagram, and sample nodes and menus. -* node:: Creating nodes, in detail. -* makeinfo Pointer Creation:: Letting makeinfo determine node pointers. -* anchor:: Defining arbitrary cross-reference targets. - - -File: texinfo, Node: Two Paths, Next: Node Menu Illustration, Up: Nodes - -6.1 Two Paths -============= - -The node and menu commands and the chapter structuring commands are -technically independent of each other: - - * In Info, node and menu commands provide structure. The chapter - structuring commands generate headings with different kinds of - underlining--asterisks for chapters, hyphens for sections, and so - on; they do nothing else. - - * In TeX, the chapter structuring commands generate chapter and - section numbers and tables of contents. The node and menu - commands provide information for cross references; they do nothing - else. - - 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. - - -File: texinfo, Node: Node Menu Illustration, Next: node, Prev: 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 (*note 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. (*Note 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 -*note 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 - - -File: texinfo, Node: node, Next: makeinfo Pointer Creation, Prev: 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 specify 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 (for details of node names, *note Node Line -Requirements::). 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 (*note makeinfo -Pointer Creation::). - - Whether the node pointers are specified implicitly or explicitly, the -HTML output from `makeinfo' for each node includes links to the `Next', -`Previous', and `Up' nodes. The HTML also uses the `accesskey' -attribute with the values `n', `p', and `u' respectively. This allows -people using web browsers to follow the nagivation using (typically) -`M-LETTER', e.g., `M-n' for the `Next' node, from anywhere within the -node. - - You may insert spaces before each name on the `@node' line if you -wish; the spaces are ignored. You must write the name of the node and -(if present) the names of the `Next', `Previous', and `Up' pointers all -on the same line. Otherwise, the formatters fail. (*note info: -(info)Top, 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. (*Note Structuring Command Types::.) - - 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 *note -Cross References::.) - -* Menu: - -* Node Names:: How to choose node and pointer names. -* Writing a Node:: How to write an `@node' line. -* Node Line Tips:: Keep names short. -* Node Line Requirements:: Keep names unique, without @-commands. -* First Node:: How to write a `Top' node. -* makeinfo top command:: How to use the `@top' command. - - -File: texinfo, Node: Node Names, Next: Writing a Node, Up: node - -6.3.1 Choosing Node and Pointer Names -------------------------------------- - -The name of a node identifies the node (for details of node names, -*note Node Line Requirements::). 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 the present node in that menu and its -`Previous' pointer contains the name of the node that precedes it in -that menu. When a node's `Previous' node is the same as its `Up' node, -both node pointers name the same node. - - 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. *Note 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 output. - - -File: texinfo, Node: Writing a Node, Next: Node Line Tips, Prev: 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. (*Note Texinfo -Mode::, and *note 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 - - The NODE-NAME argument must be present, but the others are optional. -If you wish to specify some but not others, just insert commas as -needed, as in: `@node mynode,,,uppernode'. However, we recommend -leaving off all the pointers and letting `makeinfo' determine them, as -described above. - - 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. - - -File: texinfo, Node: Node Line Tips, Next: Node Line Requirements, Prev: Writing a Node, Up: node - -6.3.3 `@node' Line Tips ------------------------ - -Here are three suggestions: - - * Try to pick node names that are informative but short. - - In the Info file, the file name, node name, and pointer names are - all inserted on one line, which may run into the right edge of the - window. (This does not cause a problem with Info, but is ugly.) - - * Try to pick node names that differ from each other near the - beginnings of their names. This way, it is easy to use automatic - name completion in Info. - - * By convention, node names are capitalized just as they would be for - section or chapter titles--initial and significant words are - capitalized; others are not. - - -File: texinfo, Node: Node Line Requirements, Next: First Node, Prev: Node Line Tips, Up: node - -6.3.4 `@node' Line Requirements -------------------------------- - -Here are several requirements for `@node' lines: - - * All the node names for a single Info file must be unique. - - Duplicates confuse the Info movement commands. This means, for - example, that if you end every chapter with a summary, you must - name each summary node differently. You cannot just call each one - "Summary". You may, however, duplicate the titles of chapters, - sections, and the like. Thus you can end each chapter in a book - with a section called "Summary", so long as the node names for - those sections are all different. - - * A pointer name must be the name of a node. - - The node to which a pointer points may come before or after the - node containing the pointer. - - * @-commands in node names are not allowed. This includes - punctuation characters that are escaped with a `@', such as `@' and - `{', and accent commands such as `@''. (For a few cases when this - is useful, Texinfo has limited support for using @-commands in - node names; see *note Pointer Validation::.) Perhaps this - limitation will be removed some day. - - * Unfortunately, you cannot use periods, commas, colons or - parentheses within a node name; these confuse the Texinfo - processors. Perhaps this limitation will be removed some day, too. - - For example, the following is a section title in this manual: - - @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading} - - But the corresponding node name lacks the commas and the @'s: - - unnumberedsec appendixsec heading - - * Case is significant in node names. - - Spaces before and after names on the `@node' line are ignored, but - spaces "inside" a name are significant. For example: - - @node foo bar, - @node foo bar , - @node foo bar , - - all define the same node, `foo bar'. References to the node - should all use that name, without the leading or trailing spaces, - but with the internal spaces. - - -File: texinfo, Node: First Node, Next: makeinfo top command, Prev: 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 (*note Include Files::). The Top node should contain a -short summary, copying permissions, and a master menu. *Note 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: - - * The Top node (which must be named `top' or `Top') should have as - its `Up' node the name of a node in another file, where there is a - menu that leads to this file. Specify the file name in - parentheses. - - Usually, all Info files are installed in the same Info directory - tree; in this case, use `(dir)' as the parent of the Top node; - this is short for `(dir)top', and specifies the Top node in the - `dir' file, which contains the main menu for the Info system as a - whole. - - * The `Prev' node of the Top node should also be your `(dir)' file. - - * The `Next' node of the Top node should be the first chapter in your - document. - - - *Note Installing an Info File::, for more information about installing -an Info file in the `info' directory. - - It is usually best to leave the pointers off entirely and let the -tools implicitly define them, with this simple result: - - @node Top - - -File: texinfo, Node: makeinfo top command, Prev: 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 - - -File: texinfo, Node: makeinfo Pointer Creation, Next: anchor, Prev: 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. We highly recommend -using it. - - 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. *Note -`@top': makeinfo 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. - - If you use a detailed menu in your master menu (*note Master Menu -Parts::), mark it with the `@detailmenu @dots{} @end detailmenu' -environment, or `makeinfo' will get confused, typically about the last -and/or first node in the document. - - This implicit node pointer creation feature in `makeinfo' relieves -you from the need to update menus and pointers manually or with Texinfo -mode commands. (*Note 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 (*note Menus::) also disables this feature, for that -group of nodes. In those cases, you will need to explicitly specify -all pointers. - - -File: texinfo, Node: anchor, Prev: 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. *Note 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. -Whitespace (including newlines) is 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. (*Note goto-node: (info-stnd)goto-node.) - - Also like node names, anchor names cannot include some characters -(*note Node Line Requirements::). - - -File: texinfo, Node: Menus, Next: Cross References, Prev: 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 text before a menu, we generally recommend moving most -of the text into a new subnode--all but a paragraph or two. Otherwise, -a reader with a terminal that displays only a few lines may miss the -menu and its associated text. As a practical matter, it is best to -locate a menu within 20 or so lines of the beginning of the node. - -* Menu: - -* Menu Location:: Menus go at the ends of short nodes. -* Writing a Menu:: What is a menu? -* Menu Parts:: A menu entry has three parts. -* Less Cluttered Menu Entry:: Two part menu entry. -* Menu Example:: Two and three part menu entries. -* Other Info Files:: How to refer to a different Info file. - - -File: texinfo, Node: Menu Location, Next: Writing a Menu, 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 (*note 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 this also does not work with -`makeinfo''s implicit pointer creation, and it also makes the XML -output incorrect, since it does not reflect the true document -structure. So, regrettably, we can no longer recommend this. - - -File: texinfo, Node: Writing a Menu, Next: Menu Parts, Prev: 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. - - In the HTML output from `makeinfo', the `accesskey' attribute is used -with the values `1'...`9' for the first nine entries. This allows -people using web browsers to follow the first menu entries using -(typically) `M-DIGIT', e.g., `M-1' for the first entry. - - -File: texinfo, Node: Menu Parts, Next: Less Cluttered Menu Entry, Prev: 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. - - -File: texinfo, Node: Less Cluttered Menu Entry, Next: Menu Example, Prev: 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. - - -File: texinfo, Node: Menu Example, Next: Other Info Files, Prev: 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 (*note Referring -to Other Info Files: Other Info Files.). - - -File: texinfo, Node: Other Info Files, Prev: 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. (*Note 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. - - -File: texinfo, Node: Cross References, Next: Marking Text, Prev: 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. - -* Menu: - -* References:: What cross references are for. -* Cross Reference Commands:: A summary of the different commands. -* Cross Reference Parts:: A cross reference has several parts. -* xref:: Begin a reference with `See' ... -* Top Node Naming:: How to refer to the beginning of another file. -* ref:: A reference for the last part of a sentence. -* pxref:: How to write a parenthetical cross reference. -* inforef:: How to refer to an Info-only file. -* uref:: How to refer to a uniform resource locator. - - -File: texinfo, Node: References, Next: Cross Reference Commands, 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. (*note Following cross-references: -(info)Help-Xref.) - - The various cross reference commands use nodes (or anchors, *note -`@anchor': 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. - - -File: texinfo, Node: Cross Reference Commands, Next: Cross Reference Parts, Prev: 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. *Note `@cite': cite.) - - -File: texinfo, Node: Cross Reference Parts, Next: xref, Prev: 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 or the topic description. If you - include this argument, it becomes the first part of the cross - reference. It is usually omitted; then the topic description - (third argument) is used if it was specified; if that was omitted - as well, the node name is used. - - 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. - - -File: texinfo, Node: xref, Next: Top Node Naming, Prev: 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. - -* Menu: - -* Reference Syntax:: What a reference looks like and requires. -* One Argument:: `@xref' with one argument. -* Two Arguments:: `@xref' with two arguments. -* Three Arguments:: `@xref' with three arguments. -* Four and Five Arguments:: `@xref' with four and five arguments. - - -File: texinfo, Node: Reference Syntax, Next: One Argument, 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. *Note `@pxref': 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 (*note 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. - - -File: texinfo, Node: One Argument, Next: Two Arguments, Prev: 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.) - - -File: texinfo, Node: Two Arguments, Next: Three Arguments, Prev: 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.) - - -File: texinfo, Node: Three Arguments, Next: Four and Five Arguments, Prev: 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}. - - -File: texinfo, Node: Four and Five Arguments, Prev: 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. - - -File: texinfo, Node: Top Node Naming, Next: ref, Prev: 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 *note Referring to -Other Info Files: 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. - - -File: texinfo, Node: ref, Next: pxref, Prev: 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, @pxref{This}, and @ref{That}. - -produces in Info: - - For more information, *note This::, and *note That::. - -and in printed output: - - For more information, see Section 1.1 [This], page 1, and Section - 1.2 [That], page 2. - - 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, "note" being a verb: - - Sea surges are described in *note Hurricanes::. - - You should write a period or comma immediately after an `@ref' -command with two or more arguments. If there is no such following -punctuation, `makeinfo' will generate a (grammatically incorrect) -period in the Info output; otherwise, the cross-reference would fail -completely, due to the current syntax of Info format. - - In general, it is best to use `@ref' only when you need some word -other than "see" to precede the reference. When "see" (or "See") is -ok, `@xref' and `@pxref' are preferable. - - -File: texinfo, Node: pxref, Next: inforef, Prev: ref, Up: Cross References - -8.7 `@pxref' -============ - -The parenthetical reference command, `@pxref', is nearly the same as -`@xref', but it is best used at the end of a sentence or before a -closing parenthesis. 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, if necessary. - - `@pxref' is designed so that the output looks right and works right -at the end of a sentence or parenthetical phrase, both in printed -output and in an Info file. In a printed manual, a closing comma or -period should not follow a cross reference within parentheses; such -punctuation is wrong. But in an Info file, suitable closing -punctuation must follow the cross reference so Info can recognize its -end. `@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' -(*note `@xref': xref.). - - In past versions of Texinfo, it was not allowed to write punctuation -after a `@pxref', so it could be used _only_ before a right -parenthesis. This is no longer the case, so now it can be used (for -example) at the end of a sentence, where a lowercase "see" works best. -For instance: - - ... For more information, @pxref{More}. - -which outputs (in Info): - - ... For more information, *note More::. - -This works fine. `@pxref' should only be followed by a comma, period, -or right parenthesis; in other cases, `makeinfo' has to insert a period -to make the cross-reference work correctly in Info, and that period -looks wrong. - - As a matter of general style, `@pxref' is best used at the ends of -sentences. Although it technically works in the middle of a sentence, -that location breaks up the flow of reading. - - -File: texinfo, Node: inforef, Next: uref, Prev: pxref, Up: Cross References - -8.8 `@inforef' -============== - -`@inforef' is used for making cross references to Info documents--even -from a printed manual. This might be because you want to refer to -conditional `@ifinfo' text (*note Conditionals::), or because printed -output is not available (perhaps because there is no Texinfo source), -among other possibilities. - - The command takes either two or three arguments, in the following -order: - - 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}, - -For example, - - @inforef{Advanced, Advanced Info commands, info}, - for more information. - -produces (in Info): - - *Note Advanced Info commands: (info)Advanced, - for more information. - -and (in the printed output): - - See Info file `info', node `Advanced', for more information. - - (This particular example is not realistic, since the Info manual is -written in Texinfo, so all formats are available.) - - The converse of `@inforef' is `@cite', which is used to refer to -printed works for which no Info form exists. *Note `@cite': cite. - - -File: texinfo, Node: uref, Prev: 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' (*note `@indicateurl': indicateurl.), but in actual -practice it was misused the vast majority of the time. So we've -changed the meaning. - - 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. *Note 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 (ftp://ftp.gnu.org/gnu) - 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} program ... - -produces: - The ls program ... - -but with HTML: - The <a href="/man.cgi/1/ls">ls</a> program ... - - To merely indicate a url without creating a link people can follow, -use `@indicateurl' (*note `@indicateurl': 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. - - -File: texinfo, Node: Marking Text, Next: Quotations and Examples, Prev: 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. - -* Menu: - -* Indicating:: How to indicate definitions, files, etc. -* Emphasis:: How to emphasize text. - - -File: texinfo, Node: Indicating, Next: Emphasis, 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. - -* Menu: - -* Useful Highlighting:: Highlighting provides useful information. -* code:: Indicating program code. -* kbd:: Showing keyboard input. -* key:: Specifying keys. -* samp:: Indicating a literal sequence of characters. -* verb:: Indicating a verbatim sequence of characters. -* var:: Indicating metasyntactic variables. -* env:: Indicating environment variables. -* file:: Indicating file names. -* command:: Indicating command names. -* option:: Indicating option names. -* dfn:: Specifying definitions. -* cite:: Referring to books not in the Info system. -* abbr:: Indicating abbreviations. -* acronym:: Indicating acronyms. -* indicateurl:: Indicating an example URL. -* email:: Indicating an electronic mail address. - - -File: texinfo, Node: Useful Highlighting, Next: code, 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. - *Note `@code': code. - -`@kbd{KEYBOARD-CHARACTERS}' - Indicate keyboard input. *Note `@kbd': kbd. - -`@key{KEY-NAME}' - Indicate the conventional name for a key on a keyboard. *Note - `@key': key. - -`@samp{TEXT}' - Indicate text that is a literal example of a sequence of - characters. *Note `@samp': samp. - -`@verb{TEXT}' - Write a verbatim sequence of characters. *Note `@verb': verb. - -`@var{METASYNTACTIC-VARIABLE}' - Indicate a metasyntactic variable. *Note `@var': var. - -`@env{ENVIRONMENT-VARIABLE}' - Indicate an environment variable. *Note `@env': env. - -`@file{FILE-NAME}' - Indicate the name of a file. *Note `@file': file. - -`@command{COMMAND-NAME}' - Indicate the name of a command. *Note `@command': command. - -`@option{OPTION}' - Indicate a command-line option. *Note `@option': option. - -`@dfn{TERM}' - Indicate the introductory or defining use of a term. *Note - `@dfn': dfn. - -`@cite{REFERENCE}' - Indicate the name of a book. *Note `@cite': cite. - -`@abbr{ABBREVIATION}' - Indicate an abbreviation. - -`@acronym{ACRONYM}' - Indicate an acronym. *Note `@acronym': acronym. - -`@indicateurl{UNIFORM-RESOURCE-LOCATOR}' - Indicate an example (that is, nonfunctional) uniform resource - locator. *Note `@indicateurl': indicateurl. (Use `@url' (*note - `@url': uref.) for live url's.) - -`@email{EMAIL-ADDRESS[, DISPLAYED-TEXT]}' - Indicate an electronic mail address. *Note `@email': email. - - - -File: texinfo, Node: code, Next: kbd, Prev: 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: - - The function returns `nil'. - - Here are some cases for which it is preferable _not_ to use `@code': - - * For shell command names such as `ls' (use `@command'). - - * For shell options such as `-c' when such options stand alone (use - `@option'). - - * Also, an entire shell command often looks better if written using - `@samp' rather than `@code'. In this case, the rule is to choose - the more pleasing format. - - * For environment variable such as `TEXINPUTS' (use `@env'). - - * For a string of characters shorter than a syntactic token. For - example, if you are writing about `goto-ch', which is just a part - of the name for the `goto-char' Emacs Lisp function, you should use - `@samp'. - - * In general, when writing about the characters used in a token; for - example, do not use `@code' when you are explaining what letters - or printable symbols can be used in the names of functions. (Use - `@samp'.) Also, you should not use `@code' to mark text that is - considered input to programs unless the input is written in a - language that is like a programming language. For example, you - should not use `@code' for the keystroke commands of GNU Emacs (use - `@kbd' instead) although you may use `@code' for the names of the - Emacs Lisp functions that the keystroke commands invoke. - - - 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. - - Ordinarily, TeX will consider breaking lines at `-' and `_' -characters within `@code' and related commands. This can be controlled -with `@allowcodebreaks' (*note `@allowcodebreaks': allowcodebreaks.). - - -File: texinfo, Node: kbd, Next: key, Prev: 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 (*note 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.) - - -File: texinfo, Node: key, Next: samp, Prev: 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>' and `M-<TAB>' you would type: - - @kbd{C-x @key{ESC}} - @kbd{M-@key{TAB}} - - 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 - - DELETE - 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>. - - As a convention in GNU manuals, `@key' should not be used in index -entries. - - -File: texinfo, Node: samp, Next: verb, Prev: 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'. - - -File: texinfo, Node: verb, Next: var, Prev: 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. -In particular, it does not work to use `@verb' in anything related to -cross-referencing, such as section titles or figure captions. - - -File: texinfo, Node: var, Next: env, Prev: 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 (*note 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.) - - -File: texinfo, Node: env, Next: file, Prev: 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 ... - - -File: texinfo, Node: file, Next: command, Prev: 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. - - -File: texinfo, Node: command, Next: option, Prev: 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. - - -File: texinfo, Node: option, Next: dfn, Prev: 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. - - -File: texinfo, Node: dfn, Next: cite, Prev: 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. - - -File: texinfo, Node: cite, Next: abbr, Prev: 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. -*Note `@xref': xref. - - -File: texinfo, Node: abbr, Next: acronym, Prev: cite, Up: Indicating - -9.1.14 `@abbr'{ABBREVIATION[, MEANING]} ---------------------------------------- - -You can use the `@abbr' command for general abbreviations. The -abbreviation is given as the single argument in braces, as in -`@abbr{Comput.}'. As a matter of style, or for particular -abbreviations, you may prefer to omit periods, as in `@abbr{Mr} -Stallman'. - - `@abbr' accepts an optional second argument, intended to be used for -the meaning of the abbreviation. - - If the abbreviation ends with a lowercase letter and a period, and is -not at the end of a sentence, and has no second argument, remember to -use the `@.' command (*note Not Ending a Sentence::) to get the correct -spacing. However, you do not have to use `@.' within the abbreviation -itself; Texinfo automatically assumes periods within the abbreviation -do not end a sentence. - - In TeX and in the Info output, the first argument is printed as-is; -if the second argument is present, it is printed in parentheses after -the abbreviation. In HTML and XML, the `<abbr>' tag is used; in -Docbook, the `<abbrev>' tag is used. For instance: - - @abbr{Comput. J., Computer Journal} - -produces: - - Comput. J. (Computer Journal) - - For abbreviations consisting of all capital letters, you may prefer to -use the `@acronym' command instead. See the next section for more on -the usage of these two commands. - - -File: texinfo, Node: acronym, Next: indicateurl, Prev: abbr, Up: Indicating - -9.1.15 `@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 acronyms, you may prefer to use periods, as in -`@acronym{N.A.S.A.}'. - - `@acronym' accepts an optional second argument, intended to be used -for the meaning of the acronym. - - If the acronym is at the end of a sentence, and if there is no second -argument, remember to use the `@.' or similar command (*note Ending a -Sentence::) to get the correct spacing. - - In TeX, the acronym is printed in slightly smaller font. In the Info -output, the argument is printed as-is. In either format, if the second -argument is present, it is printed in parentheses after the acronym. -In HTML, Docbook, and XML, the `<acronym>' tag is used. - - 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 (*note Smallcaps::). - - `@abbr' and `@acronym' are closely related commands: they both signal -to the reader that a shortened form is being used, and possibly give a -meaning. When choosing whether to use these two commands, please bear -the following in mind. - - - In standard English usage, acronyms are a subset of abbreviations: - they include pronounceable words like `NATO', `radar', and - `snafu', and some sources also include syllable acronyms like - `Usenet', hybrids like `SIGGRAPH', and unpronounceable initialisms - like `FBI'. - - - In Texinfo, an acronym (but not an abbreviation) should consist - only of capital letters and periods, no lowercase. - - - In TeX, an acronym (but not an abbreviation) is printed in a - slightly smaller font. - - - Some browsers place a dotted bottom border under abbreviations but - not acronyms. - - - It's not essential to use these commands for all abbreviations. - Text is perfectly readable without them. - - - -File: texinfo, Node: indicateurl, Next: email, Prev: acronym, Up: Indicating - -9.1.16 `@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, *note `@uref': -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>. - - -File: texinfo, Node: email, Prev: indicateurl, Up: Indicating - -9.1.17 `@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 <bug-texinfo@gnu.org>. - - -File: texinfo, Node: Emphasis, Prev: 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. - -* Menu: - -* emph & strong:: How to emphasize text in Texinfo. -* Smallcaps:: How to use the small caps font. -* Fonts:: Various font commands for printed output. - - -File: texinfo, Node: emph & strong, Next: Smallcaps, 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 - `@quotation'--`Note' is allowable there. - - -File: texinfo, Node: Smallcaps, Next: Fonts, Prev: 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 acronyms -(*note 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. - - -File: texinfo, Node: Fonts, Prev: Smallcaps, Up: Emphasis - -9.2.3 Fonts for Printing, Not Info ----------------------------------- - -Texinfo provides one command to change the size of the main body font -in the TeX output for a document: `@fonttextsize'. It has no effect at -all in other output. It takes a single argument on the remainder of -the line, which must be either `10' or `11'. For example: - - @fonttextsize 10 - - The effect is to reduce the body font to a 10pt size (the default is -11pt). Fonts for other elements, such as sections and chapters, are -reduced accordingly. This should only be used in conjunction with -`@smallbook' (*note Printing "Small" Books: smallbook.) or similar, -since 10pt fonts on standard paper (8.5x11 or A4) are too small. One -reason to use this command is to save pages, and hence printing cost, -for physical books. - - Texinfo does not at present have commands to switch the font family -to use, or more general size-changing commands. - - Texinfo also provides a number of font commands that specify font -changes in the printed manual and (where possible) in the HTML output, -but have no effect in the Info file. All the commands apply to an -argument that follows, surrounded by braces. - -`@b' - selects bold face; - -`@i' - selects an italic font; - -`@r' - selects a roman font, which is the usual font in which text is - printed. It may or may not be seriffed. - -`@sansserif' - selects a sans serif font; - -`@slanted' - selects a slanted font; - -`@t' - selects the fixed-width, typewriter-style font used by `@code'; - - - (The commands with longer names were invented much later than the -others, at which time it did not seem desirable to use very short names -for such an infrequently needed feature.) - - 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 font commands. Some of -them are only useful when documenting functionality of specific font -effects, such as in TeX and related packages. - - -File: texinfo, Node: Quotations and Examples, Next: Lists and Tables, Prev: 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 the output. - - 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, and with only one -space between the `@end' and the `example'. - -* Menu: - -* Block Enclosing Commands:: Different constructs for different purposes. -* quotation:: Writing a quotation. -* example:: Writing an example in a fixed-width font. -* verbatim:: Writing a verbatim example. -* verbatiminclude:: Including a file verbatim. -* lisp:: Illustrating Lisp code. -* small:: Examples in a smaller font. -* display:: Writing an example in the current font. -* format:: Writing an example without narrowed margins. -* exdent:: Undo indentation on a line. -* flushleft & flushright:: Pushing text flush left or flush right. -* noindent:: Preventing paragraph indentation. -* indent:: Forcing paragraph indentation. -* cartouche:: Drawing rounded rectangles around examples. - - -File: texinfo, Node: Block Enclosing Commands, Next: quotation, 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. *Note Drawing Cartouches Around Examples: -cartouche. - - -File: texinfo, Node: quotation, Next: example, Prev: 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: - - * the margins are closer to the center of the page, so the whole of - the quotation is indented; - - * and the first lines of paragraphs are indented no more than other - lines. - - - 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>'. - - -File: texinfo, Node: example, Next: verbatim, Prev: 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: - - * Each line in the input file is a line in the output; that is, the - source text is not filled as it normally is. - - * Extra spaces and blank lines are significant. - - * The output is indented. - - * The output uses a fixed-width font. - - * Texinfo commands _are_ expanded; if you want the output to be the - input verbatim, use the `@verbatim' environment instead (*note - `@verbatim': verbatim.). - - 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 (*note -`@noindent': noindent. - - If you want to embed code fragments within sentences, instead of -displaying them, use the `@code' command or its relatives (*note -`@code': 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 (*note Fonts::). - - -File: texinfo, Node: verbatim, Next: verbatiminclude, Prev: 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 files in a Texinfo manual. - - In general, the output will be just the same as the input. No -character substitutions are made, e.g., all spaces and blank lines are -significant, including tabs. In the printed manual, the text is -typeset in a fixed-width font, and not indented or filled. - - 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 - - -This 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. - - You can get a "small" verbatim by enclosing the `@verbatim' in an -`@smallformat' environment, as shown here: - -@smallformat -@verbatim -... still verbatim, but in a smaller font ... -@end verbatim -@end smallformat - - - Finally, a word of warning: it is not reliable to use `@verbatim' -inside other Texinfo constructs. - - -File: texinfo, Node: verbatiminclude, Next: lisp, Prev: 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 (*note -`@verbatim': 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' (*note `@example': example.). - - The name of the file is taken literally, with a single exception: -`@value{VAR}' references are expanded. This makes it possible to -include files in other directories within a distribution, for instance: - - @verbatiminclude @value{top_srcdir}/NEWS - -(You still have to get `top_srcdir' defined in the first place.) - - For a method on printing the file contents in a smaller font size, see -the end of the previous section on `@verbatim'. - - -File: texinfo, Node: lisp, Next: small, Prev: 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.(1) - - Mark the end of `@lisp' with `@end lisp' on a line by itself. - - ---------- Footnotes ---------- - - (1) It would be straightforward to extend Texinfo to work in a -similar fashion for C, Fortran, or other languages. - - -File: texinfo, Node: small, Next: display, Prev: 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. - - -File: texinfo, Node: display, Next: format, Prev: small, Up: Quotations and Examples - -10.8 `@display' and `@smalldisplay' -=================================== - -The `@display' command begins a kind of example, where each line of -input produces a line of output, and the output is indented. It is -thus like the `@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. *Note -small::. - - The `@table' command (*note table::) does not work inside `@display'. -Since `@display' is line-oriented, it doesn't make sense to use them -together. If you want to indent a table, try `@quotation' (*note -quotation::). - - -File: texinfo, Node: format, Next: exdent, Prev: 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. *Note -small::. - - -File: texinfo, Node: exdent, Next: flushleft & flushright, Prev: 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 example - -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. - - -File: texinfo, Node: flushleft & flushright, Next: noindent, Prev: 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. - - -File: texinfo, Node: noindent, Next: indent, Prev: 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' (*note Paragraph Indenting: paragraphindent.). - - 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 -(*note Command Syntax::). - - -File: texinfo, Node: indent, Next: cartouche, Prev: 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 -(*note 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 (*note Command -Syntax::). - - -File: texinfo, Node: cartouche, Prev: 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' (*note group::). - - -File: texinfo, Node: Lists and Tables, Next: Special Displays, Prev: 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. - -* Menu: - -* Introducing Lists:: Texinfo formats lists for you. -* itemize:: How to construct a simple list. -* enumerate:: How to construct a numbered list. -* Two-column Tables:: How to construct a two-column table. -* Multi-column Tables:: How to construct generalized tables. - - -File: texinfo, Node: Introducing Lists, Next: itemize, 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: - - * Itemized lists with and without bullets. - - * Enumerated lists, using numbers or letters. - - * Two-column tables with highlighting. - - -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. - - -File: texinfo, Node: itemize, Next: enumerate, Prev: 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: - - * Some text for foo. - - * Some text for bar. - - 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: - - * First item. - - - Inner item. - - - Second inner item. - - * Second outer item. - - -File: texinfo, Node: enumerate, Next: Two-column Tables, Prev: itemize, Up: Lists and Tables - -11.3 `@enumerate': Making a Numbered or Lettered List -===================================================== - -`@enumerate' is like `@itemize' (*note `@itemize': 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: - - 3. Predisposing causes. - - 4. Precipitating causes. - - 5. Perpetuating causes. - - - Here is a brief summary of the alternatives. The summary is -constructed using `@enumerate' with an argument of `a'. - - a. `@enumerate' - - Without an argument, produce a numbered list, starting with the - number 1. - - b. `@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. - - c. `@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. - - d. `@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. - - -File: texinfo, Node: Two-column Tables, Next: Multi-column Tables, Prev: enumerate, Up: Lists and Tables - -11.4 Making a Two-column Table -============================== - -`@table' is similar to `@itemize' (*note `@itemize': 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. - -* Menu: - -* table:: How to construct a two-column table. -* ftable vtable:: Automatic indexing for two-column tables. -* itemx:: How to put more entries in the first column. - - -File: texinfo, Node: table, Next: ftable vtable, 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' (*note 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. (*Note `@itemx': itemx.) - - -File: texinfo, Node: ftable vtable, Next: itemx, Prev: 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. *Note 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. - - -File: texinfo, Node: itemx, Prev: 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.) - - -File: texinfo, Node: Multi-column Tables, Prev: 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. - -* Menu: - -* Multitable Column Widths:: Defining multitable column widths. -* Multitable Rows:: Defining multitable rows, with examples. - - -File: texinfo, Node: Multitable Column Widths, Next: Multitable Rows, 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. - - - -File: texinfo, Node: Multitable Rows, Prev: 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. In Info, the heading row is -followed by a separator line made of dashes (`-' characters). - - Here is a complete example of a multi-column table (the text is from -`The GNU Emacs Manual', *note Splitting Windows: (emacs)Split Window.): - - @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. - - -File: texinfo, Node: Special Displays, Next: Indices, Prev: 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. - -* Menu: - -* Floats:: Figures, tables, and the like. -* Images:: Including graphics and images. -* Footnotes:: Writing footnotes. - - -File: texinfo, Node: Floats, Next: Images, 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' (*note `@group': group.). - -* Menu: - -* float:: Producing floating material. -* caption shortcaption:: Specifying descriptions for floats. -* listoffloats:: A table of contents for floats. - - -File: texinfo, Node: float, Next: caption shortcaption, 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 (*note Images::), or `@multitable' to display a table (*note -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 - `@listoffloats' output (*note 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. - - -File: texinfo, Node: caption shortcaption, Next: listoffloats, Prev: 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. For -example: - - @float - ... as above ... - @shortcaption{Text for list of floats.} - @end float - - The text for `@caption' and `@shortcaption' may not contain comments -(`@c'), verbatim text (`@verb'), environments such as `@example', or -other complex constructs. - - -File: texinfo, Node: listoffloats, Prev: 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 (*note 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' (*note 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': - -* Menu: - -* Figure 12.1: fig:ex1. - - - 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 (*note 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. - - -File: texinfo, Node: Images, Next: Footnotes, Prev: 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. - -* Menu: - -* Image Syntax:: -* Image Scaling:: - - -File: texinfo, Node: Image Syntax, Next: Image Scaling, Up: Images - -12.2.1 Image Syntax -------------------- - -Here is the 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: - - * TeX reads the file `FILENAME.eps' (Encapsulated PostScript format). - - * pdfTeX reads `FILENAME.png', `FILENAME.jpg', `FILENAME.jpeg', or - `FILENAME.pdf' (in that order). It also tries uppercase versions - of the extensions. The PDF format cannot support EPS images, so - they must be converted first. - - * `makeinfo' includes `FILENAME.txt' verbatim for Info output (more - or less as if it was an `@example'). - - * `makeinfo' uses the optional fifth argument EXTENSION to `@image' - for the filename extension, if it is specified. For example: - - @image{foo,,,,.xpm} - - will cause `makeinfo' to look for `foo.xpm' before any others. - - - The WIDTH and HEIGHT arguments are described in the next section. - - For TeX output, if an image is the only thing in a paragraph it will -ordinarily be displayed on a line by itself, respecting the current -environment indentation, but without the normal paragraph indentation. -If you want it centered, use `@center' (*note `@titlefont @center @sp': -titlefont center sp.). - - For HTML output, `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. The ALTTEXT is taken as Texinfo text, so -special characters such as `"' and `<' and `&' are escaped in the HTML -and XML output; also, you can get an empty `alt' string with `@-' (a -command that produces no output; *note - and hyphenation::). - - For Info output, the `alt' string is also processed as Texinfo text -and output. In this case, `\' is escaped as `\\' and `"' as `\"'; no -other escapes are done. - - 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. - - 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. - - -File: texinfo, Node: Image Scaling, Prev: 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 - dido^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. - - -File: texinfo, Node: Footnotes, Prev: Images, Up: Special Displays - -12.3 Footnotes -============== - -A "footnote" is for a reference that documents or elucidates the -primary text.(1) Footnotes are distracting; use them sparingly, if at -all. Standard bibliographical references are better placed in a -bibliography at the end of a document than in footnotes throughout. - -* Menu: - -* Footnote Commands:: How to write a footnote in Texinfo. -* Footnote Styles:: Controlling how footnotes appear in Info. - - ---------- Footnotes ---------- - - (1) 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. - - -File: texinfo, Node: Footnote Commands, Next: Footnote Styles, 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 footnote(1); 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). *Note -Two-column Tables::. - - ---------- Footnotes ---------- - - (1) Here is the sample footnote. - - -File: texinfo, Node: Footnote Styles, Prev: Footnote Commands, Up: Footnotes - -12.3.2 Footnote Styles ----------------------- - -Info has two footnote styles, which determine where the text of the -footnote is located: - - * In the `End' node style, all the footnotes for a single node are - placed at the end of that node. The footnotes are separated from - the rest of the node by a line of dashes with the word `Footnotes' - within it. Each footnote begins with an `(N)' reference mark. - - Here is an example of a single footnote in the end of node style: - - --------- Footnotes --------- - - (1) Here is a sample footnote. - - * In the `Separate' node style, all the footnotes for a single node - are placed in an automatically constructed node of their own. In - this style, a "footnote reference" follows each `(N)' reference - mark in the body of the node. The footnote reference is actually - a cross reference which you use to reach the footnote node. - - The name of the node with the footnotes is constructed by - appending `-Footnotes' to the name of the node that contains the - footnotes. (Consequently, the footnotes' node for the `Footnotes' - node is `Footnotes-Footnotes'!) The footnotes' node has an `Up' - node pointer that leads back to its parent node. - - Here is how the first footnote in this manual looks after being - formatted for Info in the separate node style: - - File: texinfo.info Node: Overview-Footnotes, Up: Overview - - (1) The first syllable of "Texinfo" is pronounced like "speck", not - "hex". ... - - 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. - - -File: texinfo, Node: Indices, Next: Insertions, Prev: 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. - - *Note Printing Indices & Menus::, for information on how to print -indices. - -* Menu: - -* Index Entries:: Choose different words for index entries. -* Predefined Indices:: Use different indices for different kinds - of entries. -* Indexing Commands:: How to make an index entry. -* Combining Indices:: How to combine indices. -* New Indices:: How to define your own indices. - - -File: texinfo, Node: Index Entries, Next: Predefined Indices, 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. - - *Note Printing Indices & Menus::, for information about printing an -index at the end of a book or creating an index menu in an Info file. - - -File: texinfo, Node: Predefined Indices, Next: Indexing Commands, Prev: 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 (*note 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 -(*note Combining Indices::). - - -File: texinfo, Node: Indexing Commands, Next: Combining Indices, Prev: 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 (*note Marking -Text::), and `@r' for the normal roman font (*note 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. *Note Menu Parts::, for more - information about the structure of a menu entry. - - -File: texinfo, Node: Combining Indices, Next: New Indices, Prev: 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'. - -* Menu: - -* syncodeindex:: How to merge two indices, using `@code' - font for the merged-from index. -* synindex:: How to merge two indices, using the - default font of the merged-to index. - - -File: texinfo, Node: syncodeindex, Next: synindex, 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. - - -File: texinfo, Node: synindex, Prev: 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. - - *Note Printing Indices & Menus::, for information about printing an -index at the end of a book or creating an index menu in an Info file. - - -File: texinfo, Node: New Indices, Prev: 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 (*note Texinfo File Header::). - - -File: texinfo, Node: Insertions, Next: Breaks, Prev: 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. - -* Menu: - -* Atsign Braces Comma:: Inserting @ and {} and ,. -* Inserting Quote Characters:: Inserting left and right quotes, in code. -* Inserting Space:: How to insert the right amount of space - within a sentence. -* Inserting Accents:: How to insert accents and special characters. -* Inserting Quotation Marks:: How to insert quotation marks. -* Dots Bullets:: How to insert dots and bullets. -* TeX and copyright:: How to insert the TeX logo - and the copyright symbol. -* euro:: How to insert the Euro currency symbol. -* pounds:: How to insert the pounds currency symbol. -* textdegree:: How to insert the degrees symbol. -* minus:: How to insert a minus sign. -* geq leq:: How to insert greater/less-than-or-equal signs. -* math:: How to format a mathematical expression. -* Click Sequences:: Inserting GUI usage sequences. -* Glyphs:: How to indicate results of evaluation, - expansion of macros, errors, etc. - - -File: texinfo, Node: Atsign Braces Comma, Next: Inserting Quote Characters, 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. - -* Menu: - -* Inserting an Atsign:: -* Inserting Braces:: -* Inserting a Comma:: - - -File: texinfo, Node: Inserting an Atsign, Next: Inserting Braces, 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. - - -File: texinfo, Node: Inserting Braces, Next: Inserting a Comma, Prev: 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. - - -File: texinfo, Node: Inserting a Comma, Prev: 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' (*note acronym::) and -`@xref' (*note Cross References::), as well as user-defined macros -(*note Defining Macros::), can take more than one argument. In these -cases, the comma character is used to separate arguments. - - Since a comma character would confuse Texinfo's parsing for these -commands, you must use the command `@comma{}' instead if you want to -pass an actual comma. 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 nearly anywhere, there is no need for it -anywhere except in this unusual case. - - -File: texinfo, Node: Inserting Quote Characters, Next: Inserting Space, Prev: Atsign Braces Comma, Up: Insertions - -14.2 Inserting Quote Characters -=============================== - -As explained in the early section on general Texinfo input conventions -(*note Conventions::), Texinfo source files use the ASCII character ``' -(96 decimal) to produce a left quote (`), and ASCII `'' (39 decimal) to -produce a right quote ('). Doubling these input characters (```' and -`''') produces double quotes (" and "). These are the conventions used -by TeX. - - This works all right for text. However, in examples of computer code, -readers are especially likely to cut and paste the text verbatim--and, -unfortunately, some document viewers will mangle these characters. -(The free PDF reader `xpdf' works fine, but other PDF readers, both -free and nonfree, have problems.) - - If this is a concern for your document, Texinfo provides two special -settings via `@set': - -`@set txicodequoteundirected' - causes the output for the `'' character to be the undirected - single quote, like this: - - `''. - -`@set txicodequotebacktick' - Cause the output for the ``' character to be the standalone grave - accent, like this: - - ``'. - - - `xyza`'bc' - - If you want these settings for only part of the document, `@clear' -will restore the normal behavior, as in `@clear txicodequoteundirected'. - - These settings affect `@code', `@example', and `@verbatim'; they do -not affect `@samp'. (*Note Useful Highlighting::.) - - -File: texinfo, Node: Inserting Space, Next: Inserting Accents, Prev: Inserting Quote Characters, Up: Insertions - -14.3 Inserting Space -==================== - -The following sections describe commands that control spacing of various -kinds within and after sentences. - -* Menu: - -* Not Ending a Sentence:: Sometimes a . doesn't end a sentence. -* Ending a Sentence:: Sometimes it does. -* Multiple Spaces:: Inserting multiple spaces. -* frenchspacing:: Specifying end-of-sentence spacing. -* dmn:: How to format a dimension. - - -File: texinfo, Node: Not Ending a Sentence, Next: Ending a Sentence, Up: Inserting Space - -14.3.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, - - foo vs.@: bar - foo vs. bar - -produces - - foo vs. bar - foo vs. bar - -`@:' 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: `. ? ! :'. -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). - - -File: texinfo, Node: Ending a Sentence, Next: Multiple Spaces, Prev: Not Ending a Sentence, Up: Inserting Space - -14.3.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 (*note Sentences: -(emacs)Sentences.). - - Do not put braces after any of these commands. - - -File: texinfo, Node: Multiple Spaces, Next: frenchspacing, Prev: Ending a Sentence, Up: Inserting Space - -14.3.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' -(*note Multi-column Tables::). - - Do not follow any of these commands with braces. - - To produce a non-breakable space, see *note `@tie': tie. - - -File: texinfo, Node: frenchspacing, Next: dmn, Prev: Multiple Spaces, Up: Inserting Space - -14.3.4 `@frenchspacing' VAL: Control sentence spacing ------------------------------------------------------ - -In American typography, it is traditional and correct to put extra -space at the end of a sentence, after a semi-colon, and so on. This is -the default in Texinfo. In French typography (and many others), this -extra space is wrong; all spaces are uniform. - - Therefore Texinfo provides the `@frenchspacing' command to control -the spacing after punctuation. It reads the rest of the line as its -argument, which must be the single word `on' or `off' (always these -words, regardless of the language) of the document. Here is an example: - - @frenchspacing on - This is text. Two sentences. Three sentences. French spacing. - - @frenchspacing off - This is text. Two sentences. Three sentences. Non-French spacing. - -produces (there will be no difference in Info): - - This is text. Two sentences. Three sentences. French spacing. - - This is text. Two sentences. Three sentences. Non-French spacing. - - `@frenchspacing' mainly affects the printed output, including the -output after `@.', `@!', and `@?' (*note Ending a Sentence::). - - In Info, usually space characters in the input are written unaltered -to the output, and `@frenchspacing' does not change this. It does -change the one case where `makeinfo' outputs a space on its own: when a -sentence ends at a newline in the source. Here's an example: - - Some sentence. - Next sentence. - -produces in Info output, with `@frenchspacing off' (the default), two -spaces between the sentences: - - Some sentence. Next sentence. - -With `@frenchspacing on', `makeinfo' outputs only a single space: - - Some sentence. Next sentence. - - `@frenchspacing' has no effect on the HTML or Docbook output; for -XML, it outputs a transliteration of itself (*note Output Formats::). - - -File: texinfo, Node: dmn, Prev: frenchspacing, Up: Inserting Space - -14.3.5 `@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' (*note 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. *Note Not Ending a Sentence::. - - -File: texinfo, Node: Inserting Accents, Next: Inserting Quotation Marks, Prev: Inserting Space, Up: Insertions - -14.4 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, it is necessary to specify `@documentencoding' -with an encoding which supports the required characters (*note -`@documentencoding': documentencoding.). - -Command Output What ------------------------------------------------------- -@"o o" umlaut accent -@'o o' acute accent -@,{c} c, cedilla accent -@=o o= macron/overbar accent -@^o o^ circumflex accent -@`o o` grave accent -@~o 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{} aa AA a,A with circle -@ae{} @AE{} 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 O,o with slash -@oe{} @OE{} oe OE oe,OE ligatures -@ordf{} @ordm{} a o Spanish ordinals -@ss{} ss es-zet or sharp S - - -File: texinfo, Node: Inserting Quotation Marks, Next: Dots Bullets, Prev: Inserting Accents, Up: Insertions - -14.5 Inserting Quotation Marks -============================== - -Use doubled single-quote characters to begin and end quotations: -``...''. TeX converts two single quotes to left- and right-hand -doubled quotation marks, and Info converts doubled single-quote -characters to ASCII double-quotes: ``...'' becomes "...". - - You may occasionally need to produce two consecutive single quotes; -for example, in documenting a computer language such as Maxima where '' -is a valid command. You can do this with the input '@w{}'; the empty -`@w' command stops the combination into the double-quote characters. - - The left quote character (`, ASCII code 96) used in Texinfo is a -grave accent in ANSI and ISO character set standards. We use it as a -quote character because that is how TeX is set up, by default. - - Texinfo supports several other quotation marks used in languages other -than English. Below is a table with the commands Texinfo provides for -inserting quotation marks. - - In order to get the symbols for the quotation marks in encoded Info -output, it is necessary to specify `@documentencoding UTF-8'. (*Note -`@documentencoding': documentencoding.) Double guillemets are also -present in ISO 8859-1 (aka Latin 1) and ISO 8859-15 (aka Latin 9). - - The standard TeX fonts support the usual quotation marks used in -English (the ones produced with single and doubled ASCII -single-quotes). For the other quotation marks, TeX uses European -Computer Modern (EC) fonts (`ecrm1000' and other variants). These -fonts are freely available, of course; you can download them from -`http://www.ctan.org/tex-archive/fonts/ec', among other places. - - The free EC fonts are bitmap fonts created with Metafont. Especially -for on-line viewing, Type 1 (vector) versions of the fonts are -preferable; these are available in the CM-Super font package -(`http://www.ctan.org/tex-archive/fonts/ps-type1/cm-super'). - - Both distributions include installation instructions. - -Command Glyph Unicode name (point) ------------------------------------------------------------------------------------- -@quotedblleft{} `` " Left double quotation mark (U+201C) -@quotedblright{} '' " Right double quotation mark (U+201D) -@quoteleft{} ` ` Left single quotation mark (U+2018) -@quoteright{} ' ' Right single quotation mark (U+2019) -@quotedblbase{} " Double low-9 quotation mark (U+201E) -@quotesinglbase{} , Single low-9 quotation mark (U+201A) -@guillemetleft{} << Left-pointing double angle quotation mark (U+00AB) -@guillemetright{} >> Right-pointing double angle quotation mark (U+00BB) -@guilsinglleft{} < Single left-pointing angle quotation mark (U+2039) -@guilsinglright{} > Single right-pointing angle quotation mark (U+203A) - - For the double angle quotation marks, Adobe and LaTeX glyph names are -also supported: `@guillemotleft' and `@guillemotright'. These names -are actually incorrect; a "guillemot" is a bird species (a type of auk). - - Traditions for quotation mark usage vary to a great extent between -languages -(`http://en.wikipedia.org/wiki/Quotation_mark%2C_non-English_usage#Overview'). -Texinfo does not provide commands for typesetting quotation marks -according to the numerous traditions. Therefore, you have to choose -the commands appropriate for the language of your manual. Sometimes -aliases (*note `@alias': alias.) can simplify the usage and make the -source code more readable. For example, in German, `@quotedblbase' is -used for the left double quote, and the right double quote is actually -`@quotedblleft', which is counter-intuitive. Thus, in this case the -following aliases would be convenient: - - @alias lgqq = quotedblbase - @alias rgqq = quotedblleft - - -File: texinfo, Node: Dots Bullets, Next: TeX and copyright, Prev: Inserting Quotation Marks, Up: Insertions - -14.6 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. *Note @-Command Syntax: Command Syntax, for further -information.) - -* Menu: - -* dots:: How to insert dots ... -* bullet:: How to insert a bullet. - - -File: texinfo, Node: dots, Next: bullet, Up: Dots Bullets - -14.6.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. - - -File: texinfo, Node: bullet, Prev: dots, Up: Dots Bullets - -14.6.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. (*Note `@itemize': itemize.) - - -File: texinfo, Node: TeX and copyright, Next: euro, Prev: Dots Bullets, Up: Insertions - -14.7 Inserting TeX and Legal Symbols: (C), (R) -============================================== - -The logo `TeX' is typeset in a special fashion and it needs an -@-command. The copyright and registered symbols, `(C)' and `(R)', 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. - -* Menu: - -* tex:: The TeX logos. -* copyright symbol:: The copyright symbol (c in a circle). -* registered symbol:: The registered symbol (R in a circle). - - -File: texinfo, Node: tex, Next: copyright symbol, Up: TeX and copyright - -14.7.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. - - -File: texinfo, Node: copyright symbol, Next: registered symbol, Prev: tex, Up: TeX and copyright - -14.7.2 `@copyright{}' ((C)) ---------------------------- - -Use the `@copyright{}' command to generate the copyright symbol, `(C)'. -Where possible, this is a `c' inside a circle; in Info, this is `(C)'. - - -File: texinfo, Node: registered symbol, Prev: copyright symbol, Up: TeX and copyright - -14.7.3 `@registeredsymbol{}' ((R)) ----------------------------------- - -Use the `@registeredsymbol{}' command to generate the registered -symbol, `(R)'. Where possible, this is an `R' inside a circle; in -Info, this is `(R)'. - - -File: texinfo, Node: euro, Next: pounds, Prev: TeX and copyright, Up: Insertions - -14.8 `@euro'{} (Euro ): Euro Currency Symbol -============================================ - -Use the `@euro{}' command to generate `Euro '. Where possible, this is -the symbol for the Euro currency, invented as part of the European -economic unification. In plain Info, it is the word `Euro '. A -trailing space is included in the text transliteration since typically -no space is desired after the symbol, so it would be inappropriate to -have a space in the source document. - - Texinfo cannot magically synthesize support for the Euro symbol where -the underlying system (fonts, software, whatever) does not support it. -Therefore, in many cases it is preferable to use the word "Euro". (In -banking circles, the abbreviation for the Euro is EUR.) - - In order to get the Euro symbol in encoded Info output, for example, -it is necessary to specify `@documentencoding ISO-8859-15'. (*Note -`@documentencoding': documentencoding.) The Euro symbol is in ISO -8859-15 (aka Latin 9), and is _not_ in the more widely-used and -supported ISO 8859-1 (Latin 1). - - The Euro symbol does not exist in the standard TeX fonts (which were -designed before the Euro was legislated into existence). Therefore, -TeX uses an additional font, named `feymr10' (along with other -variables). It is freely available, of course; you can download it -from `http://www.ctan.org/tex-archive/fonts/eurosym', among other -places. The distribution includes installation instructions. - - -File: texinfo, Node: pounds, Next: textdegree, Prev: euro, Up: Insertions - -14.9 `@pounds'{} (#): Pounds Sterling -===================================== - -Use the `@pounds{}' command to generate `#'. Where possible, this is -the symbol for the currency pounds sterling. In Info, it is a `#'. - - -File: texinfo, Node: textdegree, Next: minus, Prev: pounds, Up: Insertions - -14.10 `@textdegree'{} (o): Degrees Symbol -========================================= - -Use the `@textdegree{}' command to generate `o'. Where possible, this -is the normal symbol for degrees. In plain text and Info output, it is -an `o'. - - -File: texinfo, Node: minus, Next: geq leq, Prev: textdegree, Up: Insertions - -14.11 `@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 (*note `@itemize': -itemize.). - - -File: texinfo, Node: geq leq, Next: math, Prev: minus, Up: Insertions - -14.12 `@geq{}' (>=) and `@leq{}' (<=): Inserting relations -========================================================== - -Use the `@geq{}' and `@geq{}' commands to generate -greater-than-or-equal and less-than-equal-signs, `>=' and `<='. In -plain text and Info output, these are the ASCII sequences `>=' and `<='. - - -File: texinfo, Node: math, Next: Click Sequences, Prev: geq leq, Up: Insertions - -14.13 `@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 - - The `@math' command has no special effect on the Info and HTML -output. `makeinfo' expands any `@'-commands as usual, but it does not -try to produce good mathematical formatting in any way. - - However, as far as the TeX output is concerned, plain TeX -mathematical commands are allowed in `@math', starting with `\', and -the plain TeX math characters like `^' and `_' are also recognized. In -essence, `@math' drops you into plain TeX math mode. - - This allows you to conveniently write superscripts and subscripts (as -in the above example), and also to use all the plain TeX math control -sequences for symbols, functions, and so on, and thus get proper -formatting in the TeX output, at least. - - It's best to use `\' instead of `@' for any such mathematical -commands; otherwise, `makeinfo' will complain. On the other hand, -input with matching (but unescaped) braces, such as `k_{75}', is -allowed inside `@math', although `makeinfo' would complain about the -bare braces in regular input. - - Here's an example: - - @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'd 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 (*note -Raw Formatter Commands::). - - -File: texinfo, Node: Click Sequences, Next: Glyphs, Prev: math, Up: Insertions - -14.14 Click Sequences -===================== - -When documenting graphical interfaces, it is necessary to describe -sequences such as `Click on `File', then choose `Open', then ...'. -Texinfo offers commands `@clicksequence' and `click' to represent this, -typically used like this: - - ... @clicksequence{File @click{} Open} ... - -which produces: - - ... File -> Open ... - - The `@click' command produces a simple right arrow (`->' in Info) by -default; this glyph is also available independently via the command -`@arrow{}'. - - You can change the glyph produced by `@click' with the command -`@clickstyle', which takes a command name as its single argument on the -rest of the line, much like `@itemize' and friends (*note `@itemize': -itemize.). The command should produce a glyph, and the usual empty -braces `{}' are omitted. Here's an example: - - @clickstyle @result - ... @clicksequence{File @click{} Open} ... - -now produces: - - ... File => Open ... - - -File: texinfo, Node: Glyphs, Prev: Click Sequences, Up: Insertions - -14.15 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. - -* Menu: - -* Glyphs Summary:: -* result:: How to show the result of expression. -* expansion:: How to indicate an expansion. -* Print Glyph:: How to indicate printed output. -* Error Glyph:: How to indicate an error message. -* Equivalence:: How to indicate equivalence. -* Point Glyph:: How to indicate the location of point. - - -File: texinfo, Node: Glyphs Summary, Next: result, Up: Glyphs - -14.15.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. - -* Menu: - -* result:: -* expansion:: -* Print Glyph:: -* Error Glyph:: -* Equivalence:: -* Point Glyph:: - - -File: texinfo, Node: result, Next: expansion, Prev: Glyphs Summary, Up: Glyphs - -14.15.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)'". - - -File: texinfo, Node: expansion, Next: Print Glyph, Prev: result, Up: Glyphs - -14.15.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. - - -File: texinfo, Node: Print Glyph, Next: Error Glyph, Prev: expansion, Up: Glyphs - -14.15.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 - - -File: texinfo, Node: Error Glyph, Next: Equivalence, Prev: Print Glyph, Up: Glyphs - -14.15.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. - - -File: texinfo, Node: Equivalence, Next: Point Glyph, Prev: Error Glyph, Up: Glyphs - -14.15.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)'. - - -File: texinfo, Node: Point Glyph, Prev: Equivalence, Up: Glyphs - -14.15.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 - - -File: texinfo, Node: Breaks, Next: Definition Commands, Prev: 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. - -* Menu: - -* Break Commands:: Summary of break-related commands. -* Line Breaks:: Forcing line breaks. -* - and hyphenation:: Helping TeX with hyphenation points. -* allowcodebreaks:: Controlling line breaks within @code text. -* w:: Preventing unwanted line breaks in text. -* tie:: Inserting an unbreakable but varying space. -* sp:: Inserting blank lines. -* page:: Forcing the start of a new page. -* group:: Preventing unwanted page breaks. -* need:: Another way to prevent unwanted page breaks. - - -File: texinfo, Node: Break Commands, Next: Line Breaks, 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. - - -File: texinfo, Node: Line Breaks, Next: - and hyphenation, Prev: 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 (*note `@uref': 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. - - -File: texinfo, Node: - and hyphenation, Next: allowcodebreaks, Prev: 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 (*note - 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, such as plurals. - - Info, HTML, and other non-TeX output is not hyphenated, so none of -these commands have any effect there. - - -File: texinfo, Node: allowcodebreaks, Next: w, Prev: - and hyphenation, Up: Breaks - -15.4 `@allowcodebreaks': Control Line Breaks in `@code' -======================================================= - -Ordinarily, TeX will consider breaking lines at `-' and `_' characters -within `@code' and related commands (*note `@code': code.), more or -less as if they were "empty" hyphenation points. - - This is necessary as many manuals, especially for Lisp-family -languages, must document very long identifiers. On the other hand, -other manuals don't have this problems, and you may not wish to allow a -line break at the underscore in, for example, `SIZE_MAX', or even -worse, after any of the four underscores in `__typeof__'. - - So Texinfo provides this command: - - @allowcodebreaks false - -to prevent TeX from breaking at `-' or `_' within `@code'. You can go -back to allowing such breaks with `@allowcodebreaks true'. Write these -commands on lines by themselves. - - These commands can be given anywhere in the document. For example, -you may have just one problematic paragraph where you need to turn off -the breaks, but want them in general, or vice versa. - - This command has no effect in Info, HTML, and other non-TeX output. - - -File: texinfo, Node: w, Next: tie, Prev: allowcodebreaks, Up: Breaks - -15.5 `@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 manual indenting. 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$'. - - -File: texinfo, Node: tie, Next: sp, Prev: w, Up: Breaks - -15.6 `@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{ }': - - * The space produced by `@tie{}' will stretch and shrink slightly - along with the normal interword spaces in the paragraph; the space - produced by `@w{ }' will not vary. - - * `@tie{}' allows hyphenation of the surrounding words, while - `@w{ }' inhibits hyphenation of those words (for TeXnical reasons, - namely that it produces an `\hbox'). - - - -File: texinfo, Node: sp, Next: page, Prev: tie, Up: Breaks - -15.7 `@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. - - -File: texinfo, Node: page, Next: group, Prev: sp, Up: Breaks - -15.8 `@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. - - -File: texinfo, Node: group, Next: need, Prev: page, Up: Breaks - -15.9 `@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'. *Note 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. - - -File: texinfo, Node: need, Prev: group, Up: Breaks - -15.10 `@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). - - -File: texinfo, Node: Definition Commands, Next: Conditionals, Prev: 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 (*note 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. - -* Menu: - -* Def Cmd Template:: Writing descriptions using definition commands. -* Def Cmd Continuation Lines:: Continuing the heading over source lines. -* Optional Arguments:: Handling optional and repeated arguments. -* deffnx:: Group two or more `first' lines. -* Def Cmds in Detail:: Reference for all the definition commands. -* Def Cmd Conventions:: Conventions for writing definitions. -* Sample Function Definition:: An example. - - -File: texinfo, Node: Def Cmd Template, Next: Def Cmd Continuation Lines, 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 command 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. This may also be necessary if the text contains commands, -for example, `{declaraci@'on}' if you are writing in Spanish. - - 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. - - *Note 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. - - -File: texinfo, Node: Def Cmd Continuation Lines, Next: Optional Arguments, Prev: 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 -(*note Multiple Spaces::). - - -File: texinfo, Node: Optional Arguments, Next: deffnx, Prev: 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'. - - -File: texinfo, Node: deffnx, Next: Def Cmds in Detail, Prev: 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' (*note itemx::). - - -File: texinfo, Node: Def Cmds in Detail, Next: Def Cmd Conventions, Prev: 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. - -* Menu: - -* Functions Commands:: Commands for functions and similar entities. -* Variables Commands:: Commands for variables and similar entities. -* Typed Functions:: Commands for functions in typed languages. -* Typed Variables:: Commands for variables in typed languages. -* Data Types:: The definition command for data types. -* Abstract Objects:: Commands for object-oriented programming. - - -File: texinfo, Node: Functions Commands, Next: Variables Commands, 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 (*note - 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, - *note Special Forms: (elisp)Special Forms.) `@defspec' is - equivalent to `@deffn {Special Form} ...' and works like `@defun'. - - All these commands create entries in the index of functions. - - -File: texinfo, Node: Variables Commands, Next: Typed Functions, Prev: 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 (*note Variables: (emacs)Variables.). - `@defopt' is equivalent to `@defvr {User Option} ...' and works - like `@defvar'. It creates an entry in the index of variables. - - -File: texinfo, Node: Typed Functions, Next: Typed Variables, Prev: 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 (*note - 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. - - - -File: texinfo, Node: Typed Variables, Next: Data Types, Prev: 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. *Note 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. - - -File: texinfo, Node: Data Types, Next: Abstract Objects, Prev: 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. - - -File: texinfo, Node: Abstract Objects, Prev: 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. - -* Menu: - -* Variables: Object-Oriented Variables. -* Methods: Object-Oriented Methods. - - -File: texinfo, Node: Object-Oriented Variables, Next: Object-Oriented Methods, 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. - - - -File: texinfo, Node: Object-Oriented Methods, Prev: 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. - - - -File: texinfo, Node: Def Cmd Conventions, Next: Sample Function Definition, Prev: 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. - - -File: texinfo, Node: Sample Function Definition, Prev: 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 *note Calling Functions: (elisp)Calling -Functions. - - -- 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. - - -File: texinfo, Node: Conditionals, Next: Internationalization, Prev: 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. - - * Commands specific to an output format (Info, TeX, HTML, ...). - - * Commands specific to any output format _other_ than a given one - (not Info, not TeX, ...). - - * `Raw' formatter text for any output format, passed straight - through with no interpretation of @-commands. - - * Format-independent variable substitutions, and testing if a - variable is set or clear. - - -* Menu: - -* Conditional Commands:: Text for a given format. -* Conditional Not Commands:: Text for any format other than a given one. -* Raw Formatter Commands:: Using raw formatter commands. -* set clear value:: Variable tests and substitutions. -* Conditional Nesting:: Using conditionals inside conditionals. - - -File: texinfo, Node: Conditional Commands, Next: Conditional Not Commands, 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: - - However, this text will appear only in Info and plain text. - -Notice that you only see one of the input lines, depending on which -version of the manual you are reading. - - -File: texinfo, Node: Conditional Not Commands, Next: Raw Formatter Commands, Prev: 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' (*note Raw -Formatter Commands::). - - -File: texinfo, Node: Raw Formatter Commands, Next: set clear value, Prev: 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. - - -File: texinfo, Node: set clear value, Next: Conditional Nesting, Prev: 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 specified. - -`@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. - -* Menu: - -* set value:: Expand a flag variable to a string. -* ifset ifclear:: Format a region if a flag is set. -* value Example:: An easy way to update edition information. - - -File: texinfo, Node: set value, Next: ifset ifclear, 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. - - -File: texinfo, Node: ifset ifclear, Next: value Example, Prev: 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 - - -File: texinfo, Node: value Example, Prev: 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. *Note GNU Sample -Texts::, for the full text of an example of using this to work with -Automake distributions. - - This example is adapted from *note Overview: (make)Top. - - 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 (*note 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. - - -File: texinfo, Node: Conditional Nesting, Prev: 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. - - -File: texinfo, Node: Internationalization, Next: Defining New Texinfo Commands, Prev: 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 *note Inserting Accents::. - -* Menu: - -* documentlanguage:: Declaring the current language. -* documentencoding:: Declaring the input encoding. - - -File: texinfo, Node: documentlanguage, Next: documentencoding, Up: Internationalization - -18.1 `@documentlanguage LL[_CC]': Set the Document Language -=========================================================== - -The `@documentlanguage' command declares the current document locale. -Write it on a line by itself, near the beginning of the file, but after -`@setfilename' (*note `@setfilename': setfilename.). - - Include a two-letter ISO 639-2 language code (LL) following the -command name, optionally followed by a two-letter ISO 3166 two-letter -country code (CC). 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_US' for -US English. - - As with GNU Gettext (*note Top: (gettext)Top.), if the country code -is omitted, the main dialect is assumed where possible. For example, -`de' is equivalent to `de_DE' (German as spoken in Germany). - - For Info and other online output, this command changes the translation -of various "document strings" such as "see" in cross-references (*note -Cross References::), "Function' in defuns (*note Definition -Commands::), and so on. Some strings, such as "Node:", "Next:", -"Menu:", etc., are keywords in Info output, so are not translated -there; they are translated in other output formats. - - For TeX, this command causes a file `txi-LOCALE.tex' to be read (if -it exists). If `@setdocumentlanguage' argument contains the optional -`_CC' suffix, this is tried first. For example, with -`@setdocumentlanguage de_DE', TeX first looks for `txi-de_DE.tex', then -`txi-de.tex'. - - Such a `txi-*' file is intended to redefine the various English words -used in TeX output, such as `Chapter', `See', and so on. We are aware -that individual words like these cannot always be translated in -isolation, and that a very different strategy would be required for -ideographic (among other) scripts. Help in improving Texinfo's -language support is welcome. - - It would also be desirable for this command to also change TeX's -ideas of the current hyphenation patterns (via the TeX primitive -`\language'), but this is unfortunately not currently implemented. - - In September 2006, the W3C Internationalization Activity released a -new recommendation for specifying tags identifying language: - `http://www.rfc-editor.org/rfc/bcp/bcp47.txt' - When Gettext supports this new scheme, Texinfo will too. - - Since the lists of language codes and country codes are quite dynamic, -we don't attempt to list them here. The valid language codes are on -the official home page for ISO 639, -`http://www.loc.gov/standards/iso639-2/'. The country codes and the -official web site for ISO 3166 can be found via -`http://en.wikipedia.org/wiki/ISO_3166'. - - -File: texinfo, Node: documentencoding, Prev: 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, near the beginning of the file but after `@setfilename' -(*note `@setfilename': setfilename.). - - At present, Texinfo supports only these encodings: - -`US-ASCII' - This has no particular effect, but it's included for completeness. - -`UTF-8' - The vast global character encoding, expressed in 8-bit bytes. The - Texinfo processors have no deep knowledge of Unicode; for the most - part, they just pass along the input they are given to the output. - -`ISO-8859-1' -`ISO-8859-15' - -`ISO-8859-2' - These specify the standard encodings for Western European (the - first two) and Eastern European languages (the third), - respectively. ISO 8859-15 replaces some little-used characters - from 8859-1 (e.g., precomposed fractions) with more commonly - needed ones, such as the Euro symbol (Euro ). - - A full description of the encodings is beyond our scope here; one - useful reference is `http://czyborra.com/charsets/iso8859.html'. - -`koi8-r' - This is the commonly used encoding for the Russian language. - -`koi8-u' - This is the commonly used encoding for the Ukrainian language. - - - Specifying an encoding ENC has the following effects: - - In Info output, unless the option `--disable-encoding' is given to -`makeinfo', a so-called `Local Variables' section (*note File -Variables: (emacs)File Variables.) is output including ENC. This -allows Info readers to set the encoding appropriately. - - Local Variables: - coding: ENC - End: - - Also, in Info and plain text output (barring `--disable-encoding'), -accent constructs and special characters, such as `@'e', are output as -the actual 8-bit character in the given encoding. - - 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, if supported by the system. - - <meta http-equiv="Content-Type" content="text/html; - charset=ENC"> - - In split HTML output, if `--transliterate-file-names' is given (*note -HTML Xref 8-bit Character Expansion::), the names of HTML files are -formed by transliteration of the corresponding node names, using the -specified encoding. - - In XML and Docbook output, the given document encoding is written in -the output file as usual with those formats. - - In TeX output, the characters which are supported in the standard -Computer Modern fonts are output accordingly. (For example, this means -using constructed accents rather than precomposed glyphs.) Using a -missing character generates a warning message, as does specifying an -unimplemented encoding. - - -File: texinfo, Node: Defining New Texinfo Commands, Next: Hardcopy, Prev: Internationalization, Up: Top - -19 Defining New Texinfo Commands -******************************** - -Texinfo provides several ways to define new commands: - - * A Texinfo "macro" allows you to define a new Texinfo command as any - sequence of text and/or existing commands (including other - macros). The macro can have any number of "parameters"--text you - supply each time you use the macro. - - Incidentally, these macros have nothing to do with the `@defmac' - command, which is for documenting macros in the subject of the - manual (*note Def Cmd Template::). - - * `@alias' is a convenient way to define a new name for an existing - command. - - * `@definfoenclose' allows you to define new commands with - customized output in the Info file. - - -* Menu: - -* Defining Macros:: Defining and undefining new commands. -* Invoking Macros:: Using a macro, once you've defined it. -* Macro Details:: Limitations of Texinfo macros. -* alias:: Command aliases. -* definfoenclose:: Customized highlighting. - - -File: texinfo, Node: Defining Macros, Next: Invoking Macros, 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 (*note -`@math': 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 - - -File: texinfo, Node: Invoking Macros, Next: Macro Details, Prev: 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. - - Passing strings containing commas as macro arguments requires special -care, since they should be properly "quoted" to prevent `makeinfo' from -confusing them with argument separators. To manually quote a comma, -prepend it with a backslash character, like this: `\,'. Alternatively, -use the `@comma' command (*note Inserting a Comma::). However, to -facilitate use of macros, `makeinfo' implements a set of rules called -"automatic quoting": - - 1. If a macro takes only one argument, all commas in its invocation - are quoted by default. For example: - - @macro FIXME{text} - @strong{FIXME: \text\} - @end macro - - @FIXME{A nice feature, though it can be dangerous.} - - will produce the following output - - *FIXME: A nice feature, though it can be dangerous.* - - And indeed, it can. Namely, `makeinfo' does not control number of - arguments passed to one-argument macros, so be careful when you - invoke them. - - 2. If a macro invocation includes another command (including a - recursive invocation of itself), any commas in the nested command - invocation(s) are quoted by default. For example, in - - @say{@strong{Yes, I do}, person one} - - the comma after `Yes' is implicitly quoted. Here's another - example, with a recursive macro: - - @rmacro cat{a,b} - \a\\b\ - @end rmacro - - @cat{@cat{foo, bar}, baz} - - will produce the string `foobarbaz'. - - 3. Otherwise, a comma should be explicitly quoted, as above, to be - treated as a part of an argument. - - Other characters that need to be quoted in macro arguments are curly -braces and backslash. For example - - @MACNAME {\\\{\}\,} - -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. - - -File: texinfo, Node: Macro Details, Next: alias, Prev: Invoking Macros, Up: Defining New Texinfo Commands - -19.3 Macro Details and Caveats -============================== - -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 (*note Format with -texi2dvi::). - - * As mentioned earlier, macro names must consist entirely of letters. - - * It is not advisable to redefine any TeX primitive, plain, or - Texinfo command name as a macro. Unfortunately this is a very large - set of names, and the possible resulting errors are unpredictable. - - * All macros are expanded inside at least one TeX group. This means - that `@set' and other such commands have no effect inside a macro. - - * Commas in macro arguments, even if escaped by a backslash, don't - always work. - - * Macro arguments cannot cross lines. - - * It is (usually) best to avoid comments inside macro definitions, - but see the next item. - - * Macros containing a command which must be on a line by itself, - such as a conditional, cannot be invoked in the middle of a line. - In general, the interaction of newlines in the macro definitions - and invocations depends on the precise commands and context. You - may be able to work around some problems with judicious use of - `@c'. Suppose you define a macro that is always intended to be - used on a line by itself: - - @macro linemac - @cindex whatever - @c - @end macro - ... - foo - @linemac - bar - - Without the `@c', there will be an unwanted blank line between the - `@cindex whatever' and the `bar' (one newline comes from the macro - definition, one from after the invocation), causing a paragraph - break. - - On the other hand, you wouldn't want the `@c' if the macro was - sometimes invoked in the middle of a line (the text after the - invocation would be treated as a comment). - - * In general, you can't arbitrarily substitute a macro call for - Texinfo command arguments, even when the text is the same. It - might work with some commands, it fails with others. Best not to - do it at all. For instance, this fails: - - @macro offmacro - off - @end macro - @headings @offmacro - - You would expect this to be equivalent to `@headings off', but for - TeXnical reasons, it fails with a mysterious error message - (`Paragraph ended before @headings was complete'). - - * Macros cannot define macros in the natural way. To do this, you - must use conditionals and raw TeX. For example: - - @ifnottex - @macro ctor {name, arg} - @macro \name\ - something involving \arg\ somehow - @end macro - @end macro - @end ifnottex - @tex - \gdef\ctor#1{\ctorx#1,} - \gdef\ctorx#1,#2,{\def#1{something involving #2 somehow}} - @end tex - - - The `makeinfo' implementation also has limitations: - - * `@verbatim' and macros do not mix; for instance, you can't start a - verbatim block inside a macro and end it outside. (*Note - verbatim::.) Starting any environment inside a macro and ending - it outside may or may not work, for that matter. - - * Macros that completely define macros are ok, but it's not possible - to have incorrectly nested macro definitions. That is, `@macro' - and `@end macro' (likewise for `@rmacro') must be correctly - paired. For example, you cannot start a macro definition within a - macro, and then end the nested definition outside the macro. - - * `@rmacro' is a kludge. - - - 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). - - -File: texinfo, Node: alias, Next: definfoenclose, Prev: 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. - - -File: texinfo, Node: definfoenclose, Prev: 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 predefined 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 (*note 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. - - -File: texinfo, Node: Hardcopy, Next: Creating and Installing Info Files, Prev: 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. - -* Menu: - -* Use TeX:: Use TeX to format for hardcopy. -* Format with tex/texindex:: How to format with explicit shell commands. -* Format with texi2dvi:: A simpler way to format. -* Print with lpr:: How to print. -* Within Emacs:: How to format and print from an Emacs shell. -* Texinfo Mode Printing:: How to format and print in Texinfo mode. -* Compile-Command:: How to print using Emacs's compile command. -* Requirements Summary:: TeX formatting requirements summary. -* Preparing for TeX:: What to do before you use TeX. -* Overfull hboxes:: What are and what to do with overfull hboxes. -* smallbook:: How to print small format books and manuals. -* A4 Paper:: How to print on A4 or A5 paper. -* pagesizes:: How to print with customized page sizes. -* Cropmarks and Magnification:: How to print marks to indicate the size - of pages and how to print scaled up output. -* PDF Output:: Portable Document Format output. -* Obtaining TeX:: How to Obtain TeX. - - -File: texinfo, Node: Use TeX, Next: Format with tex/texindex, 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. (*Note How to Obtain TeX: -Obtaining 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 (*note Creating an Info File::). - - -File: texinfo, Node: Format with tex/texindex, Next: Format with texi2dvi, Prev: 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. 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.) (`texi2dvi' runs `tex' and `texindex' as necessary.) - - 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, *note tex invocation: (web2c)tex invocation.) -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 (*note 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' (*note 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 (*note `@setfilename': 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 (*note Pointer Validation::). - - -File: texinfo, Node: Format with texi2dvi, Next: Print with lpr, Prev: 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 `tex'--`texindex'--`tex'--`tex' 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. - - One 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' (*note smallbook::), -`@afourpaper' (*note A4 Paper::), or `@pagesizes' (*note pagesizes::), -without actually changing the document source. (You can also do this -on a site-wide basis with `texinfo.cnf'; *note Preparing for TeX: -Preparing for TeX.). - - With the `--pdf' option, `texi2dvi' produces PDF output instead of -DVI (*note PDF Output::), by running `pdftex' instead of `tex'. -Alternatively, the command `texi2pdf' is an abbreviation for running -`texi2dvi --pdf'. The command `pdftexi2dvi' is also supported as a -convenience to AUC-TeX users, since the latter merely prepends `pdf' to -DVI producing tools to have PDF producing tools. - - `texi2dvi' can also be used to process LaTeX files; simply run -`texi2dvi filename.ext'. - - Normally `texi2dvi' is able to guess the input file language by its -contents and file name suffix. If, however, it fails to do so you can -specify the input language using `--language=LANG' command line option, -where LANG is either `latex' or `texinfo'. - - `texi2dvi' will use `etex' (or `pdfetex') if they are available; -these extended versions of TeX are not required, and the DVI (or PDF) -output is identical, but they simplify the TeX programming in some -cases, and provide additional tracing information when debugging -`texinfo.tex'. - - Several options are provided for handling documents, written in -character sets other than ASCII. The `--translate-file=FILE' option -instructs `texi2dv' to translate input into internal TeX character set -using "translation file" FILE (*note TCX files: (web2c)TCX files.). - - The options `--recode' and `--recode-from=ENC' allow conversion of an -input document before running TeX. The `--recode' option recodes the -document from encoding specified by `@documentencoding' command (*note -`documentencoding': documentencoding.) to plain 7-bit `texinfo' -encoding. - - The option `--recode-from=ENC' recodes the document from ENC encoding -to the encoding specified by `@documentencoding'. This is useful, for -example, if the document is written in `UTF-8' encoding and an -equivalent 8-bit encoding is supported by `makeinfo'. - - Both `--recode' and `--recode-from=ENC' use `recode' utility to -perform the conversion. If `recode' fails to process the file, -`texi2dvi' prints a warning and continues using unmodified input file. - - For a list of other options, run `texi2dvi --help'. - - -File: texinfo, Node: Print with lpr, Next: Within Emacs, Prev: 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: - - * Find and install a Unix-like `lpr' program, or its clone. If you - can do that, you will be able to print DVI files just like - described above. - - * Send the DVI files to a network printer queue for DVI files. Some - network printers have special queues for printing DVI files. You - should be able to set up your network software to send files to - that queue. In some cases, the version of `lpr' which comes with - your network software will have a special option to send a file to - specific queues, like this: - - lpr -Qdvi -hprint.server.domain bison.dvi - - * Convert the DVI file to a Postscript or PCL file and send it to - your local printer. *Note Invoking Dvips: (dvips)Invoking Dvips, - and the man pages for `dvilj', for detailed description of these - tools. Once the DVI file is converted to the format your local - printer understands directly, just send it to the appropriate - port, usually `PRN'. - - -File: texinfo, Node: Within Emacs, Next: Texinfo Mode Printing, Prev: 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. *Note Format and Print -Hardcopy: 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. - - -File: texinfo, Node: Texinfo Mode Printing, Next: Compile-Command, Prev: 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 (*note Examining and Setting Variables: -(emacs)Examining.), or with your `.emacs' initialization file (*note -Init File: (emacs)Init File.). - - Beginning with version 20, GNU Emacs offers a user-friendly interface, -called "Customize", for changing values of user-definable variables. -*Note Easy Customization Interface: (emacs)Easy Customization, 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. - - -File: texinfo, Node: Compile-Command, Next: Requirements Summary, Prev: 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 *note Compilation: (emacs)Compilation. - - -File: texinfo, Node: Requirements Summary, Next: Preparing for TeX, Prev: 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: - - * *note `@settitle': settitle. - - * *note `@setchapternewpage': setchapternewpage. - - * *note Page Headings: Headings. - - * *note Titlepage & Copyright Page::. - - * *note Printing Indices & Menus::. - - * *note Contents::. - - -File: texinfo, Node: Preparing for TeX, Next: Overfull hboxes, Prev: 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 (*note Images::). - - To be able to use quotation marks other than those used in English -you'll need to install European Computer Modern fonts and optionally -CM-Super fonts, unless they are already installed (*note Inserting -Quotation Marks::). - - If you intend to use the `@euro' command, you should install the Euro -font, if it is not already installed. *Note euro::. - - 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 (*note `@setfilename': 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' (*note 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 this(1): - - 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 (*note Memory dumps: -(web2c)Memory dumps.) 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. - - ---------- Footnotes ---------- - - (1) Note the use of the `;' character, instead of `:', as directory -separator on these systems. - - -File: texinfo, Node: Overfull hboxes, Next: smallbook, Prev: 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. *Note Catching Errors with TeX Formatting: -Debugging with TeX, 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 - - -File: texinfo, Node: smallbook, Next: A4 Paper, Prev: 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 -(*note Start of Header::). - - *Note small::, for information about commands that make it easier to -produce examples for a smaller manual. - - *Note Format with texi2dvi::, and *note Preparing for TeX: Preparing -for TeX, for other ways to format with `@smallbook' that do not require -changing the source file. - - -File: texinfo, Node: A4 Paper, Next: pagesizes, Prev: 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 - - *Note Format with texi2dvi::, and *note Preparing for TeX: 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. - - -File: texinfo, Node: pagesizes, Next: Cropmarks and Magnification, Prev: 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', *note Preparing for TeX: Preparing for TeX.). - - *Note Format with texi2dvi::, and *note Preparing for TeX: Preparing -for TeX, for other ways to specify `@pagesizes' that do not require -changing the source file. - - `@pagesizes' is ignored by `makeinfo'. - - -File: texinfo, Node: Cropmarks and Magnification, Next: PDF Output, Prev: 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' (*note 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. - - -File: texinfo, Node: PDF Output, Next: Obtaining TeX, Prev: Cropmarks and Magnification, Up: Hardcopy - -20.15 PDF Output -================ - -The simplest way to generate PDF output from Texinfo source is to run -the convenience script `texi2pdf' (or `pdftexi2dvi'); this simply -executes the `texi2dvi' script with the `--pdf' option (*note Format -with texi2dvi::). If for some reason you want to process the document -by hand, simply run the `pdftex' program instead of plain `tex'. That -is, run `pdftex foo.texi' instead of `tex foo.texi'. - - "PDF" stands for `Portable Document Format'. It was invented by Adobe -Systems some years ago for document interchange, based on their -PostScript language. Related links: - - * GNU GV, a Ghostscript-based PDF reader - (http://www.foolabs.com/xpdf/). (It can also preview PostScript - documents.) - - * A freely available standalone PDF reader - (http://www.foolabs.com/xpdf/) for the X window system. - - * PDF definition - (http://partners.adobe.com/asn/acrobat/sdk/public/docs/). - - - At present, Texinfo does not provide `@ifpdf' or `@pdf' commands as -for the other output formats, since PDF documents contain many internal -links that would be hard or impossible to get right at the Texinfo -source level. - - PDF files require special software to be displayed, unlike the plain -ASCII formats (Info, HTML) that Texinfo supports. They also tend to be -much larger than the DVI files output by TeX by default. Nevertheless, -a PDF file does define an actual typeset document in a self-contained -file, so it has its place. - - -File: texinfo, Node: Obtaining TeX, Prev: 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. - 51 Franklin St, Fifth Floor - Boston, MA 02110-1301 - 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/'. - - -File: texinfo, Node: Creating and Installing Info Files, Next: Generating HTML, Prev: Hardcopy, Up: Top - -21 Creating and Installing Info Files -************************************* - -This chapter describes how to create and install Info files. *Note -Info Files::, for general information about the file format itself. - -* Menu: - -* Creating an Info File:: -* Installing an Info File:: - - -File: texinfo, Node: Creating an Info File, Next: Installing an Info File, 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, *note -Installing an Info File::. - -* Menu: - -* makeinfo advantages:: `makeinfo' provides better error checking. -* Invoking makeinfo:: How to run `makeinfo' from a shell. -* makeinfo options:: Specify fill-column and other options. -* Pointer Validation:: How to check that pointers point somewhere. -* makeinfo in Emacs:: How to run `makeinfo' from Emacs. -* texinfo-format commands:: Two Info formatting commands written - in Emacs Lisp are an alternative - to `makeinfo'. -* Batch Formatting:: How to format for Info in Emacs Batch mode. -* Tag and Split Files:: How tagged and split files help Info - to run better. - - -File: texinfo, Node: makeinfo advantages, Next: Invoking makeinfo, 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'. - - -File: texinfo, Node: Invoking makeinfo, Next: makeinfo options, Prev: 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. - - -File: texinfo, Node: makeinfo options, Next: Pointer Validation, Prev: 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 (*note 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. *Note 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. - *Note HTML CSS::. If FILE is `-', read standard input. - -`--css-ref=URL' - In HTML mode, add a `<link>' tag to the HTML output which - references a cascading style sheet at URL. This allows using - standalone style sheets. - -`--disable-encoding' -`--enable-encoding' - By default, or with `--enable-encoding', output accented and - special characters in Info or plain text output based on - `@documentencoding'. With `--disable-encoding', 7-bit ASCII - transliterations are output. *Note `documentencoding': - documentencoding, and *note Inserting Accents::. - -`--docbook' - Generate Docbook output rather than Info. - -`--document-language=LANG' - Use LANG to translate Texinfo keywords which end up in the output - document. The default is the locale specified by the - `@documentlanguage' command if there is one (*note - documentlanguage::). - -`--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 (*note 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. *Note 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. - -`--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' - -`--plaintext' - 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). *Note 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, and do process - `@ifnotFORMAT', even if generating the given format. For - instance, if `--no-ifhtml' is specified, then `@ifhtml' and - `@html' blocks will not be read, and `@ifnothtml' blocks will be. - -`--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. - -`--no-number-sections' - Do not output chapter, section, and appendix numbers. You need to - specify this if your manual is not hierarchically-structured. - -`--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 (*note - Generating HTML::). - -`--no-pointer-validate' -`--no-validate' - Suppress the pointer-validation phase of `makeinfo'--a dangerous - thing to do. This can also be done with the `@novalidate' command - (*note Use TeX: Use TeX.). Normally, after a Texinfo file is - processed, some consistency checks are made to ensure that cross - references can be resolved, etc. *Note Pointer Validation::. - -`--no-warn' - Suppress warning messages (but _not_ error messages). - -`--number-sections' - Output chapter, section, and appendix numbers as in printed - manuals. This is the default. It works only with - hierarchically-structured manuals. - -`--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 (*note 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 (*note 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 (*note 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. - -`--split-size=NUM' - Keep Info files to at most NUM characters; default is 300,000. - -`--transliterate-file-names' - Enable transliteration of 8-bit characters in node names for the - purpose of file name creation. *Note HTML Xref 8-bit Character - Expansion::. - -`-U VAR' - Cause VAR to be undefined. This is equivalent to `@clear VAR' in - the Texinfo file (*note 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. - - -File: texinfo, Node: Pointer Validation, Next: makeinfo in Emacs, Prev: 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 (*note Use TeX: -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. (Your best bet is to -avoid using @-commands in node names.) 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. - - -File: texinfo, Node: makeinfo in Emacs, Next: texinfo-format commands, Prev: 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' (*note 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. *Note Running -`make' or Compilers Generally: (emacs)Compilation, 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'. *Note 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 -*note Easy Customization Interface: (emacs)Easy Customization, -*note Examining and Setting Variables: (emacs)Examining, -*note Init File: (emacs)Init File, and -*note Options for `makeinfo': makeinfo options. - - -File: texinfo, Node: texinfo-format commands, Next: Batch Formatting, Prev: 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 *note Catching Mistakes::. However, -the `makeinfo' program is often faster and provides better error -checking (*note makeinfo in Emacs::). - - -File: texinfo, Node: Batch Formatting, Next: Tag and Split Files, Prev: 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. (*Note Command Arguments: -(emacs)Command Arguments.) - - Here is a shell command to format all the files that end in -`.texinfo' in the current directory: - - emacs -batch -funcall batch-texinfo-format *.texinfo - -Emacs processes all the files listed on the command line, even if an -error occurs while attempting to format some of them. - - Run `batch-texinfo-format' only with Emacs in Batch mode as shown; it -is not interactive. It kills the Batch mode Emacs on completion. - - `batch-texinfo-format' is convenient if you lack `makeinfo' and want -to format several Texinfo files at once. When you use Batch mode, you -create a new Emacs process. This frees your current Emacs, so you can -continue working in it. (When you run `texinfo-format-region' or -`texinfo-format-buffer', you cannot use that Emacs for anything else -until the command finishes.) - - -File: texinfo, Node: Tag and Split Files, Prev: 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. *Note Include -Files::, for more information. Include files are still used for very -large documents, such as `The Emacs Lisp Reference Manual', in which -each chapter is a separate file.) - - When a file is split, Info itself makes use of a shortened version of -the original file that contains just the tag table and references to -the files that were split off. The split-off files are called -"indirect" files. - - The split-off files have names that are created by appending `-1', -`-2', `-3' and so on to the file name specified by the `@setfilename' -command. The shortened version of the original file continues to have -the name specified by `@setfilename'. - - At one stage in writing this document, for example, the Info file was -saved as the file `test-texinfo' and that file looked like this: - - Info file: test-texinfo, -*-Text-*- - produced by texinfo-format-buffer - from file: new-texinfo-manual.texinfo - - ^_ - Indirect: - test-texinfo-1: 102 - test-texinfo-2: 50422 - test-texinfo-3: 101300 - ^_^L - Tag table: - (Indirect) - Node: overview^?104 - Node: info file^?1271 - Node: printed manual^?4853 - Node: conventions^?6855 - ... - -(But `test-texinfo' had far more nodes than are shown here.) Each of -the split-off, indirect files, `test-texinfo-1', `test-texinfo-2', and -`test-texinfo-3', is listed in this file after the line that says -`Indirect:'. The tag table is listed after the line that says `Tag -table:'. - - In the list of indirect files, the number following the file name -records the cumulative number of bytes in the preceding indirect files, -not counting the file list itself, the tag table, or 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 *note Using -Info-validate::. - - -File: texinfo, Node: Installing an Info File, Prev: 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. (*note info: (info)Top, for an introduction to Info.) - -* Menu: - -* Directory File:: The top level menu for all Info files. -* New Info File:: Listing a new Info file. -* Other Info Directories:: How to specify Info files that are - located in other directories. -* Installing Dir Entries:: How to specify what menu entry to add - to the Info directory. -* Invoking install-info:: `install-info' options. - - -File: texinfo, Node: Directory File, Next: New Info File, 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. *Note Nodes in Other Info Files: Other Info Files.) - - Thus, the `Info' entry points to the `Top' node of the `info' file -and the `Emacs' entry points to the `Top' node of the `emacs' file. - - In each of the Info files, the `Up' pointer of the `Top' node refers -back to the `dir' file. For example, the line for the `Top' node of -the Emacs manual looks like this in Info: - - File: emacs Node: Top, Up: (DIR), Next: Distrib - -In this case, the `dir' file name is written in 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'. - - -File: texinfo, Node: New Info File, Next: Other Info Directories, Prev: 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 -`.info'(1); so it is better to avoid clutter and not to write `.info' -explicitly in the menu entry. For example, the GDB menu entry should -use just `gdb' for the file name, not `gdb.info'. - - ---------- Footnotes ---------- - - (1) On MS-DOS/MS-Windows systems, Info will try the `.inf' extension -as well. - - -File: texinfo, Node: Other Info Directories, Next: Installing Dir Entries, Prev: 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. - - * In a `.cshrc' file, you could set the `INFOPATH' variable as - follows: - - setenv INFOPATH .:~/info:/usr/local/emacs/info - - * In a `.profile' file, you would achieve the same effect by writing: - - INFOPATH=.:$HOME/info:/usr/local/emacs/info - export INFOPATH - - * In a `autoexec.bat' file, you write this command(1): - - set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info - -The `.' indicates the current directory as usual. Emacs uses the -`INFOPATH' environment variable to initialize the value of Emacs's own -`Info-directory-list' variable. The 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 colon(2), 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. - - ---------- Footnotes ---------- - - (1) Note the use of `;' as the directory separator, and a different -syntax for using values of other environment variables. - - (2) On MS-DOS/MS-Windows systems, use semi-colon instead. - - -File: texinfo, Node: Installing Dir Entries, Next: Invoking install-info, Prev: 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. - - `install-info' will automatically reformat the description of the -menu entries it is adding. As a matter of convention, the description -of the main entry (above, `The GNU documentation format') should start -at column 32, starting at zero (as in `what-cursor-position' in Emacs). -This will make it align with most others. Description for individual -utilities best start in column 48, where possible. For more -information about formatting see the `--calign', `--align', and -`--max-width' options in *note Invoking install-info::. - - If you use `@dircategory' more than once in the Texinfo source, each -usage specifies the `current' category; any subsequent `@direntry' -commands will add to that category. - - When choosing a category name for the `@dircategory' command, we -recommend consulting the Free Software Directory -(http://www.gnu.org/directory). If your program is not listed there, -or listed incorrectly or incompletely, please report the situation to -the directory maintainers (<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. - - -File: texinfo, Node: Invoking install-info, Prev: 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). `install-info' also -removes menu entries from the `dir' file. It's most often run as part -of software installation, or when constructing a `dir' file for all -manuals on a system. Synopsis: - - install-info [OPTION]... [INFO-FILE [DIR-FILE]] - - If INFO-FILE or DIR-FILE are not specified, the options (described -below) that define them must be. There are no compile-time defaults, -and standard input is never used. `install-info' can read only one -Info file and write only one `dir' file per invocation. - - If DIR-FILE (however specified) does not exist, `install-info' -creates it if possible (with no entries). - - If any input file is compressed with `gzip' (*note Invoking gzip: -(gzip)Invoking 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: - -`--add-once' - Specifies that the entry or entries will only be put into a single - section. - -`--align=COLUMN' - Specifies the column that the second and subsequent lines of menu - entry's description will be formatted to begin at. The default - for this option is `35'. It is used in conjunction with the - `--max-width' option. COLUMN starts counting at 1. - -`--append-new-sections' - Instead of alphabetizing new sections, place them at the end of - the DIR file. - -`--calign=COLUMN' - Specifies the column that the first line of menu entry's - description will be formatted to begin at. The default for this - option is `33'. It is used in conjunction with the `--max-width' - option. When the name of the menu entry exceeds this column, - entry's description will start on the following line. COLUMN - starts counting at 1. - -`--debug' - Report what is being done. - -`--delete' - Delete the entries in INFO-FILE from DIR-FILE. The file name in - the entry in DIR-FILE must be INFO-FILE (except for an optional - `.info' in either one). Don't insert any new entries. Any empty - sections that result from the removal are also removed. - -`--description=TEXT' - Specify the explanatory portion of the menu entry. If you don't - specify a description (either via `--entry', `--item' or this - option), the description is taken from the Info file itself. - -`--dir-file=NAME' - Specify file name of the Info directory file. This is equivalent - to using the DIR-FILE argument. - -`--dry-run' - Same as `--test'. - -`--entry=TEXT' - Insert TEXT as an Info directory entry; TEXT should have the form - of an Info menu item line plus zero or more extra lines starting - with whitespace. If you specify more than one entry, they are all - added. If you don't specify any entries, they are determined from - information in the Info file itself. - -`--help' - Display a usage message with basic usage and all available options, - then exit successfully. - -`--info-file=FILE' - Specify Info file to install in the directory. This is equivalent - to using the INFO-FILE argument. - -`--info-dir=DIR' - Specify the directory where the directory file `dir' resides. - Equivalent to `--dir-file=DIR/dir'. - -`--infodir=DIR' - Same as `--info-dir'. - -`--item=TEXT' - Same as `--entry=TEXT'. An Info directory entry is actually a - menu item. - -`--keep-old' - Do not replace pre-existing menu entries. When `--remove' is - specified, this option means that empty sections are not removed. - -`--max-width=COLUMN' - Specifies the column that the menu entry's description will be - word-wrapped at. COLUMN starts counting at 1. - -`--maxwidth=COLUMN' - Same as `--max-width'. - -`--menuentry=TEXT' - Same as `--name'. - -`--name=TEXT' - Specify the name portion of the menu entry. If the TEXT does not - start with an asterisk `*', it is presumed to be the text after - the `*' and before the parentheses that specify the Info file. - Otherwise TEXT is taken verbatim, and is meant to include the text - up to and including the first dot `.'. If you don't specify the - name (either via `--entry', `--item' or this option), it is taken - from the Info file itself. If the Info does not contain the name, - the basename of the Info file is used. - -`--no-indent' - Suppress formatting of new entries into the `dir' file. - -`--quiet' -`--silent' - Suppress warnings, etc., for silent operation. - -`--remove' - Same as `--delete'. - -`--remove-exactly' - Also like `--delete', but only entries if the Info file name - matches exactly; `.info' and/or `.gz' suffixes are _not_ ignored. - -`--section=SEC' - Put this file's entries in section SEC of the directory. If you - specify more than one section, all the entries are added in each - of the sections. If you don't specify any sections, they are - determined from information in the Info file itself. If the Info - file doesn't specify a section, the menu entries are put into the - Miscellaneous section. - -`--section REGEX SEC' - Same as `--regex=REGEX --section=SEC --add-once'. - - `install-info' tries to detect when this alternate syntax is used, - but does not always guess correctly! Here is the heuristic that - `install-info' uses: - 1. If the second argument to `--section' starts with a hyphen, - the original syntax is presumed. - - 2. If the second argument to `--section' is a file that can be - opened, the original syntax is presumed - - 3. Otherwise the alternate syntax is used. - - When heuristic fails because your section title starts with a - hyphen, or it happens to be a filename that can be opened, the - syntax should be changed to `--regex=REGEX --section=SEC - --add-once'. - -`--regex=REGEX' - Put this file's entries into any section that matches REGEX. If - more than one section matches, all of the entries are added in - each of the sections. Specify REGEX using basic regular - expression syntax, more or less as used with `grep', for example. - -`--test' - Suppress updating of the directory file. - -`--version' - Display version information and exit successfully. - - - -File: texinfo, Node: Generating HTML, Next: Command List, Prev: 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. *Note Output Formats::, for a brief -overview of all the output formats. - -* Menu: - -* HTML Translation:: Details of the HTML output. -* HTML Splitting:: How HTML output is split. -* HTML CSS:: Influencing HTML output with Cascading Style Sheets. -* HTML Xref:: Cross-references in HTML output. - - -File: texinfo, Node: HTML Translation, Next: HTML Splitting, 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). *Note 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.) - - -File: texinfo, Node: HTML Splitting, Next: HTML CSS, Prev: 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). - - -File: texinfo, Node: HTML CSS, Next: HTML Xref, Prev: 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 two `makeinfo' -options: `--css-include=FILE' and `--css-ref=URL'. - - The option `--css-ref=URL' adds to each output HTML file a `<link>' -tag referencing a CSS at the given URL. This allows using external -style sheets. - - The option `--css-include=FILE' includes the contents FILE in the -HTML output, as you might expect. However, the details are somewhat -tricky, as described in the following, to provide maximum flexibility. - - The CSS file may begin with so-called `@import' directives, which -link to external CSS specifications for browsers to use when -interpreting the document. Again, a full description is beyond our -scope here, but we'll describe how they work syntactically, so we can -explain how `makeinfo' handles them. - - There can be more than one `@import', but they have to come first in -the file, with only whitespace and comments interspersed, no normal -definitions. (Technical exception: an `@charset' directive may precede -the `@import''s. This does not alter `makeinfo''s behavior, it just -copies the `@charset' if present.) Comments in CSS files are delimited -by `/* ... */', as in C. An `@import' directive must be in one of -these two forms: - - @import url(http://example.org/foo.css); - @import "http://example.net/bar.css"; - - As far as `makeinfo' is concerned, the crucial characters are the `@' -at the beginning and the semicolon terminating the directive. When -reading the CSS file, it simply copies any such `@'-directive into the -output, as follows: - - * If FILE contains only normal CSS declarations, it is included - after `makeinfo''s default CSS, thus overriding it. - - * If FILE begins with `@import' specifications (see below), then the - `import''s are included first (they have to come first, according - to the standard), and then `makeinfo''s default CSS is included. - If you need to override `makeinfo''s defaults from an `@import', - you can do so with the `! important' CSS construct, as in: - pre.smallexample { font-size: inherit ! important } - - * If FILE contains both `@import' and inline CSS specifications, the - `@import''s are included first, then `makeinfo''s defaults, and - lastly the inline CSS from FILE. - - * Any @-directive other than `@import' and `@charset' is treated as - a CSS declaration, meaning `makeinfo' includes its default CSS and - then the rest of the file. - - - If the CSS file is malformed or erroneous, `makeinfo''s output is -unspecified. `makeinfo' does not try to interpret the meaning of the -CSS file in any way; it just looks for the special `@' and `;' -characters and blindly copies the text into the output. Comments in -the CSS file may or may not be included in the output. - - -File: texinfo, Node: HTML Xref, Prev: 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. -(*Note HTML Splitting::.) - - Acknowledgement: this algorithm was primarily devised by Patrice Dumas -in 2003-04. - -* Menu: - -* Link Basics: HTML Xref Link Basics. -* Node Expansion: HTML Xref Node Name Expansion. -* Command Expansion: HTML Xref Command Expansion. -* 8-bit Expansion: HTML Xref 8-bit Character Expansion. -* Mismatch: HTML Xref Mismatch. - - -File: texinfo, Node: HTML Xref Link Basics, Next: HTML Xref Node Name Expansion, 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 (*note -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 a given MANUAL -is either available as a monolithic file `MANUAL.html', or a split -subdirectory `MANUAL/*.html'. Here are the cases: - - * If the present manual is split, and the referent manual is also - split, the directory is `../REFERENT/' and the file is the - expanded node name (described later). - - * If the present manual is split, and the referent manual is mono, - the directory is `../' and the file is `REFERENT.html'. - - * If the present manual is mono, and the referent manual is split, - the directory is `REFERENT/' and the file is the expanded node - name. - - * If the present manual is mono, and the referent manual is also - mono, the directory is `./' (or just the empty string), and the - file is `REFERENT.html'. - - - One exception: the algorithm for node name expansion prefixes the -string `g_t' when the node name begins with a non-letter. This kludge -(due to XHTML rules) is not necessary for filenames, and is therefore -omitted. - - Any directory part in the filename argument of the source -cross-reference command is ignored. Thus, `@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. *Note HTML Xref Mismatch::. - - -File: texinfo, Node: HTML Xref Node Name Expansion, Next: HTML Xref Command Expansion, Prev: 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 XHTML identifiers and -filenames. The restrictions are similar for each: plain ASCII letters, -numbers, and the `-' and `_' characters are all that can be used. -(Although HTML anchors can contain most characters, XHTML is more -restrictive.) - - Cross-references in Texinfo can actually refer either to nodes or -anchors (*note 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 (*note The Top Node::) is always -mapped to the file `index.html', to match web server software. -However, the HTML _target_ is `Top'. Thus (in the split case): - - @xref{Top, Introduction,, emacs, The GNU Emacs Manual}. - => <a href="emacs/index.html#Top"> - - 1. The standard ASCII letters (a-z and A-Z) are not modified. All - other characters are changed as specified below. - - 2. The standard ASCII numbers (0-9) are not modified except when a - number is the first character of the node name. In that case, see - below. - - 3. Multiple consecutive space, tab and newline characters are - transformed into just one space. (It's not possible to have - newlines in node names with the current implementation, but we - specify it anyway, just in case.) - - 4. Leading and trailing spaces are removed. - - 5. After the above has been applied, each remaining space character is - converted into a `-' character. - - 6. Other ASCII 7-bit characters are transformed into `_00XX', where - XX is the ASCII character code in (lowercase) hexadecimal. This - includes `_', which is mapped to `_005f'. - - 7. If the node name does not begin with a letter, the literal string - `g_t' is prefixed to the result. (Due to the rules above, that - string can never occur otherwise; it is an arbitrary choice, - standing for "GNU Texinfo".) This is necessary because XHTML - requires that identifiers begin with a letter. - - - For example: - - @node A node --- with _'% - => A-node-_002d_002d_002d-with-_005f_0027_0025 - - Notice in particular: - - * `_' => `_005f' - - * `-' => `_002d' - - * `A node' => `A-node' - - On case-folding computer systems, nodes differing only by case will be -mapped to the same file. - - In particular, as mentioned above, Top always maps to the file -`index.html'. Thus, on a case-folding system, Top and a node named -`Index' will both be written to `index.html'. - - Fortunately, the targets serve to distinguish these cases, since HTML -target names are always case-sensitive, independent of operating system. - - -File: texinfo, Node: HTML Xref Command Expansion, Next: HTML Xref 8-bit Character Expansion, Prev: 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 -(*note 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 (*note set value::) and macro invocations -(*note 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 @slanted @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-->' -`@euro' U+20AC -`@exclamdown' U+00A1 -`@expansion' U+2192 -`@minus' U+2212 -`@ordf' U+00AA -`@ordm' U+00BA -`@point' U+2605 -`@pounds' U+00A3 -`@print' U+22A3 -`@questiondown' U+00BF -`@registeredsymbol' U+00AE -`@result' U+21D2 -`@tie' (space) - - An `@acronym' or `@abbr' command is replaced by the first argument, -followed by the second argument in parentheses, if present. *Note -acronym::. - - An `@email' command is replaced by the TEXT argument if present, else -the address. *Note email::. - - An `@image' command is replaced by the filename (first) argument. -*Note Images::. - - A `@verb' command is replaced by its transformed argument. *Note -verb::. - - Any other command is an error, and the result is unspecified. - - -File: texinfo, Node: HTML Xref 8-bit Character Expansion, Next: HTML Xref Mismatch, Prev: HTML Xref Command Expansion, Up: HTML Xref - -22.4.4 HTML Cross-reference 8-bit Character Expansion ------------------------------------------------------ - -Usually, characters other than plain 7-bit ASCII are transformed into -the corresponding Unicode code point(s) in Normalization Form C, which -uses precomposed characters where available. (This is the -normalization form recommended by the W3C and other bodies.) This -holds when that code point is 0xffff or less, as it almost always is. - - These will then be further transformed by the rules above into the -string `_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). - - When the Unicode code point is above 0xffff, the transformation is -`__XXXXXX', that is, two leading underscores followed by six hex -digits. Since Unicode has declared that their highest code point is -0x10ffff, this is sufficient. (We felt it was better to define this -extra escape than to always use six hex digits, since the first two -would nearly always be zeros.) - - This method works fine if the node name consists mostly of ASCII -characters and contains only few 8-bit ones. If the document is written -in a language whose script is not based on the Latin alphabet (such as, -e.g. Ukrainian), it will create file names consisting entirely of -`_XXXX' notations, which is inconvenient. - - To handle such cases, `makeinfo' offers `--transliterate-file-names' -command line option. This option enables "transliteration" of node -names into ASCII characters for the purposes of file name creation and -referencing. The transliteration is based on phonetic principle, which -makes the produced file names easily readable. - - 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. - - -File: texinfo, Node: HTML Xref Mismatch, Prev: HTML Xref 8-bit Character Expansion, Up: HTML Xref - -22.4.5 HTML Cross-reference Mismatch ------------------------------------- - -As mentioned earlier (*note 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. - - -File: texinfo, Node: Command List, Next: Tips, Prev: Generating HTML, Up: Top - -Appendix A @-Command List -************************* - -Here is an alphabetical list of the @-commands in Texinfo. Square -brackets, [ ], indicate optional arguments; an ellipsis, `...', -indicates repeated text. - - More specifics on the general syntax of different @-commands are -given in the section below. - -* Menu: - -* Command Syntax:: General syntax for varieties of @-commands. - - -`@WHITESPACE' - An `@' followed by a space, tab, or newline produces a normal, - stretchable, interword space. *Note Multiple Spaces::. - -`@!' - Generate an exclamation point that really does end a sentence - (usually after an end-of-sentence capital letter). *Note Ending a - Sentence::. - -`@"' -`@'' - Generate an umlaut or acute accent, respectively, over the next - character, as in o" and o'. *Note Inserting Accents::. - -`@*' - Force a line break. *Note Line Breaks::. - -`@,{C}' - Generate a cedilla accent under C, as in c,. *Note Inserting - Accents::. - -`@-' - Insert a discretionary hyphenation point. *Note - and - hyphenation::. - -`@.' - Produce a period that really does end a sentence (usually after an - end-of-sentence capital letter). *Note Ending a Sentence::. - -`@/' - Produces no output, but allows a line break. *Note Line Breaks::. - -`@:' - Tell TeX to refrain from inserting extra whitespace after an - immediately preceding period, question mark, exclamation mark, or - colon, as TeX normally would. *Note Not Ending a Sentence::. - -`@=' - Generate a macron (bar) accent over the next character, as in o=. - *Note Inserting Accents::. - -`@?' - Generate a question mark that really does end a sentence (usually - after an end-of-sentence capital letter). *Note Ending a - Sentence::. - -`@@' - Stands for an at sign, `@'. *Note Inserting @ and {} and ,: - Atsign Braces Comma. - -`@\' - Stands for a backslash (`\') inside `@math'. *Note `math': math. - -`@^' -`@`' - Generate a circumflex (hat) or grave accent, respectively, over - the next character, as in o^ and e`. *Note Inserting Accents::. - -`@{' - Stands for a left brace, `{'. *Note Inserting @ and {} and ,: - Atsign Braces Comma. - -`@}' - Stands for a right-hand brace, `}'. - *Note Inserting @ and {} and ,: Atsign Braces Comma. - -`@~' - Generate a tilde accent over the next character, as in N~. *Note - Inserting Accents::. - -`@AA{}' -`@aa{}' - Generate the uppercase and lowercase Scandinavian A-ring letters, - respectively: AA, aa. *Note Inserting Accents::. - -`@abbr{ABBREVIATION}' - Tag ABBREVIATION as an abbreviation, such as `Comput.'. *Note - `abbr': abbr. - -`@acronym{ACRONYM}' - Tag ACRONYM as an acronym, such as `NASA'. *Note `acronym': - acronym. - -`@AE{}' -`@ae{}' - Generate the uppercase and lowercase AE ligatures, respectively: - AE, ae. *Note Inserting Accents::. - -`@afivepaper' - Change page dimensions for the A5 paper size. *Note A4 Paper::. - -`@afourlatex' -`@afourpaper' -`@afourwide' - Change page dimensions for the A4 paper size. *Note A4 Paper::. - -`@alias NEW=EXISTING' - Make the command `@NEW' an alias for the existing command - `@EXISTING'. *Note alias::. - -`@anchor{NAME}' - Define NAME as the current location for use as a cross-reference - target. *Note `@anchor': 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. *Note The `@unnumbered' and `@appendix' Commands: - unnumbered & appendix. - -`@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. *Note Section - Commands: unnumberedsec appendixsec heading. - -`@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. *Note Subsection Commands: - unnumberedsubsec appendixsubsec subheading. - -`@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. *Note The `subsub' - Commands: subsubsection. - -`@arrow{}' - Produce a normal right arrow glyph: `->'. Used by default for - `@click'. *Note Click Sequences::. - -`@asis' - Used following `@table', `@ftable', and `@vtable' to print the - table's first column without highlighting ("as is"). *Note - Two-column Tables::. - -`@author AUTHOR' - Typeset AUTHOR flushleft and underline it. *Note The `@title' and - `@author' Commands: title subtitle author. - -`@b{TEXT}' - Print TEXT in bold font. No effect in Info. *Note Fonts::. - -`@bullet{}' - Generate a large round dot, or the closest possible thing to one. - *Note `@bullet': bullet. - -`@bye' - Stop formatting a file. The formatters do not see the contents of - a file following an `@bye' command. *Note 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'. *Note Comments::. - -`@caption' - Define the full caption for a `@float'. *Note caption - shortcaption::. - -`@cartouche' - Highlight an example or quotation by drawing a box with rounded - corners around it. Pair with `@end cartouche'. No effect in - Info. *Note Drawing Cartouches Around Examples: cartouche.) - -`@center LINE-OF-TEXT' - Center the line of text following the command. *Note `@center': - titlefont center sp. - -`@centerchap LINE-OF-TEXT' - Like `@chapter', but centers the chapter title. *Note `@chapter': - 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. *Note `@majorheading' and `@chapheading': - majorheading & 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. *Note `@chapter': chapter. - -`@cindex ENTRY' - Add ENTRY to the index of concepts. *Note Defining the Entries of - an Index: Index Entries. - -`@cite{REFERENCE}' - Highlight the name of a book or other reference that lacks a - companion Info file. *Note `@cite': cite. - -`@click{}' - Represent a single "click" in a GUI. Used within - `@clicksequence'. *Note Click Sequences::. - -`@clicksequence{ACTION @click{} ACTION}' - Represent a sequence of clicks in a GUI. *Note Click Sequences::. - -`@clickstyle @CMD' - Execute @CMD for each `@click'; the default is `@arrow'. The - usual following empty braces on @CMD are omitted. *Note Click - Sequences::. - -`@clear FLAG' - Unset FLAG, preventing the Texinfo formatting commands from - formatting text between subsequent pairs of `@ifset FLAG' and - `@end ifset' commands, and preventing `@value{FLAG}' from - expanding to the value to which FLAG is set. *Note `@set' - `@clear' `@value': set clear value. - -`@code{SAMPLE-CODE}' - Highlight text that is an expression, a syntactically complete - token of a program, or a program name. *Note `@code': code. - -`@comma{}' - Insert a comma `,' character; only needed when a literal comma - would be taken as an argument separator. *Note Inserting a - Comma::. - -`@command{COMMAND-NAME}' - Indicate a command name, such as `ls'. *Note `@command': 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'. - *Note Comments::. - -`@contents' - Print a complete table of contents. Has no effect in Info, which - uses menus instead. *Note Generating a Table of Contents: - Contents. - -`@copyright{}' - Generate the copyright symbol (C). *Note `@copyright{}': - copyright symbol. - -`@defcodeindex INDEX-NAME' - Define a new index and its indexing command. Print entries in an - `@code' font. *Note Defining New Indices: New Indices. - -`@defcv CATEGORY CLASS NAME' -`@defcvx CATEGORY CLASS NAME' - Format a description for a variable associated with a class in - object-oriented programming. Takes three arguments: the category - of thing being defined, the class to which it belongs, and its - name. *Note Definition Commands::, and *note Def Cmds in Detail: - deffnx. - -`@deffn CATEGORY NAME ARGUMENTS...' -`@deffnx CATEGORY NAME ARGUMENTS...' - Format a description for a function, interactive command, or - similar entity that may take arguments. `@deffn' takes as - arguments the category of entity being described, the name of this - particular entity, and its arguments, if any. *Note Definition - Commands::. - -`@defindex INDEX-NAME' - Define a new index and its indexing command. Print entries in a - roman font. *Note Defining New Indices: New Indices. - -`@definfoenclose NEWCMD, BEFORE, AFTER,' - Create new @-command NEWCMD for Info that marks text by enclosing - it in strings that precede and follow the text. *Note - definfoenclose::. - -`@defivar CLASS INSTANCE-VARIABLE-NAME' -`@defivarx CLASS INSTANCE-VARIABLE-NAME' - This command formats a description for an instance variable in - object-oriented programming. The command is equivalent to `@defcv - {Instance Variable} ...'. *Note Definition Commands::, and *note - Def Cmds in Detail: deffnx. - -`@defmac MACRONAME ARGUMENTS...' -`@defmacx MACRONAME ARGUMENTS...' - Format a description for a macro. The command is equivalent to - `@deffn Macro ...'. *Note Definition Commands::, and *note Def - Cmds in Detail: deffnx. - -`@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. *Note Definition Commands::, - and *note Def Cmds in Detail: deffnx. - -`@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. *Note - Definition Commands::, and *note Abstract Objects::. - -`@defopt OPTION-NAME' -`@defoptx OPTION-NAME' - Format a description for a user option. The command is equivalent - to `@defvr {User Option} ...'. *Note Definition Commands::, and - *note Def Cmds in Detail: deffnx. - -`@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} ...'. *Note Definition - Commands::, and *note Def Cmds in Detail: deffnx. - -`@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. - *Note Definition Commands::, and *note Data Types::. - -`@deftypecv CATEGORY CLASS DATA-TYPE NAME' -`@deftypecvx CATEGORY CLASS DATA-TYPE NAME' - Format a description for a typed class variable in object-oriented - programming. *Note Definition Commands::, and *note Abstract - Objects::. - -`@deftypefn 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. *Note Definition Commands::, - and *note Def Cmds in Detail: deffnx. - -`@deftypefun DATA-TYPE FUNCTION-NAME ARGUMENTS...' -`@deftypefunx DATA-TYPE FUNCTION-NAME ARGUMENTS...' - Format a description for a function in a typed language. The - command is equivalent to `@deftypefn Function ...'. *Note - Definition Commands::, and *note Def Cmds in Detail: deffnx. - -`@deftypeivar CLASS DATA-TYPE VARIABLE-NAME' -`@deftypeivarx CLASS DATA-TYPE VARIABLE-NAME' - Format a description for a typed instance variable in - object-oriented programming. *Note Definition Commands::, and - *note Abstract Objects::. - -`@deftypemethod CLASS DATA-TYPE METHOD-NAME ARGUMENTS...' -`@deftypemethodx CLASS DATA-TYPE METHOD-NAME ARGUMENTS...' - Format a description for a typed method in object-oriented - programming. *Note Definition Commands::, and *note Def Cmds in - Detail: deffnx. - -`@deftypeop CATEGORY CLASS DATA-TYPE NAME ARGUMENTS...' -`@deftypeopx CATEGORY CLASS DATA-TYPE NAME ARGUMENTS...' - Format a description for a typed operation in object-oriented - programming. *Note Definition Commands::, and *note Abstract - Objects::. - -`@deftypevar DATA-TYPE VARIABLE-NAME' -`@deftypevarx DATA-TYPE VARIABLE-NAME' - Format a description for a variable in a typed language. The - command is equivalent to `@deftypevr Variable ...'. *Note - Definition Commands::, and *note Def Cmds in Detail: deffnx. - -`@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. *Note Definition Commands::, and *note Def Cmds in - Detail: deffnx. - -`@defun FUNCTION-NAME ARGUMENTS...' -`@defunx FUNCTION-NAME ARGUMENTS...' - Format a description for functions. The command is equivalent to - `@deffn Function ...'. *Note Definition Commands::, and *note Def - Cmds in Detail: deffnx. - -`@defvar VARIABLE-NAME' -`@defvarx VARIABLE-NAME' - Format a description for variables. The command is equivalent to - `@defvr Variable ...'. *Note Definition Commands::, and *note Def - Cmds in Detail: deffnx. - -`@defvr CATEGORY NAME' -`@defvrx CATEGORY NAME' - Format a description for any kind of variable. `@defvr' takes as - arguments the category of the entity and the name of the entity. - *Note Definition Commands::, and *note Def Cmds in Detail: deffnx. - -`@detailmenu' - Avoid `makeinfo' confusion stemming from the detailed node listing - in a master menu. *Note Master Menu Parts::. - -`@dfn{TERM}' - Highlight the introductory or defining use of a term. *Note - `@dfn': dfn. - -`@dircategory DIRPART' - Specify a part of the Info directory menu where this file's entry - should go. *Note Installing Dir Entries::. - -`@direntry' - Begin the Info directory menu entry for this file. Pair with - `@end direntry'. *Note Installing Dir Entries::. - -`@display' - Begin a kind of example. Like `@example' (indent text, do not - fill), but do not select a new font. Pair with `@end display'. - *Note `@display': display. - -`@dmn{DIMENSION}' - Format a unit of measure, as in 12pt. Causes TeX to insert a thin - space before DIMENSION. No effect in Info. *Note `@dmn': dmn. - -`@docbook' - Enter Docbook completely. Pair with `@end docbook'. *Note Raw - Formatter Commands::. - -`@documentdescription' - Set the document description text, included in the HTML output. - Pair with `@end documentdescription'. *Note - `@documentdescription': documentdescription. - -`@documentencoding ENC' - Declare the input encoding to be ENC. *Note `@documentencoding': - documentencoding. - -`@documentlanguage CC' - Declare the document language as the two-character ISO-639 - abbreviation CC. *Note `@documentlanguage': documentlanguage. - -`@dotaccent{C}' - Generate a dot accent over the character C, as in o.. *Note - Inserting Accents::. - -`@dots{}' - Insert an ellipsis: `...'. *Note `@dots': dots. - -`@email{ADDRESS[, DISPLAYED-TEXT]}' - Indicate an electronic mail address. *Note `@email': email. - -`@emph{TEXT}' - Highlight TEXT; text is displayed in _italics_ in printed output, - and surrounded by asterisks in Info. *Note Emphasizing Text: - Emphasis. - -`@end ENVIRONMENT' - Ends ENVIRONMENT, as in `@end example'. *Note @-commands: - Formatting Commands. - -`@env{ENVIRONMENT-VARIABLE}' - Indicate an environment variable name, such as `PATH'. *Note - `@env': env. - -`@enddots{}' - Generate an end-of-sentence of ellipsis, like this ... *Note - `@dots{}': dots. - -`@enumerate [NUMBER-OR-LETTER]' - Begin a numbered list, using `@item' for each entry. Optionally, - start list with NUMBER-OR-LETTER. Pair with `@end enumerate'. - *Note `@enumerate': enumerate. - -`@equiv{}' - Indicate to the reader the exact equivalence of two forms with a - glyph: `=='. *Note Equivalence::. - -`@euro{}' - Generate the Euro currency sign. *Note `@euro{}': euro. - -`@error{}' - Indicate to the reader with a glyph that the following text is an - error message: `error-->'. *Note Error Glyph::. - -`@evenfooting [LEFT] @| [CENTER] @| [RIGHT]' -`@evenheading [LEFT] @| [CENTER] @| [RIGHT]' - Specify page footings resp. headings for even-numbered (left-hand) - pages. *Note How to Make Your Own Headings: Custom Headings. - -`@everyfooting [LEFT] @| [CENTER] @| [RIGHT]' -`@everyheading [LEFT] @| [CENTER] @| [RIGHT]' - Specify page footings resp. headings for every page. Not relevant - to Info. *Note How to Make Your Own Headings: Custom Headings. - -`@example' - Begin an example. Indent text, do not fill, and select - fixed-width font. Pair with `@end example'. *Note `@example': - example. - -`@exampleindent INDENT' - Indent example-like environments by INDENT number of spaces - (perhaps 0). *Note Paragraph Indenting: exampleindent. - -`@exclamdown{}' - Produce an upside-down exclamation point. *Note Inserting - Accents::. - -`@exdent LINE-OF-TEXT' - Remove any indentation a line might have. *Note Undoing the - Indentation of a Line: exdent. - -`@expansion{}' - Indicate the result of a macro expansion to the reader with a - special glyph: `==>'. *Note ==> Indicating an Expansion: - expansion. - -`@file{FILENAME}' - Highlight the name of a file, buffer, node, or directory. *Note - `@file': file. - -`@finalout' - Prevent TeX from printing large black warning rectangles beside - over-wide lines. *Note Overfull hboxes::. - -`@findex ENTRY' - Add ENTRY to the index of functions. *Note Defining the Entries - of an Index: Index Entries. - -`@float' - Environment to define floating material. Pair with `@end float'. - *Note Floats::. - -`@flushleft' -`@flushright' - Left justify every line but leave the right end ragged. Leave - font as is. Pair with `@end flushleft'. `@flushright' analogous. - *Note `@flushleft' and `@flushright': flushleft & 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. *Note Footnotes::. - -`@footnotestyle STYLE' - Specify an Info file's footnote style, either `end' for the end - node style or `separate' for the separate node style. *Note - Footnotes::. - -`@format' - Begin a kind of example. Like `@display', but do not narrow the - margins. Pair with `@end format'. *Note `@example': 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. *Note `@ftable' and `@vtable': - ftable vtable. - -`@geq{}' - Generate a greater-than-or-equal sign, `>='. *Note geq leq::. - -`@group' - Hold text together that must appear on one printed page. Pair with - `@end group'. Not relevant to Info. *Note `@group': 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. *Note Section Commands: - unnumberedsec appendixsec heading. - -`@headings ON-OFF-SINGLE-DOUBLE' - Turn page headings on or off, and/or specify single-sided or - double-sided page headings for printing. *Note The `@headings' - Command: headings on off. - -`@html' - Enter HTML completely. Pair with `@end html'. *Note Raw - Formatter Commands::. - -`@hyphenation{HY-PHEN-A-TED WORDS}' - Explicitly define hyphenation points. *Note `@-' and - `@hyphenation': - and hyphenation. - -`@i{TEXT}' - Print TEXT in italic font. No effect in Info. *Note Fonts::. - -`@ifclear FLAG' - If FLAG is cleared, the Texinfo formatting commands format text - between `@ifclear FLAG' and the following `@end ifclear' command. - *Note `@set' `@clear' `@value': 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'. *Note 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'. *Note Conditionals::. - -`@ifplaintext' - Begin text that will appear only in the plain text output. Pair - with `@end ifplaintext'. *Note Conditionals::. - -`@ifset FLAG' - If FLAG is set, the Texinfo formatting commands format text - between `@ifset FLAG' and the following `@end ifset' command. - *Note `@set' `@clear' `@value': 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'. *Note - Conditionally Visible Text: Conditionals. - -`@ifxml' - Begin text that will appear only in the XML output. Pair with - `@end ifxml'. *Note Conditionals::. - -`@ignore' - Begin text that will not appear in any output. Pair with `@end - ignore'. *Note Comments and Ignored Text: Comments. - -`@image{FILENAME, [WIDTH], [HEIGHT], [ALT], [EXT]}' - Include graphics image in external FILENAME scaled to the given - WIDTH and/or HEIGHT, using ALT text and looking for `FILENAME.EXT' - in HTML. *Note Images::. - -`@include FILENAME' - Incorporate the contents of the file FILENAME into the Info file - or printed document. *Note Include Files::. - -`@indicateurl{INDICATEURL}' - Indicate text that is a uniform resource locator for the World Wide - Web. *Note `@indicateurl': indicateurl. - -`@inforef{NODE-NAME, [ENTRY-NAME], INFO-FILE-NAME}' - Make a cross reference to an Info file for which there is no - printed manual. *Note Cross references using `@inforef': 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. *Note 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'. *Note 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'. *Note `@itemize': itemize. - -`@itemx' - Like `@item' but do not generate extra vertical space above the - item text. *Note `@itemx': itemx. - -`@kbd{KEYBOARD-CHARACTERS}' - Indicate text that is characters of input to be typed by users. - *Note `@kbd': kbd. - -`@kbdinputstyle STYLE' - Specify when `@kbd' should use a font distinct from `@code'. - *Note `@kbd': kbd. - -`@key{KEY-NAME}' - Indicate a name for a key on a keyboard. *Note `@key': key. - -`@kindex ENTRY' - Add ENTRY to the index of keys. *Note Defining the Entries of an - Index: Index Entries. - -`@L{}' -`@l{}' - Generate the uppercase and lowercase Polish suppressed-L letters, - respectively: /L, /l. - -`@LaTeX{}' - Insert the logo LaTeX. *Note TeX and LaTeX: tex. - -`@leq{}' - Generate a less-than-or-equal sign, `<='. *Note geq leq::. - -`@lisp' - Begin an example of Lisp code. Indent text, do not fill, and - select fixed-width font. Pair with `@end lisp'. *Note `@lisp': - lisp. - -`@listoffloats' - Produce a table-of-contents-like listing of `@float's. *Note - listoffloats::. - -`@lowersections' - Change subsequent chapters to sections, sections to subsections, - and so on. *Note `@raisesections' and `@lowersections': - Raise/lower sections. - -`@macro MACRONAME {PARAMS}' - Define a new Texinfo command `@MACRONAME{PARAMS}'. Only supported - by `makeinfo' and `texi2dvi'. *Note 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. *Note - `@majorheading' and `@chapheading': majorheading & chapheading. - -`@math{MATHEMATICAL-EXPRESSION}' - Format a mathematical expression. *Note `@math': Inserting - Mathematical Expressions: math. - -`@menu' - Mark the beginning of a menu of nodes in Info. No effect in a - printed manual. Pair with `@end menu'. *Note Menus::. - -`@minus{}' - Generate a minus sign, `-'. *Note `@minus': minus. - -`@multitable COLUMN-WIDTH-SPEC' - Begin a multi-column table. Pair with `@end multitable'. *Note - Multitable Column Widths::. - -`@need N' - Start a new page in a printed manual if fewer than N mils - (thousandths of an inch) remain on the current page. *Note - `@need': need. - -`@node NAME, NEXT, PREVIOUS, UP' - Define the beginning of a new node in Info, and serve as a locator - for references for TeX. *Note `@node': node. - -`@noindent' - Prevent text from being indented as if it were a new paragraph. - *Note `@noindent': noindent. - -`@novalidate' - Suppress validation of node references, omit creation of auxiliary - files with TeX. Use before `@setfilename'. *Note Pointer - Validation::. - -`@O{}' -`@o{}' - Generate the uppercase and lowercase O-with-slash letters, - respectively: /O, /o. - -`@oddfooting [LEFT] @| [CENTER] @| [RIGHT]' -`@oddheading [LEFT] @| [CENTER] @| [RIGHT]' - Specify page footings resp. headings for odd-numbered (right-hand) - pages. *Note How to Make Your Own Headings: Custom Headings. - -`@OE{}' -`@oe{}' - Generate the uppercase and lowercase OE ligatures, respectively: - OE, oe. *Note Inserting Accents::. - -`@option{OPTION-NAME}' - Indicate a command-line option, such as `-l' or `--help'. *Note - `@option': option. - -`@page' - Start a new page in a printed manual. No effect in Info. *Note - `@page': page. - -`@pagesizes [WIDTH][, HEIGHT]' - Change page dimensions. *Note pagesizes::. - -`@paragraphindent INDENT' - Indent paragraphs by INDENT number of spaces (perhaps 0); preserve - source file indentation if INDENT is `asis'. *Note Paragraph - Indenting: paragraphindent. - -`@pindex ENTRY' - Add ENTRY to the index of programs. *Note Defining the Entries of - an Index: Index Entries. - -`@point{}' - Indicate the position of point in a buffer to the reader with a - glyph: `-!-'. *Note Indicating Point in a Buffer: Point Glyph. - -`@pounds{}' - Generate the pounds sterling currency sign. *Note `@pounds{}': - pounds. - -`@print{}' - Indicate printed output to the reader with a glyph: `-|'. *Note - 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. *Note - 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. *Note `@pxref': pxref. - -`@questiondown{}' - Generate an upside-down question mark. *Note 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'. *Note `@quotation': quotation. - -`@r{TEXT}' - Print TEXT in roman font. No effect in Info. *Note Fonts::. - -`@raisesections' - Change subsequent sections to chapters, subsections to sections, - and so on. *Note `@raisesections' and `@lowersections': - Raise/lower sections. - -`@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. *Note `@ref': ref. - -`@refill' - This command used to refill and indent the paragraph after all the - other processing has been done. It is no longer needed, since all - formatters now automatically refill as needed, but you may still - see it in the source to some manuals, as it does no harm. - -`@registeredsymbol{}' - Generate the legal symbol (R). *Note `@registeredsymbol{}': - registered symbol. - -`@result{}' - Indicate the result of an expression to the reader with a special - glyph: `=>'. *Note `@result': result. - -`@ringaccent{C}' - Generate a ring accent over the next character, as in o*. *Note - 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. *Note `@samp': samp. - -`@sansserif{TEXT}' - Print TEXT in a sans serif font if possible. No effect in Info. - *Note Fonts::. - -`@sc{TEXT}' - Set TEXT in a printed output in THE SMALL CAPS FONT and set text - in the Info file in uppercase letters. *Note 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. *Note `@section': - 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. *Note - `@set' `@clear' `@value': set clear value. - -`@setchapternewpage ON-OFF-ODD' - Specify whether chapters start on new pages, and if so, whether on - odd-numbered (right-hand) new pages. *Note `@setchapternewpage': - setchapternewpage. - -`@setcontentsaftertitlepage' - Put the table of contents after the `@end titlepage' even if the - `@contents' command is not there. *Note 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. *Note `@setfilename': setfilename. - -`@setshortcontentsaftertitlepage' - Place the short table of contents after the `@end titlepage' - command even if the `@shortcontents' command is not there. *Note - Contents::. - -`@settitle TITLE' - Provide a title for page headers in a printed manual, and the - default document description for HTML `<head>'. *Note - `@settitle': settitle. - -`@shortcaption' - Define the short caption for a `@float'. *Note 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'. *Note Generating a Table of Contents: - Contents. - -`@shorttitlepage TITLE' - Generate a minimal title page. *Note `@titlepage': titlepage. - -`@slanted{TEXT}' - Print TEXT in a slanted font if possible. No effect in Info. - *Note Fonts::. - -`@smallbook' - Cause TeX to produce a printed manual in a 7 by 9.25 inch format - rather than the regular 8.5 by 11 inch format. *Note Printing - Small Books: smallbook. Also, see *note 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'. *Note 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'. *Note small::. - -`@smallformat' - Begin a kind of example. Like `@smalldisplay', but do not narrow - the margins. Pair with `@end smallformat'. *Note small::. - -`@smalllisp' - Begin an example of Lisp code. Same as `@smallexample'. Pair - with `@end smalllisp'. *Note small::. - -`@sp N' - Skip N blank lines. *Note `@sp': sp. - -`@ss{}' - Generate the German sharp-S es-zet letter, ss. *Note 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. *Note - Emphasizing Text: emph & strong. - -`@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. *Note `@unnumberedsubsec' - `@appendixsubsec' `@subheading': 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. *Note - `@subsection': 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. *Note The `subsub' Commands: - subsubsection. - -`@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. *Note - The `subsub' Commands: subsubsection. - -`@subtitle TITLE' - In a printed manual, set a subtitle in a normal sized font flush to - the right-hand side of the page. Not relevant to Info, which does - not have title pages. *Note `@title' `@subtitle' and `@author' - Commands: title subtitle author. - -`@summarycontents' - Print a short table of contents. Not relevant to Info, which uses - menus rather than tables of contents. A synonym for - `@shortcontents'. *Note Generating a Table of Contents: 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. *Note 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. *Note Combining Indices::. - -`@t{TEXT}' - Print TEXT in a fixed-width, typewriter-like font. No effect in - Info. *Note Fonts::. - -`@tab' - Separate columns in a multitable. *Note 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'. *Note Making a Two-column Table: - Two-column Tables. Also see *note `@ftable' and `@vtable': ftable - vtable, and *note `@itemx': itemx. - -`@TeX{}' - Insert the logo TeX. *Note TeX and LaTeX: tex. - -`@tex' - Enter TeX completely. Pair with `@end tex'. *Note Raw Formatter - Commands::. - -`@thischapter' -`@thischaptername' -`@thischapternum' -`@thisfile' -`@thispage' -`@thistitle' - Only allowed in a heading or footing. Stands for, respectively, - the number and name of the current chapter (in the format `Chapter - 1: Title'), the current chapter name only, the current chapter - number only, the filename, the current page number, and the title - of the document, respectively. *Note How to Make Your Own - Headings: Custom Headings. - -`@tie{}' - Generate a normal interword space at which a line break is not - allowed. *Note `@tie{}': tie. - -`@tieaccent{CC}' - Generate a tie-after accent over the next two characters CC, as in - `oo['. *Note Inserting Accents::. - -`@tindex ENTRY' - Add ENTRY to the index of data types. *Note Defining the Entries - of an Index: Index Entries. - -`@title TITLE' - In a printed manual, set a title flush to the left-hand side of the - page in a larger than normal font and underline it with a black - rule. Not relevant to Info, which does not have title pages. - *Note The `@title' `@subtitle' and `@author' Commands: title - subtitle author. - -`@titlefont{TEXT}' - In a printed manual, print TEXT in a larger than normal font. Not - relevant to Info, which does not have title pages. *Note The - `@titlefont' `@center' and `@sp' Commands: titlefont center sp. - -`@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. - *Note `@titlepage': titlepage. - -`@today{}' - Insert the current date, in `1 Jan 1900' style. *Note How to Make - Your Own Headings: Custom 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'. *Note Creating Pointers with `makeinfo': - makeinfo Pointer Creation. - -`@u{C}' -`@ubaraccent{C}' -`@udotaccent{C}' - Generate a breve, underbar, or underdot accent, respectively, over - or under the character C, as in o(, o_, .o. *Note Inserting - Accents::. - -`@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. *Note `@unnumbered' and `@appendix': unnumbered & - 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. *Note Section Commands: unnumberedsec appendixsec heading. - -`@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. *Note - `@unnumberedsubsec' `@appendixsubsec' `@subheading': - 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. *Note The - `subsub' Commands: subsubsection. - -`@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. *Note `@uref': uref. - -`@v{C}' - Generate check accent over the character C, as in o<. *Note - Inserting Accents::. - -`@value{FLAG}' - Replace FLAG with the value to which it is set by `@set FLAG'. - *Note `@set' `@clear' `@value': set clear value. - -`@var{METASYNTACTIC-VARIABLE}' - Highlight a metasyntactic variable, which is something that stands - for another piece of text. *Note Indicating Metasyntactic - Variables: var. - -`@verb{DELIM LITERAL DELIM}' - Output LITERAL, delimited by the single character DELIM, exactly - as is (in the fixed-width font), including any whitespace or - Texinfo special characters. *Note `verb': verb. - -`@verbatim' - Output the text of the environment exactly as is (in the - fixed-width font). Pair with `@end verbatim'. *Note `verbatim': - verbatim. - -`@verbatiminclude FILENAME' - Output the contents of FILENAME exactly as is (in the fixed-width - font). *Note `verbatiminclude': verbatiminclude. - -`@vindex ENTRY' - Add ENTRY to the index of variables. *Note Defining the Entries - of an Index: Index Entries. - -`@vskip AMOUNT' - In a printed manual, insert whitespace so as to push text on the - remainder of the page towards the bottom of the page. Used in - formatting the copyright page with the argument `0pt plus 1filll'. - (Note spelling of `filll'.) `@vskip' may be used only in contexts - ignored for Info. *Note Copyright::. - -`@vtable FORMATTING-COMMAND' - Begin a two-column table, using `@item' for each entry. - Automatically enter each of the items in the first column into the - index of variables. Pair with `@end vtable'. The same as - `@table', except for indexing. *Note `@ftable' and `@vtable': - ftable vtable. - -`@w{TEXT}' - Prevent TEXT from being split across two lines. *Note `@w': w. - -`@xml' - Enter XML completely. Pair with `@end xml'. *Note 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. *Note `@xref': xref. - - -File: texinfo, Node: Command Syntax, 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. - The non-alphabetic commands include `@@', `@{', `@}', `@.', - `@SPACE', most of the accent commands, and many more. - -2. Alphabetic commands that do not require arguments. - These commands start with @ followed by a word followed by 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. - - -File: texinfo, Node: Tips, Next: Sample Texinfo Files, Prev: Command List, Up: Top - -Appendix B Tips and Hints -************************* - -Here are some tips for writing Texinfo documentation: - - * Write in the present tense, not in the past or the future. - - * Write actively! For example, write "We recommend that ..." rather - than "It is recommended that ...". - - * Use 70 or 72 as your fill column. Longer lines are hard to read. - - * Include a copyright notice and copying permissions. - -Index, Index, Index! -.................... - -Write many index entries, in different ways. Readers like indices; -they are helpful and convenient. - - Although it is easiest to write index entries as you write the body of -the text, some people prefer to write entries afterwards. In either -case, write an entry before the paragraph to which it applies. This -way, an index entry points to the first page of a paragraph that is -split across pages. - - Here are more hints we have found valuable: - - * Write each index entry differently, so each entry refers to a - different place in the document. - - * Write index entries only where a topic is discussed significantly. - For example, it is not useful to index "debugging information" in a - chapter on reporting bugs. Someone who wants to know about - debugging information will certainly not find it in that chapter. - - * Consistently capitalize the first word of every concept index - entry, or else consistently use lower case. Terse entries often - call for lower case; longer entries for capitalization. Whichever - case convention you use, please use one or the other consistently! - Mixing the two styles looks bad. - - * Always capitalize or use upper case for those words in an index for - which this is proper, such as names of countries or acronyms. - Always use the appropriate case for case-sensitive names, such as - those in C or Lisp. - - * Write the indexing commands that refer to a whole section - immediately after the section command, and write the indexing - commands that refer to a paragraph before that paragraph. - - In the example that follows, a blank line comes after the index - entry for "Leaping": - - @section The Dog and the Fox - @cindex Jumping, in general - @cindex Leaping - - @cindex Dog, lazy, jumped over - @cindex Lazy dog jumped over - @cindex Fox, jumps over dog - @cindex Quick fox jumps over dog - The quick brown fox jumps over the lazy dog. - - (Note that the example shows entries for the same concept that are - written in different ways--`Lazy dog', and `Dog, lazy'--so readers - can look up the concept in different ways.) - -Blank Lines -........... - - * Insert a blank line between a sectioning command and the first - following sentence or paragraph, or between the indexing commands - associated with the sectioning command and the first following - sentence or paragraph, as shown in the tip on indexing. - Otherwise, a formatter may fold title and paragraph together. - - * Always insert a blank line before an `@table' command and after an - `@end table' command; but never insert a blank line after an - `@table' command or before an `@end table' command. - - For example, - - Types of fox: - - @table @samp - @item Quick - Jump over lazy dogs. - - @item Brown - Also jump over lazy dogs. - @end table - @noindent - On the other hand, ... - - Insert blank lines before and after `@itemize' ... `@end itemize' - and `@enumerate' ... `@end enumerate' in the same way. - -Complete Phrases -................ - -Complete phrases are easier to read than ... - - * Write entries in an itemized list as complete sentences; or at - least, as complete phrases. Incomplete expressions ... awkward - ... like this. - - * Write the prefatory sentence or phrase for a multi-item list or - table as a complete expression. Do not write "You can set:"; - instead, write "You can set these variables:". The former - expression sounds cut off. - -Editions, Dates and Versions -............................ - -Include edition numbers, version numbers, and dates in the `@copying' -text (for people reading the Texinfo file, and for the legal copyright -in the output files). Then use `@insertcopying' in the `@titlepage' -section (for people reading the printed output) and the Top node (for -people reading the online output). - - It is easiest to do this using `@set' and `@value'. *Note `@value' -Example: value Example, and *note GNU Sample Texts::. - -Definition Commands -................... - -Definition commands are `@deffn', `@defun', `@defmac', and the like, -and enable you to write descriptions in a uniform format. - - * Write just one definition command for each entity you define with a - definition command. The automatic indexing feature creates an - index entry that leads the reader to the definition. - - * Use `@table' ... `@end table' in an appendix that contains a - summary of functions, not `@deffn' or other definition commands. - -Capitalization -.............. - - * Capitalize "Texinfo"; it is a name. Do not write the `x' or `i' - in upper case. - - * Capitalize "Info"; it is a name. - - * Write TeX using the `@TeX{}' command. Note the uppercase `T' and - `X'. This command causes the formatters to typeset the name - according to the wishes of Donald Knuth, who wrote TeX. - -Spaces -...... - -Do not use spaces to format a Texinfo file, except inside of `@example' -... `@end example' and other literal environments and commands. - - For example, TeX fills the following: - - @kbd{C-x v} - @kbd{M-x vc-next-action} - Perform the next logical operation - on the version-controlled file - corresponding to the current buffer. - -so it looks like this: - - `C-x v' `M-x vc-next-action' Perform the next logical operation on - the version-controlled file corresponding to the current buffer. - -In this case, the text should be formatted with `@table', `@item', and -`@itemx', to create a table. - -@code, @samp, @var, and `---' -............................. - - * Use `@code' around Lisp symbols, including command names. For - example, - - The main function is @code{vc-next-action}, ... - - * Avoid putting letters such as `s' immediately after an `@code'. - Such letters look bad. - - * Use `@var' around meta-variables. Do not write angle brackets - around them. - - * Use three hyphens in a row, `---', to indicate a long dash. TeX - typesets these as a long dash and the Info formatters reduce three - hyphens to two. - -Periods Outside of Quotes -......................... - -Place periods and other punctuation marks _outside_ of quotations, -unless the punctuation is part of the quotation. This practice goes -against publishing conventions in the United States, but enables the -reader to distinguish between the contents of the quotation and the -whole passage. - - For example, you should write the following sentence with the period -outside the end quotation marks: - - Evidently, `au' is an abbreviation for ``author''. - -since `au' does _not_ serve as an abbreviation for `author.' (with a -period following the word). - -Introducing New Terms -..................... - - * Introduce new terms so that a reader who does not know them can - understand them from context; or write a definition for the term. - - For example, in the following, the terms "check in", "register" and - "delta" are all appearing for the first time; the example sentence - should be rewritten so they are understandable. - - The major function assists you in checking in a file to your - version control system and registering successive sets of - changes to it as deltas. - - * Use the `@dfn' command around a word being introduced, to indicate - that the reader should not expect to know the meaning already, and - should expect to learn the meaning from this passage. - -@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 ... -............... - - * Pronounce TeX as if the `X' were a Greek `chi', as the last sound - in the name `Bach'. But pronounce Texinfo as in `speck': - "teckinfo". - - * Write notes for yourself at the very end of a Texinfo file after - the `@bye'. None of the formatters process text after the `@bye'; - it is as if the text were within `@ignore' ... `@end ignore'. - - -File: texinfo, Node: Sample Texinfo Files, Next: Include Files, Prev: Tips, Up: Top - -Appendix C Sample Texinfo Files -******************************* - -The first example is from the first chapter (*note Short Sample::), -given here in its entirety, without commentary. The second includes -the full texts to be used in GNU manuals. - -* Menu: - -* Short Sample Texinfo File:: -* GNU Sample Texts:: -* Verbatim Copying License:: -* All-permissive Copying License:: - - -File: texinfo, Node: Short Sample Texinfo File, Next: GNU Sample Texts, Up: Sample Texinfo Files - -C.1 Short Sample -================ - -Here is a complete, short sample Texinfo file, without any commentary. -You can see this file, with comments, in the first chapter. *Note -Short Sample::. - - In a nutshell: The `makeinfo' program transforms a Texinfo source -file such as this into an Info file or HTML; and TeX typesets it for a -printed manual. - - - \input texinfo @c -*-texinfo-*- - @c %**start of header - @setfilename sample.info - @settitle Sample Manual 1.0 - @c %**end of header - - @copying - This is a short example of a complete Texinfo file. - - Copyright (C) 2005 Free Software Foundation, Inc. - @end copying - - @titlepage - @title Sample Title - @page - @vskip 0pt plus 1filll - @insertcopying - @end titlepage - - @c Output the table of the contents at the beginning. - @contents - - @ifnottex - @node Top - @top GNU Sample - - @insertcopying - @end ifnottex - - @menu - * First Chapter:: The first chapter is the - only chapter in this sample. - * Index:: Complete index. - @end menu - - - @node First Chapter - @chapter First Chapter - - @cindex chapter, first - - This is the first chapter. - @cindex index entry, another - - Here is a numbered list. - - @enumerate - @item - This is the first item. - - @item - This is the second item. - @end enumerate - - - @node Index - @unnumbered Index - - @printindex cp - - @bye - - -File: texinfo, Node: GNU Sample Texts, Next: Verbatim Copying License, Prev: Short Sample Texinfo File, Up: Sample Texinfo Files - -C.2 GNU Sample Texts -==================== - -Following is a sample Texinfo document with the full texts that should -be used in GNU manuals. - - As well as the legal texts, it also serves as a practical example of -how many elements in a GNU system can affect the manual. If you're not -familiar with all these different elements, don't worry. They're not -required and a perfectly good manual can be written without them. -They're included here nonetheless because many manuals do (or could) -benefit from them. - - *Note Short Sample::, for a minimal example of a Texinfo file. *Note -Beginning a File::, for a full explanation of that minimal example. - - Here are some notes on the example: - - * The `$Id:' comment is for the CVS (*note Overview: (cvs)Top.) or - RCS (`http://www.gnu.org/software/rcs') version control systems, - which expand it into a string such as: - $Id: texinfo.txi,v 1.220 2008/04/09 17:07:31 karl Exp $ - (This is useful in all sources that use version control, not just - manuals.) You may wish to include the `$Id:' comment in the - `@copying' text, if you want a completely unambiguous reference to - the documentation version. - - If you want to literally write $Id$, use `@w': `@w{$}Id$'. - - * The `version.texi' in the `@include' command is maintained - automatically by Automake (*note Introduction: (automake)Top.). - It sets the `VERSION' and `UPDATED' values used elsewhere. If - your distribution doesn't use Automake, but you do use Emacs, you - may find the time-stamp.el package helpful (*note Time Stamps: - (emacs)Time Stamps.). - - * The `@syncodeindex' command reflects the recommendation to use - only one index where possible, to make it easier for readers to - look up index entries. - - * The `@dircategory' is for constructing the Info directory. *Note - Installing Dir Entries::, which includes a variety of recommended - category names. - - * The `Invoking' node is a GNU standard to help users find the basic - information about command-line usage of a given program. *Note - Manual Structure Details: (standards)Manual Structure Details. - - * It is best to include the entire GNU Free Documentation License in - a GNU manual, unless the manual is only a few pages long. Of - course this sample is even shorter than that, but it includes the - FDL anyway in order to show one conventional way to do so. The - `fdl.texi' file is available on the GNU machines and in the - Texinfo and other GNU source distributions. - - The FDL provides for omitting itself under certain conditions, but - in that case the sample texts given here have to be modified. - *Note GNU Free Documentation License::. - - * If the FSF is not the copyright holder, then use the appropriate - name. - - * If your manual is not published on paper by the FSF, then omit the - last sentence in the Back-Cover Text that talks about copies from - GNU Press. - - * If your manual has Invariant Sections (again, see the license - itself for details), then change the text here accordingly. - - * For documents that express your personal views, feelings or - experiences, it is more appropriate to use a license permitting - only verbatim copying, rather than the FDL. *Note Verbatim - Copying License::. - - - Here is the sample document: - -\input texinfo @c -*-texinfo-*- -@comment $Id: texinfo.txi,v 1.220 2008/04/09 17:07:31 karl Exp $ -@comment %**start of header -@setfilename sample.info -@include version.texi -@settitle GNU Sample @value{VERSION} -@syncodeindex pg cp -@comment %**end of header -@copying -This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}), -which is an example in the Texinfo documentation. - -Copyright @copyright{} 2007 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.2 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the -license is included in the section entitled ``GNU Free Documentation -License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to -copy and modify this GNU manual. Buying copies from the FSF -supports it in developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Texinfo documentation system -@direntry -* sample: (sample)Invoking sample. -@end direntry - -@titlepage -@title GNU Sample -@subtitle for version @value{VERSION}, @value{UPDATED} -@author A.U. Thor (@email{bug-texinfo@@gnu.org}) -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top GNU Sample - -This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}). -@end ifnottex - -@menu -* Invoking sample:: -* Copying This Manual:: -* Index:: -@end menu - - -@node Invoking sample -@chapter Invoking sample - -@pindex sample -@cindex invoking @command{sample} - -This is a sample manual. There is no sample program to -invoke, but if there was, you could see its basic usage -and command line options here. - - -@node GNU Free Documentation License -@appendix GNU Free Documentation License - -@include fdl.texi - - -@node Index -@unnumbered Index - -@printindex cp - -@bye - - -File: texinfo, Node: Verbatim Copying License, Next: All-permissive Copying License, Prev: GNU Sample Texts, Up: Sample Texinfo Files - -C.3 Verbatim Copying License -============================ - -For software manuals and other documentation, it is 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{} 2005 Free Software Foundation, Inc. - -@quotation -Permission is granted to make and distribute verbatim copies -of this entire document without royalty provided the -copyright notice and this permission notice are preserved. -@end quotation -@end copying - - -File: texinfo, Node: All-permissive Copying License, Prev: Verbatim Copying License, Up: Sample Texinfo Files - -C.4 All-permissive Copying License -================================== - -For software manuals and other documentation, it is important to use a -license permitting free redistribution and updating, so that when a free -program is changed, the documentation can be updated as well. - - On the other hand, for small supporting files, short manuals (under -300 lines long) and rough documentation (README files, INSTALL files, -etc.), the full FDL would be overkill. They can use a simple -all-permissive license. - - Here is sample text for such an all-permissive license. This is just -the license text itself. For a complete sample document, see the -previous sections. - - Copyright (C) 2005 Free Software Foundation, Inc. - - Copying and distribution of this file, with or without modification, - are permitted in any medium without royalty provided the copyright - notice and this notice are preserved. - - -File: texinfo, Node: Include Files, Next: Headings, Prev: 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. - -* Menu: - -* Using Include Files:: How to use the `@include' command. -* texinfo-multiple-files-update:: How to create and update nodes and - menus when using included files. -* Include Files Requirements:: `texinfo-multiple-files-update' needs. -* Sample Include File:: A sample outer file with included files - within it; and a sample included file. -* Include Files Evolution:: How use of the `@include' command - has changed over time. - - -File: texinfo, Node: Using Include Files, Next: texinfo-multiple-files-update, 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. *Note -`@verbatiminclude': 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 (*note GNU -Sample Texts::). - - -File: texinfo, Node: texinfo-multiple-files-update, Next: Include Files Requirements, Prev: 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. - - -File: texinfo, Node: Include Files Requirements, Next: Sample Include File, Prev: 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. - - -File: texinfo, Node: Sample Include File, Next: Include Files Evolution, Prev: 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 - - ... *Note 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. - - -File: texinfo, Node: Include Files Evolution, Prev: 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. (*Note Referring to Other Info Files: -Other Info Files. Also, see *note `@xref' with Four and Five -Arguments: 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. - - -File: texinfo, Node: Headings, Next: Catching Mistakes, Prev: 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.) - -* Menu: - -* Headings Introduced:: Conventions for using page headings. -* Heading Format:: Standard page heading formats. -* Heading Choice:: How to specify the type of page heading. -* Custom Headings:: How to create your own headings and footings. - - -File: texinfo, Node: Headings Introduced, Next: Heading Format, 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. - - -File: texinfo, Node: Heading Format, Next: Heading Choice, Prev: 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. - - -File: texinfo, Node: Heading Choice, Next: Custom Headings, Prev: 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 *note The `@headings' Command: headings on off.) - -`@setchapternewpage odd' - Specify the double-sided heading format, with chapters on new - pages. - -Texinfo lacks an `@setchapternewpage even' command. - - -File: texinfo, Node: Custom Headings, Prev: 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: - * `@everyheading' `@everyfooting' generate page headers and footers - that are the same for both even- and odd-numbered pages. - - * `@evenheading' and `@evenfooting' command generate headers and - footers for even-numbered (left-hand) pages. - - * `@oddheading' and `@oddfooting' generate headers and footers for - odd-numbered (right-hand) pages. - - Write custom heading specifications in the Texinfo file immediately -after the `@end titlepage' command. You must cancel the predefined -heading commands with the `@headings off' command before defining your -own specifications. - - Here is how to tell TeX to place the chapter name at the left, the -page number in the center, and the date at the right of every header -for both even- and odd-numbered pages: - - @headings off - @everyheading @thischapter @| @thispage @| @today{} - -You need to divide the left part from the central part and the central -part from the right part by inserting `@|' between parts. Otherwise, -the specification command will not be able to tell where the text for -one part ends and the next part begins. - - Each part can contain text or @-commands. The text is printed as if -the part were within an ordinary paragraph in the body of the page. -The @-commands replace themselves with the page number, date, chapter -name, or whatever. - - Here are the six heading and footing commands: - -`@everyheading LEFT @| CENTER @| RIGHT' -`@everyfooting LEFT @| CENTER @| RIGHT' - The `every' commands specify the format for both even- and - odd-numbered pages. These commands are for documents that are - printed on one side of each sheet of paper, or for documents in - which you want symmetrical headers or footers. - -`@evenheading LEFT @| CENTER @| RIGHT' -`@oddheading LEFT @| CENTER @| RIGHT' -`@evenfooting LEFT @| CENTER @| RIGHT' -`@oddfooting LEFT @| CENTER @| RIGHT' - The `even' and `odd' commands specify the format for even-numbered - pages and odd-numbered pages. These commands are for books and - manuals that are printed on both sides of each sheet of paper. - - Use the `@this...' series of @-commands to provide the names of -chapters and sections and the page number. You can use the `@this...' -commands in the left, center, or right portions of headers and footers, -or anywhere else in a Texinfo file so long as they are between `@iftex' -and `@end iftex' commands. - - Here are the `@this...' commands: - -`@thispage' - Expands to the current page number. - -`@thissectionname' - Expands to the name of the current section. - -`@thissectionnum' - Expands to the number of the current section. - -`@thissection' - Expands to the number and name of the current section, in the - format `Section 1: Title'. - -`@thischaptername' - Expands to the name of the current chapter. - -`@thischapternum' - Expands to the number of the current chapter, or letter of the - current appendix. - -`@thischapter' - Expands to the number and name of the current chapter, in the - format `Chapter 1: Title'. - -`@thistitle' - Expands to the name of the document, as specified by the - `@settitle' command. - -`@thisfile' - For `@include' files only: expands to the name of the current - `@include' file. If the current Texinfo source file is not an - `@include' file, this command has no effect. This command does - _not_ provide the name of the current Texinfo source file unless - it is an `@include' file. (*Note Include Files::, for more - information about `@include' files.) - -You can also use the `@today{}' command, which expands to the current -date, in `1 Jan 1900' format. - - Other @-commands and text are printed in a header or footer just as -if they were in the body of a page. It is useful to incorporate text, -particularly when you are writing drafts: - - @headings off - @everyheading @emph{Draft!} @| @thispage @| @thischapter - @everyfooting @| @| Version: 0.27: @today{} - - Beware of overlong titles: they may overlap another part of the -header or footer and blot it out. - - If you have very short chapters and/or sections, several of them can -appear on a single page. You can specify which chapters and sections -you want `@thischapter', `@thissection' and other such macros to refer -to on such pages as follows: - -`@everyheadingmarks REF' -`@everyfootingmarks REF' - The REF argument can be either `top' (the `@this...' commands will - refer to the chapter/section at the top of a page) or `bottom' - (the commands will reflect the situation at the bottom of a page). - These `@every...' commands specify what to do on both even- and - odd-numbered pages. - -`@evenheadingmarks REF' -`@oddheadingmarks REF' -`@evenfootingmarks REF' -`@oddfootingmarks REF' - These `@even...' and `@odd...' commands specify what to do on only - even- or odd-numbered pages, respectively. The REF argument is - the same as with the `@every...' commands. - - Write these commands immediately after the `@...contents' commands, -or after the `@end titlepage' command if you don't have a table of -contents or if it is printed at the end of your manual. - - By default the `@this...' commands reflect the situation at the -bottom of a page both in headings and in footings. - - -File: texinfo, Node: Catching Mistakes, Next: GNU Free Documentation License, Prev: 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. - -* Menu: - -* makeinfo Preferred:: `makeinfo' finds errors. -* Debugging with Info:: How to catch errors with Info formatting. -* Debugging with TeX:: How to catch errors with TeX formatting. -* Using texinfo-show-structure:: How to use `texinfo-show-structure'. -* Using occur:: How to list all lines containing a pattern. -* Running Info-Validate:: How to find badly referenced nodes. - - -File: texinfo, Node: makeinfo Preferred, Next: Debugging with Info, 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. - - -File: texinfo, Node: Debugging with Info, Next: Debugging with TeX, Prev: 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').) - - -File: texinfo, Node: Debugging with TeX, Next: Using texinfo-show-structure, Prev: 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. (*Note Debugging with Info::, for more -information.) - - For example, TeX was run on a Texinfo file, part of which is shown -here: - - ---------- Buffer: texinfo.texi ---------- - name of the Texinfo file as an extension. The - @samp{??} are `wildcards' that cause the shell to - substitute all the raw index files. (@xref{sorting - indices, for more information about sorting - indices.)@refill - ---------- Buffer: texinfo.texi ---------- - -(The cross reference lacks a closing brace.) TeX produced the -following output, after which it stopped: - - ---------- Buffer: *tex-shell* ---------- - Runaway argument? - {sorting indices, for more information about sorting - indices.) @refill @ETC. - ! Paragraph ended before @xref was complete. - <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.) - - -File: texinfo, Node: Using texinfo-show-structure, Next: Using occur, Prev: 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. *Note Using Occur: (emacs)Other Repeating -Search, for more information about `occur-mode-goto-occurrence'. - - The first line in the `*Occur*' window describes the "regular -expression" specified by TEXINFO-HEADING-PATTERN. This regular -expression is the pattern that `texinfo-show-structure' looks for. -*Note Using Regular Expressions: (emacs)Regexps, for more information. - - When you invoke the `texinfo-show-structure' command, Emacs will -display the structure of the whole buffer. If you want to see the -structure of just a part of the buffer, of one chapter, for example, -use the `C-x n n' (`narrow-to-region') command to mark the region. -(*Note Narrowing: (emacs)Narrowing.) This is how the example used -above was generated. (To see the whole buffer again, use `C-x n w' -(`widen').) - - If you call `texinfo-show-structure' with a prefix argument by typing -`C-u C-c C-s', it will list lines beginning with `@node' as well as the -lines beginning with the @-sign commands for `@chapter', `@section', -and the like. - - You can remind yourself of the structure of a Texinfo file by looking -at the list in the `*Occur*' window; and if you have mis-named a node -or left out a section, you can correct the mistake. - - -File: texinfo, Node: Using occur, Next: Running Info-Validate, Prev: 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. (*Note Regular Expressions: -(emacs)Regexps.) The `occur' command works from the current location -of the cursor in the buffer to the end of the buffer. If you want to -run `occur' on the whole buffer, place the cursor at the beginning of -the buffer. - - For example, to see all the lines that contain the word `@chapter' in -them, just type `@chapter'. This will produce a list of the chapters. -It will also list all the sentences with `@chapter' in the middle of -the line. - - If you want to see only those lines that start with the word -`@chapter', type `^@chapter' when prompted by `occur'. If you want to -see all the lines that end with a word or phrase, end the last word -with a `$'; for example, `catching mistakes$'. This can be helpful -when you want to see all the nodes that are part of the same chapter or -section and therefore have the same `Up' pointer. - - *Note Using Occur: (emacs)Other Repeating Search, for more -information. - - -File: texinfo, Node: Running Info-Validate, Prev: 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. - -* Menu: - -* Using Info-validate:: How to run `Info-validate'. -* Unsplit:: How to create an unsplit file. -* Tagifying:: How to tagify a file. -* Splitting:: How to split a file manually. - - -File: texinfo, Node: Using Info-validate, Next: Unsplit, 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'. -*Note Tagifying::. - - If your file is valid, you will receive a message that says "File -appears valid". However, if you have a pointer that does not point to -a node, error messages will be displayed in a buffer called `*problems -in info file*'. - - For example, `Info-validate' was run on a test file that contained -only the first node of this manual. One of the messages said: - - In node "Overview", invalid Next: Texinfo Mode - -This meant that the node called `Overview' had a `Next' pointer that -did not point to anything (which was true in this case, since the test -file had only one node in it). - - Now suppose we add a node named `Texinfo Mode' to our test case but -we do not specify a `Previous' for this node. Then we will get the -following error message: - - In node "Texinfo Mode", should have Previous: Overview - -This is because every `Next' pointer should be matched by a `Previous' -(in the node where the `Next' points) which points back. - - `Info-validate' also checks that all menu entries and cross references -point to actual nodes. - - `Info-validate' requires a tag table and does not work with files -that have been split. (The `texinfo-format-buffer' command -automatically splits large files.) In order to use `Info-validate' on -a large file, you must run `texinfo-format-buffer' with an argument so -that it does not split the Info file; and you must create a tag table -for the unsplit file. - - -File: texinfo, Node: Unsplit, Next: Tagifying, Prev: 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. - - -File: texinfo, Node: Tagifying, Next: Splitting, Prev: 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. - - -File: texinfo, Node: Splitting, Prev: 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. *Note -Creating an Info File::.) - - The split-off files are called the indirect subfiles. - - Info files are split to save memory. With smaller files, Emacs does -not have make such a large buffer to hold the information. - - If an Info file has more than 30 nodes, you should also make a tag -table for it. *Note Using Info-validate::, for information about -creating a tag table. (Again, tag tables are usually created -automatically by the formatting command; you only need to create a tag -table yourself if you are doing the job manually. Most likely, you -will do this for a large, unsplit file on which you have run -`Info-validate'.) - - Visit the Info file you wish to tagify and split and type the two -commands: - - M-x Info-tagify - M-x Info-split - -(Note that the `I' in `Info' is 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. - - -File: texinfo, Node: GNU Free Documentation License, Next: Command and Variable Index, Prev: Catching Mistakes, Up: Top - -Appendix G GNU Free Documentation License -***************************************** - - Version 1.2, November 2002 - - Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. - 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - 0. 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. - - 1. 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. - - 2. 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. - - 3. 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. - - 4. 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: - - A. 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. - - B. 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. - - C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. - - D. Preserve all the copyright notices of the Document. - - E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - - F. 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. - - G. Preserve in that license notice the full lists of Invariant - Sections and required Cover Texts given in the Document's - license notice. - - H. Include an unaltered copy of this License. - - I. 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. - - J. 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. - - K. 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. - - L. 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. - - M. Delete any section Entitled "Endorsements". Such a section - may not be included in the Modified Version. - - N. Do not retitle any existing section to be Entitled - "Endorsements" or to conflict in title with any Invariant - Section. - - O. 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. - - 5. 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." - - 6. 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. - - 7. 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. - - 8. 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. - - 9. 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. - - 10. 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. - -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. - - -File: texinfo, Node: Command and Variable Index, Next: General Index, Prev: GNU Free Documentation License, 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 `@'. - - -* Menu: - -* ! (end of sentence): Ending a Sentence. (line 6) -* " (umlaut accent): Inserting Accents. (line 18) -* ' (umlaut accent): Inserting Accents. (line 18) -* * (force line break): Line Breaks. (line 6) -* , (cedilla accent): Inserting Accents. (line 18) -* - (discretionary hyphen): - and hyphenation. (line 6) -* - (in image alt string): Image Syntax. (line 39) -* . (end of sentence): Ending a Sentence. (line 6) -* / (allow line break): Line Breaks. (line 6) -* <colon> (suppress end-of-sentence space): Not Ending a Sentence. - (line 16) -* <newline>: Multiple Spaces. (line 6) -* <space>: Multiple Spaces. (line 6) -* <tab>: Multiple Spaces. (line 6) -* = (macron accent): Inserting Accents. (line 18) -* ? (end of sentence): Ending a Sentence. (line 6) -* @ (literal @): Inserting an Atsign. (line 6) -* \ (literal \ in @math): math. (line 42) -* \emergencystretch: Overfull hboxes. (line 31) -* \gdef within @tex: Raw Formatter Commands. - (line 29) -* \input (raw TeX startup): Minimum. (line 24) -* \mag (raw TeX magnification): Cropmarks and Magnification. - (line 24) -* ^ (circumflex accent): Inserting Accents. (line 18) -* ` (grave accent): Inserting Accents. (line 18) -* AA: Inserting Accents. (line 39) -* aa: Inserting Accents. (line 39) -* abbr: abbr. (line 6) -* acronym: acronym. (line 6) -* AE: Inserting Accents. (line 39) -* ae: Inserting Accents. (line 39) -* afourlatex: A4 Paper. (line 23) -* afourpaper: A4 Paper. (line 6) -* afourwide: A4 Paper. (line 23) -* alias: alias. (line 6) -* allowcodebreaks: allowcodebreaks. (line 6) -* anchor: anchor. (line 6) -* appendix: unnumbered & appendix. - (line 6) -* appendixsec: unnumberedsec appendixsec heading. - (line 6) -* appendixsection: unnumberedsec appendixsec heading. - (line 19) -* appendixsubsec: unnumberedsubsec appendixsubsec subheading. - (line 6) -* appendixsubsubsec: subsubsection. (line 6) -* apply: Sample Function Definition. - (line 14) -* arrow: Click Sequences. (line 17) -* asis: table. (line 20) -* author: title subtitle author. - (line 6) -* b (bold font): Fonts. (line 30) -* bullet: bullet. (line 6) -* bye <1>: File End. (line 6) -* bye: Ending a File. (line 6) -* c (comment): Comments. (line 6) -* caption: caption shortcaption. - (line 6) -* cartouche: cartouche. (line 6) -* center: titlefont center sp. (line 6) -* centerchap: chapter. (line 25) -* chapheading: majorheading & chapheading. - (line 6) -* chapter: chapter. (line 6) -* cite: cite. (line 6) -* clear: set value. (line 6) -* click: Click Sequences. (line 17) -* clicksequence: Click Sequences. (line 6) -* clickstyle: Click Sequences. (line 21) -* code: code. (line 6) -* columnfractions: Multitable Column Widths. - (line 11) -* comma: Inserting a Comma. (line 6) -* command: command. (line 6) -* comment: Comments. (line 6) -* contents: Contents. (line 6) -* copying: copying. (line 6) -* copyright <1>: copyright symbol. (line 6) -* copyright: copying. (line 37) -* cropmarks: Cropmarks and Magnification. - (line 6) -* defcodeindex: New Indices. (line 6) -* defcv: Object-Oriented Variables. - (line 10) -* deffn: Functions Commands. (line 9) -* deffnx: deffnx. (line 6) -* defindex: New Indices. (line 6) -* definfoenclose: definfoenclose. (line 6) -* defivar: Object-Oriented Variables. - (line 47) -* defmac: Functions Commands. (line 58) -* defmethod: Object-Oriented Methods. - (line 59) -* defop: Object-Oriented Methods. - (line 11) -* defopt: Variables Commands. (line 56) -* defspec: Functions Commands. (line 63) -* deftp: Data Types. (line 8) -* deftypecv: Object-Oriented Variables. - (line 28) -* deftypefn: Typed Functions. (line 10) -* deftypefun: Typed Functions. (line 76) -* deftypeivar: Object-Oriented Variables. - (line 63) -* deftypeop: Object-Oriented Methods. - (line 51) -* deftypevar: Typed Variables. (line 40) -* deftypevr: Typed Variables. (line 12) -* defun: Functions Commands. (line 48) -* defvar: Variables Commands. (line 38) -* defvr: Variables Commands. (line 8) -* detailmenu <1>: makeinfo Pointer Creation. - (line 24) -* detailmenu: Master Menu Parts. (line 18) -* dfn: dfn. (line 6) -* dircategory: Installing Dir Entries. - (line 11) -* direntry: Installing Dir Entries. - (line 11) -* display: display. (line 6) -* dmn: dmn. (line 6) -* docbook: Raw Formatter Commands. - (line 53) -* documentdescription: documentdescription. (line 6) -* documentencoding <1>: documentencoding. (line 6) -* documentencoding <2>: Inserting Quotation Marks. - (line 24) -* documentencoding: Inserting Accents. (line 13) -* documentlanguage: documentlanguage. (line 6) -* dotaccent: Inserting Accents. (line 18) -* dotless: Inserting Accents. (line 39) -* dots: dots. (line 6) -* email: email. (line 6) -* emph: emph & strong. (line 6) -* end <1>: Introducing Lists. (line 20) -* end: Quotations and Examples. - (line 10) -* end titlepage: end titlepage. (line 6) -* enddots: dots. (line 6) -* enumerate: enumerate. (line 6) -* env: env. (line 6) -* equiv: Equivalence. (line 6) -* error: Error Glyph. (line 6) -* euro: euro. (line 6) -* evenfooting: Custom Headings. (line 55) -* evenfootingmarks: Custom Headings. (line 134) -* evenheading: Custom Headings. (line 55) -* evenheadingmarks: Custom Headings. (line 134) -* everyfooting: Custom Headings. (line 46) -* everyfootingmarks: Custom Headings. (line 124) -* everyheading: Custom Headings. (line 46) -* everyheadingmarks: Custom Headings. (line 124) -* example: example. (line 6) -* exampleindent: exampleindent. (line 6) -* exclamdown: Inserting Accents. (line 39) -* exdent: exdent. (line 6) -* expansion: expansion. (line 6) -* file: file. (line 6) -* filll TeX dimension: Copyright. (line 12) -* finalout: Overfull hboxes. (line 46) -* firstparagraphindent: firstparagraphindent. - (line 6) -* float: float. (line 6) -* flushleft: flushleft & flushright. - (line 6) -* flushright: flushleft & flushright. - (line 6) -* fn-name: Def Cmd Continuation Lines. - (line 19) -* fonttextsize: Fonts. (line 6) -* foobar: Optional Arguments. (line 23) -* footnote: Footnotes. (line 6) -* footnotestyle: Footnote Styles. (line 44) -* format: format. (line 6) -* forward-word: Def Cmd Template. (line 35) -* frenchspacing: frenchspacing. (line 6) -* ftable: ftable vtable. (line 6) -* geq: geq leq. (line 6) -* group: group. (line 6) -* guillemetleft: Inserting Quotation Marks. - (line 43) -* guillemetright: Inserting Quotation Marks. - (line 43) -* guillemotleft: Inserting Quotation Marks. - (line 43) -* guillemotright: Inserting Quotation Marks. - (line 43) -* guilsinglleft: Inserting Quotation Marks. - (line 43) -* guilsinglright: Inserting Quotation Marks. - (line 43) -* H (Hungarian umlaut accent): Inserting Accents. (line 18) -* hbox: Overfull hboxes. (line 14) -* heading: unnumberedsec appendixsec heading. - (line 6) -* headings: headings on off. (line 6) -* headitem: Multitable Rows. (line 12) -* headword: definfoenclose. (line 58) -* html: Raw Formatter Commands. - (line 45) -* hyphenation: - and hyphenation. (line 6) -* i (italic font): Fonts. (line 33) -* ifclear: ifset ifclear. (line 47) -* ifdocbook <1>: Raw Formatter Commands. - (line 53) -* ifdocbook: Conditional Commands. - (line 14) -* ifhtml <1>: Raw Formatter Commands. - (line 45) -* ifhtml: Conditional Commands. - (line 14) -* ifinfo: Conditional Commands. - (line 9) -* ifnotdocbook: Conditional Not Commands. - (line 6) -* ifnothtml: Conditional Not Commands. - (line 6) -* ifnotinfo: Conditional Not Commands. - (line 6) -* ifnotplaintext: Conditional Not Commands. - (line 6) -* ifnottex: Conditional Not Commands. - (line 6) -* ifnotxml: Conditional Not Commands. - (line 6) -* ifplaintext: Conditional Commands. - (line 14) -* ifset: ifset ifclear. (line 6) -* iftex: Conditional Commands. - (line 14) -* ifxml <1>: Raw Formatter Commands. - (line 49) -* ifxml: Conditional Commands. - (line 14) -* ignore: Comments. (line 19) -* image: Images. (line 6) -* include: Using Include Files. (line 6) -* indent: indent. (line 6) -* indicateurl: indicateurl. (line 6) -* Info-validate: Running Info-Validate. - (line 6) -* inforef: inforef. (line 6) -* insertcopying: insertcopying. (line 6) -* isearch-backward: deffnx. (line 22) -* isearch-forward: deffnx. (line 21) -* item <1>: Multitable Rows. (line 6) -* item <2>: table. (line 31) -* item: itemize. (line 22) -* itemize: itemize. (line 6) -* itemx: itemx. (line 6) -* kbd: kbd. (line 6) -* kbdinputstyle: kbd. (line 26) -* key: key. (line 6) -* L: Inserting Accents. (line 39) -* l: Inserting Accents. (line 39) -* LaTeX: tex. (line 6) -* leq: geq leq. (line 6) -* lisp: lisp. (line 6) -* listoffloats: listoffloats. (line 6) -* lowersections: Raise/lower sections. - (line 6) -* macro: Defining Macros. (line 6) -* majorheading: majorheading & chapheading. - (line 6) -* makeinfo-buffer: makeinfo in Emacs. (line 16) -* makeinfo-kill-job: makeinfo in Emacs. (line 37) -* makeinfo-recenter-output-buffer: makeinfo in Emacs. (line 42) -* makeinfo-region: makeinfo in Emacs. (line 12) -* math: math. (line 6) -* menu: Menus. (line 6) -* minus: minus. (line 6) -* multitable: Multi-column Tables. (line 6) -* need: need. (line 6) -* next-error: makeinfo in Emacs. (line 26) -* node: node. (line 6) -* noindent: noindent. (line 6) -* novalidate: Format with tex/texindex. - (line 83) -* O: Inserting Accents. (line 39) -* o: Inserting Accents. (line 39) -* occur: Using occur. (line 6) -* occur-mode-goto-occurrence: Showing the Structure. - (line 22) -* oddfooting: Custom Headings. (line 55) -* oddfootingmarks: Custom Headings. (line 134) -* oddheading: Custom Headings. (line 55) -* oddheadingmarks: Custom Headings. (line 134) -* OE: Inserting Accents. (line 39) -* oe: Inserting Accents. (line 39) -* option: option. (line 6) -* ordf: Inserting Accents. (line 39) -* ordm: Inserting Accents. (line 39) -* page: page. (line 6) -* page, within @titlepage: titlepage. (line 17) -* pagesizes: pagesizes. (line 6) -* paragraphindent: paragraphindent. (line 6) -* phoo: definfoenclose. (line 35) -* point: Point Glyph. (line 6) -* pounds: pounds. (line 6) -* print: Print Glyph. (line 6) -* printindex: Printing Indices & Menus. - (line 23) -* pxref: pxref. (line 6) -* questiondown: Inserting Accents. (line 39) -* quotation: quotation. (line 6) -* quotedblbase: Inserting Quotation Marks. - (line 43) -* quotedblleft: Inserting Quotation Marks. - (line 43) -* quotedblright: Inserting Quotation Marks. - (line 43) -* quoteleft: Inserting Quotation Marks. - (line 43) -* quoteright: Inserting Quotation Marks. - (line 43) -* quotesinglbase: Inserting Quotation Marks. - (line 43) -* r (roman font): Fonts. (line 36) -* raisesections: Raise/lower sections. - (line 6) -* ref: ref. (line 6) -* registeredsymbol: registered symbol. (line 6) -* result: result. (line 6) -* ringaccent: Inserting Accents. (line 18) -* rmacro: Defining Macros. (line 44) -* samp: samp. (line 6) -* sansserif (sans serif font): Fonts. (line 40) -* sc (small caps font): Smallcaps. (line 6) -* section: section. (line 6) -* set: set value. (line 6) -* setchapternewpage: setchapternewpage. (line 6) -* setcontentsaftertitlepage: Contents. (line 51) -* setfilename: setfilename. (line 6) -* setshortcontentsaftertitlepage: Contents. (line 51) -* settitle: settitle. (line 6) -* shortcaption: caption shortcaption. - (line 6) -* shortcontents: Contents. (line 6) -* shorttitlepage: titlepage. (line 46) -* slanted (slanted font): Fonts. (line 43) -* smallbook: smallbook. (line 6) -* smalldisplay <1>: display. (line 17) -* smalldisplay: small. (line 6) -* smallexample: small. (line 6) -* smallformat <1>: format. (line 15) -* smallformat: small. (line 6) -* smalllisp: small. (line 6) -* sp (line spacing): sp. (line 6) -* sp (titlepage line spacing): titlefont center sp. (line 6) -* ss: Inserting Accents. (line 39) -* strong: emph & strong. (line 6) -* subheading: unnumberedsubsec appendixsubsec subheading. - (line 6) -* subsection: subsection. (line 6) -* subsubheading: subsubsection. (line 6) -* subsubsection: subsubsection. (line 6) -* subtitle: title subtitle author. - (line 6) -* summarycontents: Contents. (line 6) -* syncodeindex: syncodeindex. (line 6) -* synindex: synindex. (line 6) -* t (typewriter font): Fonts. (line 46) -* tab: Multitable Rows. (line 6) -* table: Two-column Tables. (line 6) -* tex: Raw Formatter Commands. - (line 21) -* TeX: tex. (line 6) -* texinfo-all-menus-update: Updating Commands. (line 112) -* texinfo-every-node-update: Updating Commands. (line 107) -* texinfo-format-buffer <1>: texinfo-format commands. - (line 23) -* texinfo-format-buffer: Info Formatting. (line 22) -* texinfo-format-region <1>: texinfo-format commands. - (line 19) -* texinfo-format-region: Info Formatting. (line 13) -* texinfo-indent-menu-description: Other Updating Commands. - (line 45) -* texinfo-insert-@code: Inserting. (line 15) -* texinfo-insert-@dfn: Inserting. (line 19) -* texinfo-insert-@end: Inserting. (line 23) -* texinfo-insert-@example: Inserting. (line 62) -* texinfo-insert-@item: Inserting. (line 30) -* texinfo-insert-@kbd: Inserting. (line 35) -* texinfo-insert-@node: Inserting. (line 39) -* texinfo-insert-@noindent: Inserting. (line 44) -* texinfo-insert-@samp: Inserting. (line 49) -* texinfo-insert-@table: Inserting. (line 53) -* texinfo-insert-@var: Inserting. (line 58) -* texinfo-insert-braces: Inserting. (line 67) -* texinfo-insert-node-lines: Other Updating Commands. - (line 10) -* texinfo-make-menu: Updating Commands. (line 93) -* texinfo-master-menu: Updating Commands. (line 55) -* texinfo-multiple-files-update: texinfo-multiple-files-update. - (line 6) -* texinfo-multiple-files-update (in brief): Other Updating Commands. - (line 34) -* texinfo-sequential-node-update: Other Updating Commands. - (line 54) -* texinfo-show-structure <1>: Using texinfo-show-structure. - (line 6) -* texinfo-show-structure: Showing the Structure. - (line 18) -* texinfo-start-menu-description: Inserting. (line 94) -* texinfo-tex-buffer: Printing. (line 21) -* texinfo-tex-print: Printing. (line 42) -* texinfo-tex-region: Printing. (line 27) -* texinfo-update-node: Updating Commands. (line 83) -* textdegree: textdegree. (line 6) -* thischapter: Custom Headings. (line 88) -* thischaptername: Custom Headings. (line 81) -* thischapternum: Custom Headings. (line 84) -* thisfile: Custom Headings. (line 96) -* thispage: Custom Headings. (line 68) -* thissection: Custom Headings. (line 77) -* thissectionname: Custom Headings. (line 71) -* thissectionnum: Custom Headings. (line 74) -* thistitle: Custom Headings. (line 92) -* tie (unbreakable interword space): tie. (line 6) -* tieaccent: Inserting Accents. (line 18) -* title: title subtitle author. - (line 6) -* titlefont: titlefont center sp. (line 6) -* titlepage: titlepage. (line 6) -* today: Custom Headings. (line 104) -* top: The Top Node. (line 12) -* top (@-command): makeinfo top command. - (line 6) -* u (breve accent): Inserting Accents. (line 18) -* ubaraccent: Inserting Accents. (line 18) -* udotaccent: Inserting Accents. (line 18) -* unmacro: Defining Macros. (line 56) -* unnumbered: unnumbered & appendix. - (line 6) -* unnumberedsec: unnumberedsec appendixsec heading. - (line 6) -* unnumberedsubsec: unnumberedsubsec appendixsubsec subheading. - (line 6) -* unnumberedsubsubsec: subsubsection. (line 6) -* up-list: Inserting. (line 72) -* uref: uref. (line 6) -* v (check accent): Inserting Accents. (line 18) -* value: set value. (line 6) -* var: var. (line 6) -* verb: verb. (line 6) -* verbatim: verbatim. (line 6) -* verbatiminclude: verbatiminclude. (line 6) -* vskip TeX vertical skip: Copyright. (line 12) -* vtable: ftable vtable. (line 6) -* w (prevent line break): w. (line 6) -* xml: Raw Formatter Commands. - (line 49) -* xref: xref. (line 6) -* { (literal {): Inserting Braces. (line 6) -* } (literal }): Inserting Braces. (line 6) -* ~ (tilde accent): Inserting Accents. (line 18) - - -File: texinfo, Node: General Index, Prev: Command and Variable Index, Up: Top - -General Index -************* - - -* Menu: - -* !: Inserting Accents. (line 39) -* ": Inserting Quotation Marks. - (line 43) -* " (double low-9 quotation mark): Inserting Quotation Marks. - (line 43) -* $Id: GNU Sample Texts. (line 21) -* $Id expansion, preventing: w. (line 28) -* ': Inserting Quotation Marks. - (line 43) -* (dir) as Up node of Top node: First Node. (line 13) -* , (single low-9 quotation mark): Inserting Quotation Marks. - (line 43) -* -, breakpoint within @code: allowcodebreaks. (line 6) -* --align=COLUMN: Invoking install-info. - (line 37) -* --calign=COLUMN: Invoking install-info. - (line 47) -* --command (texi2dvi): Format with texi2dvi. - (line 23) -* --commands-in-node-names: makeinfo options. (line 34) -* --css-include: makeinfo options. (line 41) -* --css-ref: makeinfo options. (line 46) -* --debug: Invoking install-info. - (line 55) -* --delete: Invoking install-info. - (line 58) -* --description=TEXT: Invoking install-info. - (line 64) -* --dir-file=NAME: Invoking install-info. - (line 69) -* --disable-encoding: makeinfo options. (line 52) -* --docbook: makeinfo options. (line 59) -* --document-language: makeinfo options. (line 62) -* --dry-run: Invoking install-info. - (line 73) -* --enable-encoding <1>: makeinfo options. (line 52) -* --enable-encoding: documentencoding. (line 43) -* --entry=TEXT: Invoking install-info. - (line 76) -* --error-limit=LIMIT: makeinfo options. (line 69) -* --fill-column=WIDTH: makeinfo options. (line 75) -* --footnote-style, ignored in HTML output: HTML Translation. (line 13) -* --footnote-style=STYLE: makeinfo options. (line 84) -* --force: makeinfo options. (line 95) -* --help <1>: Invoking install-info. - (line 83) -* --help: makeinfo options. (line 100) -* --html: makeinfo options. (line 104) -* --ifdocbook: makeinfo options. (line 118) -* --ifhtml: makeinfo options. (line 119) -* --ifinfo: makeinfo options. (line 120) -* --ifplaintext: makeinfo options. (line 121) -* --iftex: makeinfo options. (line 122) -* --ifxml: makeinfo options. (line 123) -* --info-dir=DIR: Invoking install-info. - (line 91) -* --info-file=FILE: Invoking install-info. - (line 87) -* --infodir=DIR: Invoking install-info. - (line 95) -* --item=TEXT: Invoking install-info. - (line 98) -* --keep-old: Invoking install-info. - (line 102) -* --language (texi2dvi): Format with texi2dvi. - (line 42) -* --macro-expand=FILE: makeinfo options. (line 130) -* --max-width=COLUMN: Invoking install-info. - (line 106) -* --maxwidth=COLUMN: Invoking install-info. - (line 110) -* --menuentry=TEXT: Invoking install-info. - (line 113) -* --name=TEXT: Invoking install-info. - (line 116) -* --no-headers: makeinfo options. (line 138) -* --no-ifdocbook: makeinfo options. (line 153) -* --no-ifhtml: makeinfo options. (line 154) -* --no-ifinfo: makeinfo options. (line 155) -* --no-ifplaintext: makeinfo options. (line 156) -* --no-iftex: makeinfo options. (line 157) -* --no-ifxml: makeinfo options. (line 158) -* --no-indent: Invoking install-info. - (line 126) -* --no-number-footnotes: makeinfo options. (line 164) -* --no-number-sections: makeinfo options. (line 169) -* --no-pointer-validate: makeinfo options. (line 181) -* --no-split: makeinfo options. (line 173) -* --no-validate: makeinfo options. (line 181) -* --no-warn: makeinfo options. (line 188) -* --number-sections: makeinfo options. (line 191) -* --output=FILE: makeinfo options. (line 197) -* --paragraph-indent=INDENT: makeinfo options. (line 211) -* --pdf (texi2dvi): Format with texi2dvi. - (line 32) -* --plaintext: makeinfo options. (line 138) -* --quiet: Invoking install-info. - (line 129) -* --recode (texi2dvi): Format with texi2dvi. - (line 58) -* --recode-from (texi2dvi): Format with texi2dvi. - (line 64) -* --regex=REGEX: Invoking install-info. - (line 167) -* --remove: Invoking install-info. - (line 133) -* --remove-exactly: Invoking install-info. - (line 136) -* --section REGEX SEC: Invoking install-info. - (line 148) -* --section=SEC: Invoking install-info. - (line 140) -* --silent: Invoking install-info. - (line 130) -* --split-size=NUM: makeinfo options. (line 226) -* --test: Invoking install-info. - (line 173) -* --translate-file (texi2dvi): Format with texi2dvi. - (line 53) -* --transliterate-file-names: makeinfo options. (line 229) -* --verbose: makeinfo options. (line 238) -* --version <1>: Invoking install-info. - (line 176) -* --version: makeinfo options. (line 244) -* --xml: makeinfo options. (line 247) -* -D VAR: makeinfo options. (line 30) -* -E FILE: makeinfo options. (line 130) -* -e LIMIT: makeinfo options. (line 69) -* -F: makeinfo options. (line 95) -* -f WIDTH: makeinfo options. (line 75) -* -h: makeinfo options. (line 100) -* -I DIR: makeinfo options. (line 110) -* -o FILE: makeinfo options. (line 197) -* -P DIR: makeinfo options. (line 205) -* -p INDENT: makeinfo options. (line 211) -* -s STYLE: makeinfo options. (line 84) -* -V: makeinfo options. (line 244) -* .cshrc initialization file: Preparing for TeX. (line 6) -* .profile initialization file: Preparing for TeX. (line 6) -* /L: Inserting Accents. (line 39) -* /l: Inserting Accents. (line 39) -* /O: Inserting Accents. (line 39) -* /o: Inserting Accents. (line 39) -* 8-bit characters, in HTML cross-references: HTML Xref 8-bit Character Expansion. - (line 6) -* <: Inserting Quotation Marks. - (line 43) -* <<: Inserting Quotation Marks. - (line 43) -* <abbr> tag: abbr. (line 22) -* <acronym> tag: acronym. (line 19) -* <blockquote> HTML tag: quotation. (line 44) -* <lineannotation> Docbook tag: Fonts. (line 53) -* <meta> HTML tag, and charset specification: documentencoding. - (line 56) -* <meta> HTML tag, and document description: documentdescription. - (line 6) -* <note> Docbook tag: quotation. (line 44) -* <small> tag: Smallcaps. (line 25) -* <thead> HTML tag: Multitable Rows. (line 12) -* <title> HTML tag: settitle. (line 21) -* <URL: convention, not used: uref. (line 71) -* >: Inserting Quotation Marks. - (line 43) -* >>: Inserting Quotation Marks. - (line 43) -* ?: Inserting Accents. (line 39) -* @ as continuation in definition commands: Def Cmd Continuation Lines. - (line 6) -* @-command list: Command List. (line 6) -* @-command syntax: Command Syntax. (line 6) -* @-commands: Formatting Commands. (line 6) -* @-commands in @node, limited support: Pointer Validation. (line 36) -* @-commands in nodename: Node Line Requirements. - (line 23) -* @import specifications, in CSS files: HTML CSS. (line 35) -* @include file sample: Sample Include File. (line 6) -* @menu parts: Menu Parts. (line 6) -* @node line writing: Writing a Node. (line 6) -* @value in @node lines: Pointer Validation. (line 66) -* @w, for blank items: itemize. (line 10) -* \input source line ignored: setfilename. (line 16) -* ^@^H for images in Info: Image Syntax. (line 63) -* _, breakpoint within @code: allowcodebreaks. (line 6) -* `: Inserting Quotation Marks. - (line 43) -* a: Inserting Accents. (line 39) -* A4 paper, printing on: A4 Paper. (line 6) -* A5 paper, printing on: A4 Paper. (line 6) -* AA: Inserting Accents. (line 39) -* aa: Inserting Accents. (line 39) -* Abbreviations for keys: key. (line 20) -* Abbreviations, tagging: abbr. (line 6) -* Abstract of document: documentdescription. (line 6) -* Accents, inserting: Inserting Accents. (line 6) -* accesskey, in HTML output <1>: Writing a Menu. (line 28) -* accesskey, in HTML output: node. (line 27) -* Acronyms, tagging: acronym. (line 6) -* Acute accent: Inserting Accents. (line 18) -* Adding a new Info file: New Info File. (line 6) -* AE: Inserting Accents. (line 39) -* ae: Inserting Accents. (line 39) -* Aliases, command: alias. (line 6) -* All-permissive copying license: All-permissive Copying License. - (line 6) -* Allow line break: Line Breaks. (line 6) -* Alphabetical @-command list: Command List. (line 6) -* Alt attribute for images: Image Syntax. (line 39) -* Anchors: anchor. (line 6) -* Angle quotation marks: Inserting Quotation Marks. - (line 43) -* Another Info directory: Other Info Directories. - (line 6) -* Arguments, repeated and optional: Optional Arguments. (line 6) -* ASCII text output: makeinfo options. (line 138) -* Aspect ratio of images: Image Scaling. (line 6) -* autoexec.bat: Other Info Directories. - (line 70) -* automake, and version info: GNU Sample Texts. (line 32) -* Automatic pointer creation with makeinfo: makeinfo Pointer Creation. - (line 6) -* Automatically insert nodes, menus: Updating Nodes and Menus. - (line 6) -* Auxiliary files, avoiding: Format with tex/texindex. - (line 83) -* B5 paper, printing on: pagesizes. (line 16) -* Back-end output formats: Output Formats. (line 6) -* Backslash in macros: Defining Macros. (line 37) -* Backslash, and macros: Invoking Macros. (line 23) -* Badly referenced nodes: Running Info-Validate. - (line 6) -* Bastard title page: titlepage. (line 46) -* Batch formatting for Info: Batch Formatting. (line 6) -* Beebe, Nelson: Output Formats. (line 51) -* Beginning a Texinfo file: Beginning a File. (line 6) -* Beginning line of a Texinfo file: First Line. (line 6) -* Berry, Karl: History. (line 6) -* Big points: Image Scaling. (line 24) -* Black rectangle in hardcopy: Overfull hboxes. (line 41) -* Blank lines: sp. (line 6) -* Blank lines, as paragraph separator: Conventions. (line 16) -* Body of a macro: Defining Macros. (line 26) -* Bold font: Fonts. (line 30) -* Bolio: History. (line 30) -* Book characteristics, printed: Printed Books. (line 6) -* Book, printing small: smallbook. (line 6) -* border-pattern: Object-Oriented Variables. - (line 23) -* border-pattern of Window: Object-Oriented Variables. - (line 77) -* BoTeX: History. (line 30) -* Box with rounded corners: cartouche. (line 6) -* Box, ugly black in hardcopy: Overfull hboxes. (line 41) -* Braces and argument syntax: Command Syntax. (line 38) -* Braces, in macro arguments: Invoking Macros. (line 83) -* Braces, inserting: Inserting Braces. (line 6) -* Braces, when to use: Formatting Commands. (line 50) -* Breaks in a line: Line Breaks. (line 6) -* Breaks, within @code: allowcodebreaks. (line 6) -* Breve accent: Inserting Accents. (line 18) -* Buffer formatting and printing: Printing. (line 6) -* Bugs, reporting: Reporting Bugs. (line 6) -* Bullets, inserting: Dots Bullets. (line 6) -* Captions, for floats: caption shortcaption. - (line 6) -* Caron accent: Inserting Accents. (line 18) -* Cascading Style Sheets, and HTML output: HTML CSS. (line 6) -* Case in node name: Node Line Requirements. - (line 42) -* Case, not altering in @code: code. (line 19) -* Catching errors with Info formatting: Debugging with Info. (line 6) -* Catching errors with TeX formatting: Debugging with TeX. (line 6) -* Catching mistakes: Catching Mistakes. (line 6) -* Categories, choosing: Installing Dir Entries. - (line 54) -* Caveats for macro usage: Macro Details. (line 6) -* Cedilla accent: Inserting Accents. (line 18) -* Centimeters: Image Scaling. (line 30) -* Chapter structuring: Structuring. (line 6) -* Chapters, formatting one at a time: Format with tex/texindex. - (line 83) -* Character set, declaring: documentencoding. (line 6) -* Characteristics, printed books or manuals: Printed Books. (line 6) -* Characters, basic input: Conventions. (line 6) -* Characters, invalid in node name: Node Line Requirements. - (line 30) -* Chassell, Robert J.: History. (line 6) -* Check accent: Inserting Accents. (line 18) -* Checking for badly referenced nodes: Running Info-Validate. - (line 6) -* Checklist for bug reports: Reporting Bugs. (line 11) -* Ciceros: Image Scaling. (line 39) -* Circumflex accent: Inserting Accents. (line 18) -* Click sequences: Click Sequences. (line 6) -* CM-Super fonts: Inserting Quotation Marks. - (line 36) -* CM-Super fonts, installing: Preparing for TeX. (line 24) -* code, value for @kbdinputstyle: kbd. (line 32) -* Collapsing whitespace around continuations: Def Cmd Continuation Lines. - (line 31) -* Colon in nodename: Node Line Requirements. - (line 30) -* Colon, last in INFOPATH: Other Info Directories. - (line 80) -* Column widths, defining for multitables: Multitable Column Widths. - (line 6) -* Combining indices: Combining Indices. (line 6) -* Comma in nodename: Node Line Requirements. - (line 30) -* Comma, in macro arguments: Invoking Macros. (line 38) -* Command aliases: alias. (line 6) -* Command definitions: Sample Function Definition. - (line 6) -* Command names, indicating: command. (line 6) -* Command syntax: Command Syntax. (line 6) -* Commands to insert special characters: Atsign Braces Comma. (line 6) -* Commands using raw TeX: Raw Formatter Commands. - (line 6) -* Commands, inserting them: Inserting. (line 6) -* Commas, inserting: Inserting a Comma. (line 6) -* Comments: Comments. (line 6) -* Comments, in CSS files: HTML CSS. (line 41) -* Compile command for formatting: Compile-Command. (line 6) -* Compressed files, reading: Invoking install-info. - (line 23) -* Conditionally visible text: Conditionals. (line 6) -* Conditionals, nested: Conditional Nesting. (line 6) -* Conditions for copying Texinfo: Copying Conditions. (line 6) -* Contents, after title page: Contents. (line 51) -* Contents, Table of: Contents. (line 6) -* Contents-like outline of file structure: Showing the Structure. - (line 6) -* Continuation lines in definition commands: Def Cmd Continuation Lines. - (line 6) -* Conventions for writing definitions: Def Cmd Conventions. (line 6) -* Conventions, syntactic: Conventions. (line 6) -* Copying conditions: Copying Conditions. (line 6) -* Copying Permissions: Document Permissions. - (line 6) -* Copying software: Software Copying Permissions. - (line 6) -* Copying text, including: insertcopying. (line 6) -* Copyright holder for FSF works: copying. (line 53) -* Copyright page: Copyright. (line 6) -* Copyright page, for plain text: Titlepage & Copyright Page. - (line 16) -* Copyright symbol: copyright symbol. (line 6) -* Copyright word, always in English: copying. (line 44) -* Correcting mistakes: Catching Mistakes. (line 6) -* Country codes: documentlanguage. (line 50) -* cp (concept) index: Predefined Indices. (line 10) -* Create nodes, menus automatically: Updating Nodes and Menus. - (line 6) -* Creating an Info file: Creating an Info File. - (line 6) -* Creating an unsplit file: Unsplit. (line 6) -* Creating index entries: Indexing Commands. (line 6) -* Creating pointers with makeinfo: makeinfo Pointer Creation. - (line 6) -* Cropmarks for printing: Cropmarks and Magnification. - (line 6) -* Cross reference parts: Cross Reference Parts. - (line 6) -* Cross references: Cross References. (line 6) -* Cross references using @inforef: inforef. (line 6) -* Cross references using @pxref: pxref. (line 6) -* Cross references using @ref: ref. (line 6) -* Cross references using @xref: xref. (line 6) -* Cross-reference targets, arbitrary: anchor. (line 6) -* Cross-references, in HTML output: HTML Xref. (line 6) -* CSS, and HTML output: HTML CSS. (line 6) -* Custom page sizes: pagesizes. (line 6) -* Customize Emacs package (Development/Docs/Texinfo): Texinfo Mode Printing. - (line 92) -* Customized highlighting: definfoenclose. (line 6) -* Customizing of TeX for Texinfo: Preparing for TeX. (line 32) -* CVS $Id: GNU Sample Texts. (line 21) -* Dash, breakpoint within @code: allowcodebreaks. (line 6) -* Dashes in source: Conventions. (line 28) -* Debugging the Texinfo structure: Catching Mistakes. (line 6) -* Debugging with Info formatting: Debugging with Info. (line 6) -* Debugging with TeX formatting: Debugging with TeX. (line 6) -* Default font: Fonts. (line 36) -* Defining indexing entries: Indexing Commands. (line 6) -* Defining macros: Defining Macros. (line 6) -* Defining new indices: New Indices. (line 6) -* Defining new Texinfo commands: Defining New Texinfo Commands. - (line 6) -* Definition command headings, continuing: Def Cmd Continuation Lines. - (line 6) -* Definition commands: Definition Commands. (line 6) -* Definition conventions: Def Cmd Conventions. (line 6) -* Definition lists, typesetting: table. (line 6) -* Definition template: Def Cmd Template. (line 6) -* Definitions grouped together: deffnx. (line 6) -* Degree symbol: textdegree. (line 6) -* Delimiter character, for verbatim: verb. (line 6) -* Depth of text area: pagesizes. (line 6) -* Description for menu, start: Inserting. (line 94) -* Description of document: documentdescription. (line 6) -* Detail menu: makeinfo Pointer Creation. - (line 24) -* Detailed menu: Master Menu Parts. (line 18) -* Details of macro usage: Macro Details. (line 6) -* Dido^t points: Image Scaling. (line 36) -* Different cross reference commands: Cross Reference Commands. - (line 6) -* Dimension formatting: dmn. (line 6) -* Dimensions and image sizes: Image Scaling. (line 14) -* Dir categories, choosing: Installing Dir Entries. - (line 54) -* dir directory for Info installation: Installing an Info File. - (line 6) -* dir file listing: New Info File. (line 6) -* dir file, creating your own: Other Info Directories. - (line 91) -* dir files and Info directories: Other Info Directories. - (line 6) -* Dir files, compressed: Invoking install-info. - (line 23) -* dir, created by install-info: Invoking install-info. - (line 20) -* Display formatting: display. (line 6) -* Displayed equations: math. (line 47) -* distinct, value for @kbdinputstyle: kbd. (line 32) -* Distorting images: Image Scaling. (line 6) -* Distribution: Software Copying Permissions. - (line 6) -* Docbook output: Output Formats. (line 73) -* Docbook, including raw: Raw Formatter Commands. - (line 6) -* Document description: documentdescription. (line 6) -* Document input encoding: documentencoding. (line 6) -* Document language, declaring: documentlanguage. (line 6) -* Document Permissions: Document Permissions. - (line 6) -* Document strings, translation of: documentlanguage. (line 21) -* Documentation identification: GNU Sample Texts. (line 21) -* Dot accent: Inserting Accents. (line 18) -* Dotless i, j: Inserting Accents. (line 39) -* Dots, inserting <1>: dots. (line 6) -* Dots, inserting: Dots Bullets. (line 6) -* Double angle quotation marks: Inserting Quotation Marks. - (line 43) -* Double guillemets: Inserting Quotation Marks. - (line 43) -* Double left-pointing angle quotation mark: Inserting Quotation Marks. - (line 43) -* Double low-9 quotation mark: Inserting Quotation Marks. - (line 43) -* Double quotation marks: Inserting Quotation Marks. - (line 43) -* Double right-pointing angle quotation mark: Inserting Quotation Marks. - (line 43) -* Double-colon menu entries: Less Cluttered Menu Entry. - (line 6) -* DTD, for Texinfo XML: Output Formats. (line 63) -* Dumas, Patrice: HTML Xref. (line 21) -* Dumping a .fmt file: Preparing for TeX. (line 79) -* DVI file: Format with tex/texindex. - (line 6) -* DVI output: Output Formats. (line 36) -* dvips: Output Formats. (line 36) -* EC fonts: Inserting Quotation Marks. - (line 29) -* EC fonts, installing: Preparing for TeX. (line 24) -* Ellipsis, inserting: Dots Bullets. (line 6) -* Em dash, compared to minus sign: minus. (line 6) -* Em dash, producing: Conventions. (line 28) -* Emacs: Texinfo Mode. (line 6) -* Emacs shell, format, print from: Within Emacs. (line 6) -* Emacs-W3: Output Formats. (line 26) -* Emphasizing text: Emphasis. (line 6) -* Emphasizing text, font for: emph & strong. (line 6) -* En dash, producing: Conventions. (line 28) -* Encoding, declaring: documentencoding. (line 6) -* End node footnote style: Footnote Styles. (line 9) -* End of header line: End of Header. (line 6) -* End titlepage starts headings: end titlepage. (line 6) -* Ending a Sentence: Ending a Sentence. (line 6) -* Ending a Texinfo file: Ending a File. (line 6) -* Entries for an index: Indexing Commands. (line 6) -* Entries, making index: Index Entries. (line 6) -* Enumeration: enumerate. (line 6) -* Environment indentation: exampleindent. (line 6) -* Environment variable INFOPATH: Other Info Directories. - (line 50) -* Environment variable TEXINFO_OUTPUT_FORMAT: makeinfo options. - (line 250) -* Environment variable TEXINPUTS: Preparing for TeX. (line 42) -* eps image format: Image Syntax. (line 13) -* epsf.tex: Image Scaling. (line 49) -* epsf.tex, installing: Preparing for TeX. (line 20) -* Equations, displayed: math. (line 47) -* Equivalence, indicating: Equivalence. (line 6) -* Error message, indicating: Error Glyph. (line 6) -* Errors, parsing: makeinfo in Emacs. (line 26) -* Es-zet: Inserting Accents. (line 39) -* Euro font: euro. (line 24) -* Euro font, installing: Preparing for TeX. (line 29) -* Euro symbol: euro. (line 6) -* European A4 paper: A4 Paper. (line 6) -* European Computer Modern fonts: Inserting Quotation Marks. - (line 29) -* European Computer Modern fonts, installing: Preparing for TeX. - (line 24) -* Evaluation glyph: result. (line 6) -* Example beginning of Texinfo file: Sample Beginning. (line 6) -* Example indentation: exampleindent. (line 6) -* Example menu: Menu Example. (line 6) -* example, value for @kbdinputstyle: kbd. (line 32) -* Examples in smaller fonts: small. (line 6) -* Examples, formatting them: example. (line 6) -* Examples, glyphs for: Glyphs. (line 6) -* Expanding macros: Invoking Macros. (line 6) -* Expansion of 8-bit characters in HTML cross-references: HTML Xref 8-bit Character Expansion. - (line 6) -* Expansion, indicating: expansion. (line 6) -* expansion, of node names in HTML cross-references: HTML Xref Node Name Expansion. - (line 6) -* Expressions in a program, indicating: code. (line 10) -* Feminine ordinal: Inserting Accents. (line 39) -* feymr10: euro. (line 24) -* feymr10, installing: Preparing for TeX. (line 29) -* File beginning: Beginning a File. (line 6) -* File ending: Ending a File. (line 6) -* File name collision: setfilename. (line 26) -* File section structure, showing it: Showing the Structure. - (line 6) -* Final output: Overfull hboxes. (line 6) -* Finding badly referenced nodes: Running Info-Validate. - (line 6) -* Fine-tuning, and hyphenation: - and hyphenation. (line 6) -* First line of a Texinfo file: First Line. (line 6) -* First node: First Node. (line 6) -* First paragraph, suppressing indentation of: firstparagraphindent. - (line 6) -* Fixed-width font: Fonts. (line 46) -* Float environment: float. (line 6) -* Floating accents, inserting: Inserting Accents. (line 6) -* Floating, not yet implemented: Floats. (line 10) -* Floats, in general: Floats. (line 6) -* Floats, list of: listoffloats. (line 6) -* Floats, making unnumbered: float. (line 39) -* Floats, numbering of: float. (line 46) -* Flooding: pxref. (line 27) -* fn (function) index: Predefined Indices. (line 13) -* Font size, reducing: Fonts. (line 6) -* Fonts for indices: syncodeindex. (line 52) -* Fonts for printing, not Info: Fonts. (line 6) -* Footings: Headings. (line 6) -* Footnotes: Footnotes. (line 6) -* Force line break: Line Breaks. (line 6) -* Forcing indentation: indent. (line 6) -* Forcing line and page breaks: Breaks. (line 6) -* Format a dimension: dmn. (line 6) -* Format and print hardcopy: Hardcopy. (line 6) -* Format and print in Texinfo mode: Texinfo Mode Printing. - (line 6) -* Format file, dumping: Preparing for TeX. (line 79) -* Format with the compile command: Compile-Command. (line 6) -* Format, print from Emacs shell: Within Emacs. (line 6) -* Formats for images: Image Syntax. (line 10) -* Formatting a file for Info: Creating an Info File. - (line 6) -* Formatting commands: Formatting Commands. (line 6) -* Formatting examples: example. (line 6) -* Formatting for Info: Info Formatting. (line 6) -* Formatting for printing: Printing. (line 6) -* Formatting headings and footings: Headings. (line 6) -* Formatting requirements: Requirements Summary. - (line 6) -* Formatting with tex and texindex: Format with tex/texindex. - (line 6) -* Formulas, mathematical: math. (line 6) -* Fox, Brian: History. (line 6) -* Free Documentation License, including entire: GNU Sample Texts. - (line 51) -* Free Software Directory: Installing Dir Entries. - (line 54) -* French quotation marks: Inserting Quotation Marks. - (line 43) -* French spacing: frenchspacing. (line 6) -* Frequently used commands, inserting: Inserting. (line 6) -* Frontmatter, text in: Beginning a File. (line 15) -* Full texts, GNU: GNU Sample Texts. (line 6) -* Function definitions: Sample Function Definition. - (line 6) -* General syntactic conventions: Conventions. (line 6) -* Generating menus with indices: Printing Indices & Menus. - (line 6) -* Generating plain text files: makeinfo options. (line 138) -* German quotation marks: Inserting Quotation Marks. - (line 43) -* German S: Inserting Accents. (line 39) -* Global Document Commands: Global Document Commands. - (line 6) -* Globbing: Format with tex/texindex. - (line 31) -* Glyphs: Glyphs. (line 6) -* GNU Emacs: Texinfo Mode. (line 6) -* GNU Emacs shell, format, print from: Within Emacs. (line 6) -* GNU Free Documentation License, including entire: GNU Sample Texts. - (line 51) -* GNU sample texts: GNU Sample Texts. (line 6) -* Going to other Info files' nodes: Other Info Files. (line 6) -* Grave accent: Inserting Accents. (line 18) -* Grave accent, vs. left quote: Inserting Quotation Marks. - (line 16) -* Group (hold text together vertically): group. (line 6) -* Grouping two definitions together: deffnx. (line 6) -* GUI click sequence: Click Sequences. (line 6) -* Guillemets: Inserting Quotation Marks. - (line 43) -* Guillemots: Inserting Quotation Marks. - (line 43) -* Hacek accent: Inserting Accents. (line 18) -* Hardcopy, printing it: Hardcopy. (line 6) -* hboxes, overfull: Overfull hboxes. (line 6) -* Header for Texinfo files: Texinfo File Header. (line 6) -* Header of a Texinfo file: First Line. (line 6) -* Heading row, in table: Multitable Rows. (line 12) -* Headings: Headings. (line 6) -* Headings, indentation after: firstparagraphindent. - (line 6) -* Headings, page, begin to appear: end titlepage. (line 6) -* Height of images: Image Scaling. (line 6) -* Height of text area: pagesizes. (line 6) -* help2man: Output Formats. (line 91) -* Hierarchical documents, and menus: Menu Location. (line 16) -* Highlighting text: Indicating. (line 6) -* Highlighting, customized: definfoenclose. (line 6) -* Hints: Tips. (line 8) -* History of Texinfo: History. (line 24) -* Holder of copyright for FSF works: copying. (line 53) -* Holding text together vertically: group. (line 6) -* href, producing HTML: uref. (line 6) -* HTML cross-reference 8-bit character expansion: HTML Xref 8-bit Character Expansion. - (line 6) -* HTML cross-reference command expansion: HTML Xref Command Expansion. - (line 6) -* HTML cross-reference link basics: HTML Xref Link Basics. - (line 6) -* HTML cross-reference mismatch: HTML Xref Mismatch. (line 6) -* HTML cross-reference node name expansion: HTML Xref Node Name Expansion. - (line 6) -* HTML cross-references: HTML Xref. (line 6) -* HTML output <1>: Generating HTML. (line 6) -* HTML output: Output Formats. (line 26) -* HTML output, and encodings: documentencoding. (line 56) -* HTML output, browser compatibility of: HTML Translation. (line 22) -* HTML output, split: HTML Splitting. (line 6) -* HTML, and CSS: HTML CSS. (line 6) -* HTML, including raw: Raw Formatter Commands. - (line 6) -* http-equiv, and charset specification: documentencoding. (line 56) -* Hungarian umlaut accent: Inserting Accents. (line 18) -* Hurricanes: ref. (line 12) -* Hyphen, breakpoint within @code: allowcodebreaks. (line 6) -* Hyphen, compared to minus: minus. (line 6) -* Hyphenation patterns, language-dependent: documentlanguage. (line 41) -* Hyphenation, helping TeX do: - and hyphenation. (line 6) -* Hyphenation, preventing: w. (line 24) -* Hyphens in source, two or three in a row: Conventions. (line 28) -* i (dotless i): Inserting Accents. (line 39) -* Identification of documentation: GNU Sample Texts. (line 21) -* If text conditionally visible: Conditionals. (line 6) -* Ignored before @setfilename: setfilename. (line 16) -* Ignored text: Comments. (line 19) -* Image formats: Image Syntax. (line 10) -* Images, alternate text for: Image Syntax. (line 39) -* Images, inserting: Images. (line 6) -* Images, scaling: Image Scaling. (line 6) -* Inches: Image Scaling. (line 27) -* Include file sample: Sample Include File. (line 6) -* Include files: Include Files. (line 6) -* Include files requirements: Include Files Requirements. - (line 6) -* Include files, and section levels: Raise/lower sections. - (line 16) -* Including a file verbatim: verbatiminclude. (line 6) -* Including permissions text: insertcopying. (line 6) -* Indentation undoing: exdent. (line 6) -* Indentation, forcing: indent. (line 6) -* Indentation, omitting: noindent. (line 6) -* Indenting environments: exampleindent. (line 6) -* Indenting paragraphs, control of: paragraphindent. (line 6) -* Indenting, suppressing of first paragraph: firstparagraphindent. - (line 6) -* Index entries: Indexing Commands. (line 6) -* Index entries, making: Index Entries. (line 6) -* Index entry writing: Indexing Commands. (line 27) -* Index file names: Format with tex/texindex. - (line 23) -* Index font types: Indexing Commands. (line 48) -* Indexing table entries automatically: ftable vtable. (line 6) -* Indicating commands, definitions, etc.: Indicating. (line 6) -* Indicating evaluation: result. (line 6) -* Indices: Indices. (line 6) -* Indices, combining them: Combining Indices. (line 6) -* Indices, defining new: New Indices. (line 6) -* Indices, printing and menus: Printing Indices & Menus. - (line 6) -* Indices, sorting: Hardcopy. (line 6) -* Indices, two letter names: syncodeindex. (line 17) -* Indirect subfiles: Tag and Split Files. (line 11) -* Info batch formatting: Batch Formatting. (line 6) -* Info file installation: Installing an Info File. - (line 6) -* Info file name, choosing: setfilename. (line 26) -* Info file, listing a new: New Info File. (line 6) -* Info file, splitting manually: Splitting. (line 6) -* Info files: Info Files. (line 6) -* Info format, and menus: Menu Location. (line 10) -* Info formatting: Info Formatting. (line 6) -* Info installed in another directory: Other Info Directories. - (line 6) -* Info output: Output Formats. (line 10) -* Info output, and encoding: documentencoding. (line 43) -* Info validating a large file: Using Info-validate. (line 6) -* Info, creating an online file: Creating an Info File. - (line 6) -* Info-directory-list: Other Info Directories. - (line 37) -* Info; other files' nodes: Other Info Files. (line 6) -* INFOPATH: Other Info Directories. - (line 50) -* Initialization file for TeX input: Preparing for TeX. (line 6) -* Input encoding, declaring: documentencoding. (line 6) -* Insert nodes, menus automatically: Updating Nodes and Menus. - (line 6) -* Inserting @ (literal @): Inserting an Atsign. (line 6) -* Inserting accents: Inserting Accents. (line 6) -* Inserting dots <1>: dots. (line 6) -* Inserting dots: Dots Bullets. (line 6) -* Inserting ellipsis: Dots Bullets. (line 6) -* Inserting frequently used commands: Inserting. (line 6) -* Inserting indentation: indent. (line 6) -* Inserting quotation marks: Inserting Quotation Marks. - (line 6) -* Inserting quote characters: Inserting Quote Characters. - (line 6) -* Inserting space: Inserting Space. (line 6) -* Inserting special characters and symbols: Insertions. (line 6) -* INSTALL file, generating: makeinfo options. (line 138) -* install-info: Invoking install-info. - (line 6) -* Installing an Info file: Installing an Info File. - (line 6) -* Installing Info in another directory: Other Info Directories. - (line 6) -* Internationalization: Internationalization. - (line 6) -* Introduction to Texinfo: Using Texinfo. (line 6) -* Introduction, as part of file: Software Copying Permissions. - (line 16) -* Invalid characters in node names: Node Line Requirements. - (line 30) -* Invoking macros: Invoking Macros. (line 6) -* Invoking nodes, including in dir file: Installing Dir Entries. - (line 71) -* ISO 3166 country codes: documentlanguage. (line 50) -* ISO 639-2 language codes: documentlanguage. (line 50) -* ISO 8859-1: Inserting Quotation Marks. - (line 24) -* ISO 8859-15 <1>: euro. (line 18) -* ISO 8859-15: Inserting Quotation Marks. - (line 24) -* Italic font: Fonts. (line 33) -* Itemization: itemize. (line 6) -* j (dotless j): Inserting Accents. (line 39) -* JPEG image format: Image Syntax. (line 51) -* jpeg image format: Image Syntax. (line 15) -* Keyboard input: kbd. (line 6) -* Keys, recommended names: key. (line 20) -* Keyword expansion, preventing: w. (line 28) -* Keywords, indicating: code. (line 10) -* Knuth, Donald: Printed Books. (line 6) -* ky (keystroke) index: Predefined Indices. (line 17) -* LANG: makeinfo options. (line 62) -* Language codes: documentlanguage. (line 50) -* Language, declaring: documentlanguage. (line 6) -* Larger or smaller pages: Cropmarks and Magnification. - (line 24) -* LaTeX logo: tex. (line 6) -* LaTeX, processing with texi2dvi: Format with texi2dvi. - (line 39) -* Latin 1: Inserting Quotation Marks. - (line 24) -* Latin 9 <1>: euro. (line 18) -* Latin 9: Inserting Quotation Marks. - (line 24) -* Left quotation marks: Inserting Quotation Marks. - (line 43) -* Left-pointing angle quotation marks: Inserting Quotation Marks. - (line 43) -* Legal paper, printing on: pagesizes. (line 16) -* Length of file names: setfilename. (line 26) -* Less cluttered menu entry: Less Cluttered Menu Entry. - (line 6) -* License agreement: Software Copying Permissions. - (line 6) -* License for all-permissive copying: All-permissive Copying License. - (line 6) -* License for verbatim copying: Verbatim Copying License. - (line 6) -* Line breaks <1>: Line Breaks. (line 6) -* Line breaks: Breaks. (line 6) -* Line breaks, preventing: w. (line 6) -* Line length, column widths as fraction of: Multitable Column Widths. - (line 11) -* Line spacing: sp. (line 6) -* Lisp example: lisp. (line 6) -* Lisp examples in smaller fonts: small. (line 6) -* List of @-commands: Command List. (line 6) -* List of floats: listoffloats. (line 6) -* Listing a new Info file: New Info File. (line 6) -* Lists and tables, making: Lists and Tables. (line 6) -* Local variables: Compile-Command. (line 6) -* Local Variables: section, for encoding: documentencoding. (line 43) -* Locale, declaring: documentlanguage. (line 6) -* Location of menus: Menu Location. (line 6) -* Logos, TeX: tex. (line 6) -* Looking for badly referenced nodes: Running Info-Validate. - (line 6) -* Lowering and raising sections: Raise/lower sections. - (line 6) -* lpr (DVI print command): Print with lpr. (line 6) -* lpr-d, replacements on MS-DOS/MS-Windows: Print with lpr. (line 27) -* Lynx: Output Formats. (line 26) -* Macro definitions <1>: Defining Macros. (line 6) -* Macro definitions: Sample Function Definition. - (line 6) -* Macro details: Macro Details. (line 6) -* Macro expansion, indicating: expansion. (line 6) -* Macro invocation: Invoking Macros. (line 6) -* Macro names, valid characters in: Defining Macros. (line 16) -* Macron accent: Inserting Accents. (line 18) -* Macros: Defining New Texinfo Commands. - (line 6) -* Macros in definition commands: Def Cmd Template. (line 67) -* Macros, undefining: Defining Macros. (line 56) -* Magnified printing: Cropmarks and Magnification. - (line 24) -* Mailto link: email. (line 10) -* makeinfo: Invoking makeinfo. (line 6) -* makeinfo inside Emacs: makeinfo in Emacs. (line 6) -* makeinfo options: makeinfo options. (line 6) -* Making a printed manual: Hardcopy. (line 6) -* Making a tag table automatically: Tag and Split Files. (line 6) -* Making a tag table manually: Unsplit. (line 26) -* Making cross references: Cross References. (line 6) -* Making line and page breaks: Breaks. (line 6) -* Making lists and tables: Lists and Tables. (line 6) -* Man page output, not supported: Output Formats. (line 81) -* Man page, reference to: uref. (line 20) -* Manual characteristics, printed: Printed Books. (line 6) -* Margins on page, not controllable: pagesizes. (line 20) -* Marking text within a paragraph: Marking Text. (line 6) -* Marking words and phrases: Marking Text. (line 6) -* Masculine ordinal: Inserting Accents. (line 39) -* Master menu: Master Menu Parts. (line 6) -* Mathematical expressions <1>: Raw Formatter Commands. - (line 33) -* Mathematical expressions: math. (line 6) -* Menu description, start: Inserting. (line 94) -* Menu entries with two colons: Less Cluttered Menu Entry. - (line 6) -* Menu example: Menu Example. (line 6) -* Menu location: Menu Location. (line 6) -* Menu parts: Menu Parts. (line 6) -* Menu writing: Writing a Menu. (line 6) -* Menu, master: Master Menu Parts. (line 6) -* Menus: Menus. (line 6) -* Menus generated with indices: Printing Indices & Menus. - (line 6) -* Menus, omitting: makeinfo options. (line 138) -* META key: key. (line 54) -* Meta-syntactic chars for arguments: Optional Arguments. (line 6) -* Methods, object-oriented: Object-Oriented Methods. - (line 6) -* Millimeters: Image Scaling. (line 33) -* Minimal requirements for formatting: Requirements Summary. - (line 6) -* Minimal Texinfo file (requirements): Minimum. (line 6) -* Minus sign: minus. (line 6) -* Mismatched HTML cross-reference source and target: HTML Xref Mismatch. - (line 6) -* Mistakes, catching: Catching Mistakes. (line 6) -* Mode, using Texinfo: Texinfo Mode. (line 6) -* Monospace font: Fonts. (line 46) -* Mozilla: Output Formats. (line 26) -* Multiple dashes in source: Conventions. (line 28) -* Multiple spaces: Multiple Spaces. (line 6) -* Multitable column widths: Multitable Column Widths. - (line 6) -* Multitable rows: Multitable Rows. (line 6) -* Must have in Texinfo file: Minimum. (line 6) -* Mutually recursive macros: Defining Macros. (line 26) -* Names for indices: syncodeindex. (line 17) -* Names of index files: Format with tex/texindex. - (line 23) -* Names of macros, valid characters of: Defining Macros. (line 16) -* Names recommended for keys: key. (line 20) -* Naming a `Top' Node in references: Top Node Naming. (line 6) -* NASA, as acronym: acronym. (line 6) -* Navigation bar, in HTML output: HTML Translation. (line 16) -* Navigation links, omitting: makeinfo options. (line 144) -* Need space at page bottom: need. (line 6) -* Nesting conditionals: Conditional Nesting. (line 6) -* New index defining: New Indices. (line 6) -* New Info file, listing it in dir file: New Info File. (line 6) -* New Texinfo commands, defining: Defining New Texinfo Commands. - (line 6) -* Newlines, as blank lines: Conventions. (line 16) -* Next node of Top node: First Node. (line 26) -* Node line requirements: Node Line Requirements. - (line 6) -* Node line writing: Writing a Node. (line 6) -* node name expansion, in HTML cross-references: HTML Xref Node Name Expansion. - (line 6) -* Node name must be unique: Node Line Requirements. - (line 8) -* Node name, should not contain @-commands: Node Line Requirements. - (line 23) -* Node names, choosing: Node Names. (line 6) -* Node names, invalid characters in: Node Line Requirements. - (line 30) -* Node separators, omitting: makeinfo options. (line 138) -* Node, `Top': The Top Node. (line 6) -* Node, defined: node. (line 6) -* Nodes in other Info files: Other Info Files. (line 6) -* Nodes, catching mistakes: Catching Mistakes. (line 6) -* Nodes, checking for badly referenced: Running Info-Validate. - (line 6) -* Non-breakable space, fixed: w. (line 9) -* Non-breakable space, variable: tie. (line 6) -* Not ending a sentence: Not Ending a Sentence. - (line 6) -* Numbering of floats: float. (line 46) -* o: Inserting Accents. (line 39) -* O'Dea, Brendan: Output Formats. (line 91) -* Object-oriented programming: Abstract Objects. (line 6) -* Oblique font: Fonts. (line 43) -* Obtaining TeX: Obtaining TeX. (line 6) -* Occurrences, listing with @occur: Using occur. (line 6) -* OE: Inserting Accents. (line 39) -* oe: Inserting Accents. (line 39) -* Omitting indentation: noindent. (line 6) -* Optional and repeated arguments: Optional Arguments. (line 6) -* Options for makeinfo: makeinfo options. (line 6) -* Ordinals, Romance: Inserting Accents. (line 39) -* Ordinary TeX commands, using: Raw Formatter Commands. - (line 6) -* Other Info files' nodes: Other Info Files. (line 6) -* Outline of file structure, showing it: Showing the Structure. - (line 6) -* Output file splitting: makeinfo options. (line 173) -* Output formats: Output Formats. (line 6) -* Output formats, supporting more: Output Formats. (line 98) -* Overfull hboxes: Overfull hboxes. (line 6) -* Overview of Texinfo: Overview. (line 6) -* Owner of copyright for FSF works: copying. (line 53) -* Page breaks <1>: page. (line 6) -* Page breaks: Breaks. (line 11) -* Page delimiter in Texinfo mode: Showing the Structure. - (line 40) -* Page headings: Headings. (line 6) -* Page numbering: Headings. (line 6) -* Page sizes for books: smallbook. (line 6) -* Page sizes, customized: pagesizes. (line 6) -* page-delimiter: Showing the Structure. - (line 40) -* Pages, starting odd: setchapternewpage. (line 6) -* Paper size, A4: A4 Paper. (line 6) -* Paragraph indentation control: paragraphindent. (line 6) -* Paragraph separator: Conventions. (line 16) -* Paragraph, marking text within: Marking Text. (line 6) -* Parameters to macros: Defining Macros. (line 32) -* Parentheses in nodename: Node Line Requirements. - (line 30) -* Parsing errors: makeinfo in Emacs. (line 26) -* Part of file formatting and printing: Printing. (line 6) -* Parts of a cross reference: Cross Reference Parts. - (line 6) -* Parts of a master menu: Master Menu Parts. (line 6) -* Parts of a menu: Menu Parts. (line 6) -* Patches, contributing: Reporting Bugs. (line 30) -* pdf image inclusions: Image Syntax. (line 15) -* PDF output <1>: PDF Output. (line 6) -* PDF output: Output Formats. (line 51) -* pdftex <1>: PDF Output. (line 6) -* pdftex: Output Formats. (line 51) -* pdftex, and images: Image Syntax. (line 15) -* Period in nodename: Node Line Requirements. - (line 30) -* Periods, inserting: Not Ending a Sentence. - (line 6) -* Permissions text, including: insertcopying. (line 6) -* Permissions, printed: Copyright. (line 6) -* pg (program) index: Predefined Indices. (line 20) -* Picas: Image Scaling. (line 21) -* Pictures, inserting: Images. (line 6) -* Pinard, Franc,ois: History. (line 14) -* Plain TeX: Raw Formatter Commands. - (line 6) -* Plain text output <1>: makeinfo options. (line 138) -* Plain text output: Output Formats. (line 21) -* PNG image format: Image Syntax. (line 51) -* png image format: Image Syntax. (line 15) -* Point, indicating in a buffer: Point Glyph. (line 6) -* Pointer creation with makeinfo: makeinfo Pointer Creation. - (line 6) -* Pointer validation with makeinfo: Pointer Validation. (line 6) -* Pointer validation, suppressing <1>: makeinfo options. (line 181) -* Pointer validation, suppressing: Format with tex/texindex. - (line 83) -* Points (dimension): Image Scaling. (line 18) -* Pounds symbol: pounds. (line 6) -* Predefined names for indices: syncodeindex. (line 17) -* Preparing for TeX: Preparing for TeX. (line 6) -* Prev node of Top node: First Node. (line 24) -* Preventing first paragraph indentation: firstparagraphindent. - (line 6) -* Preventing line and page breaks: Breaks. (line 6) -* Print and format in Texinfo mode: Texinfo Mode Printing. - (line 6) -* Print, format from Emacs shell: Within Emacs. (line 6) -* Printed book and manual characteristics: Printed Books. (line 6) -* Printed output, indicating: Print Glyph. (line 6) -* Printed permissions: Copyright. (line 6) -* Printing a region or buffer: Printing. (line 6) -* Printing an index: Printing Indices & Menus. - (line 6) -* Printing cost, reducing: Fonts. (line 13) -* Printing cropmarks: Cropmarks and Magnification. - (line 6) -* Printing DVI files, on MS-DOS/MS-Windows: Print with lpr. (line 27) -* Printing hardcopy: Hardcopy. (line 6) -* Problems, catching: Catching Mistakes. (line 6) -* Program names, indicating: command. (line 6) -* Prototype row, column widths defined by: Multitable Column Widths. - (line 22) -* Quotation characters (`'), in source: Inserting Quotation Marks. - (line 6) -* Quotation marks, French: Inserting Quotation Marks. - (line 43) -* Quotation marks, German: Inserting Quotation Marks. - (line 43) -* Quotation marks, inserting: Inserting Quotation Marks. - (line 6) -* Quotations: quotation. (line 6) -* Quote characters, inserting: Inserting Quote Characters. - (line 6) -* Ragged left: flushleft & flushright. - (line 6) -* Ragged right: flushleft & flushright. - (line 6) -* Raising and lowering sections: Raise/lower sections. - (line 6) -* Raw formatter commands: Raw Formatter Commands. - (line 6) -* RCS $Id: GNU Sample Texts. (line 21) -* Recommended names for keys: key. (line 20) -* Rectangle, black in hardcopy: Overfull hboxes. (line 41) -* Recursion, mutual: Defining Macros. (line 26) -* Recursive macro invocations: Defining Macros. (line 44) -* Reducing font size: Fonts. (line 6) -* Reference to @-commands: Command List. (line 6) -* References: Cross References. (line 6) -* References using @inforef: inforef. (line 6) -* References using @pxref: pxref. (line 6) -* References using @ref: ref. (line 6) -* References using @xref: xref. (line 6) -* Referring to other Info files: Other Info Files. (line 6) -* Region formatting and printing: Printing. (line 6) -* Region printing in Texinfo mode: Texinfo Mode Printing. - (line 6) -* Registered symbol: registered symbol. (line 6) -* Reid, Brian: History. (line 24) -* Repeated and optional arguments: Optional Arguments. (line 6) -* Reporting bugs: Reporting Bugs. (line 6) -* Required in Texinfo file: Minimum. (line 6) -* Requirements for formatting: Requirements Summary. - (line 6) -* Requirements for include files: Include Files Requirements. - (line 6) -* Requirements for updating commands: Updating Requirements. - (line 6) -* Reserved words, indicating: code. (line 10) -* Restrictions on node names: Node Line Requirements. - (line 6) -* Result of an expression: result. (line 6) -* ridt.eps: Image Scaling. (line 44) -* Right quotation marks: Inserting Quotation Marks. - (line 43) -* Right-pointing angle quotation marks: Inserting Quotation Marks. - (line 43) -* Ring accent: Inserting Accents. (line 18) -* Roman font: Fonts. (line 36) -* Romance ordinals: Inserting Accents. (line 39) -* Rounded rectangles, around examples: cartouche. (line 6) -* Rows, of a multitable: Multitable Rows. (line 6) -* Running an Info formatter: Info Formatting. (line 6) -* Running Info-validate: Using Info-validate. (line 6) -* Running macros: Invoking Macros. (line 6) -* Running makeinfo in Emacs: makeinfo in Emacs. (line 6) -* Sample @include file: Sample Include File. (line 6) -* Sample function definition: Sample Function Definition. - (line 6) -* Sample Texinfo file, no comments: Short Sample Texinfo File. - (line 6) -* Sample Texinfo file, with comments: Short Sample. (line 6) -* Sample Texinfo files: Sample Texinfo Files. - (line 6) -* Sample texts, GNU: GNU Sample Texts. (line 6) -* Sans serif font: Fonts. (line 40) -* Scaled points: Image Scaling. (line 42) -* Scaling images: Image Scaling. (line 6) -* Schwab, Andreas: History. (line 14) -* Scribe: History. (line 24) -* Sea surges: ref. (line 28) -* Section structure of a file, showing it: Showing the Structure. - (line 6) -* Sections, raising and lowering: Raise/lower sections. - (line 6) -* Sentence ending punctuation: Ending a Sentence. (line 6) -* Sentence non-ending punctuation: Not Ending a Sentence. - (line 6) -* Sentences, spacing after: frenchspacing. (line 6) -* Separate footnote style: Footnote Styles. (line 20) -* Sequence of clicks: Click Sequences. (line 6) -* SGML-tools output format: Output Formats. (line 98) -* Sharp S: Inserting Accents. (line 39) -* Shell formatting with tex and texindex: Format with tex/texindex. - (line 6) -* Shell printing, on MS-DOS/MS-Windows: Print with lpr. (line 27) -* Shell, format, print from: Within Emacs. (line 6) -* Shell, running makeinfo in: makeinfo in Emacs. (line 6) -* Short captions, for lists of floats: caption shortcaption. - (line 6) -* Short table of contents: Contents. (line 6) -* Showing the section structure of a file: Showing the Structure. - (line 6) -* Showing the structure of a file: Using texinfo-show-structure. - (line 6) -* Shrubbery: ifset ifclear. (line 21) -* Single angle quotation marks: Inserting Quotation Marks. - (line 43) -* Single guillemets: Inserting Quotation Marks. - (line 43) -* Single left-pointing angle quotation mark: Inserting Quotation Marks. - (line 43) -* Single low-9 quotation mark: Inserting Quotation Marks. - (line 43) -* Single quotation marks: Inserting Quotation Marks. - (line 43) -* Single right-pointing angle quotation mark: Inserting Quotation Marks. - (line 43) -* Site-wide Texinfo configuration file: Preparing for TeX. (line 32) -* Size of printed book: smallbook. (line 6) -* Slanted font: Fonts. (line 43) -* Slanted typewriter font, for @kbd: kbd. (line 15) -* Small book size: smallbook. (line 6) -* Small caps font: Smallcaps. (line 6) -* Small examples: small. (line 6) -* Small verbatim: verbatim. (line 46) -* Smaller fonts: Fonts. (line 6) -* Software copying permissions: Software Copying Permissions. - (line 6) -* Sorting indices: Hardcopy. (line 6) -* Source file format: Using Texinfo. (line 19) -* Source files, characters used: Conventions. (line 9) -* Space, after sentences: frenchspacing. (line 6) -* Space, inserting horizontal: Multiple Spaces. (line 6) -* Space, inserting vertical: sp. (line 6) -* Spaces in macros: Defining Macros. (line 40) -* Spaces in node name: Node Line Requirements. - (line 44) -* Spaces, in menus: Writing a Menu. (line 25) -* Spacing, inserting: Inserting Space. (line 6) -* Special characters, inserting: Atsign Braces Comma. (line 6) -* Special displays: Special Displays. (line 6) -* Special insertions: Insertions. (line 6) -* Special typesetting commands: Dots Bullets. (line 6) -* Specifying index entries: Indexing Commands. (line 6) -* Split HTML output: HTML Splitting. (line 6) -* Splitting an Info file manually: Splitting. (line 6) -* Splitting of output files: makeinfo options. (line 173) -* ss: Inserting Accents. (line 39) -* Stallman, Richard M.: History. (line 6) -* Start of header line: Start of Header. (line 6) -* Starting chapters: setchapternewpage. (line 6) -* Structure of a file, showing it: Showing the Structure. - (line 6) -* Structure, catching mistakes in: Catching Mistakes. (line 6) -* Structuring of chapters: Structuring. (line 6) -* Styles, font: Fonts. (line 24) -* Subsection-like commands: unnumberedsubsec appendixsubsec subheading. - (line 6) -* Subsub commands: subsubsection. (line 6) -* Suggestions for Texinfo, making: Reporting Bugs. (line 6) -* Summary of document: documentdescription. (line 6) -* Suppressing first paragraph indentation: firstparagraphindent. - (line 6) -* Suppressing indentation: noindent. (line 6) -* Syntactic conventions: Conventions. (line 6) -* Syntactic tokens, indicating: code. (line 6) -* Syntax, of @-commands: Command Syntax. (line 6) -* Syntax, optional & repeated arguments: Optional Arguments. (line 6) -* Table of contents: Contents. (line 6) -* Table of contents, after title page: Contents. (line 51) -* Table of contents, for floats: listoffloats. (line 6) -* Tables and lists, making: Lists and Tables. (line 6) -* Tables with indexes: ftable vtable. (line 6) -* Tables, making multi-column: Multi-column Tables. (line 6) -* Tables, making two-column: Two-column Tables. (line 6) -* Tabs; don't use!: Conventions. (line 38) -* Tag table, making automatically: Tag and Split Files. (line 6) -* Tag table, making manually: Unsplit. (line 26) -* Targets for cross-references, arbitrary: anchor. (line 6) -* Template for a definition: Def Cmd Template. (line 6) -* TeX commands, using ordinary: Raw Formatter Commands. - (line 6) -* TeX index sorting: Hardcopy. (line 6) -* TeX input initialization: Preparing for TeX. (line 6) -* TeX logo: tex. (line 6) -* TeX, how to obtain: Obtaining TeX. (line 6) -* texi2dvi: Format with tex/texindex. - (line 75) -* texi2dvi (shell script): Format with texi2dvi. - (line 6) -* texi2roff, unsupported software: Printed Books. (line 59) -* texindex <1>: Format with tex/texindex. - (line 16) -* texindex: Hardcopy. (line 6) -* Texinfo commands, defining new: Defining New Texinfo Commands. - (line 6) -* Texinfo file beginning: Beginning a File. (line 6) -* Texinfo file ending: Ending a File. (line 6) -* Texinfo file header: Texinfo File Header. (line 6) -* Texinfo file minimum: Minimum. (line 6) -* Texinfo file section structure, showing it: Showing the Structure. - (line 6) -* Texinfo history: History. (line 24) -* Texinfo mode: Texinfo Mode. (line 6) -* Texinfo overview: Overview. (line 6) -* Texinfo printed book characteristics: Printed Books. (line 6) -* Texinfo requires @setfilename: setfilename. (line 6) -* Texinfo, introduction to: Using Texinfo. (line 6) -* texinfo.cnf: setfilename. (line 43) -* texinfo.cnf installation: Preparing for TeX. (line 32) -* texinfo.dtd: Output Formats. (line 63) -* texinfo.tex, installing: Preparing for TeX. (line 13) -* TEXINFO_OUTPUT_FORMAT: makeinfo options. (line 250) -* TEXINPUTS: Preparing for TeX. (line 42) -* Text width and height: pagesizes. (line 6) -* Text, conditionally visible: Conditionals. (line 6) -* Text, marking up: Marking Text. (line 6) -* Thin space between number, dimension: dmn. (line 6) -* Tie-after accent: Inserting Accents. (line 18) -* Tied space: tie. (line 6) -* Tilde accent: Inserting Accents. (line 18) -* time-stamp.el: GNU Sample Texts. (line 32) -* Tips: Tips. (line 8) -* Title page: titlepage. (line 6) -* Title page, bastard: titlepage. (line 46) -* Title page, for plain text: Titlepage & Copyright Page. - (line 16) -* Titlepage end starts headings: end titlepage. (line 6) -* Top node: The Top Node. (line 6) -* Top node example: Top Node Example. (line 6) -* Top node is first: First Node. (line 6) -* Top node naming for references: Top Node Naming. (line 6) -* tp (data type) index: Predefined Indices. (line 23) -* Transliteration of 8-bit characters in HTML cross-references: HTML Xref 8-bit Character Expansion. - (line 6) -* Tree structuring: Tree Structuring. (line 6) -* Two `First' Lines for @deffn: deffnx. (line 6) -* Two letter names for indices: syncodeindex. (line 17) -* Two named items for @table: itemx. (line 6) -* Two part menu entry: Less Cluttered Menu Entry. - (line 6) -* txi-CC.tex: documentlanguage. (line 28) -* Typesetting commands for dots, etc.: Dots Bullets. (line 6) -* Typewriter font: Fonts. (line 46) -* Ugly black rectangles in hardcopy: Overfull hboxes. (line 41) -* Umlaut accent: Inserting Accents. (line 18) -* Unbreakable space, fixed: w. (line 9) -* Unbreakable space, variable: tie. (line 6) -* Uncluttered menu entry: Less Cluttered Menu Entry. - (line 6) -* Undefining macros: Defining Macros. (line 56) -* Underbar accent: Inserting Accents. (line 18) -* Underdot accent: Inserting Accents. (line 18) -* Underscore, breakpoint within @code: allowcodebreaks. (line 6) -* Unicode quotation characters: Inserting Quotation Marks. - (line 16) -* Uniform resource locator, indicating: indicateurl. (line 6) -* Uniform resource locator, referring to: uref. (line 6) -* Unique nodename requirement: Node Line Requirements. - (line 8) -* Unnumbered float, creating: float. (line 39) -* Unprocessed text: Comments. (line 19) -* Unsplit file creation: Unsplit. (line 6) -* Up node of Top node: First Node. (line 13) -* UPDATED Automake variable: GNU Sample Texts. (line 32) -* Updating nodes and menus: Updating Nodes and Menus. - (line 6) -* Updating requirements: Updating Requirements. - (line 6) -* URI syntax for Info: Info Files. (line 78) -* URL, indicating: indicateurl. (line 6) -* URL, referring to: uref. (line 6) -* Usage tips: Tips. (line 8) -* User input: kbd. (line 15) -* User options, marking: Variables Commands. (line 57) -* User-defined Texinfo commands: Defining New Texinfo Commands. - (line 6) -* Using Texinfo in general: Using Texinfo. (line 6) -* UTF-8: Inserting Quotation Marks. - (line 24) -* Validating a large file: Using Info-validate. (line 6) -* Validation of pointers: Pointer Validation. (line 6) -* Value of an expression, indicating: result. (line 6) -* Variables, object-oriented: Object-Oriented Variables. - (line 6) -* Verbatim copying license: Verbatim Copying License. - (line 6) -* Verbatim environment: verbatim. (line 6) -* Verbatim in-line text: verb. (line 6) -* Verbatim, include file: verbatiminclude. (line 6) -* Verbatim, small: verbatim. (line 46) -* VERSION Automake variable: GNU Sample Texts. (line 32) -* Version control keywords, preventing expansion of: w. (line 28) -* Version number, for install-info: Invoking install-info. - (line 176) -* Vertically holding text together: group. (line 6) -* Visibility of conditional text: Conditionals. (line 6) -* vr (variable) index: Predefined Indices. (line 27) -* W3 consortium: Output Formats. (line 26) -* Weinberg, Zack: History. (line 14) -* Weisshaus, Melissa: History. (line 14) -* White space in node name: Node Line Requirements. - (line 44) -* White space, excessive: Breaks. (line 11) -* Whitespace in macros: Defining Macros. (line 40) -* Whitespace, collapsed around continuations: Def Cmd Continuation Lines. - (line 31) -* Whitespace, inserting: Multiple Spaces. (line 6) -* Width of images: Image Scaling. (line 6) -* Width of text area: pagesizes. (line 6) -* Widths, defining multitable column: Multitable Column Widths. - (line 6) -* Wildcards: Format with tex/texindex. - (line 31) -* Words and phrases, marking them: Marking Text. (line 6) -* Writing a menu: Writing a Menu. (line 6) -* Writing an @node line: Writing a Node. (line 6) -* Writing index entries: Indexing Commands. (line 27) -* xdvi: Output Formats. (line 36) -* XML output: Output Formats. (line 63) -* XML, including raw: Raw Formatter Commands. - (line 6) -* XPM image format: Image Syntax. (line 26) -* Years, in copyright line: copying. (line 48) -* Zaretskii, Eli: History. (line 14) -* Zuhn, David D.: History. (line 14) - - - -Tag Table: -Node: Top1639 -Node: Copying Conditions26594 -Node: Overview28656 -Ref: Overview-Footnote-130030 -Node: Reporting Bugs30487 -Node: Using Texinfo31751 -Node: Output Formats33335 -Node: Info Files38641 -Ref: Info Files-Footnote-143043 -Node: Printed Books43222 -Ref: Printed Books-Footnote-146064 -Node: Formatting Commands46398 -Ref: Formatting Commands-Footnote-149253 -Node: Conventions49861 -Node: Comments52467 -Node: Minimum54092 -Node: Six Parts56649 -Node: Short Sample58271 -Node: History62410 -Node: Texinfo Mode64456 -Node: Texinfo Mode Overview65828 -Node: Emacs Editing66593 -Node: Inserting68734 -Node: Showing the Structure73001 -Node: Updating Nodes and Menus75319 -Node: Updating Commands76393 -Node: Updating Requirements82390 -Node: Other Updating Commands84774 -Node: Info Formatting88035 -Node: Printing89296 -Node: Texinfo Mode Summary91599 -Node: Beginning a File96276 -Node: Sample Beginning97690 -Node: Texinfo File Header99312 -Node: First Line100771 -Node: Start of Header101797 -Node: setfilename102783 -Node: settitle105283 -Node: End of Header107539 -Node: Document Permissions107818 -Node: copying108444 -Node: insertcopying111112 -Node: Titlepage & Copyright Page112301 -Node: titlepage113975 -Ref: titlepage-Footnote-1116477 -Node: titlefont center sp116763 -Node: title subtitle author118440 -Node: Copyright121209 -Node: end titlepage122732 -Node: headings on off124518 -Node: Contents126483 -Node: The Top Node129708 -Node: Top Node Example130919 -Node: Master Menu Parts131318 -Node: Global Document Commands133123 -Node: documentdescription133874 -Node: setchapternewpage134685 -Node: paragraphindent137566 -Node: firstparagraphindent138835 -Node: exampleindent140098 -Node: Software Copying Permissions141258 -Node: Ending a File142311 -Node: Printing Indices & Menus142881 -Node: File End145976 -Node: Structuring146657 -Node: Tree Structuring148311 -Node: Structuring Command Types149725 -Node: makeinfo top152215 -Node: chapter153001 -Node: unnumbered & appendix154026 -Node: majorheading & chapheading154634 -Node: section155456 -Node: unnumberedsec appendixsec heading156484 -Node: subsection157689 -Node: unnumberedsubsec appendixsubsec subheading158274 -Node: subsubsection159451 -Node: Raise/lower sections161253 -Node: Nodes163424 -Node: Two Paths164629 -Node: Node Menu Illustration165960 -Node: node169763 -Node: Node Names172830 -Node: Writing a Node174269 -Node: Node Line Tips176602 -Node: Node Line Requirements177401 -Node: First Node179553 -Node: makeinfo top command180978 -Node: makeinfo Pointer Creation182254 -Node: anchor184148 -Node: Menus185738 -Node: Menu Location186804 -Node: Writing a Menu188434 -Node: Menu Parts189753 -Node: Less Cluttered Menu Entry190912 -Node: Menu Example191538 -Node: Other Info Files193043 -Node: Cross References194890 -Node: References195856 -Node: Cross Reference Commands197623 -Node: Cross Reference Parts198683 -Node: xref201694 -Node: Reference Syntax202494 -Node: One Argument204126 -Node: Two Arguments205148 -Node: Three Arguments206268 -Node: Four and Five Arguments208664 -Node: Top Node Naming211081 -Node: ref212092 -Node: pxref213679 -Node: inforef216215 -Node: uref217591 -Node: Marking Text220323 -Node: Indicating220971 -Node: Useful Highlighting223173 -Node: code225345 -Node: kbd228765 -Node: key230980 -Node: samp232438 -Node: verb233914 -Node: var235030 -Node: env236999 -Node: file237505 -Node: command238121 -Node: option238822 -Node: dfn239337 -Node: cite240256 -Node: abbr240716 -Node: acronym242142 -Node: indicateurl244473 -Node: email245166 -Node: Emphasis246017 -Node: emph & strong246849 -Node: Smallcaps248059 -Node: Fonts249395 -Node: Quotations and Examples251750 -Node: Block Enclosing Commands253504 -Node: quotation255686 -Node: example257260 -Node: verbatim259574 -Node: verbatiminclude261404 -Node: lisp262518 -Ref: lisp-Footnote-1263252 -Node: small263370 -Node: display264896 -Node: format266000 -Node: exdent266641 -Node: flushleft & flushright267728 -Node: noindent268998 -Node: indent270857 -Node: cartouche271896 -Node: Lists and Tables273087 -Node: Introducing Lists273771 -Node: itemize275428 -Node: enumerate277701 -Node: Two-column Tables280194 -Node: table280886 -Node: ftable vtable283559 -Node: itemx284651 -Node: Multi-column Tables285832 -Node: Multitable Column Widths286536 -Node: Multitable Rows288013 -Node: Special Displays290152 -Node: Floats290936 -Node: float291828 -Ref: fig:ex1292497 -Node: caption shortcaption293769 -Node: listoffloats295352 -Node: Images296750 -Node: Image Syntax297180 -Node: Image Scaling300421 -Node: Footnotes302140 -Ref: Footnotes-Footnote-1302701 -Node: Footnote Commands302981 -Ref: Footnote Commands-Footnote-1304853 -Node: Footnote Styles304889 -Node: Indices307499 -Node: Index Entries308708 -Node: Predefined Indices309828 -Node: Indexing Commands311932 -Node: Combining Indices314640 -Node: syncodeindex315988 -Node: synindex317631 -Node: New Indices318163 -Node: Insertions319927 -Node: Atsign Braces Comma321467 -Node: Inserting an Atsign322041 -Node: Inserting Braces322308 -Node: Inserting a Comma322719 -Node: Inserting Quote Characters323750 -Node: Inserting Space325263 -Node: Not Ending a Sentence325850 -Node: Ending a Sentence327298 -Node: Multiple Spaces328317 -Node: frenchspacing329613 -Node: dmn331551 -Node: Inserting Accents332769 -Node: Inserting Quotation Marks334891 -Node: Dots Bullets338783 -Node: dots339602 -Node: bullet340217 -Node: TeX and copyright340621 -Node: tex341290 -Node: copyright symbol342102 -Node: registered symbol342407 -Node: euro342724 -Node: pounds344260 -Node: textdegree344557 -Node: minus344876 -Node: geq leq345799 -Node: math346188 -Node: Click Sequences348122 -Node: Glyphs349168 -Node: Glyphs Summary350282 -Node: result350904 -Node: expansion351411 -Node: Print Glyph352370 -Node: Error Glyph353259 -Node: Equivalence354110 -Node: Point Glyph354857 -Node: Breaks356425 -Node: Break Commands357979 -Node: Line Breaks358870 -Node: - and hyphenation359839 -Node: allowcodebreaks361165 -Node: w362395 -Node: tie363496 -Node: sp364395 -Node: page364809 -Node: group365189 -Node: need366936 -Node: Definition Commands367671 -Node: Def Cmd Template369317 -Node: Def Cmd Continuation Lines372157 -Node: Optional Arguments373963 -Node: deffnx375565 -Node: Def Cmds in Detail376503 -Node: Functions Commands377616 -Node: Variables Commands380513 -Node: Typed Functions382651 -Node: Typed Variables386151 -Node: Data Types387867 -Node: Abstract Objects389153 -Node: Object-Oriented Variables389755 -Node: Object-Oriented Methods392383 -Node: Def Cmd Conventions396189 -Node: Sample Function Definition396755 -Node: Conditionals399586 -Node: Conditional Commands400775 -Node: Conditional Not Commands402661 -Node: Raw Formatter Commands403940 -Node: set clear value406563 -Node: set value407773 -Node: ifset ifclear409370 -Node: value Example411496 -Node: Conditional Nesting413508 -Node: Internationalization415044 -Node: documentlanguage415575 -Node: documentencoding418368 -Node: Defining New Texinfo Commands421345 -Node: Defining Macros422518 -Node: Invoking Macros424891 -Node: Macro Details428275 -Node: alias432306 -Node: definfoenclose433725 -Node: Hardcopy436467 -Node: Use TeX438538 -Node: Format with tex/texindex439166 -Node: Format with texi2dvi443470 -Node: Print with lpr446979 -Node: Within Emacs449133 -Node: Texinfo Mode Printing450019 -Node: Compile-Command453683 -Node: Requirements Summary454560 -Node: Preparing for TeX455895 -Ref: Preparing for TeX-Footnote-1459910 -Node: Overfull hboxes460009 -Node: smallbook462163 -Node: A4 Paper463364 -Node: pagesizes464295 -Node: Cropmarks and Magnification465484 -Node: PDF Output467548 -Node: Obtaining TeX469129 -Node: Creating and Installing Info Files470103 -Node: Creating an Info File470492 -Node: makeinfo advantages471715 -Node: Invoking makeinfo472646 -Node: makeinfo options473207 -Node: Pointer Validation482812 -Node: makeinfo in Emacs486000 -Node: texinfo-format commands488478 -Node: Batch Formatting489760 -Node: Tag and Split Files490967 -Node: Installing an Info File494359 -Node: Directory File495193 -Node: New Info File496987 -Ref: New Info File-Footnote-1498096 -Node: Other Info Directories498177 -Ref: Other Info Directories-Footnote-1502447 -Ref: Other Info Directories-Footnote-2502574 -Node: Installing Dir Entries502635 -Node: Invoking install-info505826 -Node: Generating HTML512434 -Node: HTML Translation513210 -Node: HTML Splitting514587 -Node: HTML CSS516265 -Node: HTML Xref519949 -Node: HTML Xref Link Basics521151 -Node: HTML Xref Node Name Expansion524191 -Node: HTML Xref Command Expansion527282 -Node: HTML Xref 8-bit Character Expansion530334 -Node: HTML Xref Mismatch532667 -Node: Command List534480 -Node: Command Syntax578272 -Node: Tips581154 -Node: Sample Texinfo Files592146 -Node: Short Sample Texinfo File592607 -Node: GNU Sample Texts594197 -Node: Verbatim Copying License599694 -Node: All-permissive Copying License600790 -Node: Include Files601815 -Node: Using Include Files602921 -Node: texinfo-multiple-files-update605468 -Node: Include Files Requirements607831 -Node: Sample Include File609080 -Node: Include Files Evolution610312 -Node: Headings612287 -Node: Headings Introduced612939 -Node: Heading Format614811 -Node: Heading Choice617250 -Node: Custom Headings618623 -Node: Catching Mistakes624284 -Node: makeinfo Preferred625597 -Node: Debugging with Info626477 -Node: Debugging with TeX629816 -Node: Using texinfo-show-structure634074 -Node: Using occur637159 -Node: Running Info-Validate638695 -Node: Using Info-validate639757 -Node: Unsplit641562 -Node: Tagifying642616 -Node: Splitting643473 -Node: GNU Free Documentation License645096 -Node: Command and Variable Index667546 -Node: General Index700891 - -End Tag Table diff --git a/Master/texmf/doc/man/man1/info.1 b/Master/texmf/doc/man/man1/info.1 deleted file mode 100644 index aadae61022c..00000000000 --- a/Master/texmf/doc/man/man1/info.1 +++ /dev/null @@ -1,93 +0,0 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.35. -.TH INFO "1" "April 2008" "info 4.12" "User Commands" -.SH NAME -info \- read Info documents -.SH SYNOPSIS -.B info -[\fIOPTION\fR]... [\fIMENU-ITEM\fR...] -.SH DESCRIPTION -Read documentation in Info format. -.SH OPTIONS -.TP -\fB\-k\fR, \fB\-\-apropos\fR=\fISTRING\fR -look up STRING in all indices of all manuals. -.TP -\fB\-d\fR, \fB\-\-directory\fR=\fIDIR\fR -add DIR to INFOPATH. -.TP -\fB\-\-dribble\fR=\fIFILENAME\fR -remember user keystrokes in FILENAME. -.TP -\fB\-f\fR, \fB\-\-file\fR=\fIFILENAME\fR -specify Info file to visit. -.TP -\fB\-h\fR, \fB\-\-help\fR -display this help and exit. -.TP -\fB\-\-index\-search\fR=\fISTRING\fR -go to node pointed by index entry STRING. -.TP -\fB\-n\fR, \fB\-\-node\fR=\fINODENAME\fR -specify nodes in first visited Info file. -.TP -\fB\-o\fR, \fB\-\-output\fR=\fIFILENAME\fR -output selected nodes to FILENAME. -.TP -\fB\-R\fR, \fB\-\-raw\-escapes\fR -output "raw" ANSI escapes (default). -.TP -\fB\-\-no\-raw\-escapes\fR -output escapes as literal text. -.TP -\fB\-\-restore\fR=\fIFILENAME\fR -read initial keystrokes from FILENAME. -.TP -\fB\-O\fR, \fB\-\-show\-options\fR, \fB\-\-usage\fR -go to command\-line options node. -.TP -\fB\-\-subnodes\fR -recursively output menu items. -.TP -\fB\-\-vi\-keys\fR -use vi\-like and less\-like key bindings. -.TP -\fB\-\-version\fR -display version information and exit. -.TP -\fB\-w\fR, \fB\-\-where\fR, \fB\-\-location\fR -print physical location of Info file. -.PP -The first non\-option argument, if present, is the menu entry to start from; -it is searched for in all `dir' files along INFOPATH. -If it is not present, info merges all `dir' files and shows the result. -Any remaining arguments are treated as the names of menu -items relative to the initial node visited. -.SH EXAMPLES -.TP -info -show top\-level dir menu -.TP -info emacs -start at emacs node from top\-level dir -.TP -info emacs buffers -start at buffers node within emacs manual -.TP -info \fB\-\-show\-options\fR emacs -start at node with emacs' command line options -.TP -info \fB\-\-subnodes\fR \fB\-o\fR out.txt emacs -dump entire manual to out.txt -.TP -info \fB\-f\fR ./foo.info -show file ./foo.info, not searching dir -.SH "REPORTING BUGS" -Email bug reports to bug\-texinfo@gnu.org, -general questions and discussion to help\-texinfo@gnu.org. -Texinfo home page: http://www.gnu.org/software/texinfo/ -.SH COPYRIGHT -Copyright \(co 2008 Free Software Foundation, Inc. -License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> -.br -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. diff --git a/Master/texmf/doc/man/man1/info.pdf b/Master/texmf/doc/man/man1/info.pdf Binary files differdeleted file mode 100644 index c383ffa5889..00000000000 --- a/Master/texmf/doc/man/man1/info.pdf +++ /dev/null diff --git a/Master/texmf/doc/man/man1/infokey.1 b/Master/texmf/doc/man/man1/infokey.1 deleted file mode 100644 index f18df20d548..00000000000 --- a/Master/texmf/doc/man/man1/infokey.1 +++ /dev/null @@ -1,42 +0,0 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.35. -.TH INFOKEY "1" "April 2008" "infokey 4.12" "User Commands" -.SH NAME -infokey \- compile customizations for Info -.SH SYNOPSIS -.B infokey -[\fIOPTION\fR]... [\fIINPUT-FILE\fR] -.SH DESCRIPTION -Compile infokey source file to infokey file. Reads INPUT\-FILE (default -$HOME/.infokey) and writes compiled key file to (by default) $HOME/.info. -.SH OPTIONS -.TP -\fB\-\-output\fR FILE -output to FILE instead of $HOME/.info -.TP -\fB\-\-help\fR -display this help and exit. -.TP -\fB\-\-version\fR -display version information and exit. -.SH "REPORTING BUGS" -Email bug reports to bug\-texinfo@gnu.org, -general questions and discussion to help\-texinfo@gnu.org. -Texinfo home page: http://www.gnu.org/software/texinfo/ -.SH COPYRIGHT -Copyright \(co 2008 Free Software Foundation, Inc. -License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> -.br -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. -.SH "SEE ALSO" -The full documentation for -.B infokey -is maintained as a Texinfo manual. If the -.B info -and -.B infokey -programs are properly installed at your site, the command -.IP -.B info infokey -.PP -should give you access to the complete manual. diff --git a/Master/texmf/doc/man/man1/infokey.pdf b/Master/texmf/doc/man/man1/infokey.pdf Binary files differdeleted file mode 100644 index f9a18ef0bb1..00000000000 --- a/Master/texmf/doc/man/man1/infokey.pdf +++ /dev/null diff --git a/Master/texmf/doc/man/man1/install-info.1 b/Master/texmf/doc/man/man1/install-info.1 deleted file mode 100644 index c0592b183d0..00000000000 --- a/Master/texmf/doc/man/man1/install-info.1 +++ /dev/null @@ -1,129 +0,0 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.35. -.TH INSTALL-INFO "1" "April 2008" "install-info 4.12" "User Commands" -.SH NAME -install-info \- update info/dir entries -.SH SYNOPSIS -.B install-info -[\fIOPTION\fR]... [\fIINFO-FILE \fR[\fIDIR-FILE\fR]] -.SH DESCRIPTION -Add or remove entries in INFO\-FILE from the Info directory DIR\-FILE. -.SH OPTIONS -.TP -\fB\-\-debug\fR -report what is being done. -.TP -\fB\-\-delete\fR -delete existing entries for INFO\-FILE from DIR\-FILE; -don't insert any new entries. -.TP -\fB\-\-description\fR=\fITEXT\fR -the description of the entry is TEXT; used with -the \fB\-\-name\fR option to become synonymous with the -\fB\-\-entry\fR option. -.TP -\fB\-\-dir\-file\fR=\fINAME\fR -specify file name of Info directory file; -equivalent to using the DIR\-FILE argument. -.TP -\fB\-\-dry\-run\fR -same as \fB\-\-test\fR. -.TP -\fB\-\-entry\fR=\fITEXT\fR -insert TEXT as an Info directory entry. -TEXT is written as an Info menu item line followed -.IP -by zero or more extra lines starting with whitespace. -.IP -If you specify more than one entry, all are added. -If you don't specify any entries, they are determined -.IP -from information in the Info file itself. -.IP -When removing, TEXT specifies the entry to remove. -TEXT is only removed as a last resort, if the -entry as determined from the Info file is not present, -and the basename of the Info file isn't found either. -.TP -\fB\-\-help\fR -display this help and exit. -.TP -\fB\-\-info\-dir\fR=\fIDIR\fR -same as \fB\-\-dir\-file\fR=\fIDIR\fR/dir. -.TP -\fB\-\-info\-file\fR=\fIFILE\fR -specify Info file to install in the directory; -equivalent to using the INFO\-FILE argument. -.TP -\fB\-\-item\fR=\fITEXT\fR -same as \fB\-\-entry\fR=\fITEXT\fR. -.TP -\fB\-\-keep\-old\fR -do not replace entries, or remove empty sections. -.TP -\fB\-\-menuentry\fR=\fITEXT\fR -same as \fB\-\-name\fR=\fITEXT\fR. -.TP -\fB\-\-name\fR=\fITEXT\fR -the name of the entry is TEXT; used with \fB\-\-description\fR -to become synonymous with the \fB\-\-entry\fR option. -.TP -\fB\-\-no\-indent\fR -do not format new entries in the DIR file. -.TP -\fB\-\-quiet\fR -suppress warnings. -.TP -\fB\-\-regex\fR=\fIR\fR -put this file's entries in all sections that match the -regular expression R (ignoring case). -.TP -\fB\-\-remove\fR -same as \fB\-\-delete\fR. -.TP -\fB\-\-remove\-exactly\fR -only remove if the info file name matches exactly; -suffixes such as .info and .gz are not ignored. -.TP -\fB\-\-section\fR=\fISEC\fR -put entries in section SEC of the directory. -If you specify more than one section, all the entries -.IP -are added in each of the sections. -.IP -If you don't specify any sections, they are determined -.IP -from information in the Info file itself. -.TP -\fB\-\-section\fR R SEC -equivalent to \fB\-\-regex\fR=\fIR\fR \fB\-\-section\fR=\fISEC\fR \fB\-\-add\-once\fR. -.TP -\fB\-\-silent\fR -suppress warnings. -.TP -\fB\-\-test\fR -suppress updating of DIR\-FILE. -.TP -\fB\-\-version\fR -display version information and exit. -.SH "REPORTING BUGS" -Email bug reports to bug\-texinfo@gnu.org, -general questions and discussion to help\-texinfo@gnu.org. -Texinfo home page: http://www.gnu.org/software/texinfo/ -.SH COPYRIGHT -Copyright \(co 2008 Free Software Foundation, Inc. -License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> -.br -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. -.SH "SEE ALSO" -The full documentation for -.B install-info -is maintained as a Texinfo manual. If the -.B info -and -.B install-info -programs are properly installed at your site, the command -.IP -.B info install-info -.PP -should give you access to the complete manual. diff --git a/Master/texmf/doc/man/man1/install-info.pdf b/Master/texmf/doc/man/man1/install-info.pdf Binary files differdeleted file mode 100644 index 6cd7ea246c4..00000000000 --- a/Master/texmf/doc/man/man1/install-info.pdf +++ /dev/null diff --git a/Master/texmf/doc/man/man1/makeinfo.1 b/Master/texmf/doc/man/man1/makeinfo.1 deleted file mode 100644 index 0850e5f1b99..00000000000 --- a/Master/texmf/doc/man/man1/makeinfo.1 +++ /dev/null @@ -1,219 +0,0 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.35. -.TH MAKEINFO "1" "April 2008" "makeinfo 4.12" "User Commands" -.SH NAME -makeinfo \- translate Texinfo documents -.SH SYNOPSIS -.B makeinfo -[\fIOPTION\fR]... \fITEXINFO-FILE\fR... -.SH DESCRIPTION -Translate Texinfo source documentation to various other formats, by default -Info files suitable for reading online with Emacs or standalone GNU Info. -.SS "General options:" -.TP -\fB\-\-error\-limit\fR=\fINUM\fR -quit after NUM errors (default 100). -.TP -\fB\-\-document\-language\fR=\fISTR\fR locale to use in translating Texinfo keywords -for the output document (default C). -.TP -\fB\-\-force\fR -preserve output even if errors. -.TP -\fB\-\-help\fR -display this help and exit. -.TP -\fB\-\-no\-validate\fR -suppress node cross\-reference validation. -.TP -\fB\-\-no\-warn\fR -suppress warnings (but not errors). -.TP -\fB\-v\fR, \fB\-\-verbose\fR -explain what is being done. -.TP -\fB\-\-version\fR -display version information and exit. -.SS "Output format selection (default is to produce Info):" -.TP -\fB\-\-docbook\fR -output Docbook XML rather than Info. -.TP -\fB\-\-html\fR -output HTML rather than Info. -.TP -\fB\-\-xml\fR -output Texinfo XML rather than Info. -.TP -\fB\-\-plaintext\fR -output plain text rather than Info. -.SS "General output options:" -.TP -\fB\-E\fR, \fB\-\-macro\-expand\fR=\fIFILE\fR -output macro\-expanded source to FILE, -ignoring any @setfilename. -.TP -\fB\-\-no\-headers\fR -suppress node separators, Node: lines, and menus -from Info output (thus producing plain text) -or from HTML (thus producing shorter output); -also, write to standard output by default. -.TP -\fB\-\-no\-split\fR -suppress the splitting of Info or HTML output, -generate only one output file. -.TP -\fB\-\-number\-sections\fR -output chapter and sectioning numbers. -.TP -\fB\-o\fR, \fB\-\-output\fR=\fIFILE\fR -output to FILE (or directory if split HTML). -.SS "Options for Info and plain text:" -.TP -\fB\-\-disable\-encoding\fR -do not output accented and special characters -in Info output based on @documentencoding. -.TP -\fB\-\-enable\-encoding\fR -override \fB\-\-disable\-encoding\fR (default). -.TP -\fB\-\-fill\-column\fR=\fINUM\fR -break Info lines at NUM characters (default 72). -.TP -\fB\-\-footnote\-style\fR=\fISTYLE\fR -output footnotes in Info according to STYLE: -`separate' to put them in their own node; -`end' to put them at the end of the node, in -which they are defined (this is the default). -.TP -\fB\-\-paragraph\-indent\fR=\fIVAL\fR -indent Info paragraphs by VAL spaces (default 3). -If VAL is `none', do not indent; if VAL is -`asis', preserve existing indentation. -.TP -\fB\-\-split\-size\fR=\fINUM\fR -split Info files at size NUM (default 300000). -.SS "Options for HTML:" -.TP -\fB\-\-css\-include\fR=\fIFILE\fR -include FILE in HTML <style> output; -read stdin if FILE is \-. -.TP -\fB\-\-css\-ref\fR=\fIURL\fR -generate reference to a CSS file. -.TP -\fB\-\-transliterate\-file\-names\fR -produce file names in ASCII transliteration. -.SS "Options for XML and Docbook:" -.TP -\fB\-\-output\-indent\fR=\fIVAL\fR -indent XML elements by VAL spaces (default 2). -If VAL is 0, ignorable whitespace is dropped. -.SS "Input file options:" -.TP -\fB\-\-commands\-in\-node\-names\fR -allow @ commands in node names. -.TP -\fB\-D\fR VAR -define the variable VAR, as with @set. -.TP -\fB\-I\fR DIR -append DIR to the @include search path. -.TP -\fB\-P\fR DIR -prepend DIR to the @include search path. -.TP -\fB\-U\fR VAR -undefine the variable VAR, as with @clear. -.SS "Conditional processing in input:" -.TP -\fB\-\-ifdocbook\fR -process @ifdocbook and @docbook even if -not generating Docbook. -.TP -\fB\-\-ifhtml\fR -process @ifhtml and @html even if not generating HTML. -.TP -\fB\-\-ifinfo\fR -process @ifinfo even if not generating Info. -.TP -\fB\-\-ifplaintext\fR -process @ifplaintext even if not generating plain text. -.TP -\fB\-\-iftex\fR -process @iftex and @tex; implies \fB\-\-no\-split\fR. -.TP -\fB\-\-ifxml\fR -process @ifxml and @xml. -.TP -\fB\-\-no\-ifdocbook\fR -do not process @ifdocbook and @docbook text. -.TP -\fB\-\-no\-ifhtml\fR -do not process @ifhtml and @html text. -.TP -\fB\-\-no\-ifinfo\fR -do not process @ifinfo text. -.TP -\fB\-\-no\-ifplaintext\fR -do not process @ifplaintext text. -.TP -\fB\-\-no\-iftex\fR -do not process @iftex and @tex text. -.TP -\fB\-\-no\-ifxml\fR -do not process @ifxml and @xml text. -.P -Also, for the \fB\-\-no\-ifFORMAT\fR options, do process @ifnotFORMAT text. -.P -The defaults for the @if... conditionals depend on the output format: -if generating HTML, \fB\-\-ifhtml\fR is on and the others are off; -if generating Info, \fB\-\-ifinfo\fR is on and the others are off; -if generating plain text, \fB\-\-ifplaintext\fR is on and the others are off; -if generating XML, \fB\-\-ifxml\fR is on and the others are off. -.SH EXAMPLES -.TP -makeinfo foo.texi -write Info to foo's @setfilename -.TP -makeinfo \fB\-\-html\fR foo.texi -write HTML to @setfilename -.TP -makeinfo \fB\-\-xml\fR foo.texi -write Texinfo XML to @setfilename -.TP -makeinfo \fB\-\-docbook\fR foo.texi -write DocBook XML to @setfilename -.TP -makeinfo \fB\-\-no\-headers\fR foo.texi -write plain text to standard output -.TP -makeinfo \fB\-\-html\fR \fB\-\-no\-headers\fR foo.texi -write html without node lines, menus -.TP -makeinfo \fB\-\-number\-sections\fR foo.texi -write Info with numbered sections -.TP -makeinfo \fB\-\-no\-split\fR foo.texi -write one Info file however big -.SH "REPORTING BUGS" -Email bug reports to bug\-texinfo@gnu.org, -general questions and discussion to help\-texinfo@gnu.org. -Texinfo home page: http://www.gnu.org/software/texinfo/ -.SH COPYRIGHT -Copyright \(co 2008 Free Software Foundation, Inc. -License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> -.br -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. -.SH "SEE ALSO" -The full documentation for -.B makeinfo -is maintained as a Texinfo manual. If the -.B info -and -.B makeinfo -programs are properly installed at your site, the command -.IP -.B info makeinfo -.PP -should give you access to the complete manual. diff --git a/Master/texmf/doc/man/man1/makeinfo.pdf b/Master/texmf/doc/man/man1/makeinfo.pdf Binary files differdeleted file mode 100644 index 58503304751..00000000000 --- a/Master/texmf/doc/man/man1/makeinfo.pdf +++ /dev/null diff --git a/Master/texmf/doc/man/man1/oxdvi.pdf b/Master/texmf/doc/man/man1/oxdvi.pdf Binary files differdeleted file mode 100644 index 000c35419d1..00000000000 --- a/Master/texmf/doc/man/man1/oxdvi.pdf +++ /dev/null diff --git a/Master/texmf/doc/man/man1/texi2dvi.1 b/Master/texmf/doc/man/man1/texi2dvi.1 deleted file mode 100644 index 98a889f6c73..00000000000 --- a/Master/texmf/doc/man/man1/texi2dvi.1 +++ /dev/null @@ -1,184 +0,0 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.35. -.TH TEXI2DVI "1" "April 2008" "texi2dvi 1.122" "User Commands" -.SH NAME -texi2dvi \- convert Texinfo documents to DVI -.SH SYNOPSIS -.B texi2dvi -[\fIOPTION\fR]... \fIFILE\fR... -.SH DESCRIPTION -Run each Texinfo or (La)TeX FILE through TeX in turn until all -cross\-references are resolved, building all indices. The directory -containing each FILE is searched for included files. The suffix of FILE -is used to determine its language ((La)TeX or Texinfo). To process -(e)plain TeX files, set the environment variable LATEX=tex. -.PP -In order to make texi2dvi a drop\-in replacement of TeX/LaTeX in AUC\-TeX, -the FILE may also be composed of the following simple TeX commands. -.TP -`\einput{FILE}' -the actual file to compile -.TP -`\enonstopmode' -same as \fB\-\-batch\fR -.PP -Makeinfo is used to perform Texinfo macro expansion before running TeX -when needed. -.SS "General options:" -.TP -\fB\-b\fR, \fB\-\-batch\fR -no interaction -.TP -\fB\-D\fR, \fB\-\-debug\fR -turn on shell debugging (set \fB\-x\fR) -.TP -\fB\-h\fR, \fB\-\-help\fR -display this help and exit successfully -.TP -\fB\-o\fR, \fB\-\-output\fR=\fIOFILE\fR -leave output in OFILE (implies \fB\-\-clean\fR); -only one input FILE may be specified in this case -.TP -\fB\-q\fR, \fB\-\-quiet\fR -no output unless errors (implies \fB\-\-batch\fR) -.TP -\fB\-s\fR, \fB\-\-silent\fR -same as \fB\-\-quiet\fR -.TP -\fB\-v\fR, \fB\-\-version\fR -display version information and exit successfully -.TP -\fB\-V\fR, \fB\-\-verbose\fR -report on what is done -.SS "TeX tuning:" -.TP -\-@ -use @input instead of \einput for preloaded Texinfo -.TP -\fB\-\-dvi\fR -output a DVI file [default] -.TP -\fB\-e\fR, \fB\-E\fR, \fB\-\-expand\fR -force macro expansion using makeinfo -.TP -\fB\-I\fR DIR -search DIR for Texinfo files -.TP -\fB\-l\fR, \fB\-\-language\fR=\fILANG\fR -specify the LANG of FILE (LaTeX or Texinfo) -.TP -\fB\-\-no\-line\-error\fR -do not pass \fB\-\-file\-line\-error\fR to TeX -.TP -\fB\-p\fR, \fB\-\-pdf\fR -use pdftex or pdflatex for processing -.TP -\fB\-r\fR, \fB\-\-recode\fR -call recode before TeX to translate input -.TP -\fB\-\-recode\-from\fR=\fIENC\fR -recode from ENC to the @documentencoding -.TP -\fB\-\-src\-specials\fR -pass \fB\-\-src\-specials\fR to TeX -.TP -\fB\-t\fR, \fB\-\-command\fR=\fICMD\fR -insert CMD in copy of input file -.TP -or \fB\-\-texinfo\fR=\fICMD\fR -multiple values accumulate -.TP -\fB\-\-translate\-file\fR=\fIFILE\fR -use given charset translation file for TeX -.SS "Build modes:" -.TP -\fB\-\-build\fR=\fIMODE\fR -specify the treatment of auxiliary files [local] -.TP -\fB\-\-tidy\fR -same as \fB\-\-build\fR=\fItidy\fR -.TP -\fB\-c\fR, \fB\-\-clean\fR -same as \fB\-\-build\fR=\fIclean\fR -.TP -\fB\-\-build\-dir\fR=\fIDIR\fR -specify where the tidy compilation is performed; -implies \fB\-\-tidy\fR; -defaults to TEXI2DVI_BUILD_DIRECTORY [.] -.TP -\fB\-\-mostly\-clean\fR -remove the auxiliary files and directories -but not the output -.PP -The MODE specifies where the TeX compilation takes place, and, as a -consequence, how auxiliary files are treated. The build mode -can also be set using the environment variable TEXI2DVI_BUILD_MODE. -.SS "Valid MODEs are:" -.TP -`local' -compile in the current directory, leaving all the auxiliary -files around. This is the traditional TeX use. -.TP -`tidy' -compile in a local *.t2d directory, where the auxiliary files -are left. Output files are copied back to the original file. -.TP -`clean' -same as `tidy', but remove the auxiliary directory afterwards. -Every compilation therefore requires the full cycle. -.SS "Using the `tidy' mode brings several advantages:" -.TP -\- -the current directory is not cluttered with plethora of temporary files. -.TP -\- -clutter can be even reduced using \fB\-\-build\-dir\fR=\fIdir\fR: all the *.t2d -directories are stored there. -.TP -\- -clutter can be reduced to zero using, e.g., \fB\-\-build\-dir=\fR/tmp/$USER.t2d -or \fB\-\-build\-dir=\fR$HOME/.t2d. -.TP -\- -the output file is updated after every succesful TeX run, for -sake of concurrent visualization of the output. In a `local' build -the viewer stops during the whole TeX run. -.TP -\- -if the compilation fails, the previous state of the output file -is preserved. -.TP -\- -PDF and DVI compilation are kept in separate subdirectories -preventing any possibility of auxiliary file incompatibility. -.PP -On the other hand, because `tidy' compilation takes place in another -directory, occasionally TeX won't be able to find some files (e.g., when -using \egraphicspath): in that case use \fB\-I\fR to specify the additional -directories to consider. -.PP -The values of the BIBTEX, LATEX (or PDFLATEX), MAKEINDEX, MAKEINFO, -TEX (or PDFTEX), TEXINDEX, and THUMBPDF environment variables are used -to run those commands, if they are set. Any CMD strings are added -after @setfilename for Texinfo input, in the first line for LaTeX input. -.SH "REPORTING BUGS" -Email bug reports to <bug\-texinfo@gnu.org>, -general questions and discussion to <help\-texinfo@gnu.org>. -Texinfo home page: http://www.gnu.org/software/texinfo/ -.SH COPYRIGHT -Copyright \(co 2008 Free Software Foundation, Inc. -License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> -.br -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. -.SH "SEE ALSO" -The full documentation for -.B texi2dvi -is maintained as a Texinfo manual. If the -.B info -and -.B texi2dvi -programs are properly installed at your site, the command -.IP -.B info texi2dvi -.PP -should give you access to the complete manual. diff --git a/Master/texmf/doc/man/man1/texi2dvi.pdf b/Master/texmf/doc/man/man1/texi2dvi.pdf Binary files differdeleted file mode 100644 index fedfa44d144..00000000000 --- a/Master/texmf/doc/man/man1/texi2dvi.pdf +++ /dev/null diff --git a/Master/texmf/doc/man/man1/texi2pdf.1 b/Master/texmf/doc/man/man1/texi2pdf.1 deleted file mode 100644 index 76d34b6e3da..00000000000 --- a/Master/texmf/doc/man/man1/texi2pdf.1 +++ /dev/null @@ -1,184 +0,0 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.35. -.TH TEXI2DVI "1" "April 2008" "texi2dvi 1.122" "User Commands" -.SH NAME -texi2dvi \- convert Texinfo documents to PDF -.SH SYNOPSIS -.B texi2dvi -[\fIOPTION\fR]... \fIFILE\fR... -.SH DESCRIPTION -Run each Texinfo or (La)TeX FILE through TeX in turn until all -cross\-references are resolved, building all indices. The directory -containing each FILE is searched for included files. The suffix of FILE -is used to determine its language ((La)TeX or Texinfo). To process -(e)plain TeX files, set the environment variable LATEX=tex. -.PP -In order to make texi2dvi a drop\-in replacement of TeX/LaTeX in AUC\-TeX, -the FILE may also be composed of the following simple TeX commands. -.TP -`\einput{FILE}' -the actual file to compile -.TP -`\enonstopmode' -same as \fB\-\-batch\fR -.PP -Makeinfo is used to perform Texinfo macro expansion before running TeX -when needed. -.SS "General options:" -.TP -\fB\-b\fR, \fB\-\-batch\fR -no interaction -.TP -\fB\-D\fR, \fB\-\-debug\fR -turn on shell debugging (set \fB\-x\fR) -.TP -\fB\-h\fR, \fB\-\-help\fR -display this help and exit successfully -.TP -\fB\-o\fR, \fB\-\-output\fR=\fIOFILE\fR -leave output in OFILE (implies \fB\-\-clean\fR); -only one input FILE may be specified in this case -.TP -\fB\-q\fR, \fB\-\-quiet\fR -no output unless errors (implies \fB\-\-batch\fR) -.TP -\fB\-s\fR, \fB\-\-silent\fR -same as \fB\-\-quiet\fR -.TP -\fB\-v\fR, \fB\-\-version\fR -display version information and exit successfully -.TP -\fB\-V\fR, \fB\-\-verbose\fR -report on what is done -.SS "TeX tuning:" -.TP -\-@ -use @input instead of \einput for preloaded Texinfo -.TP -\fB\-\-dvi\fR -output a DVI file [default] -.TP -\fB\-e\fR, \fB\-E\fR, \fB\-\-expand\fR -force macro expansion using makeinfo -.TP -\fB\-I\fR DIR -search DIR for Texinfo files -.TP -\fB\-l\fR, \fB\-\-language\fR=\fILANG\fR -specify the LANG of FILE (LaTeX or Texinfo) -.TP -\fB\-\-no\-line\-error\fR -do not pass \fB\-\-file\-line\-error\fR to TeX -.TP -\fB\-p\fR, \fB\-\-pdf\fR -use pdftex or pdflatex for processing -.TP -\fB\-r\fR, \fB\-\-recode\fR -call recode before TeX to translate input -.TP -\fB\-\-recode\-from\fR=\fIENC\fR -recode from ENC to the @documentencoding -.TP -\fB\-\-src\-specials\fR -pass \fB\-\-src\-specials\fR to TeX -.TP -\fB\-t\fR, \fB\-\-command\fR=\fICMD\fR -insert CMD in copy of input file -.TP -or \fB\-\-texinfo\fR=\fICMD\fR -multiple values accumulate -.TP -\fB\-\-translate\-file\fR=\fIFILE\fR -use given charset translation file for TeX -.SS "Build modes:" -.TP -\fB\-\-build\fR=\fIMODE\fR -specify the treatment of auxiliary files [local] -.TP -\fB\-\-tidy\fR -same as \fB\-\-build\fR=\fItidy\fR -.TP -\fB\-c\fR, \fB\-\-clean\fR -same as \fB\-\-build\fR=\fIclean\fR -.TP -\fB\-\-build\-dir\fR=\fIDIR\fR -specify where the tidy compilation is performed; -implies \fB\-\-tidy\fR; -defaults to TEXI2DVI_BUILD_DIRECTORY [.] -.TP -\fB\-\-mostly\-clean\fR -remove the auxiliary files and directories -but not the output -.PP -The MODE specifies where the TeX compilation takes place, and, as a -consequence, how auxiliary files are treated. The build mode -can also be set using the environment variable TEXI2DVI_BUILD_MODE. -.SS "Valid MODEs are:" -.TP -`local' -compile in the current directory, leaving all the auxiliary -files around. This is the traditional TeX use. -.TP -`tidy' -compile in a local *.t2d directory, where the auxiliary files -are left. Output files are copied back to the original file. -.TP -`clean' -same as `tidy', but remove the auxiliary directory afterwards. -Every compilation therefore requires the full cycle. -.SS "Using the `tidy' mode brings several advantages:" -.TP -\- -the current directory is not cluttered with plethora of temporary files. -.TP -\- -clutter can be even reduced using \fB\-\-build\-dir\fR=\fIdir\fR: all the *.t2d -directories are stored there. -.TP -\- -clutter can be reduced to zero using, e.g., \fB\-\-build\-dir=\fR/tmp/$USER.t2d -or \fB\-\-build\-dir=\fR$HOME/.t2d. -.TP -\- -the output file is updated after every succesful TeX run, for -sake of concurrent visualization of the output. In a `local' build -the viewer stops during the whole TeX run. -.TP -\- -if the compilation fails, the previous state of the output file -is preserved. -.TP -\- -PDF and DVI compilation are kept in separate subdirectories -preventing any possibility of auxiliary file incompatibility. -.PP -On the other hand, because `tidy' compilation takes place in another -directory, occasionally TeX won't be able to find some files (e.g., when -using \egraphicspath): in that case use \fB\-I\fR to specify the additional -directories to consider. -.PP -The values of the BIBTEX, LATEX (or PDFLATEX), MAKEINDEX, MAKEINFO, -TEX (or PDFTEX), TEXINDEX, and THUMBPDF environment variables are used -to run those commands, if they are set. Any CMD strings are added -after @setfilename for Texinfo input, in the first line for LaTeX input. -.SH "REPORTING BUGS" -Email bug reports to <bug\-texinfo@gnu.org>, -general questions and discussion to <help\-texinfo@gnu.org>. -Texinfo home page: http://www.gnu.org/software/texinfo/ -.SH COPYRIGHT -Copyright \(co 2008 Free Software Foundation, Inc. -License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> -.br -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. -.SH "SEE ALSO" -The full documentation for -.B texi2dvi -is maintained as a Texinfo manual. If the -.B info -and -.B texi2dvi -programs are properly installed at your site, the command -.IP -.B info texi2dvi -.PP -should give you access to the complete manual. diff --git a/Master/texmf/doc/man/man1/texi2pdf.pdf b/Master/texmf/doc/man/man1/texi2pdf.pdf Binary files differdeleted file mode 100644 index d7d6ca42629..00000000000 --- a/Master/texmf/doc/man/man1/texi2pdf.pdf +++ /dev/null diff --git a/Master/texmf/doc/man/man1/texindex.1 b/Master/texmf/doc/man/man1/texindex.1 deleted file mode 100644 index 12dfbe33dae..00000000000 --- a/Master/texmf/doc/man/man1/texindex.1 +++ /dev/null @@ -1,42 +0,0 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.35. -.TH TEXINDEX "1" "April 2008" "texindex 4.12" "User Commands" -.SH NAME -texindex \- sort Texinfo index files -.SH SYNOPSIS -.B texindex -[\fIOPTION\fR]... \fIFILE\fR... -.SH DESCRIPTION -Generate a sorted index for each TeX output FILE. -Usually FILE... is specified as `foo.??' for a document `foo.texi'. -.SH OPTIONS -.TP -\fB\-h\fR, \fB\-\-help\fR -display this help and exit -.TP -\fB\-o\fR, \fB\-\-output\fR FILE -send output to FILE -.TP -\fB\-\-version\fR -display version information and exit -.SH "REPORTING BUGS" -Email bug reports to bug\-texinfo@gnu.org, -general questions and discussion to help\-texinfo@gnu.org. -Texinfo home page: http://www.gnu.org/software/texinfo/ -.SH COPYRIGHT -Copyright \(co 2008 Free Software Foundation, Inc. -License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> -.br -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. -.SH "SEE ALSO" -The full documentation for -.B texindex -is maintained as a Texinfo manual. If the -.B info -and -.B texindex -programs are properly installed at your site, the command -.IP -.B info texindex -.PP -will give you access to the complete manual. diff --git a/Master/texmf/doc/man/man1/texindex.pdf b/Master/texmf/doc/man/man1/texindex.pdf Binary files differdeleted file mode 100644 index 4348c1d4b55..00000000000 --- a/Master/texmf/doc/man/man1/texindex.pdf +++ /dev/null diff --git a/Master/texmf/doc/man/man5/info.5 b/Master/texmf/doc/man/man5/info.5 deleted file mode 100644 index 488d2a107ac..00000000000 --- a/Master/texmf/doc/man/man5/info.5 +++ /dev/null @@ -1,72 +0,0 @@ -.\" info(5) -.\" $Id: info.5,v 1.3 2005/01/20 22:38:32 karl Exp $ -.\" -.\" Copyright (C) 1998 Free Software Foundation, Inc. -.\" -.\" Permission is granted to make and distribute verbatim copies of this -.\" manual provided the copyright notice and this permission notice are -.\" preserved on all copies. -.\" -.\" Permission is granted to copy and distribute modified versions of -.\" this manual under the conditions for verbatim copying, provided that -.\" the entire resulting derived work is distributed under the terms of a -.\" permission notice identical to this one. -.\" -.\" Permission is granted to copy and distribute translations of this -.\" manual into another language, under the above conditions for modified -.\" versions, except that this permission notice may be stated in a -.\" translation approved by the Foundation. -.\" -.de EX -.nf -.ft CW -.in +5 -.. -.de EE -.in -5 -.ft R -.fi -.. -.TH INFO 5 "GNU Info" "FSF" -.SH NAME -info \- readable online documentation -.SH DESCRIPTION -The Info file format is an easily-parsable representation for online -documents. It can be read by -.I emacs(1) -and -.I info(1) -among other programs. -.PP -Info files are usually created from -.I texinfo(5) -sources by -.IR makeinfo(1) , -but can be created from scratch if so desired. -.PP -For a full description of the Texinfo language and associated tools, -please see the Texinfo manual (written in Texinfo itself). Most likely, -running this command from your shell: -.EX -info texinfo -.EE -or this key sequence from inside Emacs: -.EX -M-x info RET m texinfo RET -.EE -will get you there. -.SH AVAILABILITY -ftp://ftp.gnu.org/pub/gnu/texinfo-<version>.tar.gz -.br -or any GNU mirror site. -.SH "REPORTING BUGS" -Please send bug reports to bug-texinfo@gnu.org, -general questions and discussion to help-texinfo@gnu.org. -.SH "SEE ALSO" -info(1), install-info(1), makeinfo(1), texi2dvi(1), -.br -texindex(1). -.br -emacs(1), tex(1). -.br -texinfo(5). diff --git a/Master/texmf/doc/man/man5/info.pdf b/Master/texmf/doc/man/man5/info.pdf Binary files differdeleted file mode 100644 index 061da49af8a..00000000000 --- a/Master/texmf/doc/man/man5/info.pdf +++ /dev/null diff --git a/Master/texmf/doc/man/man5/texinfo.5 b/Master/texmf/doc/man/man5/texinfo.5 deleted file mode 100644 index 3bdb08afed7..00000000000 --- a/Master/texmf/doc/man/man5/texinfo.5 +++ /dev/null @@ -1,61 +0,0 @@ -.\" texinfo(5) -.\" $Id: texinfo.5,v 1.3 2005/01/20 22:38:32 karl Exp $ -.\" -.\" Copyright (C) 1998, 1999, 2002 Free Software Foundation, Inc. -.\" -.\" Permission is granted to make and distribute verbatim copies of this -.\" manual provided the copyright notice and this permission notice are -.\" preserved on all copies. -.\" -.\" Permission is granted to copy and distribute modified versions of -.\" this manual under the conditions for verbatim copying, provided that -.\" the entire resulting derived work is distributed under the terms of a -.\" permission notice identical to this one. -.\" -.\" Permission is granted to copy and distribute translations of this -.\" manual into another language, under the above conditions for modified -.\" versions, except that this permission notice may be stated in a -.\" translation approved by the Foundation. -.\" -.de EX -.nf -.ft CW -.in +5 -.. -.de EE -.in -5 -.ft R -.fi -.. -.TH TEXINFO 5 "GNU Texinfo" "FSF" -.SH NAME -texinfo \- software documentation system -.SH DESCRIPTION -Texinfo is a documentation system that uses a single source file to -produce both online information and printed output. It is primarily -designed for writing software manuals. -.PP -For a full description of the Texinfo language and associated tools, -please see the Texinfo manual (written in Texinfo itself). Most likely, -running this command from your shell: -.EX -info texinfo -.EE -or this key sequence from inside Emacs: -.EX -M-x info RET m texinfo RET -.EE -will get you there. -.SH AVAILABILITY -ftp://ftp.gnu.org/gnu/texinfo/ -.br -or any GNU mirror site. -.SH "REPORTING BUGS" -Please send bug reports to bug-texinfo@gnu.org, -general questions and discussion to help-texinfo@gnu.org. -.SH "SEE ALSO" -info(1), install-info(1), makeinfo(1), texi2dvi(1), texindex(1). -.br -emacs(1), tex(1). -.br -info(5). diff --git a/Master/texmf/doc/man/man5/texinfo.pdf b/Master/texmf/doc/man/man5/texinfo.pdf Binary files differdeleted file mode 100644 index ba3fb9c11df..00000000000 --- a/Master/texmf/doc/man/man5/texinfo.pdf +++ /dev/null diff --git a/Master/tlpkg/tlpsrc/fixme.tlpsrc b/Master/tlpkg/tlpsrc/fixme.tlpsrc index e69de29bb2d..e54ed57aa85 100644 --- a/Master/tlpkg/tlpsrc/fixme.tlpsrc +++ b/Master/tlpkg/tlpsrc/fixme.tlpsrc @@ -0,0 +1 @@ +runpattern !+d texmf-dist/tex/context/third/fixme diff --git a/Master/tlpkg/tlpsrc/fontname.tlpsrc b/Master/tlpkg/tlpsrc/fontname.tlpsrc index e69de29bb2d..e51f194ee44 100644 --- a/Master/tlpkg/tlpsrc/fontname.tlpsrc +++ b/Master/tlpkg/tlpsrc/fontname.tlpsrc @@ -0,0 +1 @@ +docpattern f texmf/doc/info/fontname.info diff --git a/Master/tlpkg/tlpsrc/texdraw.tlpsrc b/Master/tlpkg/tlpsrc/texdraw.tlpsrc index e69de29bb2d..51d842a9114 100644 --- a/Master/tlpkg/tlpsrc/texdraw.tlpsrc +++ b/Master/tlpkg/tlpsrc/texdraw.tlpsrc @@ -0,0 +1 @@ +docpattern f texmf/doc/info/texdraw.info diff --git a/Master/tlpkg/tlpsrc/texworks.tlpsrc b/Master/tlpkg/tlpsrc/texworks.tlpsrc index 7d09a37b405..6e0741c6c22 100644 --- a/Master/tlpkg/tlpsrc/texworks.tlpsrc +++ b/Master/tlpkg/tlpsrc/texworks.tlpsrc @@ -1,6 +1,5 @@ -name texworks category TLCore postaction script file=tlpkg/tlpostcode/texworks.pl runpattern f tlpkg/tlpostcode/texworks.pl -binpattern f bin/${ARCH}/texworks +binpattern f/win32 bin/${ARCH}/texworks binpattern d/win32 tlpkg/texworks diff --git a/Master/tlpkg/tlpsrc/xindy.tlpsrc b/Master/tlpkg/tlpsrc/xindy.tlpsrc index cc51ae71424..7fd968d6c37 100644 --- a/Master/tlpkg/tlpsrc/xindy.tlpsrc +++ b/Master/tlpkg/tlpsrc/xindy.tlpsrc @@ -6,7 +6,7 @@ binpattern f/!mips-irix bin/${ARCH}/texindy binpattern f/!mips-irix bin/${ARCH}/tex2xindy binpattern f/!mips-irix bin/${ARCH}/xindy binpattern f/!mips-irix bin/${ARCH}/xindy.run -binpattern f/!mips-irix,universal-darwin,i386-cygwin bin/${ARCH}/xindy.mem +binpattern f/!mips-irix,universal-darwin bin/${ARCH}/xindy.mem binpattern f/i386-cygwin bin/${ARCH}/xindy-lisp.exe binpattern f/universal-darwin bin/universal-darwin/xindy-i386.mem binpattern f/universal-darwin bin/universal-darwin/xindy-ppc.mem |