diff options
Diffstat (limited to 'gnu/usr.bin/texinfo')
23 files changed, 0 insertions, 38864 deletions
diff --git a/gnu/usr.bin/texinfo/info-files/info-stnd.info b/gnu/usr.bin/texinfo/info-files/info-stnd.info deleted file mode 100644 index 31f486a..0000000 --- a/gnu/usr.bin/texinfo/info-files/info-stnd.info +++ /dev/null @@ -1,1259 +0,0 @@ -This is Info file info-stnd.info, produced by Makeinfo-1.55 from the -input file info-stnd.texi. - -This file documents GNU Info, a program for viewing the on-line -formatted versions of Texinfo files. This documentation is different -from the documentation for the Info reader that is part of GNU Emacs. -If you do not know how to use Info, but have a working Info reader, you -should read that documentation first. - -Copyright (C) 1992, 1993 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 also that the -sections entitled "Copying" and "GNU General Public License" are -included exactly as in the original, and 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 Free Software Foundation. - - -File: info-stnd.info, Node: Top, Next: What is Info, Prev: (dir), Up: (dir) - -The GNU Info Program -******************** - -This file documents GNU Info, a program for viewing the on-line -formatted versions of Texinfo files, version 2.9. This documentation -is different from the documentation for the Info reader that is part of -GNU Emacs. - -* Menu: - -* What is Info:: -* Options:: Options you can pass on the command line. -* Cursor Commands:: Commands which move the cursor within a node. -* Scrolling Commands:: Commands for moving the node around - in a window. -* 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. -* GNU Info Global Index:: Global index containing keystrokes, - command names, variable names, - and general concepts. - - -File: info-stnd.info, Node: What is Info, Next: Options, Prev: Top, Up: Top - -What is Info? -************* - -"Info" is a program which is used to view Info files on an ASCII -terminal. "Info files" are the result of processing Texinfo files with -the program `makeinfo' or with one of the Emacs commands, such as `M-x -texinfo-format-buffer'. Texinfo itself is a documentation system that -uses a single source file to produce both on-line information and -printed output. You can typeset and print the files that you read in -Info. - - -File: info-stnd.info, Node: Options, Next: Cursor Commands, Prev: What is Info, Up: Top - -Command Line Options -******************** - -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-NAME OPTION-VALUE] MENU-ITEM... - -The following OPTION-NAMES are available when invoking Info from the -shell: - -`--directory DIRECTORY-PATH' -`-d DIRECTORY-PATH' - Add 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. - Alternatively, you may specify a value for the environment variable - `INFOPATH'; if `--directory' is not given, the value of `INFOPATH' - is used. The value of `INFOPATH' is a colon separated list of - directory names. If you do not supply `INFOPATH' or - `--directory-path', Info uses a default path. - -`--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. - -`--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'(1) - (*note Options-Footnotes::). 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. - -`--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. - -`--help' -`-h' - Produces a relatively brief description of the available Info - options. - -`--version' - Prints the version information of Info and exits. - -`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, - while the second argument is a menu item in the first argument's - node. 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'. - - -File: info-stnd.info, Node: Options-Footnotes, Up: Options - -(1) 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 from -the shell as in: `info --node '(emacs)Buffers'' - - -File: info-stnd.info, Node: Cursor Commands, Next: Scrolling Commands, Prev: Options, Up: Top - -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 Character Conventions: -(emacs)Characters, if you are unfamiliar with the notation. - -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'(1) (*note Cursor Commands-Footnotes::) -command name (displayed in parentheses), and a short description of -what the command does. All of the cursor motion commands can take an -"numeric" argument (*note `universal-argument': Miscellaneous -Commands.), to find out how to supply them. 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') - Move the cursor down to the next line. - -`C-p' (`prev-line') - Move the cursor up to the previous line. - -`C-a' (`beginning-of-line') - Move the cursor to the start of the current line. - -`C-e' (`end-of-line') - Move the cursor to the end of the current line. - -`C-f' (`forward-char') - Move the cursor forward a character. - -`C-b' (`backward-char') - Move the cursor backward a character. - -`M-f' (`forward-word') - Move the cursor forward a word. - -`M-b' (`backward-word') - Move the cursor backward a word. - -`M-<' (`beginning-of-node') -`b' - Move the cursor to the start of the current node. - -`M->' (`end-of-node') - 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. - - -File: info-stnd.info, Node: Cursor Commands-Footnotes, Up: Cursor Commands - -(1) `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 - -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. - -`SPC' (`scroll-forward') -`C-v' - 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. - -`DEL' (`scroll-backward') -`M-v' - Shift the text in this window down. The inverse of - `scroll-forward'. - -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': Variables, for more -information. - -`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. - - -File: info-stnd.info, Node: Node Commands, Next: Searching Commands, Prev: Scrolling Commands, Up: Top - -Selecting a New 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'. - -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') - Select the `Next' node. - -`p' (`prev-node') - Select the `Prev' node. - -`u' (`up-node') - 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 through the list of already visited nodes for this window. `l' -with a negative numeric argument moves forward through the history of -nodes for this window, so you can quickly step between two adjacent (in -viewing history) nodes. - -`l' (`history-node') - Select the most recently selected node in this window. - -Two additional commands make it easy to select the most commonly -selected nodes; they are `t' and `d'. - -`t' (`top-node') - Select the node `Top' in the current Info file. - -`d' (`dir-node') - 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') - Selects the first node which appears in this file. This node is - most often `Top', but it does not have to be. - -`>' (`last-node') - Select the last node which appears in this file. - -`]' (`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': Variables, for more information. - -`g' (`goto-node') - Read the name of a node and select it. No completion is done while - reading the node name, since the desired node may reside in a - separate file. The node must be typed exactly as it appears in - the Info file. A file name may be included as with any node - specification, for example - - `g(emacs)Buffers' - - finds the node `Buffers' in the Info file `emacs'. - -`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 - -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. - -`C-s' (`isearch-forward') - Interactively search forward through the Info file for a string as - you type it. - -`C-r' (`isearch-backward') - Interactively search backward through the Info file for a string as - you type it. - -`i' (`index-search') - Look up a string in the indices for this Info file, and select a - node where the found index entry points to. - -`,' (`next-index-match') - Move to the node containing the next matching index item from the - last `i' command. - -The most basic searching command is `s' (`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. - -"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. - - -File: info-stnd.info, Node: Xref Commands, Next: Window Commands, Prev: Searching Commands, Up: Top - -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 - -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 - -Selecting Xrefs -=============== - -The following table lists the Info commands which operate on menu items. - -`1' (`menu-digit') -`2' ... `9' - 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. - -`0' (`last-menu-item') - 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. - -`M-x find-menu' - Move the cursor to the start of this node's menu. - -This table lists the Info commands which operate on note cross -references. - -`f' (`xref-item') -`r' - 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. - -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') - Move the cursor the start of the nearest previous menu item or note - reference in this node. - -`RET' (`select-reference-this-line') - 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 - -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 - -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--------------- - -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 - -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, please *note automatic-tiling: - Variables. for more information. - -`C-x 0' (`delete-window') - Delete the current window from the screen. If you have made too - many windows and your screen appears cluttered, this is the way to - get rid of some of them. - -`C-x 1' (`keep-one-window') - Delete all of the windows excepting the current one. - -`ESC C-v' (`scroll-other-window') - Scroll the other window, in the same fashion that `C-v' might - scroll the current window. Given a negative argument, scroll the - "other" window backward. - -`C-x ^' (`grow-window') - Grow (or shrink) the current window. Given a numeric argument, - grow the current window that many lines; with a negative numeric - argument, shrink the window instead. - -`C-x t' (`tile-windows') - Divide the available screen space among all of the visible windows. - Each window is given an equal portion of the screen in which to - display its contents. The variable `automatic-tiling' can cause - `tile-windows' to be called when a window is created or deleted. - *Note `automatic-tiling': Variables. - - -File: info-stnd.info, Node: The Echo Area, Prev: Basic Windows, Up: Window Commands - -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') - Move forward a character. - -`C-b' (`echo-area-backward') - Move backward a character. - -`C-a' (`echo-area-beg-of-line') - Move to the start of the input line. - -`C-e' (`echo-area-end-of-line') - Move to the end of the input line. - -`M-f' (`echo-area-forward-word') - Move forward a word. - -`M-b' (`echo-area-backward-word') - Move backward a word. - -`C-d' (`echo-area-delete') - Delete the character under the cursor. - -`DEL' (`echo-area-rubout') - Delete the character behind the cursor. - -`C-g' (`echo-area-abort') - Cancel or quit the current operation. If completion is being read, - `C-g' discards the text of the input line which does not match any - completion. If the input line is empty, `C-g' aborts the calling - function. - -`RET' (`echo-area-newline') - Accept (or forces completion of) the current input line. - -`C-q' (`echo-area-quoted-insert') - Insert the next character verbatim. This is how you can insert - control characters into a search string, for example. - -PRINTING CHARACTER (`echo-area-insert') - Insert the character. - -`M-TAB' (`echo-area-tab-insert') - Insert a TAB character. - -`C-t' (`echo-area-transpose-chars') - Transpose the characters at the cursor. - -The next group of commands deal with "killing", and "yanking" text. -For an in depth discussion of killing and yanking, *note Killing and -Deleting: (emacs)Killing. - -`M-d' (`echo-area-kill-word') - Kill the word following the cursor. - -`M-DEL' (`echo-area-backward-kill-word') - Kill the word preceding the cursor. - -`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 `?', the possible - completions would contain: - - 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. - - -File: info-stnd.info, Node: Printing Nodes, Next: Miscellaneous Commands, Prev: Window Commands, Up: Top - -Printing Out Nodes -****************** - -You may wish to print out the contents of a node as a quick reference -document for later use. Info provides you with a command for doing -this. 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. - -`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'. - - -File: info-stnd.info, Node: Miscellaneous Commands, Next: Variables, Prev: Printing Nodes, Up: Top - -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') -`?' - 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') - 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. - -`M-1' (`add-digit-to-numeric-arg') -`M-2' ... `M-9' - 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' - -`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') - Cancel current operation. - -The `q' command of Info simply quits running Info. - -`q' (`quit') - 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. - -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: GNU Info Global Index, Prev: Miscellaneous Commands, Up: Top - -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. - -`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; 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. - This variable is `On' 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. - -`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'. - -`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. - -`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. - -`scroll-behavior' - Control what happens when forward scrolling is requested at the - end of a node, or when backward scrolling is requested at the - beginning of a node. The default value for this variable is - `Continuous'. There are three possible values for this variable: - - `Continuous' - Try to get the first item in this node's menu, or failing - that, the `Next' node, or failing that, the `Next' of the - `Up'. This behavior is identical to using the `]' - (`global-next-node') and `[' (`global-prev-node') commands. - - `Next Only' - Only try to get the `Next' node. - - `Page Only' - Simply give up, changing nothing. If `scroll-behavior' is - `Page Only', no scrolling command can change the node that is - being viewed. - -`scroll-step' - The number of lines to scroll when the cursor moves out of the - window. Scrolling happens automatically if the cursor has moved - out of the visible portion of the node text when it is time to - display. Usually the scrolling is done so as to put the cursor on - the center line of the current window. However, if the variable - `scroll-step' has a nonzero value, Info attempts to scroll the - node text by that many lines; if that is enough to bring the - cursor back into the window, that is what is done. The default - value of this variable is 0, thus placing the cursor (and the text - it is attached to) in the center of the window. Setting this - variable to 1 causes a kind of "smooth scrolling" which some - people prefer. - -`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. - - -File: info-stnd.info, Node: GNU Info Global Index, Prev: Variables, Up: Top - -Global Index -************ - -* Menu: - -* ,: Searching Commands. -* 0, in Info windows: Selecting Xrefs. -* 1 ... 9, in Info windows: Selecting Xrefs. -* 1 ... 9, in Info windows: Selecting Xrefs. -* <: Node Commands. -* >: Node Commands. -* ?, in Info windows: Miscellaneous Commands. -* ?, in the echo area: The Echo Area. -* -subnodes, command line option: Options. -* abort-key: Miscellaneous Commands. -* add-digit-to-numeric-arg: Miscellaneous Commands. -* arguments, command line: Options. -* automatic-footnotes: Variables. -* automatic-tiling: Variables. -* b, in Info windows: Cursor Commands. -* backward-char: Cursor Commands. -* backward-word: Cursor Commands. -* beginning-of-line: Cursor Commands. -* beginning-of-node: Cursor Commands. -* C-a, in Info windows: Cursor Commands. -* C-a, in the echo area: The Echo Area. -* C-b, in Info windows: Cursor Commands. -* C-b, in the echo area: The Echo Area. -* C-d, in the echo area: The Echo Area. -* C-e, in Info windows: Cursor Commands. -* C-e, in the echo area: The Echo Area. -* C-f, in Info windows: Cursor Commands. -* C-f, in the echo area: The Echo Area. -* C-g, in Info windows: Miscellaneous Commands. -* C-g, in the echo area: The Echo Area. -* C-h: Miscellaneous Commands. -* C-k, in the echo area: The Echo Area. -* C-l: Scrolling Commands. -* C-n: Cursor Commands. -* C-p: Cursor Commands. -* C-q, in the echo area: The Echo Area. -* C-r: Searching Commands. -* C-s: Searching Commands. -* C-t, in the echo area: The Echo Area. -* C-u: Miscellaneous Commands. -* C-v: Scrolling Commands. -* C-w: Scrolling Commands. -* C-x 0: Basic Windows. -* C-x 1: Basic Windows. -* C-x 2: Basic Windows. -* C-x b: Node Commands. -* C-x C-b: Node Commands. -* C-x C-f: Node Commands. -* C-x DEL, in the echo area: The Echo Area. -* C-x k: Node Commands. -* C-x o: Basic Windows. -* C-x t: Basic Windows. -* C-x ^: Basic Windows. -* C-y, in the echo area: The Echo Area. -* cancelling the current operation: Miscellaneous Commands. -* cancelling typeahead: Miscellaneous Commands. -* command line options: Options. -* commands, describing: Miscellaneous Commands. -* cursor, moving: Cursor Commands. -* d: Node Commands. -* DEL, in Info windows: Scrolling Commands. -* DEL, in the echo area: The Echo Area. -* delete-window: Basic Windows. -* describe-command: Miscellaneous Commands. -* describe-key: Miscellaneous Commands. -* describe-variable: Variables. -* dir-node: Node Commands. -* directory path: Options. -* echo area: The Echo Area. -* echo-area-abort: The Echo Area. -* echo-area-backward: The Echo Area. -* echo-area-backward-kill-line: The Echo Area. -* echo-area-backward-kill-word: The Echo Area. -* echo-area-backward-word: The Echo Area. -* echo-area-beg-of-line: The Echo Area. -* echo-area-complete: The Echo Area. -* echo-area-delete: The Echo Area. -* echo-area-end-of-line: The Echo Area. -* echo-area-forward: The Echo Area. -* echo-area-forward-word: The Echo Area. -* echo-area-insert: The Echo Area. -* echo-area-kill-line: The Echo Area. -* echo-area-kill-word: The Echo Area. -* echo-area-newline: The Echo Area. -* echo-area-possible-completions: The Echo Area. -* echo-area-quoted-insert: The Echo Area. -* echo-area-rubout: The Echo Area. -* echo-area-scroll-completions-window: The Echo Area. -* echo-area-tab-insert: The Echo Area. -* echo-area-transpose-chars: The Echo Area. -* echo-area-yank: The Echo Area. -* echo-area-yank-pop: The Echo Area. -* end-of-line: Cursor Commands. -* end-of-node: Cursor Commands. -* errors-ring-bell: Variables. -* ESC C-f: Miscellaneous Commands. -* ESC C-v, in Info windows: Basic Windows. -* ESC C-v, in the echo area: The Echo Area. -* f: Selecting Xrefs. -* file, outputting to: Options. -* find-menu: Selecting Xrefs. -* first-node: Node Commands. -* footnotes, displaying: Miscellaneous Commands. -* forward-char: Cursor Commands. -* forward-word: Cursor Commands. -* functions, describing: Miscellaneous Commands. -* g: Node Commands. -* gc-compressed-files: Variables. -* get-help-window: Miscellaneous Commands. -* get-info-help-node: Miscellaneous Commands. -* global-next-node: Node Commands. -* global-prev-node: Node Commands. -* goto-node: Node Commands. -* grow-window: Basic Windows. -* h: Miscellaneous Commands. -* history-node: Node Commands. -* i: Searching Commands. -* index-search: Searching Commands. -* Info file, selecting: Options. -* INFO_PRINT_COMMAND, environment variable: Printing Nodes. -* isearch-backward: Searching Commands. -* isearch-forward: Searching Commands. -* ISO Latin characters: Variables. -* ISO-Latin: Variables. -* keep-one-window: Basic Windows. -* keys, describing: Miscellaneous Commands. -* kill-node: Node Commands. -* l: Node Commands. -* last-menu-item: Selecting Xrefs. -* last-node: Node Commands. -* list-visited-nodes: Node Commands. -* m: Selecting Xrefs. -* M-1 ... M-9: Miscellaneous Commands. -* M-<: Cursor Commands. -* M->: Cursor Commands. -* M-b, in Info windows: Cursor Commands. -* M-b, in the echo area: The Echo Area. -* M-d, in the echo area: The Echo Area. -* M-DEL, in the echo area: The Echo Area. -* M-f, in Info windows: Cursor Commands. -* M-f, in the echo area: The Echo Area. -* M-r: Cursor Commands. -* M-TAB, in Info windows: Selecting Xrefs. -* M-TAB, in the echo area: The Echo Area. -* M-v: Scrolling Commands. -* M-y, in the echo area: The Echo Area. -* menu, following: Options. -* menu-digit: Selecting Xrefs. -* menu-item: Selecting Xrefs. -* move-to-next-xref: Selecting Xrefs. -* move-to-prev-xref: Selecting Xrefs. -* move-to-window-line: Cursor Commands. -* n: Node Commands. -* next-index-match: Searching Commands. -* next-line: Cursor Commands. -* next-node: Node Commands. -* next-window: Basic Windows. -* node, selecting: Options. -* nodes, selection of: Node Commands. -* numeric arguments: Miscellaneous Commands. -* outputting to a file: Options. -* p: Node Commands. -* prev-line: Cursor Commands. -* prev-node: Node Commands. -* prev-window: Basic Windows. -* print-node: Printing Nodes. -* printing: Printing Nodes. -* printing characters, in the echo area: The Echo Area. -* q: Miscellaneous Commands. -* quit: Miscellaneous Commands. -* quitting: Miscellaneous Commands. -* r: Selecting Xrefs. -* redraw-display: Scrolling Commands. -* RET, in Info windows: Selecting Xrefs. -* RET, in the echo area: The Echo Area. -* s: Searching Commands. -* screen, changing the height of: Miscellaneous Commands. -* scroll-backward: Scrolling Commands. -* scroll-behavior: Variables. -* scroll-forward: Scrolling Commands. -* scroll-other-window: Basic Windows. -* scroll-step: Variables. -* scrolling: Scrolling Commands. -* scrolling through node structure: Scrolling Commands. -* search: Searching Commands. -* searching: Searching Commands. -* select-reference-this-line: Selecting Xrefs. -* select-visited-node: Node Commands. -* set-screen-height: Miscellaneous Commands. -* set-variable: Variables. -* show-footnotes: Miscellaneous Commands. -* show-index-match: Variables. -* SPC, in Info windows: Scrolling Commands. -* SPC, in the echo area: The Echo Area. -* split-window: Basic Windows. -* t: Node Commands. -* TAB, in Info windows: Selecting Xrefs. -* TAB, in the echo area: The Echo Area. -* tile-windows: Basic Windows. -* tiling: Basic Windows. -* toggle-wrap: Scrolling Commands. -* top-node: Node Commands. -* u: Node Commands. -* universal-argument: Miscellaneous Commands. -* up-node: Node Commands. -* variables, describing: Variables. -* variables, setting: Variables. -* version information: Options. -* view-file: Node Commands. -* visible-bell: Variables. -* where-is: Miscellaneous Commands. -* windows, creating: Basic Windows. -* windows, deleting: Basic Windows. -* windows, manipulating: Window Commands. -* windows, selecting: Basic Windows. -* xref-item: Selecting Xrefs. -* [: Node Commands. -* ]: Node Commands. - - - -Tag Table: -Node: Top1263 -Node: What is Info2593 -Node: Options3127 -Node: Options-Footnotes6157 -Node: Cursor Commands6411 -Node: Cursor Commands-Footnotes8906 -Node: Scrolling Commands9136 -Node: Node Commands11600 -Node: Searching Commands15563 -Node: Xref Commands17151 -Node: Parts of an Xref17766 -Node: Selecting Xrefs19711 -Node: Window Commands21298 -Node: The Mode Line22233 -Node: Basic Windows23872 -Node: The Echo Area26374 -Node: Printing Nodes30531 -Node: Miscellaneous Commands31174 -Node: Variables34345 -Node: GNU Info Global Index40515 - -End Tag Table diff --git a/gnu/usr.bin/texinfo/info-files/info.info b/gnu/usr.bin/texinfo/info-files/info.info deleted file mode 100644 index b6fd850..0000000 --- a/gnu/usr.bin/texinfo/info-files/info.info +++ /dev/null @@ -1,777 +0,0 @@ -This is Info file info.info, produced by Makeinfo-1.55 from the input -file info.texi. - - This file describes how to use Info, the on-line, menu-driven GNU -documentation system. - - Copyright (C) 1989, 1992 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 Free Software Foundation. - - -File: info.info, Node: Top, Next: Getting Started, Prev: (dir), Up: (dir) - -Info: An Introduction -********************* - - Info is a program for reading documentation, which you are using now. - - To learn how to use Info, type the command `h'. It brings you to a -programmed instruction sequence. - - To learn advanced Info commands, type `n' twice. This brings you to -`Info for Experts', skipping over the . `Getting Started' chapter. - -* Menu: - -* Getting Started:: -* Advanced Info:: -* Create an Info File:: - - -File: info.info, Node: Getting Started, Next: Advanced Info, Prev: Top, Up: Top - -Getting Started -*************** - - This first part of the Info manual describes how to get around inside -of Info. The second part of the manual describes various advanced Info -commands, and how to write an Info as distinct from a Texinfo file. -The third part is about how to generate Info files from Texinfo files. - -* 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, Rubout, B and ^L commands. -* Help-M:: Menus -* Help-Adv:: Some advanced Info commands -* Help-Q:: Quitting Info - - -File: info.info, Node: Help-Small-Screen, Next: Help, Up: Getting Started - -Starting Info on a Small Screen -=============================== - - Since your terminal has an unusually small number of lines on its -screen, it is necessary to give you special advice at the beginning. - - If you see the text `--All----' at near the bottom right corner of -the screen, it means the entire text you are looking at fits on the -screen. If you see `--Top----' instead, it means that there is more -text below that does not fit. To move forward through the text and see -another screen full, press the Space bar, SPC. To move back up, press -the key labeled `Rubout' or `Delete' or DEL. - - 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 17 -This is line 18 -This is line 19 -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 -If you have managed to get here, go back to the beginning with DEL, and -come back here again, then you understand SPC and DEL. So now type an -`n'--just one character; do not type the quotes and do not type the -Return key, RET, 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 - -How to use Info -=============== - - You are talking to the program Info, for reading documentation. - - 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 top line of a node is its "header". This node's header (look at -it now) says that it is the node named `Help' in the file `info'. It -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. - - Besides a `Next', a node can have a `Previous' or an `Up'. This -node has a `Previous' but no `Up', as you can see. - - 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. - - -File: info.info, Node: Help-P, Next: Help-^L, Prev: Help, Up: Getting Started - -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 do that yet. First, try the `p' command, which takes - you to the `Previous' node. When you get there, you can do an `n' -again to return here. - - This all probably seems insultingly simple so far, but *do not* be -led into skimming. Things will get more complicated soon. Also, do -not try a new command until you are told it is time to. Otherwise, you -may make Info skip past an important warning that was coming up. - - >> Now do an `n' to get to the node `Help-^L' and learn more. - - -File: info.info, Node: Help-^L, Next: Help-M, Prev: Help-P, Up: Getting Started - -The Space, Rubout, B and ^L commands. -===================================== - - This node's header tells you that you are now at node `Help-^L', and -that `p' would get you back to `Help-P'. The node's title is -underlined; it says what the node is about (most nodes have titles). - - This is a big node and it does not all fit on your display screen. -You can tell that there is more that is not visible because you can see -the string `--Top-----' rather than `--All----' near the bottom right -corner of the screen. - - The SPC, DEL 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 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 DEL 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 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 type a SPC when there is no more to see, it rings the bell -and otherwise does nothing. The same goes for a DEL when the header of -the node is visible. - - If your screen is ever garbaged, you can tell Info to print it out -again by typing `C-l' (`Control-L', that is--hold down "Control" and -type an L or `l'). - - >> Type `C-l' now. - - To move back to the beginning of the node you are on, you can type a -lot of DELs. You can also type simply `b' for beginning. - - >> Try that now. (I have put in enough verbiage to make sure you are - not on the first screenful now). Then come back, typing SPC -several times. - - You have just learned a considerable number of commands. If you -want to use one but have trouble remembering which, you should type a ? -which prints out a brief list of commands. When you are finished -looking at the list, make it go away by typing a SPC. - - >> Type a ? now. After it finishes, type a SPC. - - (If you are using the standalone Info reader, type `l' to return -here.) - - From now on, you will encounter large nodes without warning, and -will be expected to know how to use SPC and DEL 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' to see the description of the `m' command. - - -File: info.info, Node: Help-M, Next: Help-Adv, Prev: Help-^L, Up: Getting Started - -Menus -===== - - Menus and the `m' command - - With only the `n' and `p' 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 `:'), the name of the node that talks about -that subtopic, 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: FOO's Node This tells about FOO - - The subtopic name is Foo, and the node describing it is `FOO's Node'. -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:'.]] - - 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'. - - >> Now use SPCs to find the menu in this node, then come back to -the front with a `b'. 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. - - The command to go to one of the subnodes is `m'--but *do not do it -yet!* Before you use `m', you must understand the difference between -commands and arguments. So far, you have learned several commands that -do not need arguments. When you type one, Info processes it and is -instantly ready for another command. The `m' command is different: it -is incomplete without the "name of the subtopic". Once you have typed -`m', Info tries to read the subtopic name. - - Now look for the line containing many dashes near the bottom of the -screen. There is one more line beneath that one, but usually it is -blank If it is empty, 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 mean -Info is trying to read the "argument" to a command. At such times, -commands do not work, because Info tries to use them as the argument. -You must either type the argument and finish the command you started, -or type `Control-g' to cancel the command. When you have done one of -those things, the line becomes blank 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. - - Here is a menu to give you a chance to practice. - - * Menu: The menu starts here. - - This menu givs you three ways of going to one place, Help-FOO. - - * Foo: Help-FOO. A node you can visit for fun. -* Bar: Help-FOO. Strange! two ways to get to the same place. -* Help-FOO:: And yet another! ->> 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' item name. Do not type RET yet. - - While you are typing the item name, you can use the DEL character to -cancel one character at a time if you make a mistake. - - >> Type one to cancel the `R'. You could type another `R' to -replace it. 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. - - >> Type `n' to see more commands. - - Here is another way to get to Help-FOO, a menu. You can ignore this -if you want, or else try it (but then please come back to here). - -* Menu: - -* Help-FOO:: - - -File: info.info, Node: Help-FOO, Up: Help-M - -The `u' command ---------------- - - Congratulations! This is the node `Help-FOO'. Unlike the other -nodes you have seen, this one has an `Up': `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". That puts you at the *front* of the node--to get back to where -you were reading you have to type some SPCs. - - >> Now type `u' to move back up to `Help-M'. - - -File: info.info, Node: Help-Adv, Next: Help-Q, Prev: Help-M, Up: Getting Started - -Some advanced Info commands -=========================== - - The course is almost over, so please stick with it to the end. - - 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 at a time. If you have been following directions, an `l' command -now will get you back to `Help-M'. Another `l' command would undo the -`u' and get you back to `Help-FOO'. Another `l' would undo the `m' and -get you back to `Help-M'. - - >> Try typing three `l''s, pausing in between to see what each -`l' does. - - Then follow directions again and you will end up 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, to `Help-M'). - - The `d' command 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. - - >> Try doing a `d', then do an `l' to return here (yes, *do* -return). - - Sometimes, in Info documentation, you will see a cross reference. -Cross references look like this: *Note Cross: Help-Cross. That is a -real, live cross reference which is named `Cross' and points at the -node named `Help-Cross'. - - If you wish to follow a cross reference, you must use the `f' -command. The `f' must be followed by the cross reference name (in this -case, `Cross'). You can use DEL to edit the name, and 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. - - >> Type `f', followed by `Cross', and a RET. - - 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 printing the list, so if you do not actually -want to follow a reference you should type a `Control-g' to cancel the -`f'. - - >> Type "f?" to get a list of the footnotes in this node. Then type -a `Control-g' and see how the `f' gives up. - - >> Now type `n' to see the last node of the course. - - -File: info.info, Node: Help-Cross, Up: Help-Adv - -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 Info. So you cannot expect the -footnote to have a `Next', `Previous' or `Up' 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: Help-Q, Prev: Help-Adv, Up: Getting Started - -Quitting Info -============= - - To get out of Info, back to what you were doing before, type `q' for -"Quit". - - This is the end of the course on using Info. There are some other -commands that are not essential or are meant for experienced users; -they are useful, and you can find them by looking in the directory 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 RET, to get to the node about Info and see what other help is -available. - - -File: info.info, Node: Advanced Info, Next: Create an Info File, Prev: Getting Started, Up: Top - -Info for Experts -**************** - - This chapter describes various advanced Info commands, and how to -write an Info as distinct from a Texinfo file. (However, in most -cases, writing a Texinfo file is better, since you can use it *both* to -generate an Info file and to make a printed manual. *Note Overview of -Texinfo: (texinfo)Top.) - -* Menu: - -* Expert:: Advanced Info commands: g, s, e, and 1 - 5. -* 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 tag tables for Info files. -* Checking:: Checking an Info File - - -File: info.info, Node: Expert, Next: Add, Up: Advanced Info - -Advanced Info Commands -====================== - - `g', `s', `1', - `5', and `e' - - If you know a node's name, you can go there by typing `g', the name, -and RET. Thus, `gTopRET' would go to the node called `Top' in this -file (its directory node). `gExpertRET' would come back here. - - Unlike `m', `g' does not allow the use of abbreviations. - - To go to a node in another file, you can include the filename in the -node name by putting it at the front, in parentheses. Thus, -`g(dir)TopRET' would go to the Info Directory node, which is node `Top' -in the file `dir'. - - 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'. - - The `s' command allows you to search a whole file for a string. It -switches to the next node if and when that is necessary. You type `s' -followed by the string to search for, terminated by RET. To search for -the same string again, just `s' followed by RET will do. The file's -nodes are scanned in the order they are in in the file, which has no -necessary relationship to the order that they may be in in the tree -structure of menus and `next' pointers. But normally the two orders -are not very different. In any case, you can always do a `b' to find -out what node you have reached, if the header is not visible (this can -happen, because `s' puts your cursor at the occurrence of the string, -not at the beginning of the node). - - If you grudge the system each character of type-in it requires, you -might like to use the commands `1', `2', `3', `4', and `5'. They are -short for the `m' command together with an argument. "1", "2", "3", -"4", and "5". `1' goes through the first item in the current node's -menu; `2' goes through the second item, etc. Note that numbers larger -than 5 are not allowed. If the item you want is that far down, you are -better off using an abbreviation for its name than counting. - - The Info command `e' changes from Info mode to an ordinary Emacs -editing mode, so that you can edit the text of the current node. Type -`C-c C-c' to switch back to Info. The `e' command is allowed only if -the variable `Info-enable-edit' is non-`nil'. - - -File: info.info, Node: Add, Next: Menus, Prev: Expert, Up: Advanced Info - -Adding a new node to Info -========================= - - To add a new topic to the list in the directory, you must: - - 1. Create a node, 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, or the end of file. Note: 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 ^_. - - 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 `Top', which points at all -the documentation for Info. The `Next' node is `Menus'. - - The keywords "Node", "Previous", "Up" and "Next", 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 is relative, it is taken starting from the standard Info file -directory 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)'. 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 filename, since Info when searching for a node does not -expect one 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. - - -File: info.info, Node: Menus, Next: Cross-refs, Prev: Add, Up: Advanced Info - -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-the argument -that the user must give to the `m' command 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, than 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 on that file directory, but they do not have to; and files on that -directory are not automatically listed in the Info Directory node. - - Also, although the Info node graph is claimed to be a "hierarchy", -in fact it can be *any* directed graph. Shared structures and pointer -cycles are perfectly possible, and can be used if they are appropriate -to the meaning to be expressed. There is no need for all the nodes in -a file to form a connected structure. In fact, this file has two -connected components. You are in one of them, which is under the node -`Top'; the other contains the node `Help' which the `h' command goes -to. In fact, since there is no garbage collector, nothing terrible -happens if a substructure is not pointed to, but such a substructure is -rather useless since nobody can ever find out that it exists. - - -File: info.info, Node: Cross-refs, Next: Tags, Prev: Menus, Up: Advanced Info - -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.) - - They are just examples. The places they "lead to" do not really -exist! - - -File: info.info, Node: Tags, Next: Checking, Prev: Cross-refs, Up: Advanced Info - -Tag Tables for Info Files -========================= - - You can speed up the access to nodes of a large Info file by giving -it a tag table. Unlike the tag table for a program, the tag table for -an Info file lives inside the file itself and is used automatically -whenever Info reads in the file. - - To make a tag 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. - - Once the Info file has a tag table, you must make certain it is up -to date. If, 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 tag table, Info will no longer be able to find that node. To -update the tag table, use the `Info-tagify' command again. - - An Info file tag table appears at the end of the file and looks like -this: - - ^_ - 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: Advanced Info - -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: Create an Info File, Prev: Advanced Info, Up: Top - -Creating an Info File from a Makeinfo file -****************************************** - - `makeinfo' is a utility that converts a Texinfo file into an Info -file; `texinfo-format-region' and `texinfo-format-buffer' are GNU Emacs -functions that do the same. - - *Note Creating an Info File: (texinfo)Create an Info File, to learn -how to create an Info file from a Texinfo file. - - *Note Overview of Texinfo: (texinfo)Top, to learn how to write a -Texinfo file. - - - -Tag Table: -Node: Top913 -Node: Getting Started1431 -Node: Help-Small-Screen2179 -Node: Help3921 -Node: Help-P4949 -Node: Help-^L5811 -Node: Help-M8462 -Node: Help-FOO14030 -Node: Help-Adv14766 -Node: Help-Cross17148 -Node: Help-Q17794 -Node: Advanced Info18434 -Node: Expert19330 -Node: Add21601 -Node: Menus24635 -Node: Cross-refs27509 -Node: Tags28211 -Node: Checking29510 -Node: Create an Info File30434 - -End Tag Table diff --git a/gnu/usr.bin/texinfo/info-files/makeinfo.info b/gnu/usr.bin/texinfo/info-files/makeinfo.info deleted file mode 100644 index 81dbe14..0000000 --- a/gnu/usr.bin/texinfo/info-files/makeinfo.info +++ /dev/null @@ -1,224 +0,0 @@ -This is Info file makeinfo.info, produced by Makeinfo-1.55 from the -input file makeinfo.texi. - -This file is an extract from the `Texinfo' manual. -It documents `makeinfo', a program that converts Texinfo files into -Info files. - -Copyright (C) 1992, 1993 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 Free Software Foundation. - - -File: makeinfo.info, Node: Top, Next: What is makeinfo, Prev: (dir), Up: (dir) - -`makeinfo' -********** - -This file documents the use of the `makeinfo' program, versions 1.51 -and later. It is an extract from the `Texinfo' manual. - -* Menu: - -* What is makeinfo:: - - -File: makeinfo.info, Node: What is makeinfo, Prev: Top, Up: Top - -What is `makeinfo'? -******************* - -`makeinfo' is a program for converting "Texinfo" files into "Info" -files. Texinfo is a documentation system that uses a single source -file to produce both on-line information and printed output. - -You can read the on-line information using Info; type `info' to learn -about Info. *Note Texinfo: (texinfo.texi)Top, to learn about the -Texinfo documentation system. - -* Menu: - -* Formatting Control:: -* Options:: -* Pointer Validation:: - - -File: makeinfo.info, Node: Formatting Control, Next: Options, Up: What is makeinfo - -Controlling Paragraph Formats -============================= - -In general, `makeinfo' "fills" the paragraphs that it outputs to an -Info file. Filling is the process of breaking 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. With `makeinfo', -you can control: - - * The width of each paragraph (the "fill-column"). - - * The amount of indentation that the first line of each paragraph - receives (the "paragraph-indentation"). - - -File: makeinfo.info, Node: Options, Next: Pointer Validation, Prev: Formatting Control, Up: What is makeinfo - -Command Line Options -==================== - -The following command line options are available for `makeinfo'. - -`-D VAR' - Cause VAR to be defined. This is equivalent to `@set VAR' in the - Texinfo file. - -`--error-limit LIMIT' - Set the maximum number of errors that `makeinfo' will report - before exiting (on the assumption that continuing would be - useless). The default number of errors that can be reported before - `makeinfo' gives up is 100. - -`--fill-column 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. The default value for `fill-column' is 72. - -`--footnote-style STYLE' - Set the footnote style to STYLE, either `end' for the end node - style 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. 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. - -`-I DIR' - Add `dir' to the directory search list for finding files that are - included using the `@include' command. By default, `makeinfo' - searches only the current directory. - -`--no-headers' - Do not include menus or node lines in the output. This results in - an ASCII file that you cannot read in Info since it does not - contain the requisite nodes or menus; but you can print such a - file in a single, typewriter-like font and produce acceptable - output. - -`--no-split' - Suppress the splitting stage of `makeinfo'. Normally, large - output files (where the size is greater than 70k bytes) are split - into smaller subfiles, each one approximately 50k bytes. If you - specify `--no-split', `makeinfo' will not split up the output file. - -`--no-pointer-validate' -`--no-validate' - Suppress the pointer-validation phase of `makeinfo'. 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 the output of warning messages. This does *not* suppress - the output of error messages, only warnings. You might want this - if the file you are creating has examples of Texinfo cross - references within it, and the nodes that are referenced do not - actually exist. - -`--no-number-footnotes' - Supress automatic footnote numbering. By default, `makeinfo' - numbers each footnote sequentially in a single node, resetting the - current footnote number to 1 at the start of each node. - -`--output FILE' -`-o FILE' - Specify that the output should be directed to FILE and not to the - file name specified in the `@setfilename' command found in the - Texinfo source. FILE can be the special token `-', which specifies - standard output. - -`--paragraph-indent 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. The value of INDENT is interpreted as - follows: - - * If the value of INDENT is `asis', do not change the existing - indentation at the starts of paragraphs. - - * If the value of INDENT is zero, delete any existing - indentation. - - * If the value of INDENT is greater than zero, indent each - paragraph by that number of spaces. - -`--reference-limit LIMIT' - Set the value of the number of references to a node that - `makeinfo' will make without reporting a warning. If a node has - more than this number of references in it, `makeinfo' will make the - references but also report a warning. - -`-U VAR' - Cause VAR to be undefined. This is equivalent to `@clear VAR' in - the Texinfo file. - -`--verbose' - Cause `makeinfo' to display messages saying what it is doing. - Normally, `makeinfo' only outputs messages if there are errors or - warnings. - -`--version' - Report the version number of this copy of `makeinfo'. - - -File: makeinfo.info, Node: Pointer Validation, Prev: Options, Up: What is makeinfo - -Pointer Validation -================== - -If you do not suppress pointer-validation (by using the -`--no-pointer-validation' option), `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 `Previous' node must also be pointed to by a `Next' - node. - - 3. Every node except the `Top' node must have an `Up' pointer. - - 4. The node referenced by an `Up' pointer must contain a reference to - the current node in some manner other than through a `Next' - reference. This includes menu entries and cross references. - - 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. - - - -Tag Table: -Node: Top949 -Node: What is makeinfo1215 -Node: Formatting Control1758 -Node: Options2377 -Node: Pointer Validation6743 - -End Tag Table diff --git a/gnu/usr.bin/texinfo/info-files/texi-files/info-stnd.texi b/gnu/usr.bin/texinfo/info-files/texi-files/info-stnd.texi deleted file mode 100644 index 286973b..0000000 --- a/gnu/usr.bin/texinfo/info-files/texi-files/info-stnd.texi +++ /dev/null @@ -1,1359 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header -@setfilename info-stnd.info -@settitle GNU Info -@set InfoProgVer 2.9 -@paragraphindent none -@footnotestyle separate -@synindex vr cp -@synindex fn cp -@synindex ky cp -@comment %**end of header - -@ifinfo -This file documents GNU Info, a program for viewing the on-line formatted -versions of Texinfo files. This documentation is different from the -documentation for the Info reader that is part of GNU Emacs. If you do -not know how to use Info, but have a working Info reader, you should -read that documentation first. - -Copyright @copyright{} 1992, 1993 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. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries a copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). -@end ignore - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that the -sections entitled ``Copying'' and ``GNU General Public License'' are -included exactly as in the original, and 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 Free Software Foundation. -@end ifinfo - -@titlepage -@title GNU Info User's Guide -@subtitle For GNU Info version @value{InfoProgVer} -@author Brian J. Fox (bfox@@ai.mit.edu) -@page -@vskip 0pt plus 1filll -Copyright @copyright{} 1992, 1993 Free Software Foundation - -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 also that the -sections entitled ``Copying'' and ``GNU General Public License'' are -included exactly as in the original, and 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 Free Software Foundation. -@end titlepage - -@ifinfo -@node Top, What is Info, (dir), (dir) -@top The GNU Info Program - -This file documents GNU Info, a program for viewing the on-line -formatted versions of Texinfo files, version @value{InfoProgVer}. This -documentation is different from the documentation for the Info reader -that is part of GNU Emacs. -@end ifinfo - -@menu -* What is Info:: -* Options:: Options you can pass on the command line. -* Cursor Commands:: Commands which move the cursor within a node. -* Scrolling Commands:: Commands for moving the node around - in a window. -* 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. -* GNU Info Global Index:: Global index containing keystrokes, - command names, variable names, - and general concepts. -@end menu - -@node What is Info, Options, Top, Top -@chapter What is Info? - -@iftex -This file documents GNU Info, a program for viewing the on-line formatted -versions of Texinfo files, version @value{InfoProgVer}. -@end iftex - -@dfn{Info} is a program which is used to view Info files on an ASCII -terminal. @dfn{Info files} are the result of processing Texinfo files -with the program @code{makeinfo} or with one of the Emacs commands, such -as @code{M-x texinfo-format-buffer}. Texinfo itself is a documentation -system that uses a single source file to produce both on-line -information and printed output. You can typeset and print the -files that you read in Info.@refill - -@node Options, Cursor Commands, What is Info, Top -@chapter Command Line Options -@cindex command line options -@cindex arguments, command line - -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: - -@example -info [--@var{option-name} @var{option-value}] @var{menu-item}@dots{} -@end example - -The following @var{option-names} are available when invoking Info from -the shell: - -@table @code -@cindex directory path -@item --directory @var{directory-path} -@itemx -d @var{directory-path} -Add @var{directory-path} to the list of directory paths searched when -Info needs to find a file. You may issue @code{--directory} multiple -times; once for each directory which contains Info files. -Alternatively, you may specify a value for the environment variable -@code{INFOPATH}; if @code{--directory} is not given, the value of -@code{INFOPATH} is used. The value of @code{INFOPATH} is a colon -separated list of directory names. If you do not supply @code{INFOPATH} -or @code{--directory-path}, Info uses a default path. - -@item --file @var{filename} -@itemx -f @var{filename} -@cindex Info file, selecting -Specify a particular Info file to visit. By default, Info visits -the file @code{dir}; if you use this option, Info will start with -@code{(@var{filename})Top} as the first file and node. - -@item --node @var{nodename} -@itemx -n @var{nodename} -@cindex node, selecting -Specify a particular node to visit in the initial file that Info -loads. This is especially useful in conjunction with -@code{--file}@footnote{Of course, you can specify both the file and node -in a @code{--node} command; but don't forget to escape the open and -close parentheses from the shell as in: @code{info --node -'(emacs)Buffers'}}. You may specify @code{--node} multiple times; for -an interactive Info, each @var{nodename} is visited in its own window, -for a non-interactive Info (such as when @code{--output} is given) each -@var{nodename} is processed sequentially. - -@item --output @var{filename} -@itemx -o @var{filename} -@cindex file, outputting to -@cindex outputting to a file -Specify @var{filename} as the name of a file to which to direct output. -Each node that Info visits will be output to @var{filename} instead of -interactively viewed. A value of @code{-} for @var{filename} specifies -the standard output. - -@item --subnodes -@cindex @code{--subnodes}, command line option -This option only has meaning when given in conjunction with -@code{--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. - -@item --help -@itemx -h -Produces a relatively brief description of the available Info options. - -@item --version -@cindex version information -Prints the version information of Info and exits. - -@item @var{menu-item} -@cindex menu, following -Info treats its remaining arguments as the names of menu items. The -first argument is a menu item in the initial node visited, while -the second argument is a menu item in the first argument's node. -You can easily move to the node of your choice by specifying the menu -names which describe the path to that node. For example, - -@example -info emacs buffers -@end example - -@noindent -first selects the menu item @samp{Emacs} in the node @samp{(dir)Top}, -and then selects the menu item @samp{Buffers} in the node -@samp{(emacs)Top}. -@end table - -@node Cursor Commands, Scrolling Commands, Options, Top -@chapter Moving the Cursor -@cindex cursor, moving - -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. @xref{Characters, , Character -Conventions, emacs, the GNU Emacs Manual}, if you are unfamiliar with the -notation. - -The following table lists the basic cursor movement commands in Info. -Each entry consists of the key sequence you should type to execute the -cursor movement, the @code{M-x}@footnote{@code{M-x} is also a command; it -invokes @code{execute-extended-command}. @xref{M-x, , Executing an -extended command, emacs, the GNU Emacs Manual}, for more detailed -information.} command name (displayed in parentheses), and a short -description of what the command does. All of the cursor motion commands -can take an @dfn{numeric} argument (@pxref{Miscellaneous Commands, -@code{universal-argument}}), to find out how to supply them. With a -numeric argument, the motion commands are simply executed that -many times; for example, a numeric argument of 4 given to -@code{next-line} causes the cursor to move down 4 lines. With a -negative numeric argument, the motion is reversed; an argument of -4 -given to the @code{next-line} command would cause the cursor to move -@emph{up} 4 lines. - -@table @asis -@item @code{C-n} (@code{next-line}) -@kindex C-n -@findex next-line -Move the cursor down to the next line. - -@item @code{C-p} (@code{prev-line}) -@kindex C-p -@findex prev-line -Move the cursor up to the previous line. - -@item @code{C-a} (@code{beginning-of-line}) -@kindex C-a, in Info windows -@findex beginning-of-line -Move the cursor to the start of the current line. - -@item @code{C-e} (@code{end-of-line}) -@kindex C-e, in Info windows -@findex end-of-line -Move the cursor to the end of the current line. - -@item @code{C-f} (@code{forward-char}) -@kindex C-f, in Info windows -@findex forward-char -Move the cursor forward a character. - -@item @code{C-b} (@code{backward-char}) -@kindex C-b, in Info windows -@findex backward-char -Move the cursor backward a character. - -@item @code{M-f} (@code{forward-word}) -@kindex M-f, in Info windows -@findex forward-word -Move the cursor forward a word. - -@item @code{M-b} (@code{backward-word}) -@kindex M-b, in Info windows -@findex backward-word -Move the cursor backward a word. - -@item @code{M-<} (@code{beginning-of-node}) -@itemx @code{b} -@kindex b, in Info windows -@kindex M-< -@findex beginning-of-node -Move the cursor to the start of the current node. - -@item @code{M->} (@code{end-of-node}) -@kindex M-> -@findex end-of-node -Move the cursor to the end of the current node. - -@item @code{M-r} (@code{move-to-window-line}) -@kindex M-r -@findex move-to-window-line -Move the cursor to a specific line of the window. Without a numeric -argument, @code{M-r} moves the cursor to the start of the line in the -center of the window. With a numeric argument of @var{n}, @code{M-r} -moves the cursor to the start of the @var{n}th line in the window. -@end table - -@node Scrolling Commands, Node Commands, Cursor Commands, Top -@chapter Moving Text Within a Window -@cindex scrolling - -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. - -@table @asis -@item @code{SPC} (@code{scroll-forward}) -@itemx @code{C-v} -@kindex SPC, in Info windows -@kindex C-v -@findex 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, @key{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. - -@item @code{DEL} (@code{scroll-backward}) -@itemx @code{M-v} -@kindex DEL, in Info windows -@kindex M-v -@findex scroll-backward -Shift the text in this window down. The inverse of -@code{scroll-forward}. -@end table - -@cindex scrolling through node structure -The @code{scroll-forward} and @code{scroll-backward} commands can also -move forward and backward through the node structure of the file. If -you press @key{SPC} while viewing the end of a node, or @key{DEL} while -viewing the beginning of a node, what happens is controlled by the -variable @code{scroll-behavior}. @xref{Variables, -@code{scroll-behavior}}, for more information. - -@table @asis -@item @code{C-l} (@code{redraw-display}) -@kindex C-l -@findex redraw-display -Redraw the display from scratch, or shift the line containing the cursor -to a specified location. With no numeric argument, @samp{C-l} clears -the screen, and then redraws its entire contents. Given a numeric -argument of @var{n}, the line containing the cursor is shifted so that -it is on the @var{n}th line of the window. - -@item @code{C-x w} (@code{toggle-wrap}) -@kindex C-w -@findex toggle-wrap -Toggles the state of line wrapping in the current window. Normally, -lines which are longer than the screen width @dfn{wrap}, i.e., they are -continued on the next line. Lines which wrap have a @samp{\} appearing -in the rightmost column of the screen. You can cause such lines to be -terminated at the rightmost column by changing the state of line -wrapping in the window with @code{C-x w}. When a line which needs more -space than one screen width to display is displayed, a @samp{$} appears -in the rightmost column of the screen, and the remainder of the line is -invisible. -@end table - -@node Node Commands, Searching Commands, Scrolling Commands, Top -@chapter Selecting a New Node -@cindex nodes, selection of - -This section details the numerous Info commands which select a new node -to view in the current window. - -The most basic node commands are @samp{n}, @samp{p}, @samp{u}, and -@samp{l}. - -When you are viewing a node, the top line of the node contains some Info -@dfn{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: - -@table @asis -@item @code{n} (@code{next-node}) -@kindex n -@findex next-node -Select the `Next' node. - -@item @code{p} (@code{prev-node}) -@kindex p -@findex prev-node -Select the `Prev' node. - -@item @code{u} (@code{up-node}) -@kindex u -@findex up-node -Select the `Up' node. -@end table - -You can easily select a node that you have already viewed in this window -by using the @samp{l} command -- this name stands for "last", and -actually moves through the list of already visited nodes for this -window. @samp{l} with a negative numeric argument moves forward through -the history of nodes for this window, so you can quickly step between -two adjacent (in viewing history) nodes. - -@table @asis -@item @code{l} (@code{history-node}) -@kindex l -@findex history-node -Select the most recently selected node in this window. -@end table - -Two additional commands make it easy to select the most commonly -selected nodes; they are @samp{t} and @samp{d}. - -@table @asis -@item @code{t} (@code{top-node}) -@kindex t -@findex top-node -Select the node @samp{Top} in the current Info file. - -@item @code{d} (@code{dir-node}) -@kindex d -@findex dir-node -Select the directory node (i.e., the node @samp{(dir)}). -@end table - -Here are some other commands which immediately result in the selection -of a different node in the current window: - -@table @asis -@item @code{<} (@code{first-node}) -@kindex < -@findex first-node -Selects the first node which appears in this file. This node is most -often @samp{Top}, but it does not have to be. - -@item @code{>} (@code{last-node}) -@kindex > -@findex last-node -Select the last node which appears in this file. - -@item @code{]} (@code{global-next-node}) -@kindex ] -@findex global-next-node -Move forward or down through node structure. If the node that you are -currently viewing has a @samp{Next} pointer, that node is selected. -Otherwise, if this node has a menu, the first menu item is selected. If -there is no @samp{Next} and no menu, the same process is tried with the -@samp{Up} node of this node. - -@item @code{[} (@code{global-prev-node}) -@kindex [ -@findex global-prev-node -Move backward or up through node structure. If the node that you are -currently viewing has a @samp{Prev} pointer, that node is selected. -Otherwise, if the node has an @samp{Up} pointer, that node is selected, -and if it has a menu, the last item in the menu is selected. -@end table - -You can get the same behavior as @code{global-next-node} and -@code{global-prev-node} while simply scrolling through the file with -@key{SPC} and @key{DEL}; @xref{Variables, @code{scroll-behavior}}, for -more information. - -@table @asis -@item @code{g} (@code{goto-node}) -@kindex g -@findex goto-node -Read the name of a node and select it. No completion is done while -reading the node name, since the desired node may reside in a separate -file. The node must be typed exactly as it appears in the Info file. A -file name may be included as with any node specification, for example - -@example -@code{g(emacs)Buffers} -@end example - -finds the node @samp{Buffers} in the Info file @file{emacs}. - -@item @code{C-x k} (@code{kill-node}) -@kindex C-x k -@findex kill-node -Kill a node. The node name is prompted for in the echo area, with a -default of the current node. @dfn{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. - -@item @code{C-x C-f} (@code{view-file}) -@kindex C-x C-f -@findex view-file -Read the name of a file and selects the entire file. The command -@example -@code{C-x C-f @var{filename}} -@end example -is equivalent to typing -@example -@code{g(@var{filename})*} -@end example - -@item @code{C-x C-b} (@code{list-visited-nodes}) -@kindex C-x C-b -@findex 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. - -@item @code{C-x b} (@code{select-visited-node}) -@kindex C-x b -@findex select-visited-node -Select a node which has been previously visited in a visible window. -This is similar to @samp{C-x C-b} followed by @samp{m}, but no window is -created. -@end table - -@node Searching Commands, Xref Commands, Node Commands, Top -@chapter Searching an Info File -@cindex searching - -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. - -@table @asis -@item @code{s} (@code{search}) -@kindex s -@findex search -Read a string in the echo area and search for it. - -@item @code{C-s} (@code{isearch-forward}) -@kindex C-s -@findex isearch-forward -Interactively search forward through the Info file for a string as you -type it. - -@item @code{C-r} (@code{isearch-backward}) -@kindex C-r -@findex isearch-backward -Interactively search backward through the Info file for a string as -you type it. - -@item @code{i} (@code{index-search}) -@kindex i -@findex index-search -Look up a string in the indices for this Info file, and select a node -where the found index entry points to. - -@item @code{,} (@code{next-index-match}) -@kindex , -@findex next-index-match -Move to the node containing the next matching index item from the last -@samp{i} command. -@end table - -The most basic searching command is @samp{s} (@code{search}). The -@samp{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 -@samp{s} commands show you the default search string within @samp{[} and -@samp{]}; pressing @key{RET} instead of typing a new string will use the -default search string. - -@dfn{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. - -@node Xref Commands, Window Commands, Searching Commands, Top -@chapter Selecting Cross References - -We have already discussed the @samp{Next}, @samp{Prev}, and @samp{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 -@dfn{cross references}, or @dfn{xrefs} for short. - -@menu -* Parts of an Xref:: What a cross reference is made of. -* Selecting Xrefs:: Commands for selecting menu or note items. -@end menu - -@node Parts of an Xref, Selecting Xrefs, , Xref Commands -@section Parts of an Xref - -Cross references have two major parts: the first part is called the -@dfn{label}; it is the name that you can use to refer to the cross -reference, and the second is the @dfn{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 @samp{:}; first the -label appears, and then the target. For example, in the sample menu -cross reference below, the single colon separates the label from the -target. - -@example -* Foo Label: Foo Target. More information about Foo. -@end example - -Note the @samp{.} which ends the name of the target. The @samp{.} 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: - -@example -* Foo Commands:: Commands pertaining to Foo. -@end example - -In the above example, the name of the target is the same as the name of -the label, in this case @code{Foo Commands}. - -You will normally see two types of cross reference while viewing nodes: -@dfn{menu} references, and @dfn{note} references. Menu references -appear within a node's menu; they begin with a @samp{*} at the beginning -of a line, and continue with a label, a target, and a comment which -describes what the contents of the node pointed to contains. - -Note references appear within the body of the node text; they begin with -@code{*Note}, and continue with a label and a target. - -Like @samp{Next}, @samp{Prev}, and @samp{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: @xref{xref, , Writing an Xref, texinfo, the Texinfo -Manual}, for more information on creating your own texinfo cross -references. - -@node Selecting Xrefs, , Parts of an Xref, Xref Commands -@section Selecting Xrefs - -The following table lists the Info commands which operate on menu items. - -@table @asis -@item @code{1} (@code{menu-digit}) -@itemx @code{2} @dots{} @code{9} -@cindex 1 @dots{} 9, in Info windows -@kindex 1 @dots{} 9, in Info windows -@findex menu-digit -Within an Info window, pressing a single digit, (such as @samp{1}), -selects that menu item, and places its node in the current window. -For convenience, there is one exception; pressing @samp{0} selects the -@emph{last} item in the node's menu. - -@item @code{0} (@code{last-menu-item}) -@kindex 0, in Info windows -@findex last-menu-item -Select the last item in the current node's menu. - -@item @code{m} (@code{menu-item}) -@kindex m -@findex 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. - -@item @code{M-x find-menu} -@findex find-menu -Move the cursor to the start of this node's menu. -@end table - -This table lists the Info commands which operate on note cross references. - -@table @asis -@item @code{f} (@code{xref-item}) -@itemx @code{r} -@kindex f -@kindex r -@findex xref-item -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. -@end table - -Finally, the next few commands operate on menu or note references alike: - -@table @asis -@item @code{TAB} (@code{move-to-next-xref}) -@kindex TAB, in Info windows -@findex 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 @key{RET} -(@code{select-reference-this-line}) to select the menu or note reference. - -@item @code{M-TAB} (@code{move-to-prev-xref}) -@kindex M-TAB, in Info windows -@findex move-to-prev-xref -Move the cursor the start of the nearest previous menu item or note -reference in this node. - -@item @code{RET} (@code{select-reference-this-line}) -@kindex RET, in Info windows -@findex select-reference-this-line -Select the menu item or note reference appearing on this line. -@end table - -@node Window Commands, Printing Nodes, Xref Commands, Top -@chapter Manipulating Multiple Windows -@cindex windows, manipulating - -A @dfn{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 -@dfn{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 @dfn{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. -@end menu - -@node The Mode Line, Basic Windows, , Window Commands -@section The Mode Line - -A @dfn{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 @file{dir}, showing the node @samp{Top}. - -@example -@group ------Info: (dir)Top, 40 lines --Top--------------------------------------- - ^^ ^ ^^^ ^^ - (file)Node #lines where -@end group -@end example - -When a node comes from a file which is compressed on disk, this is -indicated in the mode line with two small @samp{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: - -@example ---zz-Info: (emacs)Top, 291 lines --Top-- Subfile: emacs-1.Z--------------- -@end example - -When Info makes a node internally, such that there is no corresponding -info file on disk, the name of the node is surrounded by asterisks -(@samp{*}). 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: - -@example ------Info: *Completions*, 7 lines --All----------------------------------- -@end example - -@node Basic Windows, The Echo Area, The Mode Line, Window Commands -@section Window Commands - -It can be convenient to view more than one node at a time. To allow -this, Info can display more than one @dfn{window}. Each window has its -own mode line (@pxref{The Mode Line}) and history of nodes viewed in that -window (@pxref{Node Commands, , @code{history-node}}). - -@table @asis -@item @code{C-x o} (@code{next-window}) -@cindex windows, selecting -@kindex C-x o -@findex 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, @samp{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, @samp{C-x o} moves over -that many windows. A negative argument causes @samp{C-x o} to select -the previous window on the screen. - -@item @code{M-x prev-window} -@findex prev-window -Select the previous window on the screen. This is identical to -@samp{C-x o} with a negative argument. - -@item @code{C-x 2} (@code{split-window}) -@cindex windows, creating -@kindex C-x 2 -@findex 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 @code{automatic-tiling} -can cause all of the windows on the screen to be resized for you -automatically, please @pxref{Variables, , automatic-tiling} for more -information. - -@item @code{C-x 0} (@code{delete-window}) -@cindex windows, deleting -@kindex C-x 0 -@findex 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. - -@item @code{C-x 1} (@code{keep-one-window}) -@kindex C-x 1 -@findex keep-one-window -Delete all of the windows excepting the current one. - -@item @code{ESC C-v} (@code{scroll-other-window}) -@kindex ESC C-v, in Info windows -@findex scroll-other-window -Scroll the other window, in the same fashion that @samp{C-v} might -scroll the current window. Given a negative argument, scroll the -"other" window backward. - -@item @code{C-x ^} (@code{grow-window}) -@kindex C-x ^ -@findex 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. - -@item @code{C-x t} (@code{tile-windows}) -@cindex tiling -@kindex C-x t -@findex 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 @code{automatic-tiling} can cause -@code{tile-windows} to be called when a window is created or deleted. -@xref{Variables, , @code{automatic-tiling}}. -@end table - -@node The Echo Area, , Basic Windows, Window Commands -@section The Echo Area -@cindex echo area - -The @dfn{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: - -@table @asis -@item @code{C-f} (@code{echo-area-forward}) -@kindex C-f, in the echo area -@findex echo-area-forward -Move forward a character. - -@item @code{C-b} (@code{echo-area-backward}) -@kindex C-b, in the echo area -@findex echo-area-backward -Move backward a character. - -@item @code{C-a} (@code{echo-area-beg-of-line}) -@kindex C-a, in the echo area -@findex echo-area-beg-of-line -Move to the start of the input line. - -@item @code{C-e} (@code{echo-area-end-of-line}) -@kindex C-e, in the echo area -@findex echo-area-end-of-line -Move to the end of the input line. - -@item @code{M-f} (@code{echo-area-forward-word}) -@kindex M-f, in the echo area -@findex echo-area-forward-word -Move forward a word. - -@item @code{M-b} (@code{echo-area-backward-word}) -@kindex M-b, in the echo area -@findex echo-area-backward-word -Move backward a word. - -@item @code{C-d} (@code{echo-area-delete}) -@kindex C-d, in the echo area -@findex echo-area-delete -Delete the character under the cursor. - -@item @code{DEL} (@code{echo-area-rubout}) -@kindex DEL, in the echo area -@findex echo-area-rubout -Delete the character behind the cursor. - -@item @code{C-g} (@code{echo-area-abort}) -@kindex C-g, in the echo area -@findex echo-area-abort -Cancel or quit the current operation. If completion is being read, -@samp{C-g} discards the text of the input line which does not match any -completion. If the input line is empty, @samp{C-g} aborts the calling -function. - -@item @code{RET} (@code{echo-area-newline}) -@kindex RET, in the echo area -@findex echo-area-newline -Accept (or forces completion of) the current input line. - -@item @code{C-q} (@code{echo-area-quoted-insert}) -@kindex C-q, in the echo area -@findex echo-area-quoted-insert -Insert the next character verbatim. This is how you can insert control -characters into a search string, for example. - -@item @var{printing character} (@code{echo-area-insert}) -@kindex printing characters, in the echo area -@findex echo-area-insert -Insert the character. - -@item @code{M-TAB} (@code{echo-area-tab-insert}) -@kindex M-TAB, in the echo area -@findex echo-area-tab-insert -Insert a TAB character. - -@item @code{C-t} (@code{echo-area-transpose-chars}) -@kindex C-t, in the echo area -@findex echo-area-transpose-chars -Transpose the characters at the cursor. -@end table - -The next group of commands deal with @dfn{killing}, and @dfn{yanking} -text. For an in depth discussion of killing and yanking, -@pxref{Killing, , Killing and Deleting, emacs, the GNU Emacs Manual} - -@table @asis -@item @code{M-d} (@code{echo-area-kill-word}) -@kindex M-d, in the echo area -@findex echo-area-kill-word -Kill the word following the cursor. - -@item @code{M-DEL} (@code{echo-area-backward-kill-word}) -@kindex M-DEL, in the echo area -@findex echo-area-backward-kill-word -Kill the word preceding the cursor. - -@item @code{C-k} (@code{echo-area-kill-line}) -@kindex C-k, in the echo area -@findex echo-area-kill-line -Kill the text from the cursor to the end of the line. - -@item @code{C-x DEL} (@code{echo-area-backward-kill-line}) -@kindex C-x DEL, in the echo area -@findex echo-area-backward-kill-line -Kill the text from the cursor to the beginning of the line. - -@item @code{C-y} (@code{echo-area-yank}) -@kindex C-y, in the echo area -@findex echo-area-yank -Yank back the contents of the last kill. - -@item @code{M-y} (@code{echo-area-yank-pop}) -@kindex M-y, in the echo area -@findex echo-area-yank-pop -Yank back a previous kill, removing the last yanked text first. -@end table - -Sometimes when reading input in the echo area, the command that needed -input will only accept one of a list of several choices. The choices -represent the @dfn{possible completions}, and you must respond with one -of them. Since there are a limited number of responses you can make, -Info allows you to abbreviate what you type, only typing as much of the -response as is necessary to uniquely identify it. In addition, you can -request Info to fill in as much of the response as is possible; this -is called @dfn{completion}. - -The following commands are available when completing in the echo area: - -@table @asis -@item @code{TAB} (@code{echo-area-complete}) -@itemx @code{SPC} -@kindex TAB, in the echo area -@kindex SPC, in the echo area -@findex echo-area-complete -Insert as much of a completion as is possible. - -@item @code{?} (@code{echo-area-possible-completions}) -@kindex ?, in the echo area -@findex 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: - -@example -@group -bar -foliate -food -forget -@end group -@end example - -@noindent -and you have typed an @samp{f}, followed by @samp{?}, the possible -completions would contain: - -@example -@group -foliate -food -forget -@end group -@end example - -@noindent -i.e., all of the choices which begin with @samp{f}. Pressing @key{SPC} -or @key{TAB} would result in @samp{fo} appearing in the echo area, since -all of the choices which begin with @samp{f} continue with @samp{o}. -Now, typing @samp{l} followed by @samp{TAB} results in @samp{foliate} -appearing in the echo area, since that is the only choice which begins -with @samp{fol}. - -@item @code{ESC C-v} (@code{echo-area-scroll-completions-window}) -@kindex ESC C-v, in the echo area -@findex echo-area-scroll-completions-window -Scroll the completions window, if that is visible, or the "other" -window if not. -@end table - -@node Printing Nodes, Miscellaneous Commands, Window Commands, Top -@chapter Printing Out Nodes -@cindex printing - -You may wish to print out the contents of a node as a quick reference -document for later use. Info provides you with a command for doing -this. In general, we recommend that you use @TeX{} to format the -document and print sections of it, by running @code{tex} on the Texinfo -source file. - -@table @asis -@item @code{M-x print-node} -@findex print-node -@cindex INFO_PRINT_COMMAND, environment variable -Pipe the contents of the current node through the command in the -environment variable @code{INFO_PRINT_COMMAND}. If the variable does not -exist, the node is simply piped to @code{lpr}. -@end table - -@node Miscellaneous Commands, Variables, Printing Nodes, Top -@chapter Miscellaneous Commands - -GNU Info contains several commands which self-document GNU Info: - -@table @asis -@item @code{M-x describe-command} -@cindex functions, describing -@cindex commands, describing -@findex describe-command -Read the name of an Info command in the echo area and then display a -brief description of what that command does. - -@item @code{M-x describe-key} -@cindex keys, describing -@findex 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. - -@item @code{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. - -@item @code{M-x where-is} -@findex 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. - -@item @code{C-h} (@code{get-help-window}) -@itemx @code{?} -@kindex C-h -@kindex ?, in Info windows -@findex get-help-window -Create (or Move into) the window displaying @code{*Help*}, and place -a node containing a quick reference card into it. This window displays -the most concise information about GNU Info available. - -@item @code{h} (@code{get-info-help-node}) -@kindex h -@findex get-info-help-node -Try hard to visit the node @code{(info)Help}. The Info file -@file{info.texi} distributed with GNU Info contains this node. Of -course, the file must first be processed with @code{makeinfo}, and then -placed into the location of your Info directory. -@end table - -Here are the commands for creating a numeric argument: - -@table @asis -@item @code{C-u} (@code{universal-argument}) -@cindex numeric arguments -@kindex C-u -@findex universal-argument -Start (or multiply by 4) the current numeric argument. @samp{C-u} is -a good way to give a small numeric argument to cursor movement or -scrolling commands; @samp{C-u C-v} scrolls the screen 4 lines, while -@samp{C-u C-u C-n} moves the cursor down 16 lines. - -@item @code{M-1} (@code{add-digit-to-numeric-arg}) -@itemx @code{M-2} @dots{} @code{M-9} -@kindex M-1 @dots{} M-9 -@findex add-digit-to-numeric-arg -Add the digit value of the invoking key to the current numeric -argument. Once Info is reading a numeric argument, you may just type -the digits of the argument, without the Meta prefix. For example, you -might give @samp{C-l} a numeric argument of 32 by typing: - -@example -@kbd{C-u 3 2 C-l} -@end example - -@noindent -or - -@example -@kbd{M-3 2 C-l} -@end example -@end table - -@samp{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. - -@table @asis -@item @code{C-g} (@code{abort-key}) -@cindex cancelling typeahead -@cindex cancelling the current operation -@kindex C-g, in Info windows -@findex abort-key -Cancel current operation. -@end table - -The @samp{q} command of Info simply quits running Info. - -@table @asis -@item @code{q} (@code{quit}) -@cindex quitting -@kindex q -@findex quit -Exit GNU Info. -@end table - -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. - -@table @asis -@item @code{M-x set-screen-height} -@findex set-screen-height -@cindex screen, changing the height of -Read a height value in the echo area and set the height of the -displayed screen to that value. -@end table - -Finally, Info provides a convenient way to display footnotes which might -be associated with the current node that you are viewing: - -@table @asis -@item @code{ESC C-f} (@code{show-footnotes}) -@kindex ESC C-f -@findex show-footnotes -@cindex footnotes, displaying -Show the footnotes (if any) associated with the current node in another -window. You can have Info automatically display the footnotes -associated with a node when the node is selected by setting the variable -@code{automatic-footnotes}. @xref{Variables, , @code{automatic-footnotes}}. -@end table - -@node Variables, GNU Info Global Index, Miscellaneous Commands, Top -@chapter Manipulating Variables - -GNU Info contains several @dfn{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. - -@table @asis -@item @code{M-x set-variable} -@cindex variables, setting -@findex 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; often, completion is available when reading -the value to give to the variable, but that depends on the variable -itself. If a variable does @emph{not} supply multiple choices to -complete over, it expects a numeric value. - -@item @code{M-x describe-variable} -@cindex variables, describing -@findex describe-variable -Read the name of a variable in the echo area and then display a brief -description of what the variable affects. -@end table - -Here is a list of the variables that you can set in Info. - -@table @code -@item automatic-footnotes -@vindex automatic-footnotes -When set to @code{On}, footnotes appear and disappear automatically. -This variable is @code{On} by default. When a node is selected, a -window containing the footnotes which appear in that node is created, -and the footnotes are displayed within the new window. The window that -Info creates to contain the footnotes is called @samp{*Footnotes*}. If -a node is selected which contains no footnotes, and a @samp{*Footnotes*} -window is on the screen, the @samp{*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. - -@item automatic-tiling -@vindex automatic-tiling -When set to @code{On}, creating or deleting a window resizes other -windows. This variable is @code{Off} by default. Normally, typing -@samp{C-x 2} divides the current window into two equal parts. When -@code{automatic-tiling} is set to @code{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 @samp{*Completions*} and @samp{*Footnotes*} are @emph{not} -resized through automatic tiling; they remain their original size. - -@item visible-bell -@vindex visible-bell -When set to @code{On}, GNU Info attempts to flash the screen instead of -ringing the bell. This variable is @code{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 -@code{errors-ring-bell} variable to @code{Off}. - -@item errors-ring-bell -@vindex errors-ring-bell -When set to @code{On}, errors cause the bell to ring. The default -setting of this variable is @code{On}. - -@item gc-compressed-files -@vindex gc-compressed-files -When set to @code{On}, Info garbage collects files which had to be -uncompressed. The default value of this variable is @code{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. -@code{gc-compressed-files} tells Info it is okay to garbage collect the -text of the nodes of a file which was compressed on disk. - -@item show-index-match -@vindex show-index-match -When set to @code{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 @code{On}. -When Info displays the location where an index match was found, -(@pxref{Searching Commands, , @code{next-index-match}}), the portion of the -string that you had typed is highlighted by displaying it in the inverse -case from its surrounding characters. - -@item scroll-behavior -@vindex scroll-behavior -Control what happens when forward scrolling is requested at the end of -a node, or when backward scrolling is requested at the beginning of a -node. The default value for this variable is @code{Continuous}. There -are three possible values for this variable: - -@table @code -@item Continuous -Try to get the first item in this node's menu, or failing that, the -@samp{Next} node, or failing that, the @samp{Next} of the @samp{Up}. -This behavior is identical to using the @samp{]} -(@code{global-next-node}) and @samp{[} (@code{global-prev-node}) -commands. - -@item Next Only -Only try to get the @samp{Next} node. - -@item Page Only -Simply give up, changing nothing. If @code{scroll-behavior} is -@code{Page Only}, no scrolling command can change the node that is being -viewed. -@end table - -@item scroll-step -@vindex 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 @code{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. - -@item ISO-Latin -@cindex ISO Latin characters -@vindex ISO-Latin -When set to @code{On}, Info accepts and displays ISO Latin characters. -By default, Info assumes an ASCII character set. @code{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. -@end table - - - -@c the following is incomplete -@ignore -@c node Info for Sys Admins -@c chapter Info for System Administrators - -This text describes some common ways of setting up an Info hierarchy -from scratch, and details the various options that are available when -installing Info. This text is designed for the person who is installing -GNU Info on the system; although users may find the information present -in this section interesting, none of it is vital to understanding how to -use GNU Info. - -@menu -* Setting the INFOPATH:: Where are my Info files kept? -* Editing the DIR node:: What goes in `DIR', and why? -* Storing Info files:: Alternate formats allow flexibility in setups. -* Using `localdir':: Building DIR on the fly. -* Example setups:: Some common ways to organize Info files. -@end menu - -@c node Setting the INFOPATH -@c section Setting the INFOPATH - -Where are my Info files kept? - -@c node Editing the DIR node -@c section Editing the DIR node - -What goes in `DIR', and why? - -@c node Storing Info files -@c section Storing Info files - -Alternate formats allow flexibility in setups. - -@c node Using `localdir' -@c section Using `localdir' - -Building DIR on the fly. - -@c node Example setups -@c section Example setups - -Some common ways to organize Info files. -@end ignore - -@node GNU Info Global Index, , Variables, Top -@appendix Global Index - -@printindex cp - -@contents -@bye diff --git a/gnu/usr.bin/texinfo/info-files/texi-files/info.texi b/gnu/usr.bin/texinfo/info-files/texi-files/info.texi deleted file mode 100644 index 5eec9f1..0000000 --- a/gnu/usr.bin/texinfo/info-files/texi-files/info.texi +++ /dev/null @@ -1,861 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header -@setfilename info.info -@settitle Info 1.0 -@comment %**end of header - -@iftex -@finalout -@end iftex - -@ifinfo -This file describes how to use Info, -the on-line, menu-driven GNU documentation system. - -Copyright (C) 1989, 1992 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. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). - -@end ignore -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 Free Software Foundation. -@end ifinfo - -@setchapternewpage odd -@titlepage -@sp 11 -@center @titlefont{Info} -@sp 2 -@center The -@sp 2 -@center On-line, Menu-driven -@sp 2 -@center GNU Documentation System - -@page -@vskip 0pt plus 1filll -Copyright @copyright{} 1989, 1992, 1993 Free Software Foundation, Inc. -@sp 2 - -Published by the Free Software Foundation @* -675 Massachusetts Avenue, @* -Cambridge, MA 02139 USA @* - -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 Free Software Foundation. -@end titlepage - -@ifinfo -@node Top, Getting Started, (dir), (dir) -@top Info: An Introduction - -Info is a program for reading documentation, which you are using now. - -To learn how to use Info, type the command @kbd{h}. It brings you -to a programmed instruction sequence. - -@c Need to make sure that `Info-help' goes to the right node, -@c which is the first node of the first chapter. (It should.) -@c (Info-find-node "info" -@c (if (< (window-height) 23) -@c "Help-Small-Screen" -@c "Help"))) - -To learn advanced Info commands, type @kbd{n} twice. This -brings you to @cite{Info for Experts}, skipping over the . -`Getting Started' chapter. -@end ifinfo - -@menu -* Getting Started:: -* Advanced Info:: -* Create an Info File:: -@end menu - -@node Getting Started, Advanced Info, Top, Top -@comment node-name, next, previous, up -@chapter Getting Started - -This first part of the Info manual describes how to get around inside -of Info. The second part of the manual describes various advanced -Info commands, and how to write an Info as distinct from a Texinfo -file. The third part is about how to generate Info files from -Texinfo files. - -@iftex -This manual is primarily designed for use on a computer, so that you can -try Info commands while reading about them. Reading it on paper is less -effective, since you must take it on faith that the commands described -really do what the manual says. By all means go through this manual now -that you have it; but please try going through the on-line version as -well. - -There are two ways of looking at the online version of this manual: - -@enumerate -@item -Type @code{info} at your shell's command line. This approach uses a -small stand-alone program designed just to read Info files. - -@item -Type @code{emacs} at the command line; then type @kbd{C-h i} (Control -@kbd{h}, followed by @kbd{i}). This approach uses -the Info mode of the Emacs program, an editor with many other -capabilities. -@end enumerate - -In either case, then type @kbd{mInfo} (just the letters), followed by -@key{RET}---the ``Return'' or ``Enter'' key. At this point, you should -be ready to follow the instructions in this manual as you read them on -the screen. -@c FIXME! (pesch@cygnus.com, 14 dec 1992) -@c Is it worth worrying about what-if the beginner goes to somebody -@c else's Emacs session, which already has an Info running in the middle -@c of something---in which case these simple instructions won't work? -@end iftex - -@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, Rubout, B and ^L commands. -* Help-M:: Menus -* Help-Adv:: Some advanced Info commands -* Help-Q:: Quitting Info -@end menu - -@node Help-Small-Screen, Help, , Getting Started -@comment node-name, next, previous, up -@section Starting Info on a Small Screen - -@iftex -(In Info, you only see this section if your terminal has a small -number of lines; most readers pass by it without seeing it.) -@end iftex - -Since your terminal has an unusually small number of lines on its -screen, it is necessary to give you special advice at the beginning. - -If you see the text @samp{--All----} at near the bottom right corner -of the screen, it means the entire text you are looking at fits on the -screen. If you see @samp{--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 the Space bar, @key{SPC}. To move -back up, press the key labeled @samp{Rubout} or @samp{Delete} or -@key{DEL}. - -@ifinfo -Here are 40 lines of junk, so you can try @key{SPC} and @key{DEL} and -see what they do. At the end are instructions of what you should do -next. - -This is line 17 @* -This is line 18 @* -This is line 19 @* -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 @* - -If you have managed to get here, go back to the beginning with -@key{DEL}, and come back here again, then you understand @key{SPC} and -@key{DEL}. So now type an @kbd{n}---just one character; do not type -the quotes and do not type the Return key, @key{RET}, afterward---to -get to the normal start of the course. -@end ifinfo - -@node Help, Help-P, Help-Small-Screen, Getting Started -@comment node-name, next, previous, up -@section How to use Info - -You are talking to the program Info, for reading documentation. - - Right now you are looking at one @dfn{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 top line of a node is its @dfn{header}. This node's header (look at -it now) says that it is the node named @samp{Help} in the file -@file{info}. It says that the @samp{Next} node after this one is the node -called @samp{Help-P}. An advanced Info command lets you go to any node -whose name you know. - - Besides a @samp{Next}, a node can have a @samp{Previous} or an @samp{Up}. -This node has a @samp{Previous} but no @samp{Up}, as you can see. - - Now it is time to move on to the @samp{Next} node, named @samp{Help-P}. - ->> Type @samp{n} to move there. Type just one character; - do not type the quotes and do not type a @key{RET} afterward. - -@samp{>>} in the margin means it is really time to try a command. - -@node Help-P, Help-^L, Help, Getting Started -@comment node-name, next, previous, up -@section Returning to the Previous node - -This node is called @samp{Help-P}. The @samp{Previous} node, as you see, -is @samp{Help}, which is the one you just came from using the @kbd{n} -command. Another @kbd{n} command now would take you to the next -node, @samp{Help-^L}. - ->> But do not do that yet. First, try the @kbd{p} command, which takes - you to the @samp{Previous} node. When you get there, you can do an - @kbd{n} again to return here. - - This all probably seems insultingly simple so far, but @emph{do not} be -led into skimming. Things will get more complicated soon. Also, -do not try a new command until you are told it is time to. Otherwise, -you may make Info skip past an important warning that was coming up. - ->> Now do an @kbd{n} to get to the node @samp{Help-^L} and learn more. - -@node Help-^L, Help-M, Help-P, Getting Started -@comment node-name, next, previous, up -@section The Space, Rubout, B and ^L commands. - - This node's header tells you that you are now at node @samp{Help-^L}, and -that @kbd{p} would get you back to @samp{Help-P}. The node's title is -underlined; it says what the node is about (most nodes have titles). - - This is a big node and it does not all fit on your display screen. -You can tell that there is more that is not visible because you -can see the string @samp{--Top-----} rather than @samp{--All----} near -the bottom right corner of the screen. - - The @key{SPC}, @key{DEL} and @kbd{b} commands exist to allow you to ``move -around'' in a node that does not all fit on the screen at once. -@key{SPC} moves forward, to show what was below the bottom of the screen. -@key{DEL} 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 @key{SPC} (afterward, type a @key{DEL} to return here). - - When you type the @key{SPC}, the two lines that were at the bottom -of the screen appear at the top, followed by more lines. @key{DEL} -takes the two lines from the top and moves them to the bottom, -@emph{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 type a @key{SPC} when there is no more to see, it rings the -bell and otherwise does nothing. The same goes for a @key{DEL} when -the header of the node is visible. - - If your screen is ever garbaged, you can tell Info to print it out -again by typing @kbd{C-l} (@kbd{Control-L}, that is---hold down ``Control'' and -type an @key{L} or @kbd{l}). - ->> Type @kbd{C-l} now. - - To move back to the beginning of the node you are on, you can type -a lot of @key{DEL}s. You can also type simply @kbd{b} for beginning. - ->> Try that now. (I have put in enough verbiage to make sure you are - not on the first screenful now). Then come back, typing @key{SPC} - several times. - - You have just learned a considerable number of commands. If you -want to use one but have trouble remembering which, you should type -a @key{?} which prints out a brief list of commands. When you are -finished looking at the list, make it go away by typing a @key{SPC}. - ->> Type a @key{?} now. After it finishes, type a @key{SPC}. - - (If you are using the standalone Info reader, type `l' to return here.) - - From now on, you will encounter large nodes without warning, and -will be expected to know how to use @key{SPC} and @key{DEL} 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 @kbd{n} to see the description of the @kbd{m} command. - -@node Help-M, Help-Adv, Help-^L, Getting Started -@comment node-name, next, previous, up -@section Menus - -Menus and the @kbd{m} command - - With only the @kbd{n} and @kbd{p} commands for moving between nodes, nodes -are restricted to a linear sequence. Menus allow a branching -structure. A menu is a list of other nodes you can move to. It is -actually just part of the text of the node formatted specially so that -Info can interpret it. The beginning of a menu is always identified -by a line which starts with @samp{* 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 @samp{*} -identifies one subtopic. The line usually contains a brief name -for the subtopic (followed by a @samp{:}), the name of the node that talks -about that subtopic, and optionally some further description of the -subtopic. Lines in the menu that do not start with a @samp{*} have no -special meaning---they are only for the human reader's benefit and do -not define additional subtopics. Here is an example: - -@example -* Foo: FOO's Node This tells about FOO -@end example - -The subtopic name is Foo, and the node describing it is @samp{FOO's Node}. -The rest of the line is just for the reader's Information. -[[ But this line is not a real menu item, simply because there is -no line above it which starts with @samp{* Menu:}.]] - - 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: - -@example -* Foo:: This tells about FOO -@end example - -@noindent -This means that the subtopic name and node name are the same; they are -both @samp{Foo}. - ->> Now use @key{SPC}s to find the menu in this node, then come back to - the front with a @kbd{b}. As you see, a menu is actually visible in - its node. If you cannot find a menu in a node by looking at it, - then the node does not have a menu and the @kbd{m} command is not - available. - - The command to go to one of the subnodes is @kbd{m}---but @emph{do not do it -yet!} Before you use @kbd{m}, you must understand the difference between -commands and arguments. So far, you have learned several commands -that do not need arguments. When you type one, Info processes it and -is instantly ready for another command. The @kbd{m} command is different: -it is incomplete without the @dfn{name of the subtopic}. Once you have -typed @kbd{m}, Info tries to read the subtopic name. - - Now look for the line containing many dashes near the bottom of the -screen. There is one more line beneath that one, but usually it is -blank If it is empty, Info is ready for a command, such as @kbd{n} or @kbd{b} -or @key{SPC} or @kbd{m}. If that line contains text ending in a colon, it -mean Info is trying to read the @dfn{argument} to a command. At such -times, commands do not work, because Info tries to use them as the -argument. You must either type the argument and finish the command -you started, or type @kbd{Control-g} to cancel the command. When you have -done one of those things, the line becomes blank again. - - The command to go to a subnode via a menu is @kbd{m}. After you type -the @kbd{m}, the line at the bottom of the screen says @samp{Menu item: }. -You must then type the name of the subtopic you want, and end it with -a @key{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. - - Here is a menu to give you a chance to practice. - -* Menu: The menu starts here. - -This menu givs you three ways of going to one place, Help-FOO. - -* Foo: Help-FOO. A node you can visit for fun.@* -* Bar: Help-FOO. Strange! two ways to get to the same place.@* -* Help-FOO:: And yet another!@* - - ->> Now type just an @kbd{m} and see what happens: - - Now you are ``inside'' an @kbd{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 @kbd{m} by typing Control-g. - ->> Try that now; notice the bottom line clear. - ->> Then type another @kbd{m}. - ->> Now type @samp{BAR} item name. Do not type @key{RET} yet. - - While you are typing the item name, you can use the @key{DEL} -character to cancel one character at a time if you make a mistake. - ->> Type one to cancel the @samp{R}. You could type another @samp{R} to - replace it. You do not have to, since @samp{BA} is a valid abbreviation. - ->> Now you are ready to go. Type a @key{RET}. - - After visiting Help-FOO, you should return here. - ->> Type @kbd{n} to see more commands. - -@c If a menu appears at the end of this node, remove it. -@c It is an accident of the menu updating command. - -Here is another way to get to Help-FOO, a menu. You can ignore this -if you want, or else try it (but then please come back to here). - -@menu -* Help-FOO:: -@end menu - -@node Help-FOO, , , Help-M -@comment node-name, next, previous, up -@subsection The @kbd{u} command - - Congratulations! This is the node @samp{Help-FOO}. Unlike the other -nodes you have seen, this one has an @samp{Up}: @samp{Help-M}, the node you -just came from via the @kbd{m} command. This is the usual -convention---the nodes you reach from a menu have @samp{Up} nodes that lead -back to the menu. Menus move Down in the tree, and @samp{Up} moves Up. -@samp{Previous}, on the other hand, is usually used to ``stay on the same -level but go backwards'' - - You can go back to the node @samp{Help-M} by typing the command -@kbd{u} for ``Up''. That puts you at the @emph{front} of the -node---to get back to where you were reading you have to type -some @key{SPC}s. - ->> Now type @kbd{u} to move back up to @samp{Help-M}. - -@node Help-Adv, Help-Q, Help-M, Getting Started -@comment node-name, next, previous, up -@section Some advanced Info commands - - The course is almost over, so please stick with it to the end. - - If you have been moving around to different nodes and wish to -retrace your steps, the @kbd{l} command (@kbd{l} for @dfn{last}) will -do that, one node at a time. If you have been following directions, -an @kbd{l} command now will get you back to @samp{Help-M}. Another -@kbd{l} command would undo the @kbd{u} and get you back to -@samp{Help-FOO}. Another @kbd{l} would undo the @kbd{m} and get you -back to @samp{Help-M}. - ->> Try typing three @kbd{l}'s, pausing in between to see what each - @kbd{l} does. - -Then follow directions again and you will end up back here. - - Note the difference between @kbd{l} and @kbd{p}: @kbd{l} moves to -where @emph{you} last were, whereas @kbd{p} always moves to the node -which the header says is the @samp{Previous} node (from this node, to -@samp{Help-M}). - - The @samp{d} command 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. - ->> Try doing a @samp{d}, then do an @kbd{l} to return here (yes, - @emph{do} return). - - Sometimes, in Info documentation, you will see a cross reference. -Cross references look like this: @xref{Help-Cross, Cross}. That is a -real, live cross reference which is named @samp{Cross} and points at -the node named @samp{Help-Cross}. - - If you wish to follow a cross reference, you must use the @samp{f} -command. The @samp{f} must be followed by the cross reference name -(in this case, @samp{Cross}). You can use @key{DEL} to edit the name, -and if you change your mind about following any reference you can use -@kbd{Control-g} to cancel the command. - - Completion is available in the @samp{f} command; you can complete among -all the cross reference names in the current node. - ->> Type @samp{f}, followed by @samp{Cross}, and a @key{RET}. - - To get a list of all the cross references in the current node, you can -type @kbd{?} after an @samp{f}. The @samp{f} continues to await a -cross reference name even after printing the list, so if you do not -actually want to follow a reference you should type a @kbd{Control-g} -to cancel the @samp{f}. - ->> Type "f?" to get a list of the footnotes in this node. Then type a - @kbd{Control-g} and see how the @samp{f} gives up. - ->> Now type @kbd{n} to see the last node of the course. - -@c If a menu appears at the end of this node, remove it. -@c It is an accident of the menu updating command. - -@node Help-Cross, , , Help-Adv -@comment node-name, next, previous, up -@unnumberedsubsec The node reached by the cross reference in Info - - This is the node reached by the cross reference named @samp{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 Info. So you cannot expect -the footnote to have a @samp{Next}, @samp{Previous} or @samp{Up} pointing back to -where you came from. In general, the @kbd{l} (el) command is the only -way to get back there. - ->> Type @kbd{l} to return to the node where the cross reference was. - -@node Help-Q, , Help-Adv, Getting Started -@comment node-name, next, previous, up -@section Quitting Info - - To get out of Info, back to what you were doing before, type @kbd{q} -for @dfn{Quit}. - - This is the end of the course on using Info. There are some other -commands that are not essential or are meant for experienced users; -they are useful, and you can find them by looking in the directory for -documentation on Info. Finding them will be a good exercise in using -Info in the usual manner. - ->> Type @samp{d} to go to the Info directory node; then type - @samp{mInfo} and @key{RET}, to get to the node about Info - and see what other help is available. - -@node Advanced Info, Create an Info File, Getting Started, Top -@comment node-name, next, previous, up -@chapter Info for Experts - -This chapter describes various advanced Info commands, and how to write -an Info as distinct from a Texinfo file. (However, in most cases, writing a -Texinfo file is better, since you can use it @emph{both} to generate an -Info file and to make a printed manual. @xref{Top,, Overview of -Texinfo, texinfo, Texinfo: The GNU Documentation Format}.) - -@menu -* Expert:: Advanced Info commands: g, s, e, and 1 - 5. -* 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 tag tables for Info files. -* Checking:: Checking an Info File -@end menu - -@node Expert, Add, , Advanced Info -@comment node-name, next, previous, up -@section Advanced Info Commands - -@kbd{g}, @kbd{s}, @kbd{1}, -- @kbd{5}, and @kbd{e} - -If you know a node's name, you can go there by typing @kbd{g}, the -name, and @key{RET}. Thus, @kbd{gTop@key{RET}} would go to the node -called @samp{Top} in this file (its directory node). -@kbd{gExpert@key{RET}} would come back here. - -Unlike @kbd{m}, @kbd{g} does not allow the use of abbreviations. - -To go to a node in another file, you can include the filename in the -node name by putting it at the front, in parentheses. Thus, -@kbd{g(dir)Top@key{RET}} would go to the Info Directory node, which is -node @samp{Top} in the file @file{dir}. - -The node name @samp{*} specifies the whole file. So you can look at -all of the current file by typing @kbd{g*@key{RET}} or all of any -other file with @kbd{g(FILENAME)@key{RET}}. - -The @kbd{s} command allows you to search a whole file for a string. -It switches to the next node if and when that is necessary. You -type @kbd{s} followed by the string to search for, terminated by -@key{RET}. To search for the same string again, just @kbd{s} followed -by @key{RET} will do. The file's nodes are scanned in the order -they are in in the file, which has no necessary relationship to the -order that they may be in in the tree structure of menus and @samp{next} pointers. -But normally the two orders are not very different. In any case, -you can always do a @kbd{b} to find out what node you have reached, if -the header is not visible (this can happen, because @kbd{s} puts your -cursor at the occurrence of the string, not at the beginning of the -node). - -If you grudge the system each character of type-in it requires, you -might like to use the commands @kbd{1}, @kbd{2}, @kbd{3}, @kbd{4}, and -@kbd{5}. They are short for the @kbd{m} command together with an -argument. "1", "2", "3", "4", and "5". @kbd{1} goes through the -first item in the current node's menu; @kbd{2} goes through the second -item, etc. Note that numbers larger than 5 are not allowed. If the -item you want is that far down, you are better off using an -abbreviation for its name than counting. - -The Info command @kbd{e} changes from Info mode to an ordinary -Emacs editing mode, so that you can edit the text of the current node. -Type @kbd{C-c C-c} to switch back to Info. The @kbd{e} command is allowed -only if the variable @code{Info-enable-edit} is non-@code{nil}. - -@node Add, Menus, Expert, Advanced Info -@comment node-name, next, previous, up -@section Adding a new node to Info - -To add a new topic to the list in the directory, you must: - -@enumerate -@item -Create a node, in some file, to document that topic. - -@item -Put that topic in the menu in the directory. @xref{Menus, Menu}. -@end enumerate - - The new node can live in an existing documentation file, or in a new -one. It must have a @key{^_} character before it (invisible to the -user; this node has one but you cannot see it), and it ends with either -a @key{^_}, a @key{^L}, or the end of file. Note: If you put in a -@key{^L} to end a new node, be sure that there is a @key{^_} after it -to start the next one, since @key{^L} cannot @emph{start} a node. -Also, a nicer way to make a node boundary be a page boundary as well -is to put a @key{^L} @emph{right after} the @key{^_}. - - The @key{^_} starting a node must be followed by a newline or a -@key{^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 @samp{Next}, @samp{Previous}, and @samp{Up} nodes (if -there are any). As you can see, this node's @samp{Up} node is the node -@samp{Top}, which points at all the documentation for Info. The @samp{Next} -node is @samp{Menus}. - - The keywords @dfn{Node}, @dfn{Previous}, @dfn{Up} and @dfn{Next}, -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 @samp{Node: } in that node's first line. For -example, this node's name is @samp{Add}. A node in another file is -named by @samp{(@var{filename})@var{node-within-file}}, as in -@samp{(info)Add} for this node. If the file name is relative, it is -taken starting from the standard Info file directory of your site. -The name @samp{(@var{filename})Top} can be abbreviated to just -@samp{(@var{filename})}. By convention, the name @samp{Top} is used for -the ``highest'' node in any single file---the node whose @samp{Up} points -out of the file. The Directory node is @file{(dir)}. The @samp{Top} node -of a document file listed in the Directory should have an @samp{Up: -(dir)} in it. - - The node name @kbd{*} is special: it refers to the entire file. -Thus, @kbd{g*} shows you the whole current file. The use of the -node @kbd{*} is to make it possible to make old-fashioned, -unstructured files into nodes of the tree. - - The @samp{Node:} name, in which a node states its own name, must not -contain a filename, since Info when searching for a node does not -expect one to be there. The @samp{Next}, @samp{Previous} and @samp{Up} names may -contain them. In this node, since the @samp{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. - -@node Menus, Cross-refs, Add, Advanced Info -@comment node-name, next, previous, up -@section How to Create Menus - - Any node in the Info hierarchy may have a @dfn{menu}---a list of subnodes. -The @kbd{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 @samp{* Menu:}. The rest of the -line is a comment. After the starting line, every line that begins -with a @samp{* } lists a single topic. The name of the topic--the -argument that the user must give to the @kbd{m} command to select this -topic---comes right after the star and space, and is followed by a -colon, spaces and tabs, and the name of the node which discusses that -topic. The node name, like node names following @samp{Next}, @samp{Previous} -and @samp{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, than rather than -giving the name twice, the abbreviation @samp{* 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 @samp{Up:} pointing at -the superior. It is often useful to arrange all or most of the -subnodes in a sequence of @samp{Next} and @samp{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 @samp{(dir)Top}---that -is, node @samp{Top} in file @file{.../info/dir}. You can put new entries -in that menu just like any other menu. The Info Directory is @emph{not} the -same as the file directory called @file{info}. It happens that many of -Info's files live on that file directory, but they do not have to; and -files on 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 @emph{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 @samp{Top}; the other contains the node @samp{Help} which the -@kbd{h} command goes to. In fact, since there is no garbage -collector, nothing terrible happens if a substructure is not pointed -to, but such a substructure is rather useless since nobody can -ever find out that it exists. - -@node Cross-refs, Tags, Menus, Advanced Info -@comment node-name, next, previous, up -@section 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 @samp{*note} instead of @kbd{*}. -It @emph{cannot} be terminated by a @samp{)}, because @samp{)}'s are -so often part of node names. If you wish to enclose a cross reference -in parentheses, terminate it with a period first. Here are two -examples of cross references pointers: - -@example -*Note details: commands. (See *note 3: Full Proof.) -@end example - -They are just examples. The places they ``lead to'' do not really exist! - -@node Tags, Checking, Cross-refs, Advanced Info -@comment node-name, next, previous, up -@section Tag Tables for Info Files - - You can speed up the access to nodes of a large Info file by giving -it a tag table. Unlike the tag table for a program, the tag table for -an Info file lives inside the file itself and is used -automatically whenever Info reads in the file. - - To make a tag table, go to a node in the file using Emacs Info mode and type -@kbd{M-x Info-tagify}. Then you must use @kbd{C-x C-s} to save the -file. - - Once the Info file has a tag table, you must make certain it is up -to date. If, 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 tag table, Info will no longer be able to find that -node. To update the tag table, use the @code{Info-tagify} command again. - - An Info file tag table appears at the end of the file and looks like -this: - -@example -^_ -Tag Table: -File: info, Node: Cross-refs^?21419 -File: info, Node: Tags^?22145 -^_ -End Tag Table -@end example - -@noindent -Note that it contains one line per node, and this line contains -the beginning of the node's header (ending just after the node name), -a @key{DEL} character, and the character position in the file of the -beginning of the node. - -@node Checking, , Tags, Advanced Info -@comment node-name, next, previous, up -@section 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 @samp{Next}, @samp{Previous}, and -@samp{Up} is checked, as is every menu item and every cross reference. In -addition, any @samp{Next} which does not have a @samp{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 @kbd{M-x Info-validate} while looking at -any node of the file with Emacs Info mode. - -@node Create an Info File, , Advanced Info, Top -@comment node-name, next, previous, up -@chapter Creating an Info File from a Makeinfo file - -@code{makeinfo} is a utility that converts a Texinfo file into an Info -file; @code{texinfo-format-region} and @code{texinfo-format-buffer} are -GNU Emacs functions that do the same. - -@xref{Create an Info File, , Creating an Info File, texinfo, the Texinfo -Manual}, to learn how to create an Info file from a Texinfo file. - -@xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU Documentation -Format}, to learn how to write a Texinfo file. - -@bye - diff --git a/gnu/usr.bin/texinfo/info-files/texi-files/makeinfo.texi b/gnu/usr.bin/texinfo/info-files/texi-files/makeinfo.texi deleted file mode 100644 index 21ee2d3..0000000 --- a/gnu/usr.bin/texinfo/info-files/texi-files/makeinfo.texi +++ /dev/null @@ -1,285 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header -@setfilename makeinfo.info -@set VERSION 1.51 -@paragraphindent none -@comment %**start of header - -@ifinfo -This file is an extract from the @cite{Texinfo} manual.@* -It documents @code{makeinfo}, a program that converts Texinfo -files into Info files. - -Copyright (C) 1992, 1993 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. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). - -@end ignore -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 Free Software Foundation. -@end ifinfo - -@titlepage -@title Makeinfo -@author Brian J. Fox and Robert J. Chassell - -@page -@vskip 0pt plus 1filll -Copyright @copyright{} 1992, 1993 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 Free Software Foundation. -@end titlepage - -@ifinfo -@node Top, What is makeinfo, (dir), (dir) -@unnumbered @code{makeinfo} - -This file documents the use of the @code{makeinfo} program, versions -@value{VERSION} and later. It is an extract from the @cite{Texinfo} manual. -@end ifinfo - -@menu -* What is makeinfo:: -@end menu - -@node What is makeinfo, , Top, Top -@chapter What is @code{makeinfo}? - -@iftex -This file documents the use of the @code{makeinfo} program, versions -@value{VERSION} and later. It is an extract from the @cite{Texinfo} manual. -@end iftex - -@code{makeinfo} is a program for converting @dfn{Texinfo} files into @dfn{Info} -files. Texinfo is a documentation system that uses a single source file to -produce both on-line information and printed output. - -You can read the on-line information using Info; type @code{info} to -learn about Info. -@ifinfo -@xref{Top, Texinfo, Overview of Texinfo, texinfo.texi, Texinfo}, -@end ifinfo -@iftex -See the @cite{Texinfo} manual, -@end iftex -to learn about the Texinfo documentation system. - -@menu -* Formatting Control:: -* Options:: -* Pointer Validation:: -@end menu - -@node Formatting Control, Options, , What is makeinfo -@section Controlling Paragraph Formats - -In general, @code{makeinfo} @dfn{fills} the paragraphs that it outputs -to an Info file. Filling is the process of breaking 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. With -@code{makeinfo}, you can control: - -@itemize @bullet -@item -The width of each paragraph (the @dfn{fill-column}). -@item -The amount of indentation that the first line of -each paragraph receives (the @dfn{paragraph-indentation}). -@end itemize - -@node Options, Pointer Validation, Formatting Control, What is makeinfo -@section Command Line Options - -The following command line options are available for @code{makeinfo}. - -@need 100 -@table @code -@item -D @var{var} -Cause @var{var} to be defined. This is equivalent to -@code{@@set @var{var}} in the Texinfo file. - -@need 150 -@item --error-limit @var{limit} -Set the maximum number of errors that @code{makeinfo} will report -before exiting (on the assumption that continuing would be useless). -The default number of errors that can be reported before -@code{makeinfo} gives up is 100.@refill - -@need 150 -@item --fill-column @var{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. The default value for @code{fill-column} is 72. -@refill - -@item --footnote-style @var{style} -Set the footnote style to @var{style}, either @samp{end} for the end -node style or @samp{separate} for the separate node style. The value -set by this option overrides the value set in a Texinfo file by an -@code{@@footnotestyle} command. When the footnote style is -@samp{separate}, @code{makeinfo} makes a new node containing the -footnotes found in the current node. When the footnote style is -@samp{end}, @code{makeinfo} places the footnote references at the end -of the current node.@refill - -@need 150 -@item -I @var{dir} -Add @code{dir} to the directory search list for finding files that are -included using the @code{@@include} command. By default, -@code{makeinfo} searches only the current directory. - -@need 150 -@item --no-headers -Do not include menus or node lines in the output. This results in an -@sc{ascii} file that you cannot read in Info since it does not contain -the requisite nodes or menus; but you can print such a file in a -single, typewriter-like font and produce acceptable output. - -@need 150 -@item --no-split -Suppress the splitting stage of @code{makeinfo}. Normally, large -output files (where the size is greater than 70k bytes) are split into -smaller subfiles, each one approximately 50k bytes. If you specify -@samp{--no-split}, @code{makeinfo} will not split up the output -file.@refill - -@need 100 -@item --no-pointer-validate -@item --no-validate -Suppress the pointer-validation phase of @code{makeinfo}. Normally, -after a Texinfo file is processed, some consistency checks are made to -ensure that cross references can be resolved, etc. -@xref{Pointer Validation}.@refill - -@need 150 -@item --no-warn -Suppress the output of warning messages. This does @emph{not} -suppress the output of error messages, only warnings. You might -want this if the file you are creating has examples of Texinfo cross -references within it, and the nodes that are referenced do not actually -exist.@refill - -@item --no-number-footnotes -Supress automatic footnote numbering. By default, @code{makeinfo} -numbers each footnote sequentially in a single node, resetting the -current footnote number to 1 at the start of each node. - -@need 150 -@item --output @var{file} -@itemx -o @var{file} -Specify that the output should be directed to @var{file} and not to the -file name specified in the @code{@@setfilename} command found in the Texinfo -source. @var{file} can be the special token @samp{-}, which specifies -standard output. - -@need 150 -@item --paragraph-indent @var{indent} -Set the paragraph indentation style to @var{indent}. The value set by -this option overrides the value set in a Texinfo file by an -@code{@@paragraphindent} command. The value of @var{indent} is -interpreted as follows:@refill - -@itemize @bullet -@item -If the value of @var{indent} is @samp{asis}, do not change the -existing indentation at the starts of paragraphs.@refill - -@item -If the value of @var{indent} is zero, delete any existing -indentation.@refill - -@item -If the value of @var{indent} is greater than zero, indent each -paragraph by that number of spaces.@refill -@end itemize - -@need 100 -@item --reference-limit @var{limit} -Set the value of the number of references to a node that -@code{makeinfo} will make without reporting a warning. If a node has more -than this number of references in it, @code{makeinfo} will make the -references but also report a warning.@refill - -@need 150 -@item -U @var{var} -Cause @var{var} to be undefined. This is equivalent to -@code{@@clear @var{var}} in the Texinfo file. - -@need 100 -@item --verbose -Cause @code{makeinfo} to display messages saying what it is doing. -Normally, @code{makeinfo} only outputs messages if there are errors or -warnings.@refill - -@need 100 -@item --version -Report the version number of this copy of @code{makeinfo}.@refill -@end table - -@node Pointer Validation, , Options, What is makeinfo -@section Pointer Validation -@cindex Pointer validation with @code{makeinfo} -@cindex Validation of pointers - -If you do not suppress pointer-validation (by using the -@samp{--no-pointer-validation} option), @code{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:@refill - -@enumerate -@item -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 -@file{(dir)}, then the referenced node must exist.@refill - -@item -In every node, if the `Previous' node is different from the `Up' node, -then the `Previous' node must also be pointed to by a `Next' node.@refill - -@item -Every node except the `Top' node must have an `Up' pointer.@refill - -@item -The node referenced by an `Up' pointer must contain a reference to the -current node in some manner other than through a `Next' reference. -This includes menu entries and cross references.@refill - -@item -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.@refill -@end enumerate - -@bye diff --git a/gnu/usr.bin/texinfo/info-files/texi-files/texi.texi b/gnu/usr.bin/texinfo/info-files/texi-files/texi.texi deleted file mode 100644 index f77f662..0000000 --- a/gnu/usr.bin/texinfo/info-files/texi-files/texi.texi +++ /dev/null @@ -1,15626 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header -@setfilename texi.info -@settitle Texinfo @value{edition} -@syncodeindex vr fn -@c footnotestyle separate -@c paragraphindent 2 -@smallbook -@comment %**end of header - -@ignore -@ifinfo -@format -START-INFO-DIR-ENTRY -* Texinfo: (texi.info). The documentation format for the GNU Project. -END-INFO-DIR-ENTRY -@end format -@end ifinfo -@end ignore - -@c Set smallbook if printing in smallbook format so the example of the -@c smallbook font is actually written using smallbook; in bigbook, a kludge -@c is used for TeX output. -@c set smallbook -@clear smallbook - -@set edition 2.18 -@set update-date 26 March 1993 -@set update-month March 1993 - -@c Experiment with smaller amounts of whitespace between chapters -@c and sections. -@tex -\global\chapheadingskip = 15pt plus 4pt minus 2pt -\global\secheadingskip = 12pt plus 3pt minus 2pt -\global\subsecheadingskip = 9pt plus 2pt minus 2pt -@end tex - -@c Experiment with smaller amounts of whitespace between paragraphs in -@c the 8.5 by 11 inch format. -@ifclear smallbook -@tex -\global\parskip 6pt plus 1pt -@end tex -@end ifclear - -@finalout - -@c Currently undocumented commands, 24 March 1993: -@c See documentation in `texinfmt.el' file. -@c -@c raisesections (Two useful commands.) -@c lowersections -@c nwnode (Same as node, but no warnings; for `makeinfo'.) -@c math (Unsatisfactory TeX definition; no processing for Info.) -@c definfoenclose (For ifinfo text only; not supported by `makeinfo'; -@c each instance requires a corresponding TeX definition.) - -@ifinfo -This file documents Texinfo, a documentation system that uses a single -source file to produce both on-line information and a printed manual. - -Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation, Inc. - -This is the second edition of the Texinfo documentation,@* -and is consistent with version 2 of @file{texinfo.tex}. - -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. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). - -@end ignore -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 Free Software Foundation. -@end ifinfo - -@setchapternewpage odd -@titlepage -@c use the new format for titles -@title Texinfo -@subtitle The GNU Documentation Format -@subtitle Edition @value{edition}, for Texinfo Version Two -@subtitle @value{update-month} - -@author by Robert J. Chassell and Richard M. Stallman - -@comment Include the Distribution inside the titlepage so -@c that headings are turned off. - -@page -@vskip 0pt plus 1filll -Copyright @copyright{} 1988, 1990, 1991, 1992, 1993 Free Software Foundation, Inc. - -@sp 2 -This is the second edition of the Texinfo documentation,@* -and is consistent with version 2 of @file{texinfo.tex}. -@sp 2 - -Published by the Free Software Foundation @* -675 Massachusetts Avenue, @* -Cambridge, MA 02139 USA @* -Printed copies are available for $15 each.@* -ISBN-1882114-12-4 - -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 Free Software Foundation. -@sp 2 -Cover art by Etienne Suvasa. -@end titlepage - -@ifinfo -@node Top, Copying, (dir), (dir) -@top Texinfo - -Texinfo is a documentation system that uses a single source file to -produce both on-line information and printed output.@refill - -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.@refill - -This is Edition @value{edition} of the Texinfo documentation, -@w{@value{update-date},} for Texinfo Version 2. -@end ifinfo - -@c Here is a spare copy of the chapter menu entry descriptions, -@c in case they are accidently deleted -@ignore -Your rights. -Texinfo in brief. -How to use Texinfo mode. -What is at the beginning of a Texinfo file? -What is at the end of a Texinfo file? -How to create chapters, sections, subsections, - appendices, and other parts. -How to provide structure for a document. -How to write nodes. -How to write menus. -How to write cross references. -How to mark words and phrases as code, - keyboard input, meta-syntactic - variables, and the like. -How to write quotations, examples, etc. -How to write lists and tables. -How to create indices. -How to insert @@-signs, braces, etc. -How to indicate results of evaluation, - expansion of macros, errors, etc. -How to force and prevent line and page breaks. -How to describe functions and the like in a uniform manner. -How to write footnotes. -How to specify text for either @TeX{} or Info. -How to print hardcopy. -How to create an Info file. -How to install an Info file -A list of all the Texinfo @@-commands. -Hints on how to write a Texinfo document. -A sample Texinfo file to look at. -Tell readers they have the right to copy - and distribute. -How to incorporate other Texinfo files. -How to write page headings and footings. -How to find formatting mistakes. -All about paragraph refilling. -A description of @@-Command syntax. -Texinfo second edition features. -A menu containing commands and variables. -A menu covering many topics. -@end ignore - -@menu -* Copying:: Your rights. -* Overview:: Texinfo in brief. -* Texinfo Mode:: How to use 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:: How to create chapters, sections, subsections, - appendices, and other parts. -* Nodes:: How to write nodes. -* Menus:: How to write menus. -* Cross References:: How to write cross references. -* Marking Text:: How to mark words and phrases as code, - keyboard input, meta-syntactic - variables, and the like. -* Quotations and Examples:: How to write quotations, examples, etc. -* Lists and Tables:: How to write lists and tables. -* Indices:: How to create indices. -* Insertions:: How to insert @@-signs, braces, etc. -* Glyphs:: How to indicate results of evaluation, - expansion of macros, errors, etc. -* Breaks:: How to force and prevent line and page breaks. -* Definition Commands:: How to describe functions and the like - in a uniform manner. -* Footnotes:: How to write footnotes. -* Conditionals:: How to specify text for either @TeX{} or Info. -* Format/Print Hardcopy:: How to convert a Texinfo file to a file - for printing and how to print that file. -* Create an Info File:: Convert a Texinfo file into an Info file. -* Install an Info File:: Make an Info file accessible to users. -* Command List:: All the Texinfo @@-commands. -* Tips:: Hints on how to write a Texinfo document. -* Sample Texinfo File:: A sample Texinfo file to look at. -* Sample Permissions:: Tell readers they have the right to copy - and distribute. -* Include Files:: How to incorporate other Texinfo files. -* Headings:: How to write page headings and footings. -* Catching Mistakes:: How to find formatting mistakes. -* Refilling Paragraphs:: All about paragraph refilling. -* Command Syntax:: A description of @@-Command syntax. -* Obtaining TeX:: How to Obtain @TeX{}. -* New Features:: Texinfo second edition features. -* Command and Variable Index:: A menu containing commands and variables. -* Concept Index:: A menu covering many topics. - - --- The Detailed Node Listing --- - -Overview of Texinfo - -* Using Texinfo:: Create a conventional printed book - or an Info file. -* 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:: How to write comments and mark regions that - the formatting commands will ignore. -* Minimum:: What a Texinfo file must have. -* Six Parts:: Usually, a Texinfo file has six parts. -* Short Sample:: A short sample Texinfo file. -* Acknowledgements:: - -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 - -* Four Parts:: Four parts begin a Texinfo file. -* Sample Beginning:: Here is a sample beginning for a Texinfo file. -* Header:: The very beginning of a Texinfo file. -* Info Summary and Permissions:: Summary and copying permissions for Info. -* Titlepage & Copyright Page:: Creating the title and copyright pages. -* The Top Node:: Creating the `Top' node and master menu. -* Software Copying Permissions:: Ensure that you and others continue to - have the right to use and share software. - -The 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. -* setchapternewpage:: Start chapters on right-hand pages. -* paragraphindent:: An option to specify paragraph indentation. -* End of Header:: Formatting a region requires this. - -The Title and Copyright Pages - -* titlepage:: Create a title for the printed document. -* titlefont center sp:: The @code{@@titlefont}, @code{@@center}, - and @code{@@sp} commands. -* title subtitle author:: The @code{@@title}, @code{@@subtitle}, - and @code{@@author} commands. -* Copyright & Permissions:: 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 - -* Title of Top Node:: Sketch what the file is about. -* Master Menu Parts:: A master menu has three or more parts. - -Ending a Texinfo File - -* Printing Indices & Menus:: How to print an index in hardcopy and - generate index menus in Info. -* Contents:: How to create a table of contents. -* File End:: How to mark the end of a file. - -Chapter Structuring - -* Tree Structuring:: A manual is like an upside down tree @dots{} -* Structuring Command Types:: How to divide a manual into parts. -* makeinfo top:: The @code{@@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. - -Nodes - -* Two Paths:: Different commands to structure - Info output and printed output. -* Node Menu Illustration:: A diagram, and sample nodes and menus. -* node:: How to write a node, in detail. -* makeinfo Pointer Creation:: How to create node pointers with @code{makeinfo}. - -The @code{@@node} Command - -* Node Names:: How to choose node and pointer names. -* Writing a Node:: How to write an @code{@@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 @code{@@top} command. -* Top Node Summary:: Write a brief description for readers. - -Menus - -* Menu Location:: Put a menu in a short node. -* 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' @dots{} -* 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. - -@code{@@xref} - -* Reference Syntax:: What a reference looks like and requires. -* One Argument:: @code{@@xref} with one argument. -* Two Arguments:: @code{@@xref} with two arguments. -* Three Arguments:: @code{@@xref} with three arguments. -* Four and Five Arguments:: @code{@@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:: How to indicate code. -* kbd:: How to show keyboard input. -* key:: How to specify keys. -* samp:: How to show a literal sequence of characters. -* var:: How to indicate a metasyntactic variable. -* file:: How to indicate the name of a file. -* dfn:: How to specify a definition. -* cite:: How to refer to a book that is not in Info. - -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:: Use different constructs for - different purposes. -* quotation:: How to write a quotation. -* example:: How to write an example in a fixed-width font. -* noindent:: How to prevent paragraph indentation. -* Lisp Example:: How to illustrate Lisp code. -* smallexample & smalllisp:: Forms for the @code{@@smallbook} option. -* display:: How to write an example in the current font. -* format:: How to write an example that does not narrow - the margins. -* exdent:: How to undo the indentation of a line. -* flushleft & flushright:: How to push text flushleft or flushright. -* cartouche:: How to draw cartouches around examples. - -Making 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. - -Making a Two-column Table - -* table:: How to construct a two-column table. -* ftable vtable:: How to construct a two-column table - with automatic indexing. -* itemx:: How to put more entries in the first column. - -Creating Indices - -* Index Entries:: Choose different words for index entries. -* Predefined Indices:: Use different indices for different kinds - of entry. -* 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{@@code} - font for the merged-from index. -* synindex:: How to merge two indices, using the - default font of the merged-to index. - -Special Insertions - -* Braces Atsigns Periods:: How to insert braces, @samp{@@} and periods. -* dmn:: How to format a dimension. -* Dots Bullets:: How to insert dots and bullets. -* TeX and copyright:: How to insert the @TeX{} logo - and the copyright symbol. -* minus:: How to insert a minus sign. - -Inserting @samp{@@}, Braces, and Periods - -* Inserting An Atsign:: -* Inserting Braces:: How to insert @samp{@{} and @samp{@}} -* Controlling Spacing:: How to insert the right amount of space - after punctuation within a sentence. - -Inserting Ellipsis, Dots, and Bullets - -* dots:: How to insert dots @dots{} -* bullet:: How to insert a bullet. - -Inserting @TeX{} and the Copyright Symbol - -* tex:: How to insert the @TeX{} logo. -* copyright symbol:: How to use @code{@@copyright}@{@}. - -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. - -Making and Preventing Breaks - -* Break Commands:: Cause and prevent splits. -* Line Breaks:: How to force a single line to use two lines. -* w:: How to prevent unwanted line breaks. -* sp:: How to insert blank lines. -* page:: How to force the start of a new page. -* group:: How to prevent unwanted page breaks. -* need:: Another way to prevent unwanted page breaks. - -Definition Commands - -* Def Cmd Template:: How to structure a description using a - definition command. -* Optional Arguments:: How to handle optional and repeated arguments. -* deffnx:: How to group two or more `first' lines. -* Def Cmds in Detail:: All the definition commands. -* Def Cmd Conventions:: Conventions for writing definitions. -* Sample Function Definition:: - -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. -* Abstract Objects:: Commands for object-oriented programming. -* Data Types:: The definition command for data types. - -Conditionally Visible Text - -* Conditional Commands:: How to specify text for Info or @TeX{}. -* Using Ordinary TeX Commands:: You can use any and all @TeX{} commands. -* set clear value:: How to designate which text to format (for - both Info and @TeX{}); and how to set a - flag to a string that you can insert. - -@code{@@set}, @code{@@clear}, and @code{@@value} - -* ifset ifclear:: Format a region if a flag is set. -* value:: Replace a flag with a string. -* value Example:: An easy way to update edition information. - -Format and Print Hardcopy - -* Use TeX:: Use @TeX{} to format for hardcopy. -* Shell Format & Print:: How to format and print a hardcopy manual - with shell commands. -* 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 you need to do to 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 European A4 paper. -* Cropmarks and Magnification:: How to print marks to indicate the size - of pages and how to print scaled up output. - -Creating an Info File - -* makeinfo advantages:: @code{makeinfo} provides better error checking. -* Invoking makeinfo:: How to run @code{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 @code{makeinfo} from Emacs. -* texinfo-format commands:: Two Info formatting commands written - in Emacs Lisp are an alternative - to @code{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. - -Sample Permissions - -* Inserting Permissions:: How to put permissions in your document. -* ifinfo Permissions:: Sample @samp{ifinfo} copying permissions. -* Titlepage Permissions:: Sample Titlepage copying permissions. - -Include Files - -* Using Include Files:: How to use the @code{@@include} command. -* texinfo-multiple-files-update:: How to create and update nodes and - menus when using included files. -* Include File Requirements:: What @code{texinfo-multiple-files-update} expects. -* Sample Include File:: A sample outer file with included files - within it; and a sample included file. -* Include Files Evolution:: How use of the @code{@@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:: @code{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 @code{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 @code{Info-validate}. -* Unsplit:: How to create an unsplit file. -* Tagifying:: How to tagify a file. -* Splitting:: How to split a file manually. - -Second Edition Features - -* New Texinfo Mode Commands:: The updating commands are especially useful. -* New Commands:: Many newly described @@-commands. -@end menu - -@node Copying, Overview, Top, Top -@comment node-name, next, previous, up -@unnumbered Texinfo Copying Conditions -@cindex Copying conditions -@cindex Conditions for copying Texinfo - -The programs currently being distributed that relate to Texinfo include -portions of GNU Emacs, plus other separate programs (including -@code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}). -These programs are @dfn{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.@refill - - 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.@refill - - 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.@refill - - 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.@refill - - 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.@refill - -@node Overview, Texinfo Mode, Copying, Top -@comment node-name, next, previous, up -@chapter Overview of Texinfo -@cindex Overview of Texinfo -@cindex Texinfo overview - -@dfn{Texinfo}@footnote{Note that the first syllable of ``Texinfo'' is -pronounced like ``speck'', not ``hex''. This odd pronunciation is -derived from, but is not the same as, the pronunciation of @TeX{}. In -the word @TeX{}, the @samp{X} is actually the Greek letter ``chi'' -rather than the English letter ``ex''. Pronounce @TeX{} as if the -@samp{X} were the last sound in the name `Bach'; but pronounce Texinfo -as if the @samp{x} were a `k'. Spell ``Texinfo'' with a capital ``T'' -and write the other letters in lower case.} -is a documentation system that uses a single source file to produce both -on-line information and printed output. This means that instead of -writing two different documents, one for the on-line help or other on-line -information and the other for a typeset manual or other printed work, you -need write only one document. When the work is revised, you need revise -only one document. (You can read the on-line information, known as an -@dfn{Info file}, with an Info documentation-reading program.)@refill - -@menu -* Using Texinfo:: Create a conventional printed book - or an Info file. -* 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:: How to write comments and mark regions that - the formatting commands will ignore. -* Minimum:: What a Texinfo file must have. -* Six Parts:: Usually, a Texinfo file has six parts. -* Short Sample:: A short sample Texinfo file. -* Acknowledgements:: -@end menu - -@node Using Texinfo, Info Files, , Overview -@ifinfo -@heading Using Texinfo -@end ifinfo - -Using Texinfo, you can create a printed document with the normal -features of a book, including chapters, sections, cross references, -and indices. From the same Texinfo source file, you can create a -menu-driven, on-line Info file with nodes, menus, cross references, -and indices. You can, if you wish, make the chapters and sections of -the printed document correspond to the nodes of the on-line -information; and you use the same cross references and indices for -both the Info file and the printed work. @cite{The GNU -Emacs Manual} is a good example of a Texinfo file, as is this manual.@refill - -To make a printed document, you process a Texinfo source file with the -@TeX{} typesetting program. This creates a @sc{dvi} file that you can -typeset and print as a book or report. (Note that the Texinfo language is -completely different from @TeX{}'s usual language, Plain@TeX{}, which -Texinfo replaces.) If you do not have @TeX{}, but do have -@code{troff} or @code{nroff}, you can use the @code{texi2roff} program -instead.@refill - -To make an Info file, you process a Texinfo source file with the -@code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command; -this creates an Info file that you can install on-line.@refill - -@TeX{} and @code{texi2roff} work with many types of printer; similarly, -Info works with almost every type of computer terminal. This power -makes Texinfo a general purpose system, but brings with it a constraint, -which is that a Texinfo file may contain only the customary -``typewriter'' characters (letters, numbers, spaces, and punctuation -marks) but no special graphics.@refill - -A Texinfo file is a plain @sc{ascii} file containing text and -@dfn{@@-commands} (words preceded by an @samp{@@}) that tell the -typesetting and formatting programs what to do. You may 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. (@xref{Texinfo -Mode}.)@refill - -Before writing a Texinfo source file, you should become familiar with -the Info documentation reading program and learn about nodes, -menus, cross references, and the rest. (@inforef{Top, info, info}, -for more information.)@refill - -You can use Texinfo to create both on-line help and printed manuals; -moreover, Texinfo is freely redistributable. For these reasons, Texinfo -is the format in which documentation for GNU utilities and libraries is -written.@refill - -@node Info Files, Printed Books, Using Texinfo, Overview -@comment node-name, next, previous, up -@section Info files -@cindex Info files - -An Info file is a Texinfo file formatted so that the Info documentation -reading program can operate on it. (@code{makeinfo} -and @code{texinfo-format-buffer} are two commands that convert a Texinfo file -into an Info file.)@refill - -Info files are divided into pieces called @dfn{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.@refill - -@ifinfo -@inforef{Top, info, info}, for more information about using Info.@refill -@end ifinfo - -Each node of an Info file may have any number of child nodes that -describe subtopics of the node's topic. The names of child -nodes are listed in a @dfn{menu} 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.@refill - -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.@footnote{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.}@refill - -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.@refill - -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.@refill - -Usually, you will design a document so that its nodes match the -structure of chapters and sections in the printed output. But 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.@refill - -Generally, you enter an Info file through a node that by convention is -called @samp{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.@refill -@c !!! With the standalone Info system you may go to specific nodes -@c directly.. - -If you want to read through an Info file in sequence, as if it were a -printed manual, you can get the whole file with the advanced Info -command @kbd{g* @key{RET}}. (@inforef{Expert, Advanced Info commands, -info}.)@refill - -@c !!! dir file may be located in one of many places: -@c /usr/local/emacs/info mentioned in info.c DEFAULT_INFOPATH -@c /usr/local/lib/emacs/info mentioned in info.c DEFAULT_INFOPATH -@c /usr/gnu/info mentioned in info.c DEFAULT_INFOPATH -@c /usr/local/info -@c /usr/local/lib/info -The @file{dir} file in the @file{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.@refill - -@node Printed Books, Formatting Commands, Info Files, Overview -@comment node-name, next, previous, up -@section Printed Books -@cindex Printed book and manual characteristics -@cindex Manual characteristics, printed -@cindex Book characteristics, printed -@cindex Texinfo printed book characteristics -@cindex Characteristics, printed books or manuals - -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.@footnote{You can also use the -@code{texi2roff} program if you do not have @TeX{}; since Texinfo is -designed for use with @TeX{}, @code{texi2roff} is not described here. -@code{texi2roff} is part of the standard GNU distribution.}@refill - -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.@refill - -You can use Texinfo to write a book without ever having the intention -of converting it into on-line 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.@refill - -@TeX{} is a general purpose typesetting program. Texinfo provides a -file called @file{texinfo.tex} that contains information (definitions or -@dfn{macros}) that @TeX{} uses when it typesets a Texinfo file. -(@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands -to @TeX{} commands, which @TeX{} can then process to create the typeset -document.) @file{texinfo.tex} contains the specifications for printing -a document.@refill - -Most often, documents are printed on 8.5 inch by 11 inch -pages (216@dmn{mm} by 280@dmn{mm}; this is the default size), but you -can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by -235@dmn{mm}; the @code{@@smallbook} size) or on European A4 size paper -(@code{@@afourpaper}). (@xref{smallbook, , Printing ``Small'' Books}. -Also, see @ref{A4 Paper, ,Printing on A4 Paper}.)@refill - -By changing the parameters in @file{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.@refill - -@TeX{} is freely distributable. It is written in a dialect 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. -(@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information -about @TeX{}.)@refill - -@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.@refill - -@xref{Obtaining TeX, , How to Obtain @TeX{}}. - - -@node Formatting Commands, Conventions, Printed Books, Overview -@comment node-name, next, previous, up -@section @@-commands -@cindex @@-commands -@cindex Formatting commands - -In a Texinfo file, the commands that tell @TeX{} how to typeset the -printed manual and tell @code{makeinfo} and -@code{texinfo-format-buffer} how to create an Info file are preceded -by @samp{@@}; they are called @dfn{@@-commands}. For example, -@code{@@node} is the command to indicate a node and @code{@@chapter} -is the command to indicate the start of a chapter.@refill - -@quotation -@strong{Please note:} All the @@-commands, with the exception of the -@code{@@TeX@{@}} command, must be written entirely in lower -case.@refill -@end quotation - -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.@refill - -Depending on what they do or what arguments@footnote{The word -@dfn{argument} comes from the way it is used in mathematics and does -not refer to a disputation between two people; it refers to the -information presented to the command. According to the @cite{Oxford -English Dictionary}, the word derives from the Latin for @dfn{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 -disputation.} they take, you need to write @@-commands on lines of -their own or as part of sentences:@refill - -@itemize @bullet -@item -Write a command such as @code{@@noindent} at the beginning of a line as -the only text on the line. (@code{@@noindent} prevents the beginning of -the next line from being indented as the beginning of a -paragraph.)@refill - -@item -Write a command such as @code{@@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. (@code{@@chapter} creates chapter titles.)@refill - -@item -Write a command such as @code{@@dots@{@}} wherever you wish but usually -within a sentence. (@code{@@dots@{@}} creates dots @dots{})@refill - -@item -Write a command such as @code{@@code@{@var{sample-code}@}} wherever you -wish (but usually within a sentence) with its argument, -@var{sample-code} in this example, between the braces. (@code{@@code} -marks text as being code.)@refill - -@item -Write a command such as @code{@@example} at the beginning of a line of -its own; write the body-text on following lines; and write the matching -@code{@@end} command, @code{@@end example} in this case, at the -beginning of a line of its own after the body-text. (@code{@@example} -@dots{} @code{@@end example} indents and typesets body-text as an -example.)@refill -@end itemize - -@noindent -@cindex Braces, when to use -As a general rule, a command requires braces if it mingles among other -text; but it does not need braces if it starts a line of its own. The -non-alphabetic commands, such as @code{@@:}, are exceptions to the rule; -they do not need braces.@refill - -As you gain experience with Texinfo, you will rapidly learn how to -write the different commands: the different ways to write commands -make it easier to write and read Texinfo files than if all commands -followed exactly the same syntax. (For details about @@-command -syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill - -@node Conventions, Comments, Formatting Commands, Overview -@comment node-name, next, previous, up -@section General Syntactic Conventions -@cindex General syntactic conventions -@cindex Syntactic conventions -@cindex Conventions, syntactic - -All @sc{ascii} printing characters except @samp{@@}, @samp{@{} and -@samp{@}} can appear in a Texinfo file and stand for themselves. -@samp{@@} is the escape character which introduces commands. -@samp{@{} and @samp{@}} should be used only to surround arguments to -certain commands. To put one of these special characters into the -document, put an @samp{@@} character in front of it, like this: -@samp{@@@@}, @samp{@@@{}, and @samp{@@@}}.@refill - -@ifinfo -It is customary in @TeX{} to use doubled single-quote characters to -begin and end quotations: ` ` and ' ' (but without a space between the -two single-quote characters). This convention should be followed in -Texinfo files. @TeX{} converts doubled single-quote characters to -left- and right-hand doubled quotation marks and Info converts doubled -single-quote characters to @sc{ascii} double-quotes: ` ` and ' ' to " .@refill -@end ifinfo -@iftex -It is customary in @TeX{} to use doubled single-quote characters to -begin and end quotations: @w{@tt{ `` }} and @w{@tt{ '' }}. This -convention should be followed in Texinfo files. @TeX{} converts -doubled single-quote characters to left- and right-hand doubled -quotation marks, ``like this'', and Info converts doubled single-quote -characters to @sc{ascii} double-quotes: @w{@tt{ `` }} and -@w{@tt{ '' }} to @w{@tt{ " }}.@refill -@end iftex - -Use three hyphens in a row, @samp{---}, for a dash---like this. In -@TeX{}, a single or even a double hyphen produces a printed dash that -is shorter than the usual typeset dash. Info reduces three hyphens to two for -display on the screen.@refill - -To prevent a paragraph from being indented in the printed manual, put -the command @code{@@noindent} on a line by itself before the -paragraph.@refill - -If you mark off a region of the Texinfo file with the @code{@@iftex} -and @w{@code{@@end iftex}} commands, that region will appear only in -the printed copy; in that region, you can use certain commands -borrowed from Plain@TeX{} that you cannot use in Info. Likewise, if -you mark off a region with the @code{@@ifinfo} and @code{@@end ifinfo} -commands, that region will appear only in the Info file; in that -region, you can use Info commands that you cannot use in @TeX{}. -(@xref{Conditionals}.) - -@cindex Tabs; don't use! -@quotation -@strong{Caution:} Do not use tabs in a Texinfo file! @TeX{} uses -variable-width fonts, which means that it cannot predefine a tab to work -in all circumstances. Consequently, @TeX{} treats tabs like single -spaces, and that is not what they look like.@refill - -@noindent -To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple -spaces when you press the @key{TAB} key.@refill - -@noindent -Also, you can run @code{untabify} in Emacs to convert tabs in a region -to multiple spaces.@refill -@end quotation - -@node Comments, Minimum, Conventions, Overview -@comment node-name, next, previous, up -@section 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 -@code{@@comment} command (which may be abbreviated to @code{@@c}). -Such comments are for the person who reads the Texinfo file. All the -text on a line that follows either @code{@@comment} or @code{@@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 @code{@@comment} or -@code{@@c} in the middle of a line, and only the text that follows after -the @code{@@comment} or @code{@@c} command does not appear; but some -commands, such as @code{@@settitle} and @code{@@setfilename}, work on a -whole line. You cannot use @code{@@comment} or @code{@@c} in a line -beginning with such a command.)@refill -@cindex Comments -@findex comment -@findex c @r{(comment)} - -You can write long stretches of text that will not appear in either -the Info file or the printed manual by using the @code{@@ignore} and -@code{@@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 @code{@@ignore} and @code{@@end ignore} for writing -comments. Often, @code{@@ignore} and @code{@@end ignore} is used -to enclose a part of the copying permissions that applies to the -Texinfo source file of a document, but not to the Info or printed -version of the document.@refill -@cindex Ignored text -@cindex Unprocessed text -@findex ignore -@c !!! Perhaps include this comment about ignore and ifset: -@ignore -Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or -@code{@@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 -@emph{stop} ignoring text from the source file; that means that you -will still get error messages if you have invalid Texinfo markup -within ignored text. -@end ignore - -@node Minimum, Six Parts, Comments, Overview -@comment node-name, next, previous, up -@section What a Texinfo File Must Have -@cindex Minimal Texinfo file (requirements) -@cindex Must have in Texinfo file -@cindex Required in Texinfo file -@cindex Texinfo file minimum - -By convention, the names of Texinfo files end with one of the -extensions @file{.texinfo}, @file{.texi}, or @file{.tex}. The longer -extension is preferred since it describes more clearly to a human -reader the nature of the file. The shorter extensions are for -operating systems that cannot handle long file names.@refill - -In order to be made into a printed manual and an Info file, a -Texinfo file @strong{must} begin with lines like this:@refill - -@example -@group -\input texinfo -@@setfilename @var{info-file-name} -@@settitle @var{name-of-manual} -@end group -@end example - -@noindent -The contents of the file follow this beginning, and then you @strong{must} end -a Texinfo file with a line like this:@refill - -@example -@@bye -@end example - -@findex input @r{(@TeX{} command)} -@noindent -The @samp{\input texinfo} line tells @TeX{} to use the -@file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo -@@-commands into @TeX{} typesetting commands. (Note the use of the -backslash, @samp{\}; this is correct for @TeX{}.) The -@samp{@@setfilename} line provides a name for the Info file and the -@samp{@@settitle} line specifies a title for the page headers (or -footers) of the printed manual.@refill - -The @code{@@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.@refill - -Usually, 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:@refill - -@example -@group -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename @var{info-file-name} -@@settitle @var{name-of-manual} -@@c %**end of header -@end group -@end example - -@noindent -In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into -Texinfo mode when you edit the file. - -The @code{@@c} lines which surround the @samp{@@setfilename} and -@samp{@@settitle} lines are optional, but you need them in order to -run @TeX{} or Info on just part of the file. (@xref{Start of Header}, -for more information.)@refill - -Furthermore, you will usually provide a Texinfo file with a title -page, indices, and the like. 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.@refill - -@node Six Parts, Short Sample, Minimum, Overview -@comment node-name, next, previous, up -@section Six Parts of a Texinfo File - -Generally, a Texinfo file contains more than the minimal -beginning and end---it usually contains six parts:@refill - -@table @r -@item 1. Header -The @dfn{Header} names the file, tells @TeX{} which definitions' file to -use, and performs other ``housekeeping'' tasks.@refill - -@item 2. Summary Description and Copyright -The @dfn{Summary Description and Copyright} segment describes the document -and contains the copyright notice and copying permissions for the Info -file. The segment must be enclosed between @code{@@ifinfo} and -@code{@@end ifinfo} commands so that the formatters place it only in the Info -file.@refill - -@item 3. Title and Copyright -The @dfn{Title and Copyright} segment contains the title and copyright pages -and copying permissions for the printed manual. The segment must be -enclosed between @code{@@titlepage} and @code{@@end titlepage} commands. -The title and copyright page appear only in the printed @w{manual}.@refill - -@item 4. `Top' Node and Master Menu -The @dfn{Master Menu} contains a complete menu of all the nodes in the whole -Info file. It appears only in the Info file, in the `Top' node.@refill - -@item 5. Body -The @dfn{Body} of the document may be structured like a traditional book or -encyclopedia or it may be free form.@refill - -@item 6. End -The @dfn{End} contains commands for printing indices and generating -the table of contents, and the @code{@@bye} command on a line of its -own.@refill -@end table - -@node Short Sample, Acknowledgements, Six Parts, Overview -@comment node-name, next, previous, up -@section A Short Sample Texinfo File -@cindex Sample Texinfo file - -Here is a complete but very short Texinfo file, in 6 parts. The first -three parts of the file, from @samp{\input texinfo} through to -@samp{@@end titlepage}, look more intimidating than they are. Most of -the material is standard boilerplate; when you write a manual, simply -insert the names for your own manual in this segment. (@xref{Beginning a -File}.)@refill - -@noindent -In the following, the sample text is @emph{indented}; comments on it are -not. The complete file, without any comments, is shown in -@ref{Sample Texinfo File}. - -@subheading Part 1: Header - -@noindent -The header does not appear in either the Info file or the@* -printed output. It sets various parameters, including the@* -name of the Info file and the title used in the header. - -@example -@group -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename sample.info -@@settitle Sample Document -@@c %**end of header - -@@setchapternewpage odd -@end group -@end example - -@subheading Part 2: Summary Description and Copyright - -@noindent -The summary description and copyright segment does not@* -appear in the printed document. - -@example -@group -@@ifinfo -This is a short example of a complete Texinfo file. - -Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. -@@end ifinfo -@end group -@end example - -@subheading Part 3: Titlepage and Copyright - -@noindent -The titlepage segment does not appear in the Info file. - -@example -@group -@@titlepage -@@sp 10 -@@comment The title is printed in a large font. -@@center @@titlefont@{Sample Title@} -@end group - -@group -@@c The following two commands start the copyright page. -@@page -@@vskip 0pt plus 1filll -Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. -@@end titlepage -@end group -@end example - -@subheading Part 4: `Top' Node and Master Menu - -@noindent -The `Top' node contains the master menu for the Info file.@* -Since a printed manual uses a table of contents rather than@* -a menu, the master menu appears only in the Info file. - -@example -@group -@@node Top, First Chapter, (dir), (dir) -@@comment node-name, next, previous, up -@end group -@end example - -@example -@group -@@menu -* First Chapter:: The first chapter is the - only chapter in this sample. -* Concept Index:: This index has two entries. -@@end menu -@end group -@end example - -@subheading Part 5: The Body of the Document - -@noindent -The body segment contains all the text of the document, but not the -indices or table of contents. This example illustrates a node and a -chapter containing an enumerated list.@refill - -@example -@group -@@node First Chapter, Concept Index, Top, Top -@@comment node-name, next, previous, up -@@chapter First Chapter -@@cindex Sample index entry -@end group - -@group -This is the contents of the first chapter. -@@cindex Another sample index entry -@end group - -@group -Here is a numbered list. - -@@enumerate -@@item -This is the first item. - -@@item -This is the second item. -@@end enumerate -@end group - -@group -The @@code@{makeinfo@} and @@code@{texinfo-format-buffer@} -commands transform a Texinfo file such as this into -an Info file; and @@TeX@{@} typesets it for a printed -manual. -@end group -@end example - -@subheading Part 6: The End of the Document - -@noindent -The end segment contains commands both for generating an index in a node -and unnumbered chapter of its own and for generating the table of -contents; and it contains the @code{@@bye} command that marks the end of -the document.@refill - -@example -@group -@@node Concept Index, , First Chapter, Top -@@comment node-name, next, previous, up -@@unnumbered Concept Index -@end group - -@group -@@printindex cp - -@@contents -@@bye -@end group -@end example - -@subheading The Results - -Here is what the contents of the first chapter of the sample look like: - -@sp 1 -@need 700 -@quotation -This is the contents of the first chapter. - -Here is a numbered list. - -@enumerate -@item -This is the first item. - -@item -This is the second item. -@end enumerate - -The @code{makeinfo} and @code{texinfo-format-buffer} -commands transform a Texinfo file such as this into -an Info file; and @TeX{} typesets it for a printed -manual. -@end quotation - -@node Acknowledgements, , Short Sample, Overview -@comment node-name, next, previous, up -@section Acknowledgements - -Richard M.@: Stallman wrote Edition 1.0 of this manual. -@w{Robert J.@: Chassell} revised and extended it, -starting with Edition 1.1. - -Our thanks go out to all who helped improve this work, particularly to -@w{Francois Pinard} and @w{David D.@: Zuhn}, who tirelessly recorded -and reported mistakes and obscurities; our special thanks go to -@w{Melissa Weisshaus} for her frequent and often tedious reviews of -nearly similar editions. Our mistakes are our own. - -@c ignore until mailing lists set up -@ignore -Please send suggestions and corrections to: - -@example -@group -@r{Internet address:} - bug-gnu-texinfo@@prep.ai.mit.edu - -@r{UUCP path:} - mit-eddie!prep.ai.mit.edu!bug-gnu-texinfo -@end group -@end example - -@noindent -Please include the manual's edition number in your messages. -@end ignore - -@node Texinfo Mode, Beginning a File, Overview, Top -@comment node-name, next, previous, up -@chapter Using Texinfo Mode -@cindex Texinfo mode -@cindex Mode, using Texinfo -@cindex GNU Emacs -@cindex Emacs - -You may edit a Texinfo file with any text editor you choose. A Texinfo -file is no different from any other @sc{ascii} file. However, GNU Emacs -comes with a special mode, called Texinfo -mode, that provides Emacs commands and tools to help ease your work.@refill - -This chapter describes features of GNU Emacs' Texinfo mode but not any -features of the Texinfo formatting language. 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.@refill - -@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. -@end menu - -@node Texinfo Mode Overview, Emacs Editing, , Texinfo Mode -@ifinfo -@heading Texinfo Mode Overview -@end ifinfo - -Texinfo mode provides special features for working with Texinfo -files:@refill - -@itemize @bullet -@item -Insert frequently used @@commands. @refill - -@item -Automatically create @code{@@node} lines. - -@item -Show the structure of a Texinfo source file.@refill - -@item -Automatically create or update the `Next',@* -`Previous', and `Up' pointers of a node. - -@item -Automatically create or update menus.@refill - -@item -Automatically create a master menu.@refill - -@item -Format a part or all of a file for Info.@refill - -@item -Typeset and print part or all of a file.@refill -@end itemize - -Perhaps the two most helpful features are those for inserting frequently -used @@-commands and for creating node pointers and menus.@refill - -@node Emacs Editing, Inserting, Texinfo Mode Overview, Texinfo Mode -@section 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 @kbd{M-q} (@code{fill-paragraph}) -command will refill a paragraph but not mix an indexing command on a -line adjacent to it into the paragraph.@refill - -In addition, Texinfo mode sets the @code{page-delimiter} variable to -the value of @code{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 -@kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [} -(@code{backward-page}) commands and narrow to a chapter with the -@kbd{C-x p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs, -The GNU Emacs Manual}, for details about the page commands.)@refill - -You may name a Texinfo file however you wish, but the convention is to -end a Texinfo file name with one of the three extensions -@file{.texinfo}, @file{.texi}, or @file{.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 @file{.texinfo} or @file{.texi} -extension. Also, Emacs switches to Texinfo mode -when you visit a -file that has @samp{-*-texinfo-*-} in its first line. If ever you are -in another mode and wish to switch to Texinfo mode, type @code{M-x -texinfo-mode}.@refill - -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.@refill - -@node Inserting, Showing the Structure, Emacs Editing, Texinfo Mode -@comment node-name, next, previous, up -@section Inserting Frequently Used Commands -@cindex Inserting frequently used commands -@cindex Frequently used commands, inserting -@cindex Commands, inserting them - -Texinfo mode provides commands to insert various frequently used -@@-commands into the buffer. You can use these commands to save -keystrokes.@refill - -The insert commands are invoked by typing @kbd{C-c} twice and then the -first letter of the @@-command:@refill - -@table @kbd -@item C-c C-c c -@itemx M-x texinfo-insert-@@code -@findex texinfo-insert-@@code -Insert @code{@@code@{@}} and put the -cursor between the braces.@refill - -@item C-c C-c d -@itemx M-x texinfo-insert-@@dfn -@findex texinfo-insert-@@dfn -Insert @code{@@dfn@{@}} and put the -cursor between the braces.@refill - -@item C-c C-c e -@itemx M-x texinfo-insert-@@end -@findex texinfo-insert-@@end -Insert @code{@@end} and attempt to insert the correct following word, -such as @samp{example} or @samp{table}. (This command does not handle -nested lists correctly, but inserts the word appropriate to the -immediately preceding list.)@refill - -@item C-c C-c i -@itemx M-x texinfo-insert-@@item -@findex texinfo-insert-@@item -Insert @code{@@item} and put the -cursor at the beginning of the next line.@refill - -@item C-c C-c k -@itemx M-x texinfo-insert-@@kbd -@findex texinfo-insert-@@kbd -Insert @code{@@kbd@{@}} and put the -cursor between the braces.@refill - -@item C-c C-c n -@itemx M-x texinfo-insert-@@node -@findex texinfo-insert-@@node -Insert @code{@@node} and a comment line -listing the sequence for the `Next', -`Previous', and `Up' nodes. -Leave point after the @code{@@node}.@refill - -@item C-c C-c o -@itemx M-x texinfo-insert-@@noindent -@findex texinfo-insert-@@noindent -Insert @code{@@noindent} and put the -cursor at the beginning of the next line.@refill - -@item C-c C-c s -@itemx M-x texinfo-insert-@@samp -@findex texinfo-insert-@@samp -Insert @code{@@samp@{@}} and put the -cursor between the braces.@refill - -@item C-c C-c t -@itemx M-x texinfo-insert-@@table -@findex texinfo-insert-@@table -Insert @code{@@table} followed by a @key{SPC} -and leave the cursor after the @key{SPC}.@refill - -@item C-c C-c v -@itemx M-x texinfo-insert-@@var -@findex texinfo-insert-@@var -Insert @code{@@var@{@}} and put the -cursor between the braces.@refill - -@item C-c C-c x -@itemx M-x texinfo-insert-@@example -@findex texinfo-insert-@@example -Insert @code{@@example} and put the -cursor at the beginning of the next line.@refill - -@c M-@{ was the binding for texinfo-insert-braces; -@c in Emacs 19, backward-paragraph will take this binding. -@item C-c C-c @{ -@itemx M-x texinfo-insert-braces -@findex texinfo-insert-braces -Insert @code{@{@}} and put the cursor between the braces.@refill - -@item C-c C-c @} -@itemx C-c C-c ] -@itemx M-x up-list -@findex up-list -Move from between a pair of braces forward past the closing brace. -Typing @kbd{C-c C-c ]} is easier than typing @kbd{C-c C-c @}}, which -is, however, more mnemonic; hence the two keybindings. (Also, you can -move out from between braces by typing @kbd{C-f}.)@refill -@end table - -To put a command such as @w{@code{@@code@{@dots{}@}}} around an -@emph{existing} word, position the cursor in front of the word and type -@kbd{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 @code{@@kbd} and @code{@@var}.@refill - -This set of insert commands was created after analyzing the frequency -with which different @@-commands are used in the @cite{GNU Emacs -Manual} and the @cite{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 @file{texinfo.el}.@refill - -@findex texinfo-start-menu-description -@cindex Menu description, start -@cindex Description for menu, start -@kbd{C-c C-c C-d} (@code{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. -@xref{Menu Parts, , The Parts of a Menu}.)@refill - -To use @code{texinfo-start-menu-description}, position point in a menu -entry line and type @kbd{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.@refill - -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.@refill - -@node Showing the Structure, Updating Nodes and Menus, Inserting, Texinfo Mode -@comment node-name, next, previous, up -@section Showing the Section Structure of a File -@cindex Showing the section structure of a file -@cindex Section structure of a file, showing it -@cindex Structure of a file, showing it -@cindex Outline of file structure, showing it -@cindex Contents-like outline of file structure -@cindex File section structure, showing it -@cindex Texinfo file section structure, showing it - -You can show the section structure of a Texinfo file by using the -@kbd{C-c C-s} command (@code{texinfo-show-structure}). This command -shows the section structure of a Texinfo file by listing the lines -that begin with the @@-commands for @code{@@chapter}, -@code{@@section}, and the like. It constructs what amounts -to a table of contents. These lines are displayed in another buffer -called the @samp{*Occur*} buffer. In that buffer, you can position -the cursor over one of the lines and use the @kbd{C-c C-c} command -(@code{occur-mode-goto-occurrence}), to jump to the corresponding spot -in the Texinfo file.@refill - -@table @kbd -@item C-c C-s -@itemx M-x texinfo-show-structure -@findex texinfo-show-structure -Show the @code{@@chapter}, @code{@@section}, and such lines of a -Texinfo file.@refill - -@item C-c C-c -@itemx M-x occur-mode-goto-occurrence -@findex occur-mode-goto-occurrence -Go to the line in the Texinfo file corresponding to the line under the -cursor in the @file{*Occur*} buffer.@refill -@end table - -If you call @code{texinfo-show-structure} with a prefix argument by -typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the -@@-commands for @code{@@chapter}, @code{@@section}, and the like, -but also the @code{@@node} lines. (This is how the -@code{texinfo-show-structure} command worked without an argument in -the first version of Texinfo. It was changed because @code{@@node} -lines clutter up the @samp{*Occur*} buffer and are usually not -needed.) You can use @code{texinfo-show-structure} with a prefix -argument to check whether the `Next', `Previous', and `Up' pointers of -an @code{@@node} line are correct.@refill - -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 with the -@kbd{C-x n} (@code{narrow-to-region}) command and -@code{texinfo-show-structure} will work on only that region. To see -the whole buffer again, use @w{@kbd{C-x w}} (@code{widen}). -(@xref{Narrowing, , , emacs, The GNU Emacs Manual}, for more -information about the narrowing commands.)@refill - -@vindex page-delimiter -@cindex Page delimiter in Texinfo mode -In addition to providing the @code{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 @kbd{C-x -]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page}) -commands to move forward and backward by chapter, and to use the -@kbd{C-x p} (@code{narrow-to-page}) command to narrow to a chapter. -@xref{Pages, , , emacs, The GNU Emacs Manual}, for more information -about the page commands.@refill - -@node Updating Nodes and Menus, Info Formatting, Showing the Structure, Texinfo Mode -@comment node-name, next, previous, up -@section Updating Nodes and Menus -@cindex Updating nodes and menus -@cindex Create nodes, menus automatically -@cindex Insert nodes, menus automatically -@cindex Automatically insert nodes, 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 @code{@@node} line that has none and to -create menus in a file that has none.@refill - -If you do not use the updating commands, you need to write menus and -node pointers by hand, which is a tedious task.@refill - -@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. -@end menu - -@node Updating Commands, Updating Requirements, , Updating Nodes and Menus -@ifinfo -@subheading The Updating Commands -@end ifinfo - -You can use the updating commands@refill - -@itemize @bullet -@item -to insert or update the `Next', `Previous', and `Up' pointers of a -node,@refill - -@item -to insert or update the menu for a section, and@refill - -@item -to create a master menu for a Texinfo source file.@refill -@end itemize - -You can also use the commands to update all the nodes and menus in a -region or in a whole Texinfo file.@refill - -The updating commands work only with conventional Texinfo files, which -are structured hierarchically like books. In such files, a structuring -command line must follow closely after each @code{@@node} line, except -for the `Top' @code{@@node} line. (A @dfn{structuring command line} is -a line beginning with @code{@@chapter}, @code{@@section}, or other -similar command.) - -You can write the structuring command line on the line that follows -immediately after an @code{@@node} line or else on the line that -follows after a single @code{@@comment} line or a single -@code{@@ifinfo} line. You cannot interpose more than one line between -the @code{@@node} line and the structuring command line; and you may -interpose only an @code{@@comment} line or an @code{@@ifinfo} line. - -Commands which work on a whole buffer require that the `Top' node be -followed by a node with an @code{@@chapter} or equivalent-level command. -Note that the menu updating commands will not create a main or master -menu for a Texinfo file that has only @code{@@chapter}-level nodes! The -menu updating commands only create menus @emph{within} nodes for lower level -nodes. To create a menu of chapters, you must provide a `Top' -node.@refill - -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.@refill - -Texinfo mode has five updating commands that are used most often: two -are for updating the node pointers or menu of a single node (or a -region); two are for updating every node pointer and menu in a file; -and one, the @code{texinfo-master-menu} command, is for creating a -master menu for a complete file, and optionally, for updating every -node and menu in the whole Texinfo file.@refill - -The @code{texinfo-master-menu} command is the primary command:@refill - -@table @kbd -@item C-c C-u m -@itemx M-x texinfo-master-menu -@findex texinfo-master-menu -Create or update a master menu that includes all the other menus -(incorporating the descriptions from pre-existing menus, if -any).@refill - -With an argument (prefix argument, @kbd{C-u,} if interactive), first create or -update all the nodes and all the regular menus in the buffer before -constructing the master menu. (@xref{The Top Node, , The Top Node and -Master Menu}, for more about a master menu.)@refill - -For @code{texinfo-master-menu} to work, the Texinfo file must have a -`Top' node and at least one subsequent node.@refill - -After extensively editing a Texinfo file, you can type the following: - -@example -C-u M-x texinfo-master-menu -@exdent or -C-u C-c C-u m -@end example - -@noindent -This updates all the nodes and menus completely and all at once.@refill -@end table - -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.@refill - -@need 1000 -The commands are:@refill - -@table @kbd -@item C-c C-u C-n -@itemx M-x texinfo-update-node -@findex texinfo-update-node -Insert the `Next', `Previous', and `Up' pointers for the node that point is -within (i.e., for the @code{@@node} line preceding point). If the -@code{@@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, @kbd{C-u}, if interactive), this command -updates all @code{@@node} lines in the region (which is the text -between point and mark).@refill - -@item C-c C-u C-m -@itemx M-x texinfo-make-menu -@findex texinfo-make-menu -Create or update the menu in the node that point is within. -With an argument (@kbd{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.@refill - -Whenever @code{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.@refill - -@item C-c C-u C-e -@itemx M-x texinfo-every-node-update -@findex texinfo-every-node-update -Insert or update the `Next', `Previous', and `Up' pointers for every -node in the buffer.@refill - -@item C-c C-u C-a -@itemx M-x texinfo-all-menus-update -@findex texinfo-all-menus-update -Create or update all the menus in the buffer. With an argument -(@kbd{C-u} as prefix argument, if interactive), first insert -or update all the node -pointers before working on the menus.@refill - -If a master menu exists, the @code{texinfo-all-menus-update} command -updates it; but the command does not create a new master menu if none -already exists. (Use the @code{texinfo-master-menu} command for -that.)@refill - -When working on a document that does not merit a master menu, you can -type the following: - -@example -C-u C-c C-u C-a -@exdent or -C-u M-x texinfo-all-menus-update -@end example - -@noindent -This updates all the nodes and menus.@refill -@end table - -The @code{texinfo-column-for-description} variable specifies the -column to which menu descriptions are indented. By default, the value -is 32 although it is often useful to reduce it to as low as 24. You -can set the variable with the @kbd{M-x edit-options} command -(@pxref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs -Manual}) or with the @kbd{M-x set-variable} command (@pxref{Examining, -, Examining and Setting Variables, emacs, The GNU Emacs -Manual}).@refill - -Also, the @code{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 @code{texinfo-insert-node-lines} command to -insert missing @code{@@node} lines into a file. (@xref{Other Updating -Commands}, for more information.)@refill - -@node Updating Requirements, Other Updating Commands, Updating Commands, Updating Nodes and Menus -@comment node-name, next, previous, up -@subsection Updating Requirements -@cindex Updating requirements -@cindex Requirements for updating commands - -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.@refill - -Each @code{@@node} line, with the exception of the line for the `Top' -node, must be followed by a line with a structuring command such as -@code{@@chapter}, @code{@@section}, or -@code{@@unnumberedsubsec}.@refill - -Each @code{@@node} line/structuring-command line combination -must look either like this:@refill - -@example -@group -@@node Comments, Minimum, Conventions, Overview -@@comment node-name, next, previous, up -@@section Comments -@end group -@end example - -or like this (without the @code{@@comment} line): - -@example -@group -@@node Comments, Minimum, Conventions, Overview -@@section Comments -@end group -@end example - -@noindent -In this example, `Comments' is the name of both the node and the -section. The next node is called `Minimum' and the previous node is -called `Conventions'. The `Comments' section is within the `Overview' -node, which is specified by the `Up' pointer. (Instead of an -@code{@@comment} line, you can write an @code{@@ifinfo} line.)@refill - -If a file has a `Top' node, it must be called @samp{top} or @samp{Top} -and be the first node in the file.@refill - -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.@refill - -Incidentally, the @code{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 @code{makeinfo}, you have no need for the -`update node' commands. (@xref{Create an Info File, , Creating an -Info File}, for more information about @code{makeinfo}.) However, -both @code{makeinfo} and the @code{texinfo-format-@dots{}} commands -require that you insert menus in the file.@refill - -@node Other Updating Commands, , Updating Requirements, Updating Nodes and Menus -@comment node-name, next, previous, up -@subsection Other Updating Commands - -In addition to the five major updating commands, Texinfo mode -possesses several less frequently used updating commands:@refill - -@table @kbd -@item M-x texinfo-insert-node-lines -@findex texinfo-insert-node-lines -Insert @code{@@node} lines before the @code{@@chapter}, -@code{@@section}, and other sectioning commands wherever they are -missing throughout a region in a Texinfo file.@refill - -With an argument (@kbd{C-u} as prefix argument, if interactive), the -@code{texinfo-insert-node-lines} command not only inserts -@code{@@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 @code{@@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.@refill - -For example, the following marks a whole buffer as a region and inserts -@code{@@node} lines and titles throughout:@refill - -@example -C-x h C-u M-x texinfo-insert-node-lines -@end example - -(Note that this command inserts titles as node names in @code{@@node} -lines; the @code{texinfo-start-menu-description} command -(@pxref{Inserting, Inserting Frequently Used Commands}) inserts titles -as descriptions in menu entries, a different action. However, in both -cases, you need to edit the inserted text.)@refill - -@item M-x texinfo-multiple-files-update -@findex texinfo-multiple-files-update @r{(in brief)} -Update nodes and menus in a document built from several separate files. -With @kbd{C-u} as a prefix argument, create and insert a master menu in -the outer file. With a numeric prefix argument, such as @kbd{C-u 2}, first -update all the menus and all the `Next', `Previous', and `Up' pointers -of all the included files before creating and inserting a master menu in -the outer file. The @code{texinfo-multiple-files-update} command is -described in the appendix on @code{@@include} files. -@ifinfo -@xref{texinfo-multiple-files-update}.@refill -@end ifinfo -@iftex -@xref{texinfo-multiple-files-update, , -@code{texinfo-multiple-files-update}}.@refill -@end iftex - -@item M-x texinfo-indent-menu-description -@findex 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 (@kbd{C-u} as prefix argument, if -interactive), the @code{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.@refill - -@item M-x texinfo-sequential-node-update -@findex 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 @code{g* @key{RET}} command lets -you look through the file sequentially, so sequentially ordered nodes -are not strictly necessary.) With an argument (prefix argument, if -interactive), the @code{texinfo-sequential-node-update} command -sequentially updates all the nodes in the region.@refill -@end table - -@node Info Formatting, Printing, Updating Nodes and Menus, Texinfo Mode -@comment node-name, next, previous, up -@section Formatting for Info -@cindex Formatting for Info -@cindex Running an Info formatter -@cindex Info formatting - -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.@refill - -You can use either the @code{texinfo-format-region} or the -@code{makeinfo-region} command to format a region:@refill - -@table @kbd -@findex texinfo-format-region -@item C-c C-e C-r -@itemx M-x texinfo-format-region -@itemx C-c C-m C-r -@itemx M-x makeinfo-region -Format the current region for Info.@refill -@end table - -You can use either the @code{texinfo-format-buffer} or the -@code{makeinfo-buffer} command to format a whole buffer:@refill - -@table @kbd -@findex texinfo-format-buffer -@item C-c C-e C-b -@itemx M-x texinfo-format-buffer -@itemx C-c C-m C-b -@itemx M-x makeinfo-buffer -Format the current buffer for Info.@refill -@end table - -@need 1000 -For example, after writing a Texinfo file, you can type the following: - -@example -C-u C-c C-u m -@exdent or -C-u M-x texinfo-master-menu -@end example - -@noindent -This updates all the nodes and menus. Then type the following to create -an Info file: - -@example -C-c C-m C-b -@exdent or -M-x makeinfo-buffer -@end example - -For the Info formatting commands to work, the file @emph{must} include -a line that has @code{@@setfilename} in its header.@refill - -Not all systems support the @code{makeinfo}-based formatting commands.@refill - -@xref{Create an Info File}, for details about Info formatting.@refill - -@node Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode -@comment node-name, next, previous, up -@section Formatting and Printing -@cindex Formatting for printing -@cindex Printing a region or buffer -@cindex Region formatting and printing -@cindex Buffer formatting and printing -@cindex Part of file formatting and printing - -Typesetting and printing a Texinfo file is a multi-step process in which -you first create a file for printing (called a @sc{dvi} file), and then -print the file. Optionally, you may also create indices. To do this, -you must run the @code{texindex} command after first running the -@code{tex} typesetting command; and then you must run the @code{tex} -command again. @refill - -Often, when you are writing a document, you want to typeset and print -only part of a file to see what it will look like. You can use the -@code{texinfo-tex-region} and related commands for this purpose. Use -the @code{texinfo-tex-buffer} command to format all of a -buffer.@refill - -@table @kbd -@item C-c C-t C-r -@itemx M-x texinfo-tex-region -@findex texinfo-tex-region -Run @TeX{} on the region.@refill - -@item C-c C-t C-b -@itemx M-x texinfo-tex-buffer -@findex texinfo-tex-buffer -Run @TeX{} on the buffer.@refill - -@item C-c C-t C-i -@itemx M-x texinfo-texindex -Run @code{texindex} to sort the indices of a Texinfo file formatted with -@code{texinfo-tex-region} or @code{texinfo-tex-buffer}. You must run -the @code{tex} command a second time after sorting the raw index -files.@refill - -@item C-c C-t C-p -@itemx M-x texinfo-tex-print -@findex texinfo-tex-print -Print the file (or the part of the file) previously formatted with -@code{texinfo-tex-buffer} or @code{texinfo-tex-region}.@refill -@end table - -For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the -file @emph{must} start with a @samp{\input texinfo} line and must -include an @code{@@settitle} line. The file must end with @code{@@bye} -on a line by itself. (When you use @code{texinfo-tex-region}, you must -surround the @code{@@settitle} line with start-of-header and -end-of-header lines.)@refill - -@xref{Format/Print Hardcopy}, for a description of the other @TeX{} related -commands, such as @code{tex-show-print-queue}.@refill - -@node Texinfo Mode Summary, , Printing, Texinfo Mode -@comment node-name, next, previous, up -@section 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 @kbd{C-c}. The keys are somewhat -mnemonic.@refill - -@subheading Insert Commands - -The insert commands are invoked by typing @kbd{C-c} twice and then the -first letter of the @@-command to be inserted. (It might make more -sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but -@kbd{C-c C-c} is quick to type.)@refill - -@example -C-c C-c c @r{Insert} @samp{@@code}. -C-c C-c d @r{Insert} @samp{@@dfn}. -C-c C-c e @r{Insert} @samp{@@end}. -C-c C-c i @r{Insert} @samp{@@item}. -C-c C-c n @r{Insert} @samp{@@node}. -C-c C-c s @r{Insert} @samp{@@samp}. -C-c C-c v @r{Insert} @samp{@@var}. -C-c C-c @{ @r{Insert braces.} -C-c C-c ] -C-c C-c @} @r{Move out of enclosing braces.} - -@group -C-c C-c C-d @r{Insert a node's section title} - @r{in the space for the description} - @r{in a menu entry line.} -@end group -@end example - -@subheading Show Structure - -The @code{texinfo-show-structure} command is often used within a -narrowed region.@refill - -@example -C-c C-s @r{List all the headings.} -@end example - -@subheading The Master Update Command - -The @code{texinfo-master-menu} command creates a master menu; and can -be used to update every node and menu in a file as well.@refill - -@example -@group -C-c C-u m -M-x texinfo-master-menu - @r{Create or update a master menu.} -@end group - -@group -C-u C-c C-u m @r{With @kbd{C-u} as a prefix argument, first} - @r{create or update all nodes and regular} - @r{menus, and then create a master menu.} -@end group -@end example - -@subheading Update Pointers - -@c !!! added verbiage to prevent overfull hbox --bob 26 Mar 93 -The update pointer commands are invoked by typing @kbd{C-c C-u} and -then either typing @kbd{C-n} for @code{texinfo-update-node} or typing -@kbd{C-e} for @code{texinfo-every-node-update}.@refill - -@example -C-c C-u C-n @r{Update a node.} -C-c C-u C-e @r{Update every node in the buffer.} -@end example - -@subheading Update Menus - -Invoke the update menu commands by typing @kbd{C-c C-u} -and then either @kbd{C-m} for @code{texinfo-make-menu} or -@kbd{C-a} for @code{texinfo-all-menus-update}. To update -both nodes and menus at the same time, precede @kbd{C-c C-u -C-a} with @kbd{C-u}.@refill - -@example -C-c C-u C-m @r{Make or update a menu.} - -@group -C-c C-u C-a @r{Make or update all} - @r{menus in a buffer.} -@end group - -@group -C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,} - @r{first create or update all nodes and} - @r{then create or update all menus.} -@end group -@end example - -@subheading Format for Info - -The Info formatting commands that are written in Emacs Lisp are -invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region -or @kbd{C-b} for the whole buffer.@refill - -The Info formatting commands that are written in C and based on the -@code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then -either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.@refill - -@need 800 -@noindent -Use the @code{texinfo-format@dots{}} commands: - -@example -@group -C-c C-e C-r @r{Format the region.} -C-c C-e C-b @r{Format the buffer.} -@end group -@end example - -@need 750 -@noindent -Use @code{makeinfo}: - -@example -C-c C-m C-r @r{Format the region.} -C-c C-m C-b @r{Format the buffer.} -C-c C-m C-l @r{Recenter the @code{makeinfo} output buffer.} -C-c C-m C-k @r{Kill the @code{makeinfo} formatting job.} -@end example - -@subheading Typeset and Print - -The @TeX{} typesetting and printing commands are invoked by typing -@kbd{C-c C-t} and then another control command: @kbd{C-r} for -@code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer}, -and so on.@refill - -@example -C-c C-t C-r @r{Run @TeX{} on the region.} -C-c C-t C-b @r{Run @TeX{} on the buffer.} -C-c C-t C-i @r{Run} @code{texindex}. -C-c C-t C-p @r{Print the @sc{dvi} file.} -C-c C-t C-q @r{Show the print queue.} -C-c C-t C-d @r{Delete a job from the print queue.} -C-c C-t C-k @r{Kill the current @TeX{} formatting job.} -C-c C-t C-x @r{Quit a currently stopped @TeX{} formatting job.} -C-c C-t C-l @r{Recenter the output buffer.} -@end example - -@subheading Other Updating Commands - -The `other updating commands' do not have standard keybindings because -they are rarely used. - -@example -@group -M-x texinfo-insert-node-lines - @r{Insert missing @code{@@node} lines in region.} - @r{With @kbd{C-u} as a prefix argument,} - @r{use section titles as node names.} -@end group - -@group -M-x texinfo-multiple-files-update - @r{Update a multi-file document.} - @r{With @kbd{C-u 2} as a prefix argument,} - @r{create or update all nodes and menus} - @r{in all included files first.} -@end group - -@group -M-x texinfo-indent-menu-description - @r{Indent descriptions.} -@end group - -@group -M-x texinfo-sequential-node-update - @r{Insert node pointers in strict sequence.} -@end group -@end example - -@node Beginning a File, Ending a File, Texinfo Mode, Top -@comment node-name, next, previous, up -@chapter Beginning a Texinfo File -@cindex Beginning a Texinfo file -@cindex Texinfo file beginning -@cindex File beginning - -Certain pieces of information must be provided at the beginning of a -Texinfo file, such as the name of the file and the title of the -document.@refill - -@menu -* Four Parts:: Four parts begin a Texinfo file. -* Sample Beginning:: Here is a sample beginning for a Texinfo file. -* Header:: The very beginning of a Texinfo file. -* Info Summary and Permissions:: Summary and copying permissions for Info. -* Titlepage & Copyright Page:: Creating the title and copyright pages. -* The Top Node:: Creating the `Top' node and master menu. -* Software Copying Permissions:: Ensure that you and others continue to - have the right to use and share software. -@end menu - -@node Four Parts, Sample Beginning, , Beginning a File -@ifinfo -@heading Four Parts Begin a File -@end ifinfo - -Generally, the beginning of a Texinfo file has four parts:@refill - -@enumerate -@item -The header, delimited by special comment lines, that includes the -commands for naming the Texinfo file and telling @TeX{} what -definitions' file to use when processing the Texinfo file.@refill - -@item -A short statement of what the file is about, with a copyright notice -and copying permissions. This is enclosed in @code{@@ifinfo} and -@code{@@end ifinfo} commands so that the formatters place it only -in the Info file.@refill - -@item -A title page and copyright page, with a copyright notice and copying -permissions. This is enclosed between @code{@@titlepage} and -@code{@@end titlepage} commands. The title and copyright page appear -only in the printed @w{manual}.@refill - -@item -The `Top' node that contains a menu for the whole Info file. The -contents of this node appear only in the Info file.@refill -@end enumerate - -Also, optionally, you may include the copying conditions for a program -and a warranty disclaimer. The copying section will be followed by an -introduction or else by the first chapter of the manual.@refill - -Since the copyright notice and copying permissions for the Texinfo -document (in contrast to the copying permissions for a program) are in -parts that appear only in the Info file or only in the printed manual, -this information must be given twice.@refill - -@node Sample Beginning, Header, Four Parts, Beginning a File -@comment node-name, next, previous, up -@section Sample Texinfo File Beginning - -The following sample shows what is needed.@refill - -@example -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename @var{name-of-info-file} -@@settitle @var{name-of-manual} -@@setchapternewpage odd -@@c %**end of header - -@@ifinfo -This file documents @dots{} - -Copyright @var{year} @var{copyright-owner} - -@group -Permission is granted to @dots{} -@@end ifinfo -@end group - -@group -@@c This title page illustrates only one of the -@@c two methods of forming a title page. -@end group - -@group -@@titlepage -@@title @var{name-of-manual-when-printed} -@@subtitle @var{subtitle-if-any} -@@subtitle @var{second-subtitle} -@@author @var{author} -@end group - -@group -@@c The following two commands -@@c start the copyright page. -@@page -@@vskip 0pt plus 1filll -Copyright @@copyright@{@} @var{year} @var{copyright-owner} -@end group - -Published by @dots{} - -Permission is granted to @dots{} -@@end titlepage - -@@node Top, Overview, (dir), (dir) - -@@ifinfo -This document describes @dots{} - -This document applies to version @dots{} -of the program named @dots{} -@@end ifinfo - -@group -@@menu -* Copying:: Your rights and freedoms. -* First Chapter:: Getting started @dots{} -* Second Chapter:: @dots{} - @dots{} - @dots{} -@@end menu -@end group - -@group -@@node First Chapter, Second Chapter, top, top -@@comment node-name, next, previous, up -@@chapter First Chapter -@@cindex Index entry for First Chapter -@end group -@end example - -@node Header, Info Summary and Permissions, Sample Beginning, Beginning a File -@comment node-name, next, previous, up -@section The Texinfo File Header -@cindex Header for Texinfo files -@cindex Texinfo file header - -Texinfo files start with at least three lines that provide Info and -@TeX{} with necessary information. These are the @code{\input -texinfo} line, the @code{@@settitle} line, and the -@code{@@setfilename} line. If you want to run @TeX{} on just a part -of the Texinfo File, you must write the @code{@@settitle} -and @code{@@setfilename} lines between start-of-header and end-of-header -lines.@refill - -Thus, the beginning of a Texinfo file looks like this: - -@example -@group -\input texinfo @@c -*-texinfo-*- -@@setfilename sample.info -@@settitle Sample Document -@end group -@end example - -@noindent -or else like this: - -@example -@group -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename sample.info -@@settitle Sample Document -@@c %**end of header -@end group -@end example - -@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. -* setchapternewpage:: Start chapters on right-hand pages. -* paragraphindent:: An option to specify paragraph indentation. -* End of Header:: Formatting a region requires this. -@end menu - -@node First Line, Start of Header, , Header -@comment node-name, next, previous, up -@subsection The First Line of a Texinfo File -@cindex First line of a Texinfo file -@cindex Beginning line of a Texinfo file -@cindex Header 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:@refill - -@example -\input texinfo @@c -*-texinfo-*- -@end example - -@noindent -This line serves two functions: - -@enumerate -@item -When the file is processed by @TeX{}, the @code{\input texinfo} command -tells @TeX{} to load the macros needed for processing a Texinfo file. -These are in a file called @file{texinfo.tex}, which is usually located -in the @file{/usr/lib/tex/macros} directory. @TeX{} uses the backslash, -@samp{\}, to mark the beginning of a command, just as Texinfo uses -@code{@@}. The @file{texinfo.tex} file causes the switch from @samp{\} -to @samp{@@}; before the switch occurs, @TeX{} requires @samp{\}, which -is why it appears at the beginning of the file.@refill - -@item -When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode -specification tells Emacs to use Texinfo mode.@refill -@end enumerate - -@node Start of Header, setfilename, First Line, Header -@comment node-name, next, previous, up -@subsection Start of Header -@cindex Start of header line - -Write a start-of-header line on the second line of a Texinfo file. -Follow the start-of-header line with @code{@@setfilename} and -@code{@@settitle} lines and, optionally, with other command lines, such -as @code{@@smallbook} or @code{@@footnotestyle}; and then by an -end-of-header line (@pxref{End of Header}).@refill - -With these lines, you can format part of a Texinfo file for Info or -typeset part for printing.@refill - -A start-of-header line looks like this:@refill - -@example -@@c %**start of header -@end example - -The odd string of characters, @samp{%**}, is to ensure that no other -comment is accidentally taken for a start-of-header line.@refill - -@node setfilename, settitle, Start of Header, Header -@comment node-name, next, previous, up -@subsection @code{@@setfilename} -@cindex Info file requires @code{@@setfilename} -@findex setfilename - -In order to be made into an Info file, a Texinfo file must contain a line -that looks like this:@refill - -@example -@@setfilename @var{info-file-name} -@end example - -Write the @code{@@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 a comment.@refill - -The @code{@@setfilename} line specifies the name of the Info file to be -generated. This name should be different from the name of the Texinfo -file. The convention is to write a name with a @samp{.info} extension, -to produce an Info file name such as @file{texinfo.info}.@refill - -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', @dots{}, -`-10', `-11', and so on, to the original file name. (@xref{Tag and -Split Files, , Tag Files and Split Files}.) The subfile name -@file{texinfo.info-10}, for example, is too long for some systems; so -the Info file name for this document is actually @file{texinfo} rather than -@file{texinfo.info}.@refill - -The Info formatting commands ignore everything written before the -@code{@@setfilename} line, which is why the very first line of -the file (the @code{\input} line) does not need to be commented out. -The @code{@@setfilename} line is ignored when you typeset a printed -manual.@refill - -@node settitle, setchapternewpage, setfilename, Header -@comment node-name, next, previous, up -@subsection @code{@@settitle} -@findex settitle - -In order to be made into a printed manual, a Texinfo file must contain -a line that looks like this:@refill - -@example -@@settitle @var{title} -@end example - -Write the @code{@@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 a comment.@refill - -Conventionally, @TeX{} formats a Texinfo file for double-sided output -so as to print the title in the left-hand (even-numbered) page -headings and the current chapter titles in the right-hand -(odd-numbered) page headings. (@TeX{} learns the title of each -chapter from each @code{@@chapter} command.) Page footers are not -printed.@refill - -Even if you are printing in a single-sided style, @TeX{} looks for an -@code{@@settitle} command line, in case you include the manual title -in the heading. @refill - -The @code{@@settitle} command should precede everything that generates -actual output in @TeX{}.@refill - -Although the title in the @code{@@settitle} command is usually the -same as the title on the title page, it does not affect the title as -it appears on the title page. Thus, the two do not need not match -exactly; and the title in the @code{@@settitle} command can be a -shortened or expanded version of the title as it appears on the title -page. (@xref{titlepage, , @code{@@titlepage}}.)@refill - -@TeX{} prints page headings only for that text that comes after the -@code{@@end titlepage} command in the Texinfo file, or that comes -after an @code{@@headings} command that turns on headings. -(@xref{headings on off, , The @code{@@headings} Command}, for more -information.)@refill - -You may, if you wish, create your own, customized headings and -footings. @xref{Headings, , Page Headings}, for a detailed discussion -of this process.@refill - -@node setchapternewpage, paragraphindent, settitle, Header -@comment node-name, next, previous, up -@subsection @code{@@setchapternewpage} -@cindex Starting chapters -@cindex Pages, starting odd -@findex setchapternewpage - -In a book or a manual, 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.@refill - -You can use the @code{@@setchapternewpage} command with various -arguments to specify how @TeX{} should start chapters and whether it -should typeset pages for printing on one or both sides of the paper -(single-sided or double-sided printing).@refill - -Write the @code{@@setchapternewpage} command at the beginning of a -line followed by its argument.@refill - -For example, you would write the following to cause each chapter to -start on a fresh odd-numbered page:@refill - -@example -@@setchapternewpage odd -@end example - -You can specify one of three alternatives with the -@code{@@setchapternewpage} command:@refill - -@table @asis -@ignore -@item No @code{@@setchapternewpage} command -If the Texinfo file does not contain an @code{@@setchapternewpage} -command before the @code{@@titlepage} command, @TeX{} automatically -begins chapters on new pages and prints headings in the standard -format for single-sided printing. This is the conventional format for -single-sided printing.@refill - -The result is exactly the same as when you write -@code{@@setchapternewpage on}.@refill -@end ignore -@item @code{@@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. (You can override the -headers format with the @code{@@headings double} command; see -@ref{headings on off, , The @code{@@headings} Command}.)@refill - -@item @code{@@setchapternewpage on} -Cause @TeX{} to start new chapters on new pages and to typeset page -headers for single-sided printing. This is the form most often -used for short reports.@refill - -This alternative is the default.@refill - -@item @code{@@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.@refill -@end table - -@noindent -Texinfo does not have an @code{@@setchapternewpage even} command.@refill - -@noindent -(You can countermand or modify an @code{@@setchapternewpage} command -with an @code{@@headings} command. @xref{headings on off, , The -@code{@@headings} Command}.)@refill - -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 pages are numbered with roman -numerals and not in sequence with the rest of the document.@refill - -Since an Info file does not have pages, the @code{@@setchapternewpage} -command has no effect on it.@refill - -Usually, you do not write an @code{@@setchapternewpage} command for -single-sided printing, but accept the default which is to typeset for -single-sided printing and to start new chapters on new pages. Usually, -you write an @code{@@setchapternewpage odd} command for double-sided -printing.@refill - -@node paragraphindent, End of Header, setchapternewpage, Header -@comment node-name, next, previous, up -@subsection Paragraph Indenting -@cindex Indenting paragraphs -@cindex Paragraph indentation -@findex paragraphindent - -The Info formatting commands may insert spaces at the beginning of the -first line of each paragraph, thereby indenting that paragraph. You -can use the @code{@@paragraphindent} command to specify the -indentation. Write an @code{@@paragraphindent} command at the -beginning of a line followed by either @samp{asis} or a number. The -template is:@refill - -@example -@@paragraphindent @var{indent} -@end example - -The Info formatting commands indent according to the value of -@var{indent}:@refill - -@itemize @bullet -@item -If the value of @var{indent} is @samp{asis}, the Info formatting -commands do not change the existing indentation.@refill - -@item -If the value of @var{indent} is 0, the Info formatting commands delete -existing indentation.@refill - -@item -If the value of @var{indent} is greater than 0, the Info formatting -commands indent the paragraph by that number of spaces.@refill -@end itemize - -The default value of @var{indent} is @samp{asis}.@refill - -Write the @code{@@paragraphindent} command before or shortly after the -end-of-header line at the beginning of a Texinfo file. (If you write -the command between the start-of-header and end-of-header lines, the -region formatting commands indent paragraphs as specified.)@refill - -@c !!! added verbiage to prevent overfull hbox --bob 26 Mar 93 -A peculiarity of @code{texinfo-format-buffer} and -@code{texinfo-format-region} is that they do not indent (nor -fill) paragraphs that contain @code{@@w} or @code{@@*} commands. -@xref{Refilling Paragraphs}, for a detailed description of what goes -on.@refill - -@node End of Header, , paragraphindent, Header -@comment node-name, next, previous, up -@subsection End of Header -@cindex End of header line - -Follow the header lines with an @w{end-of-header} line. -An end-of-header line looks like this:@refill - -@example -@@c %**end of header -@end example - -If you include the @code{@@setchapternewpage} command between the -start-of-header and end-of-header lines, @TeX{} will typeset a region as -that command specifies. Similarly, if you include an @code{@@smallbook} -command between the start-of-header and end-of-header lines, @TeX{} will -typeset a region in the ``small'' book format.@refill - -@ifinfo -The reason for the odd string of characters (@samp{%**}) is so that the -@code{texinfo-tex-region} command does not accidentally find -something that it should not when it is looking for the header.@refill - -The start-of-header line and the end-of-header line are Texinfo mode -variables that you can change.@refill -@end ifinfo - -@iftex -@xref{Start of Header}. -@end iftex - -@node Info Summary and Permissions, Titlepage & Copyright Page, Header, Beginning a File -@comment node-name, next, previous, up -@section Summary and Copying Permissions for Info - -The title page and the copyright page appear only in the printed copy of -the manual; therefore, the same information must be inserted in a -section that appears only in the Info file. This section usually -contains a brief description of the contents of the Info file, a -copyright notice, and copying permissions.@refill - -The copyright notice should read:@refill - -@example -Copyright @var{year} @var{copyright-owner} -@end example - -@noindent -and be put on a line by itself.@refill - -Standard text for the copyright permissions is contained in an appendix -to this manual; see @ref{ifinfo Permissions, , @samp{ifinfo} Copying -Permissions}, for the complete text.@refill - -The permissions text appears in an Info file @emph{before} the first -node. This mean that a reader does @emph{not} see this text when -reading the file using Info, except when using the advanced Info command -@kbd{g *}. - -@node Titlepage & Copyright Page, The Top Node, Info Summary and Permissions, Beginning a File -@comment node-name, next, previous, up -@section The Title and Copyright Pages - -A manual's name and author are usually printed on a title page. -Sometimes copyright information is printed on the title page as well; -more often, copyright information is 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 will appear in the printed manual.@refill - -@xref{Titlepage Permissions, , Titlepage Copying Permissions}, for the -standard text for the copyright permissions.@refill - -@menu -* titlepage:: Create a title for the printed document. -* titlefont center sp:: The @code{@@titlefont}, @code{@@center}, - and @code{@@sp} commands. -* title subtitle author:: The @code{@@title}, @code{@@subtitle}, - and @code{@@author} commands. -* Copyright & Permissions:: 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. -@end menu - -@node titlepage, titlefont center sp, , Titlepage & Copyright Page -@comment node-name, next, previous, up -@subsection @code{@@titlepage} -@cindex Title page -@findex titlepage - -Start the material for the title page and following copyright page -with @code{@@titlepage} on a line by itself and end it with -@code{@@end titlepage} on a line by itself.@refill - -The @code{@@end titlepage} command starts a new page and turns on page -numbering. (@xref{Headings, , Page Headings}, for details about how to -generate of page headings.) All the material that you want to -appear on unnumbered pages should be put between the -@code{@@titlepage} and @code{@@end titlepage} commands. By using the -@code{@@page} command you can force a page break within the region -delineated by the @code{@@titlepage} and @code{@@end titlepage} -commands and thereby create more than one unnumbered page. This is -how the copyright page is produced. (The @code{@@titlepage} command -might perhaps have been better named the -@code{@@titleandadditionalpages} command, but that would have been -rather long!)@refill - -@c !!! append refill to footnote when makeinfo can handle it. -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@footnote{We have found that it is helpful to refer to versions -of 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.} 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 @ref{makeinfo top, , -@code{@@top}}.)@refill - -Texinfo provides two methods for creating a title page. One method -uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands -to generate a title page in which the words on the page are -centered.@refill - -The second method uses the @code{@@title}, @code{@@subtitle}, and -@code{@@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.@refill - -@node titlefont center sp, title subtitle author, titlepage, Titlepage & Copyright Page -@comment node-name, next, previous, up -@subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp} -@findex titlefont -@findex center -@findex sp @r{(titlepage line spacing)} - -You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@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.)@refill - -Use the @code{@@titlefont} command to select a large font suitable for -the title itself.@refill - -@need 700 -For example: - -@example -@@titlefont@{Texinfo@} -@end example - -Use the @code{@@center} command at the beginning of a line to center -the remaining text on that line. Thus,@refill - -@example -@@center @@titlefont@{Texinfo@} -@end example - -@noindent -centers the title, which in this example is ``Texinfo'' printed -in the title font.@refill - -Use the @code{@@sp} command to insert vertical space. For example:@refill - -@example -@@sp 2 -@end example - -@noindent -This inserts two blank lines on the printed page. (@xref{sp, , -@code{@@sp}}, for more information about the @code{@@sp} -command.)@refill - -A template for this method looks like this:@refill - -@example -@group -@@titlepage -@@sp 10 -@@center @@titlefont@{@var{name-of-manual-when-printed}@} -@@sp 2 -@@center @var{subtitle-if-any} -@@sp 2 -@@center @var{author} -@dots{} -@@end titlepage -@end group -@end example - -The spacing of the example fits an 8 1/2 by 11 inch manual.@refill - -@node title subtitle author, Copyright & Permissions, titlefont center sp, Titlepage & Copyright Page -@comment node-name, next, previous, up -@subsection @code{@@title}, @code{@@subtitle}, and @code{@@author} -@findex title -@findex subtitle -@findex author - -You can use the @code{@@title}, @code{@@subtitle}, and @code{@@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 @code{@@sp} command is needed to -adjust vertical spacing.@refill - -Write the @code{@@title}, @code{@@subtitle}, or @code{@@author} -commands at the beginning of a line followed by the title, subtitle, -or author.@refill - -The @code{@@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.@refill - -The @code{@@subtitle} command sets subtitles in a normal-sized font -flush to the right-hand side of the page.@refill - -The @code{@@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 @code{@@author} command line is -followed by an @code{@@page} command line.)@refill - -There are two ways to use the @code{@@author} command: you can write -the name or names on the remaining part of the line that starts with -an @code{@@author} command:@refill - -@example -@@author by Jane Smith and John Doe -@end example - -@noindent -or you can write the names one above each other by using two (or more) -@code{@@author} commands:@refill - -@example -@group -@@author Jane Smith -@@author John Doe -@end group -@end example - -@noindent -(Only the bottom name is underlined with a black rule.)@refill - -@need 950 -A template for this method looks like this:@refill - -@example -@group -@@titlepage -@@title @var{name-of-manual-when-printed} -@@subtitle @var{subtitle-if-any} -@@subtitle @var{second-subtitle} -@@author @var{author} -@@page -@dots{} -@@end titlepage -@end group -@end example - -@ifinfo -@noindent -Contrast this form with the form of a title page written using the -@code{@@sp}, @code{@@center}, and @code{@@titlefont} commands:@refill - -@example -@@titlepage -@@sp 10 -@@center @@titlefont@{Name of Manual When Printed@} -@@sp 2 -@@center Subtitle, If Any -@@sp 1 -@@center Second subtitle -@@sp 2 -@@center Author -@@page -@dots{} -@@end titlepage -@end example -@end ifinfo - -@node Copyright & Permissions, end titlepage, title subtitle author, Titlepage & Copyright Page -@comment node-name, next, previous, up -@subsection Copyright Page and Permissions -@cindex Copyright page -@cindex Printed permissions -@cindex Permissions, printed - -By international treaty, the copyright notice for a book should be -either on the title page or on the back of the title page. The -copyright notice should include the year followed by the name of the -organization or person who owns the copyright.@refill - -When the copyright notice is on the back of the title page, that page -is customarily not numbered. Therefore, in Texinfo, the information -on the copyright page should be within @code{@@titlepage} and -@code{@@end titlepage} commands.@refill - -@findex vskip -@findex filll -@cindex Vertical whitespace (@samp{vskip}) -Use the @code{@@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, you can write a somewhat mysterious line after the -@code{@@page} command that reads like this:@refill - -@example -@@vskip 0pt plus 1filll -@end example - -@noindent -This is a @TeX{} command that is not supported by the Info formatting -commands. The @code{@@vskip} command inserts whitespace. The -@samp{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 -@samp{l}s in the word @samp{filll}; this is the correct usage in -@TeX{}.@refill - -@findex copyright -In a printed manual, the @code{@@copyright@{@}} command generates a -@samp{c} inside a circle. (In Info, it generates @samp{(C)}.) The -copyright notice itself has the following legally defined sequence:@refill - -@example -Copyright @copyright{} @var{year} @var{copyright-owner} -@end example - -It is customary to put information on how to get a manual after the -copyright notice, followed by the copying permissions for the -manual.@refill - -Note that permissions must be given here as well as in the summary -segment within @code{@@ifinfo} and @code{@@end ifinfo} that -immediately follows the header since this text appears only in the -printed manual and the @samp{ifinfo} text appears only in the Info -file.@refill - -@xref{Sample Permissions}, for the standard text.@refill - -@node end titlepage, headings on off, Copyright & Permissions, Titlepage & Copyright Page -@comment node-name, next, previous, up -@subsection Heading Generation -@findex end titlepage -@cindex Headings, page, begin to appear -@cindex Titlepage end starts headings -@cindex End titlepage starts headings - -An @code{@@end titlepage} command on a line by itself 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). -(@xref{setchapternewpage, ,@code{@@setchapternewpage}}.) -You can specify these formats in different ways:@refill - -@itemize @bullet -@item -The conventional way is to write an @code{@@setchapternewpage} command -before the title page commands, and then have the @code{@@end -titlepage} command start generating page headings in the manner desired. -(@xref{setchapternewpage, , @code{@@setchapternewpage}}.)@refill - -@item -Alternatively, you can use the @code{@@headings} command to prevent page -headings from being generated or to start them for either single or -double-sided printing. (Write an @code{@@headings} command immediately -after the @code{@@end titlepage} command. @xref{headings on off, , The -@code{@@headings} Command}, for more information.)@refill - -@item -Or, you may specify your own page heading and footing format. -@xref{Headings, , Page Headings}, for detailed -information about page headings and footings.@refill -@end itemize - -Most documents are formatted with the standard single-sided or -double-sided format, using @code{@@setchapternewpage odd} for -double-sided printing and no @code{@@setchapternewpage} command for -single-sided printing.@refill - -@node headings on off, , end titlepage, Titlepage & Copyright Page -@comment node-name, next, previous, up -@subsection The @code{@@headings} Command -@findex headings - -The @code{@@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 @code{@@setchapternewpage} command. You need the -@code{@@headings} command only if the @code{@@setchapternewpage} command -does not do what you want, or if you want to turn off pre-defined page -headings prior to defining your own. Write an @code{@@headings} command -immediately after the @code{@@end titlepage} command.@refill - -There are four ways to use the @code{@@headings} command:@refill - -@table @code -@item @@headings off -Turn off printing of page headings.@refill - -@item @@headings single -Turn on page headings appropriate for single-sided printing. -@refill - -@item @@headings double -@itemx @@headings on -Turn on page headings appropriate for double-sided printing. The two -commands, @code{@@headings on} and @code{@@headings double}, are -synonymous.@refill -@end table - -For example, suppose you write @code{@@setchapternewpage off} before the -@code{@@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 @code{@@headings -double} after the @code{@@end titlepage} command. - -You can stop @TeX{} from generating any page headings at all by -writing @code{@@headings off} on a line of its own immediately after the -line containing the @code{@@end titlepage} command, like this:@refill - -@example -@@end titlepage -@@headings off -@end example - -@noindent -The @code{@@headings off} command overrides the @code{@@end titlepage} -command, which would otherwise cause @TeX{} to print page -headings.@refill - -You can also specify your own style of page heading and footing. -@xref{Headings, , Page Headings}, for more information.@refill - -@node The Top Node, Software Copying Permissions, Titlepage & Copyright Page, Beginning a File -@comment node-name, next, previous, up -@section The `Top' Node and Master Menu -@cindex @samp{@r{Top}} node -@cindex Master menu -@cindex Node, `Top' - -The `Top' node is the node from which you enter an Info file.@refill - -A `Top' node should contain a brief description of the Info file and an -extensive, master menu for the whole Info file. -This helps the reader understand what the Info file is -about. Also, you should write the version number of the program to -which the Info file applies; or, at least, the edition number.@refill - -The contents of the `Top' node should appear only in the Info file; none -of it should appear in printed output, so enclose it between -@code{@@ifinfo} and @code{@@end ifinfo} commands. (@TeX{} does not -print either an @code{@@node} line or a menu; they appear only in Info; -strictly speaking, you are not required to enclose these parts between -@code{@@ifinfo} and @code{@@end ifinfo}, but it is simplest to do so. -@xref{Conditionals, , Conditionally Visible Text}.)@refill - -@menu -* Title of Top Node:: Sketch what the file is about. -* Master Menu Parts:: A master menu has three or more parts. -@end menu - -@node Title of Top Node, Master Menu Parts, , The Top Node -@ifinfo -@subheading `Top' Node Title -@end ifinfo - -Sometimes, you will want to place an @code{@@top} sectioning command -line containing the title of the document immediately after the -@code{@@node Top} line (@pxref{makeinfo top command, , The @code{@@top} -Sectioning Command}, for more information).@refill - -For example, the beginning of the Top node of this manual contains an -@code{@@top} sectioning command, a short description, and edition and -version information. It looks like this:@refill - -@example -@group -@dots{} -@@end titlepage - -@@ifinfo -@@node Top, Copying, (dir), (dir) -@@top Texinfo - -Texinfo is a documentation system@dots{} -@end group - -@group -This is edition@dots{} -@dots{} -@@end ifinfo -@end group - -@group -@@menu -* Copying:: Texinfo is freely - redistributable. -* Overview:: What is Texinfo? -@dots{} -@end group -@@end menu -@end example - -In a `Top' node, the `Previous', and `Up' nodes usually refer to the top -level directory of the whole Info system, which is called @samp{(dir)}. -The `Next' node refers to the first node that follows the main or master -menu, which is usually the copying permissions, introduction, or first -chapter.@refill - -@node Master Menu Parts, , Title of Top Node, The Top Node -@subsection Parts of a Master Menu -@cindex Master menu parts -@cindex Parts of a master menu - -A @dfn{master menu} is a detailed main menu listing all the nodes in a -file. - -A master menu is enclosed in @code{@@menu} and @code{@@end menu} -commands and does not appear in the printed document.@refill - -Generally, a master menu is divided into parts.@refill - -@itemize @bullet -@item -The first part contains the major nodes in the Texinfo file: the nodes -for the chapters, chapter-like sections, and the appendices.@refill - -@item -The second part contains nodes for the indices.@refill - -@item -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.@refill -@end itemize - -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. (@xref{Writing a Menu}, for more -information.)@refill - -For example, the master menu for this manual looks like the following -(but has many more entries):@refill - -@example -@group -@@menu -* Copying:: Texinfo is freely - redistributable. -* Overview:: What is Texinfo? -* Texinfo Mode:: Special features in GNU Emacs. -@dots{} -@dots{} -@end group -@group -* Command and Variable Index:: - An entry for each @@-command. -* Concept Index:: An entry for each concept. -@end group - -@group - --- The Detailed Node Listing --- - -Overview of Texinfo - -* Info Files:: What is an Info file? -* Printed Manuals:: Characteristics of - a printed manual. -@dots{} -@dots{} -@end group - -@group -Using Texinfo Mode - -* Info on a Region:: Formatting part of a file - for Info. -@dots{} -@dots{} -@@end menu -@end group -@end example - -@node Software Copying Permissions, , The Top Node, Beginning a File -@comment node-name, next, previous, up -@section Software Copying Permissions -@cindex Software copying permissions -@cindex Copying software -@cindex Distribution -@cindex License agreement - -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, this section usually follows 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.@refill - -The copying and distribution information and the disclaimer are -followed by an introduction or else by the first chapter of the -manual.@refill - -@cindex Introduction, as part of file -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. -Usually, an introduction is put in an @code{@@unnumbered} section. -(@xref{unnumbered & appendix, , The @code{@@unnumbered} and -@code{@@appendix} Commands}.)@refill - -@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 -@findex bye - -The end of a Texinfo file should include the commands that create -indices and generate detailed and summary tables of contents. -And it must include the @code{@@bye} command that marks the last line -processed by @TeX{}.@refill - -@need 700 -For example: - -@example -@@node Concept Index, , Variables Index, Top -@@c node-name, next, previous, up -@@unnumbered Concept Index - -@@printindex cp - -@@contents -@@bye -@end example - -@menu -* Printing Indices & Menus:: How to print an index in hardcopy and - generate index menus in Info. -* Contents:: How to create a table of contents. -* File End:: How to mark the end of a file. -@end menu - -@node Printing Indices & Menus, Contents, , Ending a File -@comment node-name, next, previous, up -@section Index Menus and Printing an Index -@findex printindex -@cindex Printing an index -@cindex Indices, printing and menus -@cindex Generating menus with indices -@cindex Menus generated with indices - -To print an index means to include it as part of a manual or Info -file. This does not happen automatically just because you use -@code{@@cindex} or other index-entry generating commands in the -Texinfo file; those just cause the raw data for the index to be -accumulated. To generate an index, you must include the -@code{@@printindex} command at the place in the document where you -want the index to appear. Also, as part of the process of creating a -printed manual, you must run a program called @code{texindex} -(@pxref{Format/Print 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.@refill - -Texinfo offers six different types of predefined index: the concept -index, the function index, the variables index, the keystroke index, the -program index, and the data type index (@pxref{Predefined Indices}). Each -index type has a two-letter name: @samp{cp}, @samp{fn}, @samp{vr}, -@samp{ky}, @samp{pg}, and @samp{tp}. You may merge indices, or put them -into separate sections (@pxref{Combining Indices}); or you may define -your own indices (@pxref{New Indices, , Defining New Indices}).@refill - -The @code{@@printindex} command takes a two-letter index name, reads -the corresponding sorted index file and formats it appropriately into -an index.@refill - -@ignore -The two-letter index names are: - -@table @samp -@item cp -concept index -@item fn -function index -@item vr -variable index -@item ky -key index -@item pg -program index -@item tp -data type index -@end table -@end ignore -The @code{@@printindex} command does not generate a chapter heading -for the index. Consequently, you should precede the -@code{@@printindex} command with a suitable section or chapter command -(usually @code{@@unnumbered}) to supply the chapter heading and put -the index into the table of contents. Precede the @code{@@unnumbered} -command with an @code{@@node} line.@refill - -@need 1200 -For example: - -@smallexample -@group -@@node Variable Index, Concept Index, Function Index, Top -@@comment node-name, next, previous, up -@@unnumbered Variable Index - -@@printindex vr -@end group - -@group -@@node Concept Index, , Variable Index, Top -@@comment node-name, next, previous, up -@@unnumbered Concept Index - -@@printindex cp -@end group - -@group -@@summarycontents -@@contents -@@bye -@end group -@end smallexample - -@noindent -(Readers often prefer that the concept index come last in a book, -since that makes it easiest to find.)@refill - -@ignore -In @TeX{}, the @code{@@printindex} command needs a sorted index file -to work from. @TeX{} does not know how to do sorting; this is a -deficiency. @TeX{} writes output files of raw index data; use the -@code{texindex} program to convert these files to sorted index files. -(@xref{Format/Print Hardcopy}, for more information.)@refill -@end ignore -@node Contents, File End, Printing Indices & Menus, Ending a File -@comment node-name, next, previous, up -@section Generating a Table of Contents -@cindex Table of contents -@cindex Contents, Table of -@findex contents -@findex summarycontents -@findex shortcontents - -The @code{@@chapter}, @code{@@section}, and other structuring commands -supply the information to make up a table of contents, but they do not -cause an actual table to appear in the manual. To do this, you must -use the @code{@@contents} and @code{@@summarycontents} -commands:@refill - -@table @code -@item @@contents -Generate a table of contents in a printed manual, including all -chapters, sections, subsections, etc., as well as appendices and -unnumbered chapters. (Headings generated by the @code{@@heading} -series of commands do not appear in the table of contents.) The -@code{@@contents} command should be written on a line by -itself.@refill - -@item @@shortcontents -@itemx @@summarycontents -(@code{@@summarycontents} is a synonym for @code{@@shortcontents}; the -two commands are exactly the same.)@refill - -Generate a short or summary table of contents that lists only the -chapters (and appendices and unnumbered chapters). Omit sections, subsections -and subsubsections. Only a long manual needs a short table -of contents in addition to the full table of contents.@refill - -Write the @code{@@shortcontents} command on a line by itself right -@emph{before} the @code{@@contents} command.@refill -@end table - -The table of contents commands automatically generate a chapter-like -heading at the top of the first table of contents page. Write the table -of contents commands at the very end of a Texinfo file, just before the -@code{@@bye} command, following any index sections---anything in the -Texinfo file after the table of contents commands will be omitted from -the table of contents.@refill - -When you print a manual with a table of contents, the table of -contents are printed last and numbered with roman numerals. You need -to place those pages in their proper place, after the title page, -yourself. (This is the only collating you need to do for a printed -manual. The table of contents is printed last because it is generated -after the rest of the manual is typeset.)@refill - -@need 700 -Here is an example of where to write table of contents commands:@refill - -@example -@group -@var{indices}@dots{} -@@shortcontents -@@contents -@@bye -@end group -@end example - -Since an Info file uses menus instead of tables of contents, the Info -formatting commands ignore the @code{@@contents} and -@code{@@shortcontents} commands.@refill - -@node File End, , Contents, Ending a File -@comment node-name, next, previous, up -@section @code{@@bye} File Ending -@findex bye - -An @code{@@bye} command terminates @TeX{} or Info formatting. None of -the formatting commands see any of the file following @code{@@bye}. -The @code{@@bye} command should be on a line by itself.@refill - -If you wish, you may follow the @code{@@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 @code{@@bye} were within @code{@@ignore} -@dots{} @code{@@end ignore}. Also, you may follow the @code{@@bye} line -with a local variables list. @xref{Compile-Command, , Using Local -Variables and the Compile Command}, for more information.@refill - -@node Structuring, Nodes, Ending a File, Top -@comment node-name, next, previous, up -@chapter Chapter Structuring -@cindex Chapter structuring -@cindex Structuring of chapters - -The @dfn{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 (@pxref{Contents, , Generating a Table -of Contents}).@refill - -The chapter structuring commands do not create an Info node structure, -so normally you should put an @code{@@node} command immediately before -each chapter structuring command (@pxref{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.@refill - -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.@refill - -@menu -* Tree Structuring:: A manual is like an upside down tree @dots{} -* Structuring Command Types:: How to divide a manual into parts. -* makeinfo top:: The @code{@@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. -@end menu - -@node Tree Structuring, Structuring Command Types, , Structuring -@comment node-name, next, previous, up -@section Tree Structure of Sections -@cindex Tree structuring - -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.@refill - -Here is a diagram that shows a Texinfo file with three chapters, -each of which has two sections.@refill - -@example -@group - 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 - -@end group -@end example - -In a Texinfo file that has this structure, the beginning of Chapter 2 -looks like this:@refill - -@example -@group -@@node Chapter 2, Chapter 3, Chapter 1, top -@@chapter Chapter 2 -@end group -@end example - -The chapter structuring commands are described in the sections that -follow; the @code{@@node} and @code{@@menu} commands are described in -following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill - -@node Structuring Command Types, makeinfo top, Tree Structuring, Structuring -@comment node-name, next, previous, up -@section Types of Structuring Command - -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.@refill - -The four groups are the @code{@@chapter} series, the -@code{@@unnumbered} series, the @code{@@appendix} series, and the -@code{@@heading} series.@refill - -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.@refill - -@itemize @bullet -@item -The @code{@@chapter} and @code{@@appendix} series of commands produce -numbered or lettered entries both in the body of a printed work and in -its table of contents.@refill - -@item -The @code{@@unnumbered} series of commands produce unnumbered entries -both in the body of a printed work and in its table of contents. The -@code{@@top} command, which has a special use, is a member of this -series (@pxref{makeinfo top, , @code{@@top}}).@refill - -@item -The @code{@@heading} series of commands produce unnumbered headings -that do not appear in a table of contents. The heading commands never -start a new page.@refill - -@item -The @code{@@majorheading} command produces results similar to using -the @code{@@chapheading} command but generates a larger vertical -whitespace before the heading.@refill - -@item -When an @code{@@setchapternewpage} command says to do so, the -@code{@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands -start new pages in the printed manual; the @code{@@heading} commands -do not.@refill -@end itemize - -@need 1000 -Here are the four groups of chapter structuring commands:@refill - -@c Slightly different formatting for regular sized books and smallbooks. -@ifset smallbook -@sp 1 -@tex -{\let\rm=\indrm \let\tt=\indtt -\halign{\hskip\itemindent#\hfil& \hskip.5em#\hfil& \hskip.5em#\hfil& -\hskip.5em#\hfil\cr - -& & & \rm No new pages\cr -\rm Numbered& \rm Unnumbered& \rm Lettered and numbered& \rm Unnumbered\cr -\rm In contents& \rm In contents& \rm In contents& \rm Not in contents\cr - -& & & \cr - & \tt @@top& & \tt @@majorheading\cr -\tt @@chapter& \tt @@unnumbered& \tt @@appendix& \tt @@chapheading\cr -\tt @@section& \tt @@unnumberedsec& \tt @@appendixsec& \tt @@heading\cr -\tt @@subsection&\tt @@unnumberedsubsec&\tt @@appendixsubsec& -\tt @@subheading\cr -\tt @@subsubsection& \tt @@unnumberedsubsubsec& \tt @@appendixsubsubsec& -\tt @@subsubheading\cr}} -@end tex -@end ifset -@ifclear smallbook -@sp 1 -@tex -\vbox{ -\halign{\hskip\itemindent\hskip.5em#\hfil& \hskip.5em#\hfil& -\hskip.5em#\hfil& \hskip.5em #\hfil\cr - -& & & \cr -& & & \rm No new pages\cr -\rm Numbered& \rm Unnumbered& \rm Lettered and numbered& \rm Unnumbered\cr -\rm In contents& \rm In contents& \rm In contents& \rm Not in contents\cr - -& & & \cr - & \tt @@top& & \tt @@majorheading\cr -\tt @@chapter& \tt @@unnumbered& \tt @@appendix& \tt @@chapheading\cr -\tt @@section& \tt @@unnumberedsec& \tt @@appendixsec& \tt @@heading\cr -\tt @@subsection&\tt @@unnumberedsubsec&\tt @@appendixsubsec& -\tt @@subheading\cr -\tt @@subsubsection& \tt @@unnumberedsubsubsec& \tt @@appendixsubsubsec& -\tt @@subsubheading\cr}} -@end tex -@end ifclear -@ifinfo -@example -@group - @r{No new pages} -@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered} -@r{In contents} @r{In contents} @r{In contents} @r{Not in contents} - - @@top @@majorheading -@@chapter @@unnumbered @@appendix @@chapheading -@@section @@unnumberedsec @@appendixsec @@heading -@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading -@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading -@end group -@end example -@end ifinfo - -@c Cannot line up columns properly inside of an example because of roman -@c proportional fonts. -@ignore -@ifset smallbook -@iftex -@smallexample -@group - @r{No new pages} -@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered} -@r{In contents} @r{In contents} @r{In contents} @r{Not in contents} - - @@top @@majorheading -@@chapter @@unnumbered @@appendix @@chapheading -@@section @@unnumberedsec @@appendixsec @@heading -@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading -@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading -@end group -@end smallexample -@end iftex -@end ifset -@ifclear smallbook -@iftex -@smallexample -@group - @r{No new pages} -@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered} -@r{In contents} @r{In contents} @r{In contents} @r{Not in contents} - - @@top @@majorheading -@@chapter @@unnumbered @@appendix @@chapheading -@@section @@unnumberedsec @@appendixsec @@heading -@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading -@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading -@end group -@end smallexample -@end iftex -@end ignore - -@node makeinfo top, chapter, Structuring Command Types, Structuring -@comment node-name, next, previous, up -@section @code{@@top} - -The @code{@@top} command is a special sectioning command that you use -only after an @code{@@node Top} line at the beginning of a Texinfo file. -The @code{@@top} command tells the @code{makeinfo} formatter -which node is the `Top' -node. It has the same typesetting effect as @code{@@unnumbered} -(@pxref{unnumbered & appendix, , @code{@@unnumbered}, @code{@@appendix}}). -For detailed information, see -@ref{makeinfo top command, , The @code{@@top} Command}.@refill - -@node chapter, unnumbered & appendix, makeinfo top, Structuring -@comment node-name, next, previous, up -@section @code{@@chapter} -@findex chapter - -@code{@@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.@refill - -For example, this chapter in this manual is entitled ``Chapter -Structuring''; the @code{@@chapter} line looks like this:@refill - -@example -@@chapter Chapter Structuring -@end example - -In @TeX{}, the @code{@@chapter} command creates a chapter in the -document, specifying the chapter title. The chapter is numbered -automatically.@refill - -In Info, the @code{@@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:@refill - -@example -Chapter Structuring -******************* -@end example - -@node unnumbered & appendix, majorheading & chapheading, chapter, Structuring -@comment node-name, next, previous, up -@section @code{@@unnumbered}, @code{@@appendix} -@findex unnumbered -@findex appendix - -Use the @code{@@unnumbered} command to create a chapter that appears -in a printed manual without chapter numbers of any kind. Use the -@code{@@appendix} command to create an appendix in a printed manual -that is labelled by letter instead of by number.@refill - -For Info file output, the @code{@@unnumbered} and @code{@@appendix} -commands are equivalent to @code{@@chapter}: the title is printed on a -line by itself with a line of asterisks underneath. (@xref{chapter, , -@code{@@chapter}}.)@refill - -To create an appendix or an unnumbered chapter, write an -@code{@@appendix} or @code{@@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.@refill - -@node majorheading & chapheading, section, unnumbered & appendix, Structuring -@section @code{@@majorheading}, @code{@@chapheading} -@findex majorheading -@findex chapheading - -The @code{@@majorheading} and @code{@@chapheading} commands put -chapter-like headings in the body of a document.@refill - -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.@refill - -In @TeX{}, an @code{@@majorheading} command generates a larger vertical -whitespace before the heading than an @code{@@chapheading} command but -is otherwise the same.@refill - -In Info, -the @code{@@majorheading} and -@code{@@chapheading} commands are equivalent to -@code{@@chapter}: the title is printed on a line by itself with a line -of asterisks underneath. (@xref{chapter, , @code{@@chapter}}.)@refill - -@node section, unnumberedsec appendixsec heading, majorheading & chapheading, Structuring -@comment node-name, next, previous, up -@section @code{@@section} -@findex section - -In a printed manual, an @code{@@section} command identifies a -numbered section within a chapter. The section title appears in the -table of contents. In Info, an @code{@@section} command provides a -title for a segment of text, underlined with @samp{=}.@refill - -This section is headed with an @code{@@section} command and looks like -this in the Texinfo file:@refill - -@example -@@section @@code@{@@@@section@} -@end example - -To create a section, write the @code{@@section} command at the -beginning of a line and follow it on the same line by the section -title.@refill - -Thus, - -@example -@@section This is a section -@end example - -@noindent -produces - -@example -@group -This is a section -================= -@end group -@end example - -@noindent -in Info. - -@node unnumberedsec appendixsec heading, subsection, section, Structuring -@comment node-name, next, previous, up -@section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading} -@findex unnumberedsec -@findex appendixsec -@findex heading - -The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading} -commands are, respectively, the unnumbered, appendix-like, and -heading-like equivalents of the @code{@@section} command. -(@xref{section, , @code{@@section}}.)@refill - -@table @code -@item @@unnumberedsec -The @code{@@unnumberedsec} command may be used within an -unnumbered chapter or within a regular chapter or appendix to -provide an unnumbered section.@refill - -@item @@appendixsec -@itemx @@appendixsection -@code{@@appendixsection} is a longer spelling of the -@code{@@appendixsec} command; the two are synonymous.@refill -@findex appendixsection - -Conventionally, the @code{@@appendixsec} or @code{@@appendixsection} -command is used only within appendices.@refill - -@item @@heading -You may use the @code{@@heading} command anywhere you wish for a -section-style heading that will not appear in the table of contents.@refill -@end table - -@node subsection, unnumberedsubsec appendixsubsec subheading, unnumberedsec appendixsec heading, Structuring -@comment node-name, next, previous, up -@section The @code{@@subsection} Command -@findex subsection - -Subsections are to sections as sections are to chapters. -(@xref{section, , @code{@@section}}.) In Info, subsection titles are -underlined with @samp{-}. For example,@refill - -@example -@@subsection This is a subsection -@end example - -@noindent -produces - -@example -@group -This is a subsection --------------------- -@end group -@end example - -In a printed manual, subsections are listed in the table of contents -and are numbered three levels deep.@refill - -@node unnumberedsubsec appendixsubsec subheading, subsubsection, subsection, Structuring -@comment node-name, next, previous, up -@section The @code{@@subsection}-like Commands -@cindex Subsection-like commands -@findex unnumberedsubsec -@findex appendixsubsec -@findex subheading - -The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and -@code{@@subheading} commands are, respectively, the unnumbered, -appendix-like, and heading-like equivalents of the @code{@@subsection} -command. (@xref{subsection, , @code{@@subsection}}.)@refill - -In Info, the @code{@@subsection}-like commands generate a title -underlined with hyphens. In a printed manual, an @code{@@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 @code{@@unnumberedsubsec} command produces an unnumbered heading like -that of a subsection and an @code{@@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.@refill - -@node subsubsection, , unnumberedsubsec appendixsubsec subheading, Structuring -@comment node-name, next, previous, up -@section The `subsub' Commands -@cindex Subsub commands -@findex subsubsection -@findex unnumberedsubsubsec -@findex appendixsubsubsec -@findex subsubheading - -The fourth and lowest level sectioning commands in Texinfo are the -`subsub' commands. They are:@refill - -@table @code -@item @@subsubsection -Subsubsections are to subsections as subsections are to sections. -(@xref{subsection, , @code{@@subsection}}.) In a printed manual, -subsubsection titles appear in the table of contents and are numbered -four levels deep.@refill - -@item @@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.@refill - -@item @@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.@refill - -@item @@subsubheading -The @code{@@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.@refill -@end table - -In Info, `subsub' titles are underlined with periods. -For example,@refill - -@example -@@subsubsection This is a subsubsection -@end example - -@noindent -produces - -@example -@group -This is a subsubsection -....................... -@end group -@end example - -@node Nodes, Menus, Structuring, Top -@comment node-name, next, previous, up -@chapter Nodes - -@dfn{Nodes} are the primary segments of a Texinfo file. They do not -themselves impose a hierarchic or any other kind of structure on a file. -Nodes contain @dfn{node pointers} that name other nodes, and can contain -@dfn{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.@refill - -@menu -* Two Paths:: Different commands to structure - Info output and printed output. -* Node Menu Illustration:: A diagram, and sample nodes and menus. -* node:: How to write a node, in detail. -* makeinfo Pointer Creation:: How to create node pointers with @code{makeinfo}. -@end menu - -@node Two Paths, Node Menu Illustration, , Nodes -@ifinfo -@heading Two Paths -@end ifinfo - -The node and menu commands and the chapter structuring commands are -independent of each other: - -@itemize @bullet -@item -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.@refill - -@item -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.@refill -@end itemize - -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, most Texinfo -files are written such that the structure for the Info output -corresponds to the structure for the printed output. It is not -convenient to do otherwise.@refill - -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.@refill - -@node Node Menu Illustration, node, Two Paths, Nodes -@comment node-name, next, previous, up -@section 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.@refill - -Note that 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.@refill - -@example -@group - 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 - -@end group -@end example - -Write the beginning of the node for Chapter 2 like this:@refill - -@example -@group -@@node Chapter 2, Chapter 3, Chapter 1, top -@@comment node-name, next, previous, up -@end group -@end example - -@noindent -This @code{@@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''. - -@quotation -@strong{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 may follow a chapter-level -node, and a subsection-level node may follow a section-level node. -`Next' and `Previous' refer to nodes at the @emph{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.)@refill -@end quotation - -To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter -2. (@xref{Menus}.) You would write the menu just -before the beginning of Section 2.1, like this:@refill - -@example -@group - @@menu - * Sect. 2.1:: Description of this section. - * Sect. 2.2:: - @@end menu -@end group -@end example - -Write the node for Sect. 2.1 like this:@refill - -@example -@group - @@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2 - @@comment node-name, next, previous, up -@end group -@end example - -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 @ref{Cross References}.)@refill - -Usually, an @code{@@node} command and a chapter structuring command are -used in sequence, along with indexing commands. (You may follow the -@code{@@node} line with a comment line that reminds you which pointer is -which.)@refill - -Here is the beginning of the chapter in this manual called ``Ending a -Texinfo File''. This shows an @code{@@node} line followed by a comment -line, an @code{@@chapter} line, and then by indexing lines.@refill - -@example -@group -@@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 -@end group -@end example - -@node node, makeinfo Pointer Creation, Node Menu Illustration, Nodes -@comment node-name, next, previous, up -@section The @code{@@node} Command - -@cindex Node, defined -A @dfn{node} is a segment of text that begins at an @code{@@node} -command and continues until the next @code{@@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 @code{@@node} command in the file. A node usually -contains only one chapter structuring command, the one that follows -the @code{@@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.@refill - -To create a node, write an @code{@@node} command at the beginning of a -line, and follow it with four arguments, separated by commas, on the -rest of the same line. These arguments are the name of the node, and -the names of the `Next', `Previous', and `Up' pointers, in that order. -You may insert spaces before each pointer if you wish; the spaces are -ignored. You must write the name of the node, and the names of the -`Next', `Previous', and `Up' pointers, all on the same line. Otherwise, -the formatters fail. (@inforef{Top, info, info}, for more information -about nodes in Info.)@refill - -Usually, you write one of the chapter-structuring command lines -immediately after an @code{@@node} line---for example, an -@code{@@section} or @code{@@subsection} line. (@xref{Structuring -Command Types, , Types of Structuring Command}.)@refill - -@quotation -@strong{Please note:} The GNU Emacs Texinfo mode updating commands work -only with Texinfo files in which @code{@@node} lines are followed by chapter -structuring lines. @xref{Updating Requirements}.@refill -@end quotation - -@TeX{} uses @code{@@node} lines to identify the names to use for cross -references. For this reason, you must write @code{@@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 @code{@@xref} and its related -commands; see @ref{Cross References}.)@refill - -@menu -* Node Names:: How to choose node and pointer names. -* Writing a Node:: How to write an @code{@@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 @code{@@top} command. -* Top Node Summary:: Write a brief description for readers. -@end menu - -@node Node Names, Writing a Node, , node -@ifinfo -@subheading Choosing Node and Pointer Names -@end ifinfo - -The name of a node identifies the node. The pointers enable -you to reach other nodes and consist of the names of those nodes.@refill - -Normally, a node's `Up' pointer contains the name of the node whose menu -mentions that node. The node's `Next' pointer contains the name of the -node that follows that node in that menu and its `Previous' pointer -contains the name of the node that precedes it in that menu. When a -node's `Previous' node is the same as its `Up' node, both node pointers -name the same node.@refill - -Usually, the first node of a Texinfo file is the `Top' node, and its -`Up' and `Previous' pointers point to the @file{dir} file, which -contains the main menu for all of Info.@refill - -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. @xref{First Node}, for information on how to write the -first node of a Texinfo file.@refill - -@node Writing a Node, Node Line Tips, Node Names, node -@comment node-name, next, previous, up -@subsection How to Write an @code{@@node} Line -@cindex Writing an @code{@@node} line -@cindex @code{@@node} line writing -@cindex Node line writing - -The easiest way to write an @code{@@node} line is to write @code{@@node} -at the beginning of a line and then the name of the node, like -this:@refill - -@example -@@node @var{node-name} -@end example - -If you are using GNU Emacs, you can use the update node commands -provided by Texinfo mode to insert the names of the pointers; or you -can leave the pointers out of the Texinfo file and let @code{makeinfo} -insert node pointers into the Info file it creates. (@xref{Texinfo -Mode}, and @ref{makeinfo Pointer Creation}.)@refill - -Alternatively, you can insert the `Next', `Previous', and `Up' -pointers yourself. If you do this, you may find it helpful to use the -Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts -@samp{@@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.@refill - -The template for a node line with `Next', `Previous', and `Up' pointers -looks like this:@refill - -@example -@@node @var{node-name}, @var{next}, @var{previous}, @var{up} -@end example - -If you wish, you can ignore @code{@@node} lines altogether in your first -draft and then use the @code{texinfo-insert-node-lines} command to -create @code{@@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.@refill - -After you have inserted an @code{@@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.@refill - -@node Node Line Tips, Node Line Requirements, Writing a Node, node -@comment node-name, next, previous, up -@subsection @code{@@node} Line Tips - -Here are three suggestions: - -@itemize @bullet -@item -Try to pick node names that are informative but short.@refill - -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.)@refill - -@item -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.@refill - -@item -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.@refill -@end itemize - -@node Node Line Requirements, First Node, Node Line Tips, node -@comment node-name, next, previous, up -@subsection @code{@@node} Line Requirements - -@cindex Node line requirements -Here are several requirements for @code{@@node} lines: - -@itemize @bullet -@cindex Unique nodename requirement -@cindex Nodename must be unique -@item -All the node names for a single Info file must be unique.@refill - -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.@refill - -@item -A pointer name must be the name of a node.@refill - -The node to which a pointer points may come before or after the -node containing the pointer.@refill - -@cindex @@-command in nodename -@cindex Nodename, cannot contain -@item -You cannot use any of the Texinfo @@-commands in a node name; -@w{@@-commands} confuse Info.@refill - -@need 750 -Thus, the beginning of the section called @code{@@chapter} looks like -this:@refill - -@smallexample -@group -@@node chapter, unnumbered & appendix, makeinfo top, Structuring -@@comment node-name, next, previous, up -@@section @@code@{@@@@chapter@} -@@findex chapter -@end group -@end smallexample - -@cindex Comma in nodename -@cindex Colon in nodename -@cindex Apostrophe in nodename -@item -You cannot use commas, colons, or apostrophes within a node name; these -confuse @TeX{} or the Info formatters.@refill - -@need 700 -For example, the following is a section title: - -@smallexample -@@code@{@@@@unnumberedsec@}, @@code@{@@@@appendixsec@}, @@code@{@@@@heading@} -@end smallexample - -@noindent -The corresponding node name is: - -@smallexample -unnumberedsec appendixsec heading -@end smallexample - -@cindex Case in nodename -@item -Case is significant. -@end itemize - -@node First Node, makeinfo top command, Node Line Requirements, node -@comment node-name, next, previous, up -@subsection The First Node -@cindex @samp{@r{Top}} node is first -@cindex First node - -The first node of a Texinfo file is the `Top' node, except in an -included file (@pxref{Include Files}). - -The `Top' node (which must be named @samp{top} or @samp{Top}) should -have as its `Up' and `Previous' nodes the name of a node in another -file, where there is a menu that leads to this file. Specify the file -name in parentheses. If the file is to be installed directly in the -Info directory file, use @samp{(dir)} as the parent of the `Top' node; -this is short for @samp{(dir)top}, and specifies the `Top' node in the -@file{dir} file, which contains the main menu for Info. For example, -the @code{@@node Top} line of this manual looks like this:@refill - -@example -@@node Top, Overview, (dir), (dir) -@end example - -@noindent -(You may use the Texinfo updating commands or the @code{makeinfo} -utility to insert these `Next' and @samp{(dir)} pointers -automatically.)@refill - -@xref{Install an Info File}, for more information about installing -an Info file in the @file{info} directory.@refill - -The `Top' node contains the main or master menu for the document. - -@node makeinfo top command, Top Node Summary, First Node, node -@comment node-name, next, previous, up -@subsection The @code{@@top} Sectioning Command -@findex top @r{(@@-command)} - -A special sectioning command, @code{@@top}, has been created for use -with the @code{@@node Top} line. The @code{@@top} sectioning command tells -@code{makeinfo} that it marks the `Top' node in the file. It provides -the information that @code{makeinfo} needs to insert node -pointers automatically. Write the @code{@@top} command at the -beginning of the line immediately following the @code{@@node Top} -line. Write the title on the remaining part of the same line as the -@code{@@top} command.@refill - -In Info, the @code{@@top} sectioning command causes the title to appear on a -line by itself, with a line of asterisks inserted underneath.@refill - -In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top} -sectioning command is merely a synonym for @code{@@unnumbered}. -Neither of these formatters require an @code{@@top} command, and do -nothing special with it. You can use @code{@@chapter} or -@code{@@unnumbered} after the @code{@@node Top} line when you use -these formatters. Also, you can use @code{@@chapter} or -@code{@@unnumbered} when you use the Texinfo updating commands to -create or update pointers and menus.@refill - -Whatever sectioning command follows an @code{@@node Top} line, whether -it be @code{@@top} or @code{@@chapter}, the @code{@@node Top} line and -the immediately following line and any additional text must be -enclosed between @code{@@ifinfo} and @code{@@end ifinfo} commands. -(@xref{Conditionals}.) This prevents the title and the accompanying -text from appearing in printed output. Write the @code{@@ifinfo} -command before the @code{@@node} line and write the @code{@@end ifinfo} command -after the @code{@@top} or other sectioning command and after any -additional text. (You can write the @code{@@end ifinfo} command after -the @code{@@end menu} command if you like.)@refill - -@node Top Node Summary, , makeinfo top command, node -@subsection The `Top' Node Summary -@cindex @samp{@r{Top}} node summary - -You can help readers by writing a summary in the `Top' node, after the -@code{@@top} line, before the main or master menu. The summary should -briefly describe the Info file. You should also write the version -number of the program to which the manual applies in this section. This -helps the reader keep track of which manual is for which version of the -program. If the manual changes more frequently than the program or is -independent of it, you should also include an edition number for the -manual. (The title page should also contain this information: -see @ref{titlepage, , @code{@@titlepage}}.)@refill - -Put the whole of the `Top' node, including the @code{@@top} sectioning -command line if you -have one, between @code{@@ifinfo} and @code{@@end -ifinfo} so none of the text appears in the printed output -(@pxref{Conditionals, , Conditionally Visible Text}). (You may want to -repeat the brief description from the `Top' node within @code{@@iftex} -@dots{} @code{@@end iftex} at the beginning of the first chapter, for -those who read the printed manual.) - -@node makeinfo Pointer Creation, , node, Nodes -@section Creating Pointers with @code{makeinfo} -@cindex Creating pointers with @code{makeinfo} -@cindex Pointer creation with @code{makeinfo} -@cindex Automatic pointer creation with @code{makeinfo} - -The @code{makeinfo} program has a feature for automatically creating -node pointers for a hierarchically organized file that lacks -them.@refill - -When you take advantage of this feature, you do not need to write the -`Next', `Previous', and `Up' pointers after the name of a node. -However, you must write a sectioning command, such as @code{@@chapter} -or @code{@@section}, on the line immediately following each truncated -@code{@@node} line. You cannot write a comment line after a node -line; the section line must follow it immediately.@refill - -In addition, you must follow the `Top' @code{@@node} line with a line beginning -with @code{@@top} to mark the `Top' node in the file. @xref{makeinfo -top, , @code{@@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.@refill - -This node pointer insertion feature in @code{makeinfo} is an -alternative to the menu and pointer creation and update commands in -Texinfo mode. (@xref{Updating Nodes and Menus}.) It is especially -helpful to people who do not use GNU Emacs for writing Texinfo -documents.@refill - -@node Menus, Cross References, Nodes, Top -@comment node-name, next, previous, up -@chapter Menus -@cindex Menus -@findex menu - -@dfn{Menus} contain pointers to subordinate -nodes.@footnote{Menus can carry you to any node, regardless -of the hierarchical structure; even to nodes in a different -Info file. However, the GNU Emacs Texinfo mode updating -commands work only to create menus of subordinate nodes. -Conventionally, cross references are used to refer to other -nodes.} In Info, you use menus to go to such nodes. Menus -have no effect in printed manuals and do not appear in -them.@refill - -By convention, a menu is put at the end of a node since a reader who -uses the menu may not see text that follows it.@refill - -@ifinfo -A node that has a menu should @emph{not} contain much text. If you -have a lot of text and a menu, move most of the text into a new -subnode---all but a few lines.@refill -@end ifinfo -@iftex -@emph{A node that has a menu should not contain much text.} If you -have a lot of text and a menu, move most of the text into a new -subnode---all but a few lines. Otherwise, a reader with a terminal -that displays only a few lines may miss the menu and its associated -text. As a practical matter, you should locate a menu within 20 lines -of the beginning of the node.@refill -@end iftex - -@menu -* Menu Location:: Put a menu in a short node. -* 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. -@end menu - -@node Menu Location, Writing a Menu, , Menus -@ifinfo -@heading Menus Need Short Nodes -@end ifinfo -@cindex Menu location -@cindex Location of menus -@cindex Nodes for menus are short -@cindex Short nodes for menus - -@ifinfo -A reader can easily see a menu that is close to the beginning of the -node. The node should be short. As a practical matter, you should -locate a menu within 20 lines of the beginning of the node. -Otherwise, a reader with a terminal that displays only a few lines may -miss the menu and its associated text.@refill -@end ifinfo - -The short text before a menu may look awkward in a printed manual. To -avoid this, you can write a menu near the beginning of its node and -follow the menu by an @code{@@node} line, and then an @code{@@heading} -line located within @code{@@ifinfo} and @code{@@end ifinfo}. This way, -the menu, @code{@@node} line, and title appear only in the Info file, -not the printed document.@refill - -For example, the preceding two paragraphs follow an Info-only menu, -@code{@@node} line, and heading, and look like this:@refill - -@example -@group -@@menu -* Menu Location:: Put a menu in a short node. -* 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 entries. -* Other Info Files:: How to refer to a different - Info file. -@@end menu - -@@node Menu Location, Writing a Menu, , Menus -@@ifinfo -@@heading Menus Need Short Nodes -@@end ifinfo -@end group -@end example - -The Texinfo file for this document contains more than a dozen -examples of this procedure. One is at the beginning of this chapter; -another is at the beginning of the ``Cross References'' chapter.@refill - -@node Writing a Menu, Menu Parts, Menu Location, Menus -@section Writing a Menu -@cindex Writing a menu -@cindex Menu writing - -A menu consists of an @code{@@menu} command on a line by -itself followed by menu entry lines or menu comment lines -and then by an @code{@@end menu} command on a line by -itself.@refill - -A menu looks like this:@refill - -@example -@group -@@menu -Larger Units of Text - -* Files:: All about handling files. -* Multiples: Buffers. Multiple buffers; editing - several files at once. -@@end menu -@end group -@end example - -In a menu, every line that begins with an @w{@samp{* }} is a -@dfn{menu entry}. (Note the space after the asterisk.) A -line that does not start with an @w{@samp{* }} may also -appear in a menu. Such a line is not a menu entry but is a -menu comment line that appears in the Info file. In -the example above, the line @samp{Larger Units of Text} is a -menu comment line; the two lines starting with @w{@samp{* }} -are menu entries. - -@node Menu Parts, Less Cluttered Menu Entry, Writing a Menu, Menus -@section The Parts of a Menu -@cindex Parts of a menu -@cindex Menu parts -@cindex @code{@@menu} parts - -A menu entry has three parts, only the second of which is -required:@refill - -@enumerate -@item -The menu entry name. - -@item -The name of the node (required). - -@item -A description of the item. -@end enumerate - -The template for a menu entry looks like this:@refill - -@example -* @var{menu-entry-name}: @var{node-name}. @var{description} -@end example - -Follow the menu entry name with a single colon and follow the node name -with tab, comma, period, or newline.@refill - -In Info, a user selects a node with the @kbd{m} (@code{Info-menu}) -command. The menu entry name is what the user types after the @kbd{m} -command.@refill - -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. The -description, which is optional, can spread over two or more lines. A -useful description complements the node name rather than repeats -it.@refill - -@node Less Cluttered Menu Entry, Menu Example, Menu Parts, Menus -@comment node-name, next, previous, up -@section Less Cluttered Menu Entry -@cindex Two part menu entry -@cindex Double-colon menu entries -@cindex Menu entries with two colons -@cindex Less cluttered menu entry -@cindex Uncluttered 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.@refill - -@need 800 -For example, write - -@example -* Name:: @var{description} -@end example - -@need 800 -@noindent -instead of - -@example -* Name: Name. @var{description} -@end example - -You should use the node name for the menu entry name whenever possible, -since it reduces visual clutter in the menu.@refill - -@node Menu Example, Other Info Files, Less Cluttered Menu Entry, Menus -@comment node-name, next, previous, up -@section A Menu Example -@cindex Menu example -@cindex Example menu - -A menu looks like this in Texinfo:@refill - -@example -@group -@@menu -* menu entry name: Node name. A short description. -* Node name:: This form is preferred. -@@end menu -@end group -@end example - -@need 800 -@noindent -This produces: - -@example -@group -* menu: - -* menu entry name: Node name. A short description. -* Node name:: This form is preferred. -@end group -@end example - -@need 700 -Here is an example as you might see it in a Texinfo file:@refill - -@example -@group -@@menu -Larger Units of Text - -* Files:: All about handling files. -* Multiples: Buffers. Multiple buffers; editing - several files at once. -@@end menu -@end group -@end example - -@need 800 -@noindent -This produces: - -@example -@group -* menu: -Larger Units of Text - -* Files:: All about handling files. -* Multiples: Buffers. Multiple buffers; editing - several files at once. -@end group -@end example - -In this example, the menu has two entries. @samp{Files} is both a menu -entry name and the name of the node referred to by that name. -@samp{Multiples} is the menu entry name; it refers to the node named -@samp{Buffers}. The line @samp{Larger Units of Text} is a comment; it -appears in the menu, but is not an entry.@refill - -Since no file name is specified with either @samp{Files} or -@samp{Buffers}, they must be the names of nodes in the same Info file -(@pxref{Other Info Files, , Referring to Other Info Files}).@refill - -@node Other Info Files, , Menu Example, Menus -@comment node-name, next, previous, up -@section Referring to Other Info Files -@cindex Referring to other Info files -@cindex Nodes in other Info files -@cindex Other Info files' nodes -@cindex Going to other Info files' nodes -@cindex Info; other files' nodes - -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.@refill - -@need 800 -The format looks like this:@refill - -@example -@group -@@menu -* @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description} -* @var{second-entry-name}:(@var{filename})@var{second-node}. @var{description} -@@end menu -@end group -@end example - -For example, to refer directly to the @samp{Outlining} and -@samp{Rebinding} nodes in the @cite{Emacs Manual}, you would write a -menu like this:@refill - -@example -@group -@@menu -* Outlining: (emacs)Outline Mode. The major mode for - editing outlines. -* Rebinding: (emacs)Rebinding. How to redefine the - meaning of a key. -@@end menu -@end group -@end example - -If you do not list the node name, but only name the file, then Info -presumes that you are referring to the `Top' node.@refill - -The @file{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. (@xref{Install an Info File}.)@refill - -@need 700 -For example: - -@example -@group -* Info: (info). Documentation browsing system. -* Emacs: (emacs). The extensible, self-documenting - text editor. -@end group -@end example - -@noindent -(The @file{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.)@refill - -Note that 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.@refill - -@node Cross References, Marking Text, Menus, Top -@comment node-name, next, previous, up -@chapter Cross References -@cindex Making cross references -@cindex Cross references -@cindex References - -@dfn{Cross references} are used to refer the reader to other parts of the -same or different Texinfo files. In Texinfo, nodes are the -places to which cross references can refer.@refill - -@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' @dots{} -* 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. -@end menu - -@node References, Cross Reference Commands, , Cross References -@ifinfo -@heading What References Are For -@end ifinfo - -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.@refill - -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 on-line 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.@refill - -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.@refill - -In Info, a cross reference results in an entry that you can follow using -the Info @samp{f} command. (@inforef{Help-Adv, Some advanced Info -commands, info}.)@refill - -The various cross reference commands use nodes to define cross -reference locations. This is evident in Info, in which a cross -reference takes you to the specified node. @TeX{} also uses nodes to -define cross reference locations, but the action is less obvious. When -@TeX{} generates a @sc{dvi} file, it records nodes' page numbers 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 on-line, you -must nonetheless write @code{@@node} lines to name the places to which -you make cross references.@refill - -@need 800 -@node Cross Reference Commands, Cross Reference Parts, References, Cross References -@comment node-name, next, previous, up -@section Different Cross Reference Commands -@cindex Different cross reference commands - -There are four different cross reference commands:@refill - -@table @code -@item @@xref -Used to start a sentence in the printed manual saying -@w{`See @dots{}'} or an entry in the Info file saying -@samp{*Note @dots{}}. - -@item @@ref -Used within or, more often, at the end of a sentence; same as -@code{@@xref} for Info; produces just the reference in the printed -manual without a preceding `See'.@refill - -@item @@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. (@samp{p} is for `parenthesis'.)@refill - -@item @@inforef -Used to make a reference to an Info file for which there is no printed -manual.@refill -@end table - -@noindent -(The @code{@@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. @xref{cite, , @code{@@cite}}.)@refill - -@node Cross Reference Parts, xref, Cross Reference Commands, Cross References -@comment node-name, next, previous, up -@section Parts of a Cross Reference -@cindex Cross reference parts -@cindex 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.@refill - -Here is a simple cross reference example:@refill - -@example -@@xref@{Node name@}. -@end example - -@noindent -which produces - -@example -*Note Node name::. -@end example - -@noindent -and - -@quotation -See Section @var{nnn} [Node name], page @var{ppp}. -@end quotation - -@need 700 -Here is an example of a full five-part cross reference:@refill - -@example -@group -@@xref@{Node name, Cross Reference Name, Particular Topic, -info-file-name, A Printed Manual@}, for details. -@end group -@end example - -@noindent -which produces - -@example -*Note Cross Reference Name: (info-file-name)Node name, -for details. -@end example - -@noindent -in Info and - -@quotation -See section ``Particular Topic'' in @i{A Printed Manual}, for details. -@end quotation - -@noindent -in a printed book. - -The five possible arguments for a cross reference are:@refill - -@enumerate -@item -The node name (required). This is the node 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.@refill - -@item -The cross reference name for the Info reference, if it is to be different -from the node name. If you include this argument, it argument becomes -the first part of the cross reference. It is usually omitted.@refill - -@item -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.@refill - -@item -The name of the Info file in which the reference is located, if it is -different from the current file.@refill - -@item -The name of a printed manual from a different Texinfo file.@refill -@end enumerate - -The template for a full five argument cross reference looks like -this:@refill - -@example -@group -@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}, -@var{info-file-name}, @var{printed-manual-title}@}. -@end group -@end example - -Cross references with one, two, three, four, and five arguments are -described separately following the description of @code{@@xref}.@refill - -Write a node name in a cross reference in exactly the same way as in -the @code{@@node} line, including the same capitalization; otherwise, the -formatters may not find the reference.@refill - -You can write cross reference commands within a paragraph, but note -how Info and @TeX{} format the output of each of the various commands: -write @code{@@xref} at the beginning of a sentence; write -@code{@@pxref} only within parentheses, and so on.@refill - -@node xref, Top Node Naming, Cross Reference Parts, Cross References -@comment node-name, next, previous, up -@section @code{@@xref} -@findex xref -@cindex Cross references using @code{@@xref} -@cindex References using @code{@@xref} - -The @code{@@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 @samp{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.@refill - -@menu -* Reference Syntax:: What a reference looks like and requires. -* One Argument:: @code{@@xref} with one argument. -* Two Arguments:: @code{@@xref} with two arguments. -* Three Arguments:: @code{@@xref} with three arguments. -* Four and Five Arguments:: @code{@@xref} with four and five arguments. -@end menu - -@node Reference Syntax, One Argument, , xref -@ifinfo -@subheading What a Reference Looks Like and Requires -@end ifinfo - -Most often, an Info cross reference looks like this:@refill - -@example -*Note @var{node-name}::. -@end example - -@noindent -or like this - -@example -*Note @var{cross-reference-name}: @var{node-name}. -@end example - -@noindent -In @TeX{}, a cross reference looks like this: - -@example -See Section @var{section-number} [@var{node-name}], page @var{page}. -@end example - -@noindent -or like this - -@example -See Section @var{section-number} [@var{title-or-topic}], page @var{page}. -@end example - -The @code{@@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 @code{@@pxref} command works -differently. @xref{pxref, , @code{@@pxref}}.)@refill - -@quotation -@strong{Please note:} A period or comma @strong{must} follow the closing -brace of an @code{@@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.@refill -@end quotation - -@code{@@xref} must refer to an Info node by name. Use @code{@@node} -to define the node (@pxref{Writing a Node}).@refill - -@code{@@xref} is followed by several arguments inside braces, separated by -commas. Whitespace before and after these commas is ignored.@refill - -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.@refill - -@quotation -@strong{Please note:} Commas separate arguments in a cross reference; -avoid including them in the title or other part lest the formatters -mistake them for separators.@refill -@end quotation - -@node One Argument, Two Arguments, Reference Syntax, xref -@subsection @code{@@xref} with One Argument - -The simplest form of @code{@@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.@refill - -@need 700 -@noindent -For example, - -@example -@@xref@{Tropical Storms@}. -@end example - -@noindent -produces - -@example -*Note Tropical Storms::. -@end example - -@noindent -and - -@quotation -See Section 3.1 [Tropical Storms], page 24. -@end quotation - -@noindent -(Note that in the preceding example the closing brace is followed by a -period.)@refill - -You can write a clause after the cross reference, like this:@refill - -@example -@@xref@{Tropical Storms@}, for more info. -@end example - -@noindent -which produces - -@example -*Note Tropical Storms::, for more info. -@end example - -@quotation -See Section 3.1 [Tropical Storms], page 24, for more info. -@end quotation - -@noindent -(Note that in the preceding example the closing brace is followed by a -comma, and then by the clause, which is followed by a period.)@refill - -@node Two Arguments, Three Arguments, One Argument, xref -@subsection @code{@@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.@refill - -@need 750 -@noindent -The template is like this: - -@example -@@xref@{@var{node-name}, @var{cross-reference-name}@}. -@end example - -@need 700 -@noindent -For example, - -@example -@@xref@{Electrical Effects, Lightning@}. -@end example - -@noindent -produces: - -@example -*Note Lightning: Electrical Effects. -@end example - -@noindent -and - -@quotation -See Section 5.2 [Electrical Effects], page 57. -@end quotation - -@noindent -(Note that in the preceding example the closing brace is followed by a -period; and that the node name is printed, not the cross reference name.)@refill - -You can write a clause after the cross reference, like this:@refill - -@example -@@xref@{Electrical Effects, Lightning@}, for more info. -@end example - -@noindent -which produces -@example -*Note Lightning: Electrical Effects, for more info. -@end example - -@noindent -and - -@quotation -See Section 5.2 [Electrical Effects], page 57, for more info. -@end quotation - -@noindent -(Note that in the preceding example the closing brace is followed by a -comma, and then by the clause, which is followed by a period.)@refill - -@node Three Arguments, Four and Five Arguments, Two Arguments, xref -@subsection @code{@@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.@refill - -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.@refill - -Also, remember to write a comma or period after the closing brace of a -@code{@@xref} to terminate the cross reference. In the following -examples, a clause follows a terminating comma.@refill - - -@need 750 -@noindent -The template is like this: - -@example -@group -@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}@}. -@end group -@end example - -@need 700 -@noindent -For example, - -@example -@group -@@xref@{Electrical Effects, Lightning, Thunder and Lightning@}, -for details. -@end group -@end example - -@noindent -produces - -@example -*Note Lightning: Electrical Effects, for details. -@end example - -@noindent -and - -@quotation -See Section 5.2 [Thunder and Lightning], page 57, for details. -@end quotation - -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.)@refill - -@example -@group -@@xref@{Electrical Effects, , Thunder and Lightning@}, -for details. -@end group -@end example - -@noindent -produces - -@example -*Note Thunder and Lightning: Electrical Effects, for details. -@end example - -@noindent -and - -@quotation -See Section 5.2 [Thunder and Lightning], page 57, for details. -@end quotation - -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.@refill - -Here are several examples from @cite{The GAWK Manual}:@refill - -@smallexample -@@xref@{Sample Program@}. -@@xref@{Glossary@}. -@@xref@{Case-sensitivity, ,Case-sensitivity in Matching@}. -@@xref@{Close Output, , Closing Output Files and Pipes@}, - for more information. -@@xref@{Regexp, , Regular Expressions as Patterns@}. -@end smallexample - -@node Four and Five Arguments, , Three Arguments, xref -@subsection @code{@@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.@refill - -Remember that a comma or period must follow the closing brace of an -@code{@@xref} command to terminate the cross reference. In the -following examples, a clause follows a terminating comma.@refill - -@need 800 -@noindent -The template is: - -@example -@group -@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}, -@var{info-file-name}, @var{printed-manual-title}@}. -@end group -@end example - -@need 700 -@noindent -For example, - -@example -@@xref@{Electrical Effects, Lightning, Thunder and Lightning, -weather, An Introduction to Meteorology@}, for details. -@end example - -@noindent -produces - -@example -*Note Lightning: (weather)Electrical Effects, for details. -@end example - -@noindent -The name of the Info file is enclosed in parentheses and precedes -the name of the node. - -@noindent -In a printed manual, the reference looks like this:@refill - -@quotation -See section ``Thunder and Lightning'' in @i{An Introduction to -Meteorology}, for details. -@end quotation - -@noindent -The title of the printed manual is typeset in italics; and the -reference lacks a page number since @TeX{} cannot know to which page a -reference refers when that reference is to another manual.@refill - -Often, you will leave out the second argument when you use the long -version of @code{@@xref}. In this case, the third argument, the topic -description, will be used as the cross reference name in Info.@refill - -@noindent -The template looks like this: - -@example -@@xref@{@var{node-name}, , @var{title-or-topic}, @var{info-file-name}, -@var{printed-manual-title}@}, for details. -@end example - -@noindent -which produces - -@example -*Note @var{title-or-topic}: (@var{info-file-name})@var{node-name}, for details. -@end example - -@noindent -and - -@quotation -See section @var{title-or-topic} in @var{printed-manual-title}, for details. -@end quotation - -@need 700 -@noindent -For example, - -@example -@@xref@{Electrical Effects, , Thunder and Lightning, -weather, An Introduction to Meteorology@}, for details. -@end example - -@noindent -produces - -@example -@group -*Note Thunder and Lightning: (weather)Electrical Effects, -for details. -@end group -@end example - -@noindent -and - -@quotation -See section ``Thunder and Lightning'' in @i{An Introduction to -Meteorology}, for details. -@end quotation - -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.@refill - -@node Top Node Naming, ref, xref, Cross References -@section Naming a `Top' Node -@cindex Naming a `Top' Node in references -@cindex @samp{@r{Top}} node naming for references - -In a cross reference, you must always name a node. This means that in -order to refer to a whole manual, you must identify the `Top' node by -writing it as the first argument to the @code{@@xref} command. (This -is different from the way you write a menu entry; see @ref{Other Info -Files, , Referring to Other Info Files}.) At the same time, to -provide a meaningful section topic or title in the printed cross -reference (instead of the word `Top'), you must write an appropriate -entry for the third argument to the @code{@@xref} command. -@refill - -@noindent -Thus, to make a cross reference to @cite{The GNU Make Manual}, -write:@refill - -@example -@@xref@{Top, , Overview, make, The GNU Make Manual@}. -@end example - -@noindent -which produces - -@example -*Note Overview: (make)Top. -@end example - -@noindent -and - -@quotation -See section ``Overview'' in @i{The GNU Make Manual}. -@end quotation - -@noindent -In this example, @samp{Top} is the name of the first node, and -@samp{Overview} is the name of the first section of the manual.@refill -@node ref, pxref, Top Node Naming, Cross References -@comment node-name, next, previous, up -@section @code{@@ref} -@cindex Cross references using @code{@@ref} -@cindex References using @code{@@ref} -@findex ref - -@code{@@ref} is nearly the same as @code{@@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.@refill - -@need 700 -@noindent -For example, - -@example -For more information, see @@ref@{Hurricanes@}. -@end example - -@noindent -produces - -@example -For more information, see *Note Hurricanes. -@end example - -@noindent -and - -@quotation -For more information, see Section 8.2 [Hurricanes], page 123. -@end quotation - -The @code{@@ref} command sometimes leads 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.@refill - -@need 800 -@noindent -For example, - -@example -@group -Sea surges are described in @@ref@{Hurricanes@}. -@end group -@end example - -@need 800 -@noindent -produces - -@quotation -Sea surges are described in Section 6.7 [Hurricanes], page 72. -@end quotation - -@need 800 -@noindent -in a printed document, and the following in Info: - -@example -Sea surges are described in *Note Hurricanes::. -@end example - -@quotation -@strong{Caution:} You @emph{must} write a period or comma immediately -after an @code{@@ref} command with two or more arguments. Otherwise, -Info will not find the end of the cross reference entry and its -attempt to follow the cross reference will fail. As a general rule, -you should write a period or comma after every @code{@@ref} command. -This looks best in both the printed and the Info output.@refill -@end quotation - -@node pxref, inforef, ref, Cross References -@comment node-name, next, previous, up -@section @code{@@pxref} -@cindex Cross references using @code{@@pxref} -@cindex References using @code{@@pxref} -@findex pxref - -The parenthetical reference command, @code{@@pxref}, is nearly the -same as @code{@@xref}, but you use it @emph{only} inside parentheses -and you do @emph{not} type a comma or period after the command's -closing brace. The command differs from @code{@@xref} in two -ways:@refill - -@enumerate -@item -@TeX{} typesets the reference for the printed manual with a lower case -`see' rather than an upper case `See'.@refill - -@item -The Info formatting commands automatically end the reference with a -closing colon or period.@refill -@end enumerate - -Because one type of formatting automatically inserts closing -punctuation and the other does not, you should use @code{@@pxref} -@emph{only} inside parentheses as part of another sentence. Also, you -yourself should not insert punctuation after the reference, as you do -with @code{@@xref}.@refill - -@code{@@pxref} is designed so that the output looks right and works -right between parentheses both in printed output and in an Info file. -In a printed manual, a closing comma or period should not follow a -cross reference within parentheses; such punctuation is wrong. But in -an Info file, suitable closing punctuation must follow the cross -reference so Info can recognize its end. @code{@@pxref} spares you -the need to use complicated methods to put a terminator into one form -of the output and not the other.@refill - -@noindent -With one argument, a parenthetical cross reference looks like -this:@refill - -@example -@dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{} -@end example - -@need 800 -@noindent -which produces - -@example -@group -@dots{} storms cause flooding (*Note Hurricanes::) @dots{} -@end group -@end example - -@noindent -and - -@quotation -@dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{} -@end quotation - -With two arguments, a parenthetical cross reference has this -template:@refill - -@example -@dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{} -@end example - -@noindent -which produces - -@example -@dots{} (*Note @var{cross-reference-name}: @var{node-name}.) @dots{} -@end example - -@noindent -and - -@need 1500 -@quotation -@dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{} -@end quotation - -@code{@@pxref} can be used with up to five arguments just like -@code{@@xref} (@pxref{xref, , @code{@@xref}}).@refill - -@quotation -@strong{Please note:} Use @code{@@pxref} only as a parenthetical -reference. Do not try to use @code{@@pxref} as a clause in a sentence. -It will look bad in either the Info file, the printed output, or -both.@refill - -Also, parenthetical cross references look best at the ends of sentences. -Although you may write them in the middle of a sentence, that location -breaks up the flow of text.@refill -@end quotation - -@node inforef, , pxref, Cross References -@comment node-name, next, previous, up -@section @code{@@inforef} -@cindex Cross references using @code{@@inforef} -@cindex References using @code{@@inforef} -@findex inforef - -@code{@@inforef} is used for cross references to Info files for which -there are no printed manuals. Even in a printed manual, -@code{@@inforef} generates a reference directing the user to look in -an Info file.@refill - -The command takes either two or three arguments, in the following -order:@refill - -@enumerate -@item -The node name. - -@item -The cross reference name (optional). - -@item -The Info file name. -@end enumerate - -@noindent -Separate the arguments with commas, as with @code{@@xref}. Also, you -must terminate the reference with a comma or period after the -@samp{@}}, as you do with @code{@@xref}.@refill - -@noindent -The template is: - -@example -@@inforef@{@var{node-name}, @var{cross-reference-name}, @var{info-file-name}@}, -@end example - -@need 800 -@noindent -Thus, - -@example -@group -@@inforef@{Expert, Advanced Info commands, info@}, -for more information. -@end group -@end example - -@need 800 -@noindent -produces - -@example -@group -*Note Advanced Info commands: (info)Expert, -for more information. -@end group -@end example - -@need 800 -@noindent -and - -@quotation -See Info file @file{info}, node @samp{Expert}, for more information. -@end quotation - -@need 800 -@noindent -Similarly, - -@example -@group -@@inforef@{Expert, , info@}, for more information. -@end group -@end example - -@need 800 -@noindent -produces - -@example -*Note (info)Expert::, for more information. -@end example - -@need 800 -@noindent -and - -@quotation -See Info file @file{info}, node @samp{Expert}, for more information. -@end quotation - -The converse of @code{@@inforef} is @code{@@cite}, which is used to -refer to printed works for which no Info form exists. @xref{cite, , -@code{@@cite}}.@refill - -@node Marking Text, Quotations and Examples, Cross References, Top -@comment node-name, next, previous, up -@chapter Marking Words and Phrases -@cindex Paragraph, marking text within -@cindex Marking words and phrases -@cindex Words and phrases, marking them -@cindex Marking text within a paragraph - -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.@refill - -@menu -* Indicating:: How to indicate definitions, files, etc. -* Emphasis:: How to emphasize text. -@end menu - -@node Indicating, Emphasis, , Marking Text -@comment node-name, next, previous, up -@section Indicating Definitions, Commands, etc. -@cindex Highlighting text -@cindex Indicating commands, definitions, etc. - -Texinfo has commands for indicating just what kind of object a piece of -text refers to. For example, metasyntactic variables are marked by -@code{@@var}, and code by @code{@@code}. Since the pieces of text are -labelled by commands that tell what kind of object they are, it is easy -to change the way the Texinfo formatters prepare such text. (Texinfo is -an @emph{intentional} formatting language rather than a @emph{typesetting} -formatting language.)@refill - -For example, in a printed manual, -code is usually illustrated in a typewriter font; -@code{@@code} tells @TeX{} to typeset this text in this font. But it -would be easy to change the way @TeX{} highlights code to use another -font, and this change would not effect 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.@refill - -@menu -* Useful Highlighting:: Highlighting provides useful information. -* code:: How to indicate code. -* kbd:: How to show keyboard input. -* key:: How to specify keys. -* samp:: How to show a literal sequence of characters. -* var:: How to indicate a metasyntactic variable. -* file:: How to indicate the name of a file. -* dfn:: How to specify a definition. -* cite:: How to refer to a book that is not in Info. -@end menu - -@node Useful Highlighting, code, , Indicating -@ifinfo -@subheading Highlighting Commands are Useful -@end ifinfo - -The highlighting commands can be used to generate 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.@refill - -The commands serve a variety of purposes:@refill - -@table @code -@item @@code@{@var{sample-code}@} -Indicate text that is a literal example of a piece of a program.@refill - -@item @@kbd@{@var{keyboard-characters}@} -Indicate keyboard input.@refill - -@item @@key@{@var{key-name}@} -Indicate the conventional name for a key on a keyboard.@refill - -@item @@samp@{@var{text}@} -Indicate text that is a literal example of a sequence of characters.@refill - -@item @@var@{@var{metasyntactic-variable}@} -Indicate a metasyntactic variable.@refill - -@item @@file@{@var{file-name}@} -Indicate the name of a file.@refill - -@item @@dfn@{@var{term}@} -Indicate the introductory or defining use of a term.@refill - -@item @@cite@{@var{reference}@} -Indicate the name of a book.@refill - -@ignore -@item @@ctrl@{@var{ctrl-char}@} -Use for an @sc{ascii} control character.@refill -@end ignore -@end table - -@node code, kbd, Useful Highlighting, Indicating -@comment node-name, next, previous, up -@subsection @code{@@code}@{@var{sample-code}@} -@findex code - -Use the @code{@@code} command to indicate text that is a piece of a -program and which consists of entire syntactic tokens. Enclose the -text in braces.@refill - -Thus, you should use @code{@@code} for an expression in a program, for -the name of a variable or function used in a program, or for a -keyword. Also, you should use @code{@@code} for the name of a -program, such as @code{diff}, that is a name used in the machine. (You -should write the name of a program in the ordinary text font if you -regard it as a new English word, such as `Emacs' or `Bison'.)@refill - -Use @code{@@code} for environment variables such as @code{TEXINPUTS}, -and other variables.@refill - -Use @code{@@code} for command names in command languages that -resemble programming languages, such as Texinfo or the shell. -For example, @code{@@code} and @code{@@samp} are produced by writing -@samp{@@code@{@@@@code@}} and @samp{@@code@{@@@@samp@}} in the Texinfo -source, respectively.@refill - -Note, however, that you should not use @code{@@code} for shell options -such as @samp{-c} when such options stand alone. (Use @code{@@samp}.) -Also, an entire shell command often looks better if written using -@code{@@samp} rather than @code{@@code}. In this case, the rule is to -choose the more pleasing format.@refill - -It is incorrect to alter the case of a word inside an @code{@@code} -command when it appears at the beginning of a sentence. Most computer -languages are case sensitive. In C, for example, @code{Printf} is -different from the identifier @code{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 written all in lower case, you should -rearrange the sentence.@refill - -Do not use the @code{@@code} command for a string of characters shorter -than a syntactic token. If you are writing about @samp{TEXINPU}, which -is just a part of the name for the @code{TEXINPUTS} environment -variable, you should use @code{@@samp}.@refill - -In particular, you should not use the @code{@@code} command when writing -about the characters used in a token; do not, for example, use -@code{@@code} when you are explaining what letters or printable symbols -can be used in the names of functions. (Use @code{@@samp}.) Also, you -should not use @code{@@code} to mark text that is considered input to -programs unless the input is written in a language that is like a -programming language. For example, you should not use @code{@@code} for -the keystroke commands of GNU Emacs (use @code{@@kbd} instead) although -you may use @code{@@code} for the names of the Emacs Lisp functions that -the keystroke commands invoke.@refill - -In the printed manual, @code{@@code} causes @TeX{} to typeset the -argument in a typewriter face. In the Info file, it causes the Info -formatting commands to use single quotation marks around the text. - -@need 700 -For example, - -@example -Use @@code@{diff@} to compare two files. -@end example - -@noindent -produces this in the printed manual:@refill - -@quotation -Use @code{diff} to compare two files. -@end quotation -@iftex - -@noindent -and this in the Info file:@refill - -@example -Use `diff' to compare two files. -@end example -@end iftex - -@node kbd, key, code, Indicating -@comment node-name, next, previous, up -@subsection @code{@@kbd}@{@var{keyboard-characters}@} -@findex kbd - -Use the @code{@@kbd} command for characters of input to be typed by -users. For example, to refer to the characters @kbd{M-a}, -write@refill - -@example -@@kbd@{M-a@} -@end example - -@noindent -and to refer to the characters @kbd{M-x shell}, write@refill - -@example -@@kbd@{M-x shell@} -@end example - -The @code{@@kbd} command has the same effect as @code{@@code} in Info, -but may produce a different font in a printed manual.@refill - -You can embed another @@-command inside the braces of an @code{@@kbd} -command. Here, for example, is the way to describe a command that -would be described more verbosely as ``press an @samp{r} and then -press the @key{RET} key'':@refill - -@example -@@kbd@{r @@key@{RET@}@} -@end example - -@noindent -This produces: @kbd{r @key{RET}} - -You also use the @code{@@kbd} command if you are spelling out the letters -you type; for example:@refill - -@example -To give the @@code@{logout@} command, -type the characters @@kbd@{l o g o u t @@key@{RET@}@}. -@end example - -@noindent -This produces: - -@quotation -To give the @code{logout} command, -type the characters @kbd{l o g o u t @key{RET}}. -@end quotation - -(Also, this example shows that you can add spaces for clarity. If you -really want to mention a space character as one of the characters of -input, write @kbd{@@key@{SPC@}} for it.)@refill - -@node key, samp, kbd, Indicating -@comment node-name, next, previous, up -@subsection @code{@@key}@{@var{key-name}@} -@findex key - -Use the @code{@@key} command for the conventional name for a key on a -keyboard, as in:@refill - -@example -@@key@{RET@} -@end example - -You can use the @code{@@key} command within the argument of an -@code{@@kbd} command when the sequence of characters to be typed -includes one or more keys that are described by name.@refill - -@need 700 -For example, to produce @kbd{C-x @key{ESC}} you would type:@refill - -@example -@@kbd@{C-x @@key@{ESC@}@} -@end example - -@c bob: this next sentence looks weird, having a semi-colon followed by -@c a colon that ends the "sentence".. --mew -Here is a list of the recommended names for keys; they are all in -upper case:@refill -@cindex Recommended names for keys -@cindex Keys, recommended names -@cindex Names recommended for keys -@cindex Abbreviations for keys - -@quotation -@table @t -@item SPC -Space -@item RET -Return -@item LFD -Linefeed -@item TAB -Tab -@item BS -Backspace -@item ESC -Escape -@item DEL -Delete -@item SFT -Shift -@item CTL -Control -@item META -Meta -@end table -@end quotation - -There are subtleties to handling words like `meta' or `ctl' that are -names of shift keys. When mentioning a character in which the shift -key is used, such as @kbd{Meta-a}, use the @code{@@kbd} command alone; -do not use the @code{@@key} command; but when you are referring to the -shift key in isolation, use the @code{@@key} command. For example, -write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and -@samp{@@key@{META@}} to produce @key{META}. This is because -@kbd{Meta-a} refers to keys that you press on a keyboard, but -@key{META} refers to a key without implying that you press it. In -short, use @code{@@kbd} for what you do, and use @code{@@key} for what -you talk about: ``Press @code{@@kbd@{M-a@}} to move point to the -beginning of the sentence. The @code{@@key@{META@}} key is often in the -lower left of the keyboard.''@refill -@cindex META key - -@node samp, var, key, Indicating -@comment node-name, next, previous, up -@subsection @code{@@samp}@{@var{text}@} -@findex samp - -Use the @code{@@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.@refill - -@example -To match @@samp@{foo@} at the end of the line, -use the regexp @@samp@{foo$@}. -@end example - -@noindent -produces - -@quotation -To match @samp{foo} at the end of the line, use the regexp -@samp{foo$}.@refill -@end quotation - -Any time you are referring to single characters, you should use -@code{@@samp} unless @code{@@kbd} is more appropriate. Use -@code{@@samp} for the names of command-line options. Also, you may use -@code{@@samp} for entire statements in C and for entire shell -commands---in this case, @code{@@samp} often looks better than -@code{@@code}. Basically, @code{@@samp} is a catchall for whatever is -not covered by @code{@@code}, @code{@@kbd}, or @code{@@key}.@refill - -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:@refill - -@example -@group -In English, the vowels are @@samp@{a@}, @@samp@{e@}, -@@samp@{i@}, @@samp@{o@}, @@samp@{u@}, and sometimes -@@samp@{y@}. -@end group -@end example - -@noindent -This produces: - -@quotation -In English, the vowels are @samp{a}, @samp{e}, -@samp{i}, @samp{o}, @samp{u}, and sometimes -@samp{y}. -@end quotation - -@node var, file, samp, Indicating -@comment node-name, next, previous, up -@subsection @code{@@var}@{@var{metasyntactic-variable}@} -@findex var - -Use the @code{@@var} command to indicate metasyntactic variables. A -@dfn{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.@refill - -Do not use @code{@@var} for the names of particular variables in -programming languages. These are specific names from a program, so -@code{@@code} is correct for them. For example, the Lisp variable -@code{texinfo-tex-command} is not a metasyntactic variable; it is -properly formatted using @code{@@code}.@refill - -The effect of @code{@@var} in the Info file is to change the case of -the argument to all upper case; in the printed manual, to italicize it. - -@need 700 -For example, - -@example -To delete file @@var@{filename@}, -type @@code@{rm @@var@{filename@}@}. -@end example - -@noindent -produces - -@quotation -To delete file @var{filename}, type @code{rm @var{filename}}. -@end quotation - -@noindent -(Note that @code{@@var} may appear inside @code{@@code}, -@code{@@samp}, @code{@@file}, etc.)@refill - -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:@refill - -@example -@group -\input texinfo -@@@@setfilename @@var@{info-file-name@} -@@@@settitle @@var@{name-of-manual@} -@end group -@end example - -@noindent -This produces: - -@example -@group -\input texinfo -@@setfilename @var{info-file-name} -@@settitle @var{name-of-manual} -@end group -@end example - -In some documentation styles, metasyntactic variables are shown with -angle brackets, for example:@refill - -@example -@dots{}, type rm <filename> -@end example - -@noindent -However, that is not the style that Texinfo uses. (You can, of -course, modify the sources to @TeX{} and the Info formatting commands -to output the @code{<@dots{}>} format if you wish.)@refill - -@node file, dfn, var, Indicating -@comment node-name, next, previous, up -@subsection @code{@@file}@{@var{file-name}@} -@findex file - -Use the @code{@@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 @code{@@file} -for symbols in a programming language; use @code{@@code}. - -Currently, @code{@@file} is equivalent to @code{@@samp} in its effects. -For example,@refill - -@example -The @@file@{.el@} files are in -the @@file@{/usr/local/emacs/lisp@} directory. -@end example - -@noindent -produces - -@quotation -The @file{.el} files are in -the @file{/usr/local/emacs/lisp} directory. -@end quotation - -@node dfn, cite, file, Indicating -@comment node-name, next, previous, up -@subsection @code{@@dfn}@{@var{term}@} -@findex dfn - -Use the @code{@@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 @code{@@dfn}. The command generates italics in -the printed manual, and double quotation marks in the Info file. For -example:@refill - -@example -Getting rid of a file is called @@dfn@{deleting@} it. -@end example - -@noindent -produces - -@quotation -Getting rid of a file is called @dfn{deleting} it. -@end quotation - -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. - -@node cite, , dfn, Indicating -@comment node-name, next, previous, up -@subsection @code{@@cite}@{@var{reference}@} -@findex cite - -Use the @code{@@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.@refill - -(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. -@xref{xref, , @code{@@xref}}.)@refill -@ignore - -@c node ctrl, , cite, Indicating -@comment node-name, next, previous, up -@c subsection @code{@@ctrl}@{@var{ctrl-char}@} -@findex ctrl - -The @code{@@ctrl} command is seldom used. It describes an @sc{ascii} -control character by inserting the actual character into the Info -file. - -Usually, in Texinfo, you talk what you type as keyboard entry by -describing it with @code{@@kbd}: thus, @samp{@@kbd@{C-a@}} for -@kbd{C-a}. Use @code{@@kbd} in this way when talking about a control -character that is typed on the keyboard by the user. When talking -about a control character appearing in a file or a string, do not use -@code{@@kbd} since the control character is not typed. Also, do not -use @samp{C-} but spell out @code{control-}, as in @samp{control-a}, -to make it easier for a reader to understand.@refill - -@code{@@ctrl} is an idea from the beginnings of Texinfo which may not -really fit in to the scheme of things. But there may be times when -you want to use the command. The pattern is -@code{@@ctrl@{@var{ch}@}}, where @var{ch} is an @sc{ascii} character -whose control-equivalent is wanted. For example, to specify -@samp{control-f}, you would enter@refill - -@example -@@ctrl@{f@} -@end example - -@noindent -produces - -@quotation -@ctrl{f} -@end quotation - -In the Info file, this generates the specified control character, output -literally into the file. This is done so a user can copy the specified -control character (along with whatever else he or she wants) into another -Emacs buffer and use it. Since the `control-h',`control-i', and -`control-j' characters are formatting characters, they should not be -indicated with @code{@@ctrl}.@refill - -In a printed manual, @code{@@ctrl} generates text to describe or -identify that control character: an uparrow followed by the character -@var{ch}.@refill -@end ignore - -@node Emphasis, , Indicating, Marking Text -@comment node-name, next, previous, up -@section Emphasizing Text -@cindex 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{@@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 affect on Info and only one of them, -the @code{@@r} command, has any regular use.@refill - -@menu -* emph & strong:: How to emphasize text in Texinfo. -* Smallcaps:: How to use the small caps font. -* Fonts:: Various font commands for printed output. -@end menu - -@node emph & strong, Smallcaps, , Emphasis -@comment node-name, next, previous, up -@subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@} -@cindex Emphasizing text, font for -@findex emph -@findex strong - -The @code{@@emph} and @code{@@strong} commands are for emphasis; -@code{@@strong} is stronger. In printed output, @code{@@emph} -produces @emph{italics} and @code{@@strong} produces -@strong{bold}.@refill - -@need 800 -For example, - -@example -@group -@@quotation -@@strong@{Caution:@} @@code@{rm * .[^.]*@} removes @@emph@{all@} -files in the directory. -@@end quotation -@end group -@end example - -@iftex -@noindent -produces the following in printed output: - -@quotation -@strong{Caution}: @code{rm * .[^.]*} removes @emph{all} -files in the directory. -@end quotation - -@noindent -and the following in Info: -@end iftex -@ifinfo -@noindent -produces: -@end ifinfo - -@example - *Caution*: `rm * .[^.]*' removes *all* - files in the directory. -@end example - -The @code{@@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 file, both @code{@@emph} and @code{@@strong} put asterisks -around the text.@refill - -@quotation -@strong{Caution:} Do not use @code{@@emph} or @code{@@strong} with the -word @samp{Note}; Info will mistake the combination for a cross -reference. Use a phrase such as @strong{Please note} or -@strong{Caution} instead.@refill -@end quotation - -@node Smallcaps, Fonts, emph & strong, Emphasis -@subsection @code{@@sc}@{@var{text}@}: The Small Caps Font -@cindex Small caps font -@findex sc @r{(small caps font)} - -@iftex -Use the @samp{@@sc} command to set text in the printed output in @sc{a -small caps font} and set text in the Info file in upper case letters.@refill -@end iftex -@ifinfo -Use the @samp{@@sc} command to set text in the printed output in a -small caps font and set text in the Info file in upper case letters.@refill -@end ifinfo - -Write the text between braces in lower case, like this:@refill - -@example -The @@sc@{acm@} and @@sc@{ieee@} are technical societies. -@end example - -@noindent -This produces: - -@display -The @sc{acm} and @sc{ieee} are technical societies. -@end display - -@TeX{} typesets the small caps font in a manner that prevents the -letters from `jumping out at you on the page'. This makes small caps -text easier to read than text in all upper case. The Info formatting -commands set all small caps text in upper case.@refill - -@ifinfo -If the text between the braces of an @code{@@sc} command is upper case, -@TeX{} typesets in full-size capitals. Use full-size capitals -sparingly.@refill -@end ifinfo -@iftex -If the text between the braces of an @code{@@sc} command is upper case, -@TeX{} typesets in @sc{FULL-SIZE CAPITALS}. Use full-size capitals -sparingly.@refill -@end iftex - -You may also use the small caps font for a jargon word such as -@sc{ato} (a @sc{nasa} word meaning `abort to orbit').@refill - -There are subtleties to using the small caps font with a jargon word -such as @sc{cdr}, a word used in Lisp programming. In this case, you -should use the small caps font when the word refers to the second and -subsequent elements of a list (the @sc{cdr} of the list), but you -should use @samp{@@code} when the word refers to the Lisp function of -the same spelling.@refill - -@node Fonts, , Smallcaps, Emphasis -@comment node-name, next, previous, up -@subsection Fonts for Printing, Not Info -@cindex Fonts for printing, not for Info -@findex i @r{(italic font)} -@findex b @r{(bold font)} -@findex t @r{(typewriter font)} -@findex r @r{(Roman font)} - -Texinfo provides four font commands that specify font changes in the -printed manual but have no effect in the Info file. @code{@@i} -requests @i{italic} font (in some versions of @TeX{}, a slanted font -is used), @code{@@b} requests @b{bold} face, @code{@@t} requests the -@t{fixed-width}, typewriter-style font used by @code{@@code}, and @code{@@r} requests a -@r{roman} font, which is the usual font in which text is printed. All -four commands apply to an argument that follows, surrounded by -braces.@refill - -Only the @code{@@r} command has much use: in example programs, you -can use the @code{@@r} command to convert code comments from the -fixed-width font to a roman font. This looks better in printed -output.@refill - -@need 700 -For example, - -@example -@group -@@lisp -(+ 2 2) ; @@r@{Add two plus two.@} -@@end lisp -@end group -@end example - -@noindent -produces - -@lisp -(+ 2 2) ; @r{Add two plus two.} -@end lisp - -If possible, you should avoid using the other three font commands. If -you need to use one, it probably indicates a gap in the Texinfo -language.@refill - -@node Quotations and Examples, Lists and Tables, Marking Text, Top -@comment node-name, next, previous, up -@chapter 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.@refill - -In Texinfo, you always begin a quotation or example by writing an -@@-command at the beginning of a line by itself, and end it by writing -an @code{@@end} command that is also at the beginning of a line by -itself. For instance, you begin an example by writing @code{@@example} -by itself at the beginning of a line and end the example by writing -@code{@@end example} on a line by itself, at the beginning of that -line.@refill -@findex end - -@menu -* Block Enclosing Commands:: Use different constructs for - different purposes. -* quotation:: How to write a quotation. -* example:: How to write an example in a fixed-width font. -* noindent:: How to prevent paragraph indentation. -* Lisp Example:: How to illustrate Lisp code. -* smallexample & smalllisp:: Forms for the @code{@@smallbook} option. -* display:: How to write an example in the current font. -* format:: How to write an example that does not narrow - the margins. -* exdent:: How to undo the indentation of a line. -* flushleft & flushright:: How to push text flushleft or flushright. -* cartouche:: How to draw cartouches around examples. -@end menu - -@node Block Enclosing Commands, quotation, , Quotations and Examples -@section The Block Enclosing Commands - -Here are commands for quotations and examples:@refill - -@table @code -@item @@quotation -Indicate text that is quoted. The text is filled, indented, and -printed in a roman font by default.@refill - -@item @@example -Illustrate code, commands, and the like. The text is printed -in a fixed-width font, and indented but not filled.@refill - -@item @@lisp -Illustrate Lisp code. The text is printed in a fixed-width font, -and indented but not filled.@refill - -@item @@smallexample -Illustrate code, commands, and the like. Similar to -@code{@@example}, except that in @TeX{} this command typesets text in -a smaller font for the smaller @code{@@smallbook} format than for the -8.5 by 11 inch format.@refill - -@item @@smalllisp -Illustrate Lisp code. Similar to @code{@@lisp}, except that -in @TeX{} this command typesets text in a smaller font for the smaller -@code{@@smallbook} format than for the 8.5 by 11 inch format.@refill - -@item @@display -Display illustrative text. The text is indented but not filled, and -no font is specified (so, by default, the font is roman).@refill - -@item @@format -Print illustrative text. The text is not indented and not filled -and no font is specified (so, by default, the font is roman).@refill -@end table - -The @code{@@exdent} command is used within the above constructs to -undo the indentation of a line. - -The @code{@@flushleft} and @code{@@flushright} commands are used to line -up the left or right margins of unfilled text.@refill - -The @code{@@noindent} command may be used after one of the above -constructs to prevent the following text from being indented as a new -paragraph.@refill - -You can use the @code{@@cartouche} command within one of the above -constructs to highlight the example or quotation by drawing a box with -rounded corners around it. (The @code{@@cartouche} command affects -only the printed manual; it has no effect in the Info file; see -@ref{cartouche, , Drawing Cartouches Around Examples}.)@refill - -@node quotation, example, Block Enclosing Commands, Quotations and Examples -@comment node-name, next, previous, up -@section @code{@@quotation} -@cindex Quotations -@findex quotation - -The text of a quotation is -processed normally except that:@refill - -@itemize @bullet -@item -the margins are closer to the center of the page, so the whole of the -quotation is indented;@refill - -@item -the first lines of paragraphs are indented no more than other -lines;@refill - -@item -in the printed output, interparagraph spacing is reduced.@refill -@end itemize - -@quotation -This is an example of text written between an @code{@@quotation} -command and an @code{@@end quotation} command. An @code{@@quotation} -command is most often used to indicate text that is excerpted from -another (real or hypothetical) printed work.@refill -@end quotation - -Write an @code{@@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 @code{@@end quotation}. -The @code{@@end quotation} line will likewise disappear from the -output. Thus, the following,@refill - -@example -@@quotation -This is -a foo. -@@end quotation -@end example - -@noindent -produces - -@quotation -This is a foo. -@end quotation - -@node example, noindent, quotation, Quotations and Examples -@comment node-name, next, previous, up -@section @code{@@example} -@cindex Examples, formatting them -@cindex Formatting examples -@findex example - -The @code{@@example} command is used to indicate an example that is -not part of the running text, such as computer input or output.@refill - -@example -@group -This is an example of text written between an -@code{@@example} command -and an @code{@@end example} command. -The text is indented but not filled. -@end group - -@group -In the printed manual, the text is typeset in a -fixed-width font, and extra spaces and blank lines are -significant. In the Info file, an analogous result is -obtained by indenting each line with five spaces. -@end group -@end example - -Write an @code{@@example} command at the beginning of a line by itself. -This line will disappear from the output. Mark the end of the example -with an @code{@@end example} command, also written at the beginning of a -line by itself. The @code{@@end example} will disappear from the -output.@refill - -@need 700 -For example, - -@example -@@example -mv foo bar -@@end example -@end example - -@noindent -produces - -@example -mv foo bar -@end example - -Since the lines containing @code{@@example} and @code{@@end example} -will disappear, you should put a blank line before the -@code{@@example} and another blank line after the @code{@@end -example}. (Remember that blank lines between the beginning -@code{@@example} and the ending @code{@@end example} will appear in -the output.)@refill - -@quotation -@strong{Caution:} Do not use tabs in the lines of an example (or anywhere -else in Texinfo, for that matter)! @TeX{} treats tabs as single -spaces, and that is not what they look like. This is a problem with -@TeX{}. (If necessary, in Emacs, you can use @kbd{M-x untabify} to -convert tabs in a region to multiple spaces.)@refill -@end quotation - -Examples are often, logically speaking, ``in the middle'' of a -paragraph, and the text continues after an example should not be -indented. The @code{@@noindent} command prevents a piece of text from -being indented as if it were a new paragraph. -@ifinfo -(@xref{noindent}.) -@end ifinfo - -(The @code{@@code} command is used for examples of code that are -embedded within sentences, not set off from preceding and following -text. @xref{code, , @code{@@code}}.) - -@node noindent, Lisp Example, example, Quotations and Examples -@comment node-name, next, previous, up -@section @code{@@noindent} -@findex noindent - -An example or other inclusion can break a paragraph into segments. -Ordinarily, the formatters indent text that follows an example as a new -paragraph. However, you can prevent this by writing @code{@@noindent} -at the beginning of a line by itself preceding the continuation -text.@refill - -@need 750 -For example: - -@example -@group -@@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@}.) -@end group -@end example - -@noindent -produces - -@display -@example -This is an example -@end example -@tex -% Remove extra vskip; this is a kludge to counter the effect of display -\vskip-3.5\baselineskip -@end tex - -@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}.) -@end display - -To adjust the number of blank lines properly in the Info file output, -remember that the line containing @code{@@noindent} does not generate a -blank line, and neither does the @code{@@end example} line.@refill - -In the Texinfo source file for this manual, each line that says -`produces' is preceded by a line containing @code{@@noindent}.@refill - -Do not put braces after an @code{@@noindent} command; they are not -necessary, since @code{@@noindent} is a command used outside of -paragraphs (@pxref{Command Syntax}).@refill - -@node Lisp Example, smallexample & smalllisp, noindent, Quotations and Examples -@comment node-name, next, previous, up -@section @code{@@lisp} -@cindex Lisp example -@findex lisp - -The @code{@@lisp} command is used for Lisp code. It is synonymous -with the @code{@@example} command. - -@lisp -This is an example of text written between an -@code{@@lisp} command and an @code{@@end lisp} command. -@end lisp - -Use @code{@@lisp} instead of @code{@@example} so as 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.@footnote{It would be straightforward to extend Texinfo to -work in a similar fashion for C, @sc{fortran}, or other languages.}@refill - -Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by -itself.@refill - -@node smallexample & smalllisp, display, Lisp Example, Quotations and Examples -@comment node-name, next, previous, up -@section @code{@@smallexample} and @code{@@smalllisp} -@cindex Small book example -@cindex Example for a small book -@cindex Lisp example for a small book -@findex smallexample -@findex smalllisp - -In addition to the regular @code{@@example} and @code{@@lisp} commands, -Texinfo has two other ``example-style'' commands. These are the -@code{@@smallexample} and @code{@@smalllisp} commands. Both these -commands are designed for use with the @code{@@smallbook} command that -causes @TeX{} to produce a printed manual in a 7 by 9.25 inch format -rather than the regular 8.5 by 11 inch format.@refill - -In @TeX{}, the @code{@@smallexample} and @code{@@smalllisp} commands -typeset text in a smaller font for the smaller @code{@@smallbook} -format than for the 8.5 by 11 inch format. Consequently, many examples -containing long lines fit in a narrower, @code{@@smallbook} page -without needing to be shortened. Both commands typeset in the normal -font size when you format for the 8.5 by 11 inch size; indeed, -in this situation, the @code{@@smallexample} and @code{@@smalllisp} -commands are defined to be the @code{@@example} and @code{@@lisp} -commands.@refill - -In Info, the @code{@@smallexample} and @code{@@smalllisp} commands are -equivalent to the @code{@@example} and @code{@@lisp} commands, and work -exactly the same.@refill - -Mark the end of @code{@@smallexample} or @code{@@smalllisp} with -@code{@@end smallexample} or @code{@@end smalllisp}, -respectively.@refill - -@iftex -Here is an example written in the small font used by the -@code{@@smallexample} and @code{@@smalllisp} commands: - -@ifclear smallbook -@display -@tex -% Remove extra vskip; this is a kludge to counter the effect of display -\vskip-3\baselineskip -{\ninett -\dots{} 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.} -@end tex -@end display -@end ifclear -@end iftex -@ifset smallbook -@iftex -@smallexample -This is an example of text written between @code{@@smallexample} and -@code{@@end smallexample}. In Info and in an 8.5 by 11 inch manual, -this text appears in its normal size; but in a 7 by 9.25 inch manual, -this text appears in a smaller font. -@end smallexample -@end iftex -@end ifset -@ifinfo -@smallexample -This is an example of text written between @code{@@smallexample} and -@code{@@end smallexample}. In Info and in an 8.5 by 11 inch manual, -this text appears in its normal size; but in a 7 by 9.25 inch manual, -this text appears in a smaller font. -@end smallexample -@end ifinfo - -The @code{@@smallexample} and @code{@@smalllisp} commands make it -easier to prepare smaller format manuals without forcing you to edit -examples by hand to fit them onto narrower pages.@refill - -As a general rule, a printed document looks better if you write all the -examples in a chapter consistently in @code{@@example} or in -@code{@@smallexample}. Only occasionally should you mix the two -formats.@refill - -@xref{smallbook, , Printing ``Small'' Books}, for more information -about the @code{@@smallbook} command.@refill - -@node display, format, smallexample & smalllisp, Quotations and Examples -@comment node-name, next, previous, up -@section @code{@@display} -@cindex Display formatting -@findex display - -The @code{@@display} command begins a kind of example. It is like the -@code{@@example} command -except that, in -a printed manual, @code{@@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 -@code{@@display} command.@refill - -@display -This is an example of text written between an @code{@@display} command -and an @code{@@end display} command. The @code{@@display} command -indents the text, but does not fill it. -@end display - -@node format, exdent, display, Quotations and Examples -@comment node-name, next, previous, up -@section @code{@@format} -@findex format - -The @code{@@format} command is similar to @code{@@example} except -that, in the printed manual, @code{@@format} does not select the -fixed-width font and does not narrow the margins.@refill - -@format -This is an example of text written between an @code{@@format} command -and an @code{@@end format} command. As you can see -from this example, -the @code{@@format} command does not fill the text. -@end format - -@node exdent, flushleft & flushright, format, Quotations and Examples -@section @code{@@exdent}: Undoing a Line's Indentation -@cindex Indentation undoing -@findex exdent - -The @code{@@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 -@code{@@exdent} line is printed in the roman font.@refill - -@code{@@exdent} is usually used within examples. Thus,@refill - -@example -@group -@@example -This line follows an @@@@example command. -@@exdent This line is exdented. -This line follows the exdented line. -The @@@@end example comes on the next line. -@@end group -@end group -@end example - -@noindent -produces - -@example -@group -This line follows an @@example command. -@exdent This line is exdented. -This line follows the exdented line. -The @@end example comes on the next line. -@end group -@end example - -In practice, the @code{@@exdent} command is rarely used. -Usually, you un-indent text by ending the example and -returning the page to its normal width.@refill - -@node flushleft & flushright, cartouche, exdent, Quotations and Examples -@section @code{@@flushleft} and @code{@@flushright} -@findex flushleft -@findex flushright - -The @code{@@flushleft} and @code{@@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 @code{@@flushleft} and @code{@@flushright} -commands are ended by @code{@@end flushleft} and @code{@@end -flushright} commands on lines of their own.@refill - -@need 800 -For example, - -@example -@group -@@flushleft -This text is -written flushleft. -@@end flushleft -@end group -@end example - -@noindent -produces - -@quotation -@flushleft -This text is -written flushleft. -@end flushleft -@end quotation - - -Flushright produces the type of indentation often used in the return -address of letters.@refill - -@need 800 -@noindent -For example, - -@example -@group -@@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 -@end group -@end example - -@noindent -produces - -@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 - -@node cartouche, , flushleft & flushright, Quotations and Examples -@section Drawing Cartouches Around Examples -@findex cartouche -@cindex Box with rounded corners - -In a printed manual, the @code{@@cartouche} command draws a box with -rounded corners around its contents. 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.@refill - -The @code{@@cartouche} command affects only the printed manual; it has -no effect in the Info file.@refill - -@need 1500 -For example, - -@example -@group -@@example -@@cartouche -% pwd -/usr/local/lib/emacs/info -@@end cartouche -@@end example -@end group -@end example - -@noindent -surrounds the two-line example with a box with rounded corners, in the -printed manual. - -@iftex -In a printed manual, the example looks like this:@refill - -@example -@group -@cartouche -% pwd -/usr/local/lib/emacs/info -@end cartouche -@end group -@end example -@end iftex - -@node Lists and Tables, Indices, Quotations and Examples, Top -@comment node-name, next, previous, up -@chapter Making Lists and Tables -@cindex Making lists and tables -@cindex Lists and tables, making them -@cindex Tables and lists, making them - -Texinfo has several ways of making lists and two-column tables. Lists can -be bulleted or numbered, while two-column tables can highlight the items in -the first column.@refill - -@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. -@end menu - -@ifinfo -@node Introducing Lists, itemize, , Lists and Tables -@heading Introducing Lists -@end ifinfo - -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.@refill - -Numbered lists and tables begin with the appropriate @@-command at the -beginning of a line, and end with the corresponding @code{@@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.@refill - -Begin an enumerated list, for example, with an @code{@@enumerate} -command and end the list with an @code{@@end enumerate} command. -Begin an itemized list with an @code{@@itemize} command, followed on -the same line by a formatting command such as @code{@@bullet}, and end -the list with an @code{@@end itemize} command.@refill -@findex end - -Precede each element of a list with an @code{@@item} or @code{@@itemx} -command.@refill - -@sp 1 -@noindent -Here is an itemized list of the different kinds of table and lists:@refill - -@itemize @bullet -@item -Itemized lists with and without bullets. - -@item -Enumerated lists, using numbers or letters. - -@item -Two-column tables with highlighting. -@end itemize - -@sp 1 -@noindent -Here is an enumerated list with the same items:@refill - -@enumerate -@item -Itemized lists with and without bullets. - -@item -Enumerated lists, using numbers or letters. - -@item -Two-column tables with highlighting. -@end enumerate - -@sp 1 -@noindent -And here is a two-column table with the same items and their -@w{@@-commands}:@refill - -@table @code -@item @@itemize -Itemized lists with and without bullets. - -@item @@enumerate -Enumerated lists, using numbers or letters. - -@item @@table -@itemx @@ftable -@itemx @@vtable -Two-column tables with highlighting. -@end table - -@node itemize, enumerate, Introducing Lists, Lists and Tables -@comment node-name, next, previous, up -@section Making an Itemized List -@cindex Itemization -@findex itemize - -The @code{@@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.@refill - -Begin an itemized list by writing @code{@@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 -@code{@@bullet} after @code{@@itemize}, but you can use -@code{@@minus}, or any character or any special symbol that results in -a single character in the Info file. (When you write @code{@@bullet} -or @code{@@minus} after an @code{@@itemize} command, you may omit the -@samp{@{@}}.)@refill - -Write the text of the indented paragraphs themselves after the -@code{@@itemize}, up to another line that says @code{@@end -itemize}.@refill - -Before each paragraph for which a mark in the margin is desired, write -a line that says just @code{@@item}. Do not write any other text on this -line.@refill -@findex item - -Usually, you should put a blank line before an @code{@@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.@refill - -Here is an example of the use of @code{@@itemize}, followed by the -output it produces. Note that @code{@@bullet} produces an @samp{*} in -Info and a round dot in @TeX{}.@refill - -@example -@group -@@itemize @@bullet -@@item -Some text for foo. - -@@item -Some text -for bar. -@@end itemize -@end group -@end example - -@noindent -This produces: - -@quotation -@itemize @bullet -@item -Some text for foo. - -@item -Some text -for bar. -@end itemize -@end quotation - -Itemized lists may be embedded within other itemized lists. Here is a -list marked with dashes embedded in a list marked with bullets:@refill - -@example -@group -@@itemize @@bullet -@@item -First item. - -@@itemize @@minus -@@item -Inner item. - -@@item -Second inner item. -@@end itemize - -@@item -Second outer item. -@@end itemize -@end group -@end example - -@noindent -This produces: - -@quotation -@itemize @bullet -@item -First item. - -@itemize @minus -@item -Inner item. - -@item -Second inner item. -@end itemize - -@item -Second outer item. -@end itemize -@end quotation - -@node enumerate, Two-column Tables, itemize, Lists and Tables -@comment node-name, next, previous, up -@section Making a Numbered or Lettered List -@cindex Enumeration -@findex enumerate - -@code{@@enumerate} is like @code{@@itemize} except that the marks in -the left margin contain successive integers or letters. -(@xref{itemize, , @code{@@itemize}}.)@refill - -Write the @code{@@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, @code{@@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 @kbd{a} or @kbd{A}, -the command starts the list with that letter.@refill - -Write the text of the enumerated list in the same way you write an -itemized list: put @code{@@item} on a line of its own before the start of -each paragraph that you want enumerated. Do not write any other text on -the line beginning with @code{@@item}.@refill - -You should put a blank line between entries in the list. -This generally makes it easier to read the Info file.@refill - -@need 1500 -Here is an example of @code{@@enumerate} without an argument:@refill - -@example -@group -@@enumerate -@@item -Underlying causes. - -@@item -Proximate causes. -@@end enumerate -@end group -@end example - -@noindent -This produces: - -@enumerate -@item -Underlying causes. - -@item -Proximate causes. -@end enumerate -@sp 1 -Here is an example with an argument of @kbd{3}:@refill -@sp 1 -@example -@group -@@enumerate 3 -@@item -Predisposing causes. - -@@item -Precipitating causes. - -@@item -Perpetuating causes. -@@end enumerate -@end group -@end example - -@noindent -This produces: - -@enumerate 3 -@item -Predisposing causes. - -@item -Precipitating causes. - -@item -Perpetuating causes. -@end enumerate -@sp 1 -Here is a brief summary of the alternatives. The summary is constructed -using @code{@@enumerate} with an argument of @kbd{a}.@refill -@sp 1 -@enumerate a -@item -@code{@@enumerate} - -Without an argument, produce a numbered list, starting with the number -1.@refill - -@item -@code{@@enumerate @var{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.@refill - -@item -@code{@@enumerate @var{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.@refill - -@item -@code{@@enumerate @var{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.@refill -@end enumerate - -You can also nest enumerated lists, as in an outline.@refill - -@node Two-column Tables, , enumerate, Lists and Tables -@comment node-name, next, previous, up -@section Making a Two-column Table -@cindex Tables, making two-column -@findex table - -@code{@@table} is similar to @code{@@itemize}, but the command allows -you to specify a name or heading line for each item. (@xref{itemize, -, @code{@@itemize}}.) The @code{@@table} command is used to produce -two-column tables, and is especially useful for glossaries and -explanatory exhibits.@refill - -@menu -* table:: How to construct a two-column table. -* ftable vtable:: How to construct a two-column table - with automatic indexing. -* itemx:: How to put more entries in the first column. -@end menu - -@ifinfo -@node table, ftable vtable, , Two-column Tables -@subheading Using the @code{@@table} Command - -Use the @code{@@table} command to produce two-column tables.@refill -@end ifinfo - -Write the @code{@@table} command at the beginning of a line and follow -it on the same line with an argument that is a Texinfo command such as -@code{@@code}, @code{@@samp}, @code{@@var}, or @code{@@kbd}. -Although these commands are usually followed by arguments in braces, -in this case you use the command name without an argument because -@code{@@item} will supply the argument. This command will be applied -to the text that goes into the first column of each item and -determines how it will be highlighted. For example, @code{@@samp} -will cause the text in the first column to be highlighted with an -@code{@@samp} command.@refill - -You may also choose to use the @code{@@asis} command as an argument to -@code{@@table}. @code{@@asis} is a command that does nothing; if you use this -command after @code{@@table}, @TeX{} and the Info formatting commands -output the first column entries without added highlighting (`as -is').@refill - -(The @code{@@table} command may work with other commands besides those -listed here. However, you can only use commands -that normally take arguments in braces.)@refill - -Begin each table entry with an @code{@@item} command at the beginning -of a line. Write the first column text on the same line as the -@code{@@item} command. Write the second column text on the line -following the @code{@@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 text on the same line as the @code{@@item} will -be placed in the first column.@refill -@findex item - -Normally, you should put a blank line before an @code{@@item} line. -This puts a blank like in the Info file. Except when the entries are -very brief, a blank line looks better.@refill - -@need 1500 -The following table, for example, highlights the text in the first -column with an @code{@@samp} command:@refill - -@example -@group -@@table @@samp -@@item foo -This is the text for -@@samp@{foo@}. - -@@item bar -Text for @@samp@{bar@}. -@@end table -@end group -@end example - -@noindent -This produces: - -@table @samp -@item foo -This is the text for -@samp{foo}. -@item bar -Text for @samp{bar}. -@end table - -If you want to list two or more named items with a single block of -text, use the @code{@@itemx} command. (@xref{itemx, , -@code{@@itemx}}.)@refill - -@node ftable vtable, itemx, table, Two-column Tables -@comment node-name, next, previous, up -@subsection @code{@@ftable} and @code{@@vtable} -@cindex Tables with indexes -@cindex Indexing table entries automatically -@findex ftable -@findex vtable - -The @code{@@ftable} and @code{@@vtable} commands are the same as the -@code{@@table} command except that @code{@@ftable} automatically enters -each of the items in the first column of the table into the index of -functions and @code{@@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 @code{@@item} commands are indexed, and they are indexed in -exactly the form that they appear on that line. @xref{Indices, , -Creating Indices}, for more information about indices.@refill - -Begin a two-column table using @code{@@ftable} or @code{@@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{@@code}, -exactly as you would for an @code{@@table} command; and end the table -with an @code{@@end ftable} or @code{@@end vtable} command on a line by -itself. - -@node itemx, , ftable vtable, Two-column Tables -@comment node-name, next, previous, up -@subsection @code{@@itemx} -@cindex Two named items for @code{@@table} -@findex itemx - -Use the @code{@@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 @code{@@itemx} for all but the first -entry. The @code{@@itemx} command works exactly like @code{@@item} -except that it does not generate extra vertical space above the first -column text.@refill - -@need 1000 -For example, - -@example -@group -@@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 -@end group -@end example - -@noindent -This produces: - -@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.@refill -@end table - -@noindent -(Note also that this example illustrates multi-line supporting text in -a two-column table.)@refill - -@node Indices, Insertions, Lists and Tables, Top -@comment node-name, next, previous, up -@chapter Creating Indices -@cindex Indices -@cindex Creating 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.@refill - -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. If you wish, you can define your own indices.@refill - -@menu -* Index Entries:: Choose different words for index entries. -* Predefined Indices:: Use different indices for different kinds - of entry. -* Indexing Commands:: How to make an index entry. -* Combining Indices:: How to combine indices. -* New Indices:: How to define your own indices. -@end menu - -@node Index Entries, Predefined Indices, , Indices -@comment node-name, next, previous, up -@section Making Index Entries -@cindex Index entries, making -@cindex Entries, making index - -When you are making index entries, it is good practice to think of the -different ways people may look for something. Different people -@emph{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.@refill - -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.@refill - -@xref{Printing Indices & Menus}, for information about printing an index -at the end of a book or creating an index menu in an Info file.@refill - -@node Predefined Indices, Indexing Commands, Index Entries, Indices -@comment node-name, next, previous, up -@section Predefined Indices - -Texinfo provides six predefined indices:@refill - -@itemize @bullet -@item -A @dfn{concept index} listing concepts that are discussed.@refill - -@item -A @dfn{function index} listing functions (such as entry points of -libraries).@refill - -@item -A @dfn{variables index} listing variables (such as global variables -of libraries).@refill - -@item -A @dfn{keystroke index} listing keyboard commands.@refill - -@item -A @dfn{program index} listing names of programs.@refill - -@item -A @dfn{data type index} listing data types (such as structures defined in -header files).@refill -@end itemize - -@noindent -Not every manual needs all of these, and most manuals use two or three -of them. This manual 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). Two or -more indices can be combined into one using the @code{@@synindex} or -@code{@@syncodeindex} commands. @xref{Combining Indices}.@refill - -@node Indexing Commands, Combining Indices, Predefined Indices, Indices -@comment node-name, next, previous, up -@section Defining the Entries of an Index -@cindex Defining indexing entries -@cindex Index entries -@cindex Entries for an index -@cindex Specifying index entries -@cindex Creating index entries - -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.@refill - -An index entry consists of an indexing command at the beginning of a -line followed, on the rest of the line, by the entry.@refill - -For example, this section begins with the following five entries for -the concept index:@refill - -@example -@@cindex Defining indexing entries -@@cindex Index entries -@@cindex Entries for an index -@@cindex Specifying index entries -@@cindex Creating index entries -@end example - -Each predefined index has its own indexing command---@code{@@cindex} -for the concept index, @code{@@findex} for the function index, and so -on.@refill - -@cindex Capitalizing index entries -@cindex Index entry capitalization -The usual convention is to capitalize the first word of each index -entry, unless that word is the name of a function, variable, or other -such entity that should not be capitalized. Thus, if you are -documenting Emacs Lisp, you should usually capitalize entries in -the concept index, but not those in the function index. -However, if your -concept index entries are consistently short (one or two words each) -it may look better for each regular entry to start with a lower case -letter. Whichever convention you adapt, please be consistent! - -By default, entries for a concept index are printed in a small roman -font and entries for the other indices are printed in a small -@code{@@code} font. You may change the way part of an entry is -printed with the usual Texinfo commands, such as @code{@@file} for -file names and @code{@@emph} for emphasis (@pxref{Marking -Text}).@refill -@cindex Index font types - -@cindex Predefined indexing commands -@cindex Indexing commands, predefined -The six indexing commands for predefined indices are: - -@table @code -@item @@cindex @var{concept} -@findex cindex -Make an entry in the concept index for @var{concept}.@refill - -@item @@findex @var{function} -@findex findex -Make an entry in the function index for @var{function}.@refill - -@item @@vindex @var{variable} -@findex vindex -Make an entry in the variable index for @var{variable}.@refill - -@item @@kindex @var{keystroke} -@findex kindex -Make an entry in the key index for @var{keystroke}.@refill - -@item @@pindex @var{program} -@findex pindex -Make an entry in the program index for @var{program}.@refill - -@item @@tindex @var{data type} -@findex tindex -Make an entry in the data type index for @var{data type}.@refill -@end table - -@quotation -@strong{Caution:} Do not use a colon in an index entry. In Info, a -colon separates the menu entry name from the node name. An extra -colon confuses Info. -@xref{Menu Parts, , The Parts of a Menu}, -for more information about the structure of a menu entry.@refill -@end quotation - -If you write several identical index entries in different places in a -Texinfo file, the index in the printed manual will list all the pages to -which those entries refer. However, the index in the Info file will -list @strong{only} the node that references the @strong{first} of those -index entries. Therefore, it is best to write indices in which each -entry refers to only one place in the Texinfo file. Fortunately, this -constraint is a feature rather than a loss since it means that the index -will be easy to use. Otherwise, you could create an index that lists -several pages for one entry and your reader would not know to which page -to turn. If you have two identical entries for one topic, change the -topics slightly, or qualify them to indicate the difference.@refill - -You are not actually required to use the predefined indices for their -canonical purposes. For example, suppose you wish to index some C -preprocessor macros. You could put them in the function index along -with actual functions, just by writing @code{@@findex} 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. Or you could put the macros in -with the data types by writing @code{@@tindex} commands for them, and -give that index a suitable title so the reader will understand. -(@xref{Printing Indices & Menus}.)@refill - -@node Combining Indices, New Indices, Indexing Commands, Indices -@comment node-name, next, previous, up -@section Combining Indices -@cindex Combining indices -@cindex Indices, combining them - -Sometimes you will want to combine two disparate indices such as functions -and concepts, perhaps because you have few enough of one of them that -a separate index for them would look silly.@refill - -You could put functions into the concept index by writing -@code{@@cindex} commands for them instead of @code{@@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{@@code}.@refill - -@menu -* syncodeindex:: How to merge two indices, using @code{@@code} - font for the merged-from index. -* synindex:: How to merge two indices, using the - default font of the merged-to index. -@end menu - -@node syncodeindex, synindex, , Combining Indices -@subsubsection @code{@@syncodeindex} -@findex syncodeindex - -When you want to combine functions and concepts into one index, you -should index the functions with @code{@@findex} and index the concepts -with @code{@@cindex}, and use the @code{@@syncodeindex} command to -redirect the function index entries into the concept index.@refill -@findex syncodeindex - -The @code{@@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:@refill - -@example -@@syncodeindex @var{from} @var{to} -@end example - -@cindex Predefined names for indices -@cindex Two letter names for indices -@cindex Indices, two letter names -@cindex Names for indices -For this purpose, the indices are given two-letter names:@refill - -@table @samp -@item cp -concept index -@item fn -function index -@item vr -variable index -@item ky -key index -@item pg -program index -@item tp -data type index -@end table - -Write an @code{@@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:@refill - -@example -@@syncodeindex fn cp -@end example - -@noindent -This will cause all entries designated for the function index to merge -in with the concept index instead.@refill - -To merge both a variables index and a function index into a concept -index, write the following:@refill - -@example -@group -@@syncodeindex vr cp -@@syncodeindex fn cp -@end group -@end example - -@cindex Fonts for indices -The @code{@@syncodeindex} command puts all the entries from the `from' -index (the redirected index) into the @code{@@code} font, overriding -whatever default font is used by the index to which the entries are -now directed. This way, if you direct function names from a function -index into a concept index, all the function names are printed in the -@code{@@code} font as you would expect.@refill - -@node synindex, , syncodeindex, Combining Indices -@subsubsection @code{@@synindex} -@findex synindex - -The @code{@@synindex} command is nearly the same as the -@code{@@syncodeindex} command, except that it does not put the -`from' index entries into the @code{@@code} font; rather it puts -them in the roman font. Thus, you use @code{@@synindex} when you -merge a concept index into a function index.@refill - -@xref{Printing Indices & Menus}, for information about printing an index -at the end of a book or creating an index menu in an Info file.@refill - -@node New Indices, , Combining Indices, Indices -@section Defining New Indices -@cindex Defining new indices -@cindex Indices, defining new -@cindex New index defining -@findex defindex -@findex defcodeindex - -In addition to the predefined indices, you may use the -@code{@@defindex} and @code{@@defcodeindex} commands to define new -indices. These commands create new indexing @@-commands with which -you mark index entries. The @code{@@defindex }command is used like -this:@refill - -@example -@@defindex @var{name} -@end example - -The name of an index should be a two letter word, such as @samp{au}. -For example:@refill - -@example -@@defindex au -@end example - -This defines a new index, called the @samp{au} index. At the same -time, it creates a new indexing command, @code{@@auindex}, that you -can use to make index entries. Use the new indexing command just as -you would use a predefined indexing command.@refill - -For example, here is a section heading followed by a concept index -entry and two @samp{au} index entries.@refill - -@example -@@section Cognitive Semantics -@@cindex kinesthetic image schemas -@@auindex Johnson, Mark -@@auindex Lakoff, George -@end example - -@noindent -(Evidently, @samp{au} serves here as an abbreviation for ``author''.) -Texinfo constructs the new indexing command by concatenating the name -of the index with @samp{index}; thus, defining an @samp{au} index -leads to the automatic creation of an @code{@@auindex} command.@refill - -Use the @code{@@printindex} command to print the index, as you do with -the predefined indices. For example:@refill - -@example -@group -@@node Author Index, Subject Index, , Top -@@unnumbered Author Index - -@@printindex au -@end group -@end example - -The @code{@@defcodeindex} is like the @code{@@defindex} command, except -that, in the printed output, it prints entries in an @code{@@code} font -instead of a roman font. Thus, it parallels the @code{@@findex} command -rather than the @code{@@cindex} command.@refill - -You should define new indices within or right after the end-of-header -line of a Texinfo file, before any @code{@@synindex} or -@code{@@syncodeindex} commands (@pxref{Header}).@refill - -@node Insertions, Glyphs, Indices, Top -@comment node-name, next, previous, up -@chapter Special Insertions -@cindex Inserting special characters and symbols -@cindex Special insertions - -Texinfo provides several commands for formatting dimensions, for -inserting single characters that have special meaning in Texinfo, such -as braces, and for inserting special graphic symbols that do not -correspond to characters, such as dots and bullets.@refill - -@iftex -These are: - -@itemize @bullet -@item -Braces, @samp{@@} and periods. - -@item -Format a dimension, such as @samp{12@dmn{pt}}. - -@item -Dots and bullets. - -@item -The @TeX{} logo and the copyright symbol. - -@item -A minus sign. -@end itemize -@end iftex - -@menu -* Braces Atsigns Periods:: How to insert braces, @samp{@@} and periods. -* dmn:: How to format a dimension. -* Dots Bullets:: How to insert dots and bullets. -* TeX and copyright:: How to insert the @TeX{} logo - and the copyright symbol. -* minus:: How to insert a minus sign. -@end menu - -@node Braces Atsigns Periods, dmn, , Insertions -@comment node-name, next, previous, up -@section Inserting @samp{@@}, Braces, and Periods -@cindex Inserting @@, braces, and periods -@cindex Braces, inserting -@cindex Periods, inserting -@cindex Single characters, commands to insert -@cindex Commands to insert single characters - -@samp{@@} and curly braces are special characters in Texinfo. To -insert these characters so they appear in text, you must put an @samp{@@} in front -of these characters to prevent Texinfo from misinterpreting them.@refill - -Periods are also special. Depending on whether the period 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 for -Texinfo 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.)@refill - -Do not put braces after any of these commands; they are not -necessary.@refill - -@menu -* Inserting An Atsign:: -* Inserting Braces:: How to insert @samp{@{} and @samp{@}} -* Controlling Spacing:: How to insert the right amount of space - after punctuation within a sentence. -@end menu - -@node Inserting An Atsign, Inserting Braces, , Braces Atsigns Periods -@comment node-name, next, previous, up -@subsection Inserting @samp{@@} with @@@@ -@findex @@ @r{(single @samp{@@})} - -@code{@@@@} stands for a single @samp{@@} in either printed or Info -output.@refill - -Do not put braces after an @code{@@@@} command.@refill - -@node Inserting Braces, Controlling Spacing, Inserting An Atsign, Braces Atsigns Periods -@comment node-name, next, previous, up -@subsection Inserting @samp{@{} and @samp{@}}with @@@{ and @@@} -@findex @{ @r{(single @samp{@{})} -@findex @} @r{(single @samp{@}})} - -@code{@@@{} stands for a single @samp{@{} in either printed or Info -output.@refill - -@code{@@@}} stands for a single @samp{@}} in either printed or Info -output.@refill - -Do not put braces after either an @code{@@@{} or an @code{@@@}} -command.@refill - -@node Controlling Spacing, , Inserting Braces, Braces Atsigns Periods -@comment node-name, next, previous, up -@subsection Spacing After Colons and Periods -@findex : @r{(suppress widening)} - -Use the @code{@@:}@: command after a period, question mark, -exclamation mark, or colon that should not be followed by extra space. -For example, use @code{@@:}@: after periods that end abbreviations -which are not at the ends of sentences. @code{@@:}@: has no effect on -the Info file output.@refill - -@need 700 -For example, - -@example -The s.o.p.@@: has three parts @dots{} -The s.o.p. has three parts @dots{} -@end example - -@noindent -@ifinfo -produces -@end ifinfo -@iftex -produces the following. If you look carefully at this printed output, -you will see a little more whitespace after @samp{s.o.p.} in the second -line.@refill -@end iftex - -@quotation -The s.o.p.@: has three parts @dots{}@* -The s.o.p. has three parts @dots{} -@end quotation - -@noindent -@kbd{@@:} has no effect on the Info output. (@samp{s.o.p} is an acronym -for ``Standard Operating Procedure''.) - -@findex . @r{(true end of sentence)} -Use @code{@@.}@: instead of a period at the end of a sentence that -ends with a single 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:@refill - -@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. -@end example - -@noindent -@ifinfo -produces -@end ifinfo -@iftex -produces the following. If you look carefully at this printed output, -you will see a little more whitespace after the @samp{W} in the first -line.@refill -@end iftex - -@quotation -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. -@end quotation - -In the Info file output, @code{@@.}@: is equivalent to a simple -@samp{.}.@refill - -The meanings of @code{@@:}@: and @code{@@.}@: in Texinfo are designed -to work well with the Emacs sentence motion commands. This made it -necessary for them to be incompatible with some other formatting -systems that use @@-commands.@refill - -Do not put braces after either an @code{@@:} or an @code{@@.} command.@refill - -@node dmn, Dots Bullets, Braces Atsigns Periods, Insertions -@section @code{@@dmn}@{@var{dimension}@}: Format a Dimension -@cindex Thin space between number, dimension -@cindex Dimension formatting -@cindex Format a dimension -@findex dmn - -At times, you may want to write @samp{12@dmn{pt}} or -@samp{8.5@dmn{in}} with little or no space between the number and the -abbreviation for the dimension. You can use the @code{@@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.@refill - -To use the @code{@@dmn} command, write the number and then follow it -immediately, with no intervening space, by @code{@@dmn}, and then by -the dimension within braces.@refill - -@need 700 -@noindent -For example, - -@example -A4 paper is 8.27@@dmn@{in@} wide. -@end example - -@noindent -produces - -@quotation -A4 paper is 8.27@dmn{in} wide. -@end quotation - -Not everyone uses this style. Instead of writing -@w{@samp{8.27@@dmn@{in@}}} in the Texinfo file, you may write -@w{@samp{8.27 in.}} or @w{@samp{8.27 inches}}. (In these cases, the -formatters may insert a line break between the number and the -dimension. Also, if you write a period after an abbreviation within a -sentence, you should write @samp{@@:} after the period to prevent -@TeX{} from inserting extra whitespace. @xref{Controlling Spacing, , -Spacing After Colons and Periods}.)@refill - -@node Dots Bullets, TeX and copyright, dmn, Insertions -@comment node-name, next, previous, up -@section Inserting Ellipsis, Dots, and Bullets -@cindex Dots, inserting -@cindex Bullets, inserting -@cindex Ellipsis, inserting -@cindex Inserting ellipsis -@cindex Inserting dots -@cindex Special typesetting commands -@cindex Typesetting commands for dots, etc. - -An @dfn{ellipsis} (a line of dots) is not typeset as a string of -periods, so a special command is used for ellipsis in Texinfo. The -@code{@@bullet} command is special, too. Each of these commands is -followed by a pair of braces, @samp{@{@}}, without any whitespace -between the name of the command and the braces. (You need to use braces -with these commands because you can use them next to other text; without -the braces, the formatters would be confused. @xref{Command Syntax, , -@@-Command Syntax}, for further information.)@refill - -@menu -* dots:: How to insert dots @dots{} -* bullet:: How to insert a bullet. -@end menu - -@node dots, bullet, , Dots Bullets -@comment node-name, next, previous, up -@subsection @code{@@dots}@{@} -@findex dots -@cindex Inserting dots -@cindex Dots, inserting - -Use the @code{@@dots@{@}} command to generate an ellipsis, which is -three dots in a row, appropriately spaced, like this: `@dots{}'. 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.@refill - -@iftex -Here is an ellipsis: @dots{} - -Here are three periods in a row: ... - -In printed output, the three periods in a row are closer together than -the dots in the ellipsis. -@end iftex - -@node bullet, , dots, Dots Bullets -@comment node-name, next, previous, up -@subsection @code{@@bullet}@{@} -@findex bullet - -Use the @code{@@bullet@{@}} command to generate a large round dot, or -the closest possible thing to one. In Info, an asterisk is used.@refill - -Here is a bullet: @bullet{} - -When you use @code{@@bullet} in @code{@@itemize}, you do not need to -type the braces, because @code{@@itemize} supplies them. @xref{itemize}.@refill - -@node TeX and copyright, minus, Dots Bullets, Insertions -@comment node-name, next, previous, up -@section Inserting @TeX{} and the Copyright Symbol - -The logo `@TeX{}' is typeset in a special fashion and it needs an -@@-command. The copyright symbol, `@copyright{}', is also special. -Each of these commands is followed by a pair of braces, @samp{@{@}}, -without any whitespace between the name of the command and the -braces.@refill - -@menu -* tex:: How to insert the @TeX{} logo. -* copyright symbol:: How to use @code{@@copyright}@{@}. -@end menu - -@node tex, copyright symbol, , TeX and copyright -@comment node-name, next, previous, up -@subsection @code{@@TeX}@{@} -@findex tex (command) - -Use the @code{@@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 @samp{TeX}. The -@code{@@TeX@{@}} command is unique among Texinfo commands in that the -@key{T} and the @key{X} are in upper case.@refill - -@node copyright symbol, , tex, TeX and copyright -@comment node-name, next, previous, up -@subsection @code{@@copyright}@{@} -@findex copyright - -Use the @code{@@copyright@{@}} command to generate `@copyright{}'. In -a printed manual, this is a @samp{c} inside a circle, and in Info, -this is @samp{(C)}.@refill - -@node minus, , TeX and copyright, Insertions -@section @code{@@minus}@{@}: Inserting a Minus Sign -@findex minus - -Use the @code{@@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.@refill - -You can compare the two forms: - -@display -@samp{@minus{}} is a minus sign generated with @samp{@@minus@{@}}, - -`-' is a hyphen generated with the character @samp{-}. -@end display - -@noindent -In the fixed-width font used by Info, @code{@@minus@{@}} is the same -as a hyphen.@refill - -You should not use @code{@@minus@{@}} inside @code{@@code} or -@code{@@example} because the width distinction is not made in the -fixed-width font they use.@refill - -When you use @code{@@minus} to specify the mark beginning each entry in -an itemized list, you do not need to type the braces -(@pxref{itemize}).@refill - -@node Glyphs, Breaks, Insertions, Top -@comment node-name, next, previous, up -@chapter Glyphs for Examples -@cindex Glyphs - -In Texinfo, code is often illustrated in examples that are delimited -by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and -@code{@@end lisp}. In such examples, you can indicate the results of -evaluation or an expansion using @samp{@result{}} or -@samp{@expansion{}}. Likewise, there are commands to insert glyphs -to indicate -printed output, error messages, equivalence of expressions, and the -location of point.@refill - -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.@refill - -@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. -@end menu - -@node Glyphs Summary, result, , Glyphs -@ifinfo -@heading Glyphs Summary - -Here are the different glyph commands:@refill -@end ifinfo - -@table @asis -@item @result{} -@code{@@result@{@}} points to the result of an expression.@refill - -@item @expansion{} -@code{@@expansion@{@}} shows the results of a macro expansion.@refill - -@item @print{} -@code{@@print@{@}} indicates printed output.@refill - -@item @error{} -@code{@@error@{@}} indicates that the following text is an error -message.@refill - -@item @equiv{} -@code{@@equiv@{@}} indicates the exact equivalence of two forms.@refill - -@item @point{} -@code{@@point@{@}} shows the location of point.@refill -@end table - -@node result, expansion, Glyphs Summary, Glyphs -@section @result{}: Indicating Evaluation -@cindex Result of an expression -@cindex Indicating evaluation -@cindex Evaluation glyph -@cindex Value of an expression, indicating - -Use the @code{@@result@{@}} command to indicate the result of -evaluating an expression.@refill - -@iftex -The @code{@@result@{@}} command is displayed as @samp{=>} in Info and -as @samp{@result{}} in the printed output. -@end iftex -@ifinfo -The @code{@@result@{@}} command is displayed as @samp{@result{}} in Info -and as a double stemmed arrow in the printed output.@refill -@end ifinfo - -Thus, the following, - -@lisp -(cdr '(1 2 3)) - @result{} (2 3) -@end lisp - -@noindent -may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''. - -@node expansion, Print Glyph, result, Glyphs -@section @expansion{}: Indicating an Expansion -@cindex Expansion, indicating it - -When an expression is a macro call, it expands into a new expression. -You can indicate the result of the expansion with the -@code{@@expansion@{@}} command.@refill - -@iftex -The @code{@@expansion@{@}} command is displayed as @samp{==>} in Info and -as @samp{@expansion{}} in the printed output. -@end iftex -@ifinfo -The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}} -in Info and as a long arrow with a flat base in the printed output.@refill -@end ifinfo - -@need 700 -For example, the following - -@example -@group -@@lisp -(third '(a b c)) - @@expansion@{@} (car (cdr (cdr '(a b c)))) - @@result@{@} c -@@end lisp -@end group -@end example - -@noindent -produces - -@lisp -@group -(third '(a b c)) - @expansion{} (car (cdr (cdr '(a b c)))) - @result{} c -@end group -@end lisp - -@noindent -which may be read as: - -@quotation -@code{(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))}; -the result of evaluating the expression is @code{c}. -@end quotation - -@noindent -Often, as in this case, an example looks better if the -@code{@@expansion@{@}} and @code{@@result@{@}} commands are indented -five spaces.@refill - -@node Print Glyph, Error Glyph, expansion, Glyphs -@section @print{}: Indicating Printed Output -@cindex Printed output, indicating it - -Sometimes an expression will print output during its execution. You -can indicate the printed output with the @code{@@print@{@}} command.@refill - -@iftex -The @code{@@print@{@}} command is displayed as @samp{-|} in Info and -as @samp{@print{}} in the printed output. -@end iftex -@ifinfo -The @code{@@print@{@}} command is displayed as @samp{@print{}} in Info -and similarly, as a horizontal dash butting against a vertical bar, in -the printed output.@refill -@end ifinfo - -In the following example, the printed text is indicated with -@samp{@print{}}, and the value of the expression follows on the -last line.@refill - -@lisp -@group -(progn (print 'foo) (print 'bar)) - @print{} foo - @print{} bar - @result{} bar -@end group -@end lisp - -@noindent -In a Texinfo source file, this example is written as follows: - -@lisp -@group -@@lisp -(progn (print 'foo) (print 'bar)) - @@print@{@} foo - @@print@{@} bar - @@result@{@} bar -@@end lisp -@end group -@end lisp - -@node Error Glyph, Equivalence, Print Glyph, Glyphs -@section @error{}: Indicating an Error Message -@cindex Error message, indicating it - -A piece of code may cause an error when you evaluate it. You can -designate the error message with the @code{@@error@{@}} command.@refill - -@iftex -The @code{@@error@{@}} command is displayed as @samp{error-->} in Info -and as @samp{@error{}} in the printed output. -@end iftex -@ifinfo -The @code{@@error@{@}} command is displayed as @samp{@error{}} in Info -and as the word `error' in a box in the printed output.@refill -@end ifinfo - -@need 700 -Thus, - -@example -@@lisp -(+ 23 'x) -@@error@{@} Wrong type argument: integer-or-marker-p, x -@@end lisp -@end example - -@noindent -produces - -@lisp -(+ 23 'x) -@error{} Wrong type argument: integer-or-marker-p, x -@end lisp - -@noindent -This indicates that the following error message is printed -when you evaluate the expression: - -@lisp -Wrong type argument: integer-or-marker-p, x -@end lisp - -Note that @samp{@error{}} itself is not part of the error -message. - -@node Equivalence, Point Glyph, Error Glyph, Glyphs -@section @equiv{}: Indicating Equivalence -@cindex Equivalence, indicating it - -Sometimes two expressions produce identical results. You can indicate the -exact equivalence of two forms with the @code{@@equiv@{@}} command.@refill - -@iftex -The @code{@@equiv@{@}} command is displayed as @samp{==} in Info and -as @samp{@equiv{}} in the printed output. -@end iftex -@ifinfo -The @code{@@equiv@{@}} command is displayed as @samp{@equiv{}} in Info -and as a three parallel horizontal lines in the printed output.@refill -@end ifinfo - -Thus, - -@example -@@lisp -(make-sparse-keymap) @@equiv@{@} (list 'keymap) -@@end lisp -@end example - -@noindent -produces - -@lisp -(make-sparse-keymap) @equiv{} (list 'keymap) -@end lisp - -@noindent -This indicates that evaluating @code{(make-sparse-keymap)} produces -identical results to evaluating @code{(list 'keymap)}. - -@c Cannot write point command here because it causes trouble with TOC. -@node Point Glyph, , Equivalence, Glyphs -@section Indicating Point in a Buffer -@cindex Point, indicating it 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.@refill - -You can use the @samp{@@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 @emph{between} -two characters where point is located.)@refill - -@iftex -The @code{@@point@{@}} command is displayed as @samp{-!-} in Info and -as @samp{@point{}} in the printed output. -@end iftex -@ifinfo -The @code{@@point@{@}} command is displayed as @samp{@point{}} in Info -and as a small five pointed star in the printed output.@refill -@end ifinfo - -The following example shows the contents of buffer @file{foo} before -and after evaluating a Lisp command to insert the word @code{changed}.@refill - -@example -@group ----------- Buffer: foo ---------- -This is the @point{}contents of foo. ----------- Buffer: foo ---------- - -@end group -@end example - -@example -@group -(insert "changed ") - @result{} nil ----------- Buffer: foo ---------- -This is the changed @point{}contents of foo. ----------- Buffer: foo ---------- - -@end group -@end example - -In a Texinfo source file, the example is written like this:@refill - -@example -@@example ----------- Buffer: foo ---------- -This is the @@point@{@}contents of foo. ----------- Buffer: foo ---------- - -(insert "changed ") - @@result@{@} nil ----------- Buffer: foo ---------- -This is the changed @@point@{@}contents of foo. ----------- Buffer: foo ---------- -@@end example -@end example - -@node Breaks, Definition Commands, Glyphs, Top -@comment node-name, next, previous, up -@chapter Making and Preventing Breaks -@cindex Making line and page breaks -@cindex Preventing line and page 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.@refill - -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.@refill - -@menu -* Break Commands:: Cause and prevent splits. -* Line Breaks:: How to force a single line to use two lines. -* w:: How to prevent unwanted line breaks. -* sp:: How to insert blank lines. -* page:: How to force the start of a new page. -* group:: How to prevent unwanted page breaks. -* need:: Another way to prevent unwanted page breaks. -@end menu - -@ifinfo -@node Break Commands, Line Breaks, , Breaks -@heading The Break Commands -@end ifinfo -@iftex -@sp 1 -@end iftex - -The break commands create line and paragraph breaks:@refill - -@table @code -@item @@* -Force a line break. - -@item @@sp @var{n} -Skip @var{n} blank lines.@refill -@end table -@iftex -@sp 1 -@end iftex - -The line-break-prevention command holds text together all on one -line:@refill - -@table @code -@item @@w@{@var{text}@} -Prevent @var{text} from being split and hyphenated across two lines.@refill -@end table -@iftex -@sp 1 -@end iftex - -The pagination commands apply only to printed output, since Info -files do not have pages.@refill - -@table @code -@item @@page -Start a new page in the printed manual.@refill - -@item @@group -Hold text together that must appear on one printed page.@refill - -@item @@need @var{mils} -Start a new printed page if not enough space on this one.@refill -@end table - -@node Line Breaks, w, Break Commands, Breaks -@comment node-name, next, previous, up -@section @code{@@*}: Generate Line Breaks -@findex * @r{(force line break)} -@cindex Line breaks -@cindex Breaks in a line - -The @code{@@*} command forces a line break in both the printed manual and -in Info.@refill - -@need 700 -For example, - -@example -This line @@* is broken @@*in two places. -@end example - -@noindent -produces - -@example -@group -This line - is broken -in two places. -@end group -@end example - -@noindent -(Note that the space after the first @code{@@*} command is faithfully -carried down to the next line.)@refill - -@need 800 -The @code{@@*} command is often used in a file's copyright page:@refill - -@example -@group -This is edition 2.0 of the Texinfo documentation,@@* -and is for @dots{} -@end group -@end example - -@noindent -In this case, the @code{@@*} command keeps @TeX{} from stretching the -line across the whole page in an ugly manner.@refill - -@quotation -@strong{Please note:} Do not write braces after an @code{@@*} command; -they are not needed.@refill - -Do not write an @code{@@refill} command at the end of a paragraph -containing an @code{@@*} command; it will cause the paragraph to be -refilled after the line break occurs, negating the effect of the line -break.@refill -@end quotation - -@node w, sp, Line Breaks, Breaks -@comment node-name, next, previous, up -@section @code{@@w}@{@var{text}@}: Prevent Line Breaks -@findex w @r{(prevent line break)} -@cindex Line breaks, preventing - -@code{@@w@{@var{text}@}} outputs @var{text} and prohibits line breaks -within @var{text}.@refill - -You can use the @code{@@w} command to prevent @TeX{} from automatically -hyphenating a long name or phrase that accidentally falls near the end -of a line.@refill - -@example -You can copy GNU software from @@w@{@@file@{prep.ai.mit.edu@}@}. -@end example - -@noindent -produces - -@quotation -You can copy GNU software from @w{@file{prep.ai.mit.edu}}. -@end quotation - -In the Texinfo file, you must write the @code{@@w} command and its -argument (all the affected text) all on one line.@refill - -@quotation -@strong{Caution:} Do not write an @code{@@refill} command at the end -of a paragraph containing an @code{@@w} command; it will cause the -paragraph to be refilled and may thereby negate the effect of the -@code{@@w} command.@refill -@end quotation - -@node sp, page, w, Breaks -@comment node-name, next, previous, up -@section @code{@@sp} @var{n}: Insert Blank Lines -@findex sp @r{(line spacing)} -@cindex Spaces (blank lines) -@cindex Blank lines -@cindex Line spacing - -A line beginning with and containing only @code{@@sp @var{n}} -generates @var{n} blank lines of space in both the printed manual and -the Info file. @code{@@sp} also forces a paragraph break. For -example,@refill - -@example -@@sp 2 -@end example - -@noindent -generates two blank lines. - -The @code{@@sp} command is most often used in the title page.@refill - -@ignore -@c node br, page, sp, Breaks -@comment node-name, next, previous, up -@c section @code{@@br}: Generate Paragraph Breaks -@findex br @r{(paragraph breaks)} -@cindex Paragraph breaks -@cindex Breaks in a paragraph - -The @code{@@br} command forces a paragraph break. It inserts a blank -line. You can use the command within or at the end of a line. If -used within a line, the @code{@@br@{@}} command must be followed by -left and right braces (as shown here) to mark the end of the -command.@refill - -@need 700 -For example, - -@example -@group -This line @@br@{@}contains and is ended by paragraph breaks@@br -and is followed by another line. -@end group -@end example - -@noindent -produces - -@example -@group -This line - -contains and is ended by paragraph breaks - -and is followed by another line. -@end group -@end example - -The @code{@@br} command is seldom used. -@end ignore - -@node page, group, sp, Breaks -@comment node-name, next, previous, up -@section @code{@@page}: Start a New Page -@cindex Page breaks -@findex page - -A line containing only @code{@@page} starts a new page in a printed -manual. The command has no effect on Info files since they are not -paginated. An @code{@@page} command is often used in the @code{@@titlepage} -section of a Texinfo file to start the copyright page.@refill - -@node group, need, page, Breaks -@comment node-name, next, previous, up -@section @code{@@group}: Prevent Page Breaks -@cindex Group (hold text together vertically) -@cindex Holding text together vertically -@cindex Vertically holding text together -@findex group - -The @code{@@group} command (on a line by itself) is used inside an -@code{@@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 @code{@@end group}. -These two lines produce no output of their own, and in the Info file -output they have no effect at all.@refill - -@c Once said that these environments -@c turn off vertical spacing between ``paragraphs''. -@c Also, quotation used to work, but doesn't in texinfo-2.72 -Although @code{@@group} would make sense conceptually in a wide -variety of contexts, its current implementation works reliably only -within @code{@@example} and variants, and within @code{@@display}, -@code{@@format}, @code{@@flushleft} and @code{@@flushright}. -@xref{Quotations and Examples}. (What all these commands have in -common is that each line of input produces a line of output.) In -other contexts, @code{@@group} can cause anomalous vertical -spacing.@refill - -@need 750 -This formatting requirement means that you should write: - -@example -@group -@@example -@@group -@dots{} -@@end group -@@end example -@end group -@end example - -@noindent -with the @code{@@group} and @code{@@end group} commands inside the -@code{@@example} and @code{@@end example} commands. - -The @code{@@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 @code{@@group} and @code{@@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 -@code{@@end group} if you get incomprehensible error messages in -@TeX{}.@refill - -@node need, , group, Breaks -@comment node-name, next, previous, up -@section @code{@@need @var{mils}}: Prevent Page Breaks -@cindex Need space at page bottom -@findex need - -A line containing only @code{@@need @var{n}} starts -a new page in a printed manual if fewer than @var{n} mils (thousandths -of an inch) remain on the current page. Do not use -braces around the argument @var{n}. The @code{@@need} command has no -effect on Info files since they are not paginated.@refill - -@need 800 -This paragraph is preceded by an @code{@@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:@refill - -@example -@group -@@need 800 -This paragraph is preceded by @dots{} -@end group -@end example - -The @code{@@need} command is useful for preventing orphans (single -lines at the bottoms of printed pages).@refill - -@node Definition Commands, Footnotes, Breaks, Top -@chapter Definition Commands -@cindex Definition commands - -The @code{@@deffn} command and the other @dfn{definition commands} -enable you to describe functions, variables, macros, commands, user -options, special forms and other such artifacts in a uniform -format.@refill - -In the Info file, a definition causes the entity -category---`Function', `Variable', or whatever---to appear at the -beginning of the first line of the definition, followed by the -entity's name and arguments. In the printed manual, the command -causes @TeX{} to print the entity's name and its arguments on the left -margin and print the category next to the right margin. In both -output formats, the body of the definition is indented. Also, the -name of the entity is entered into the appropriate index: -@code{@@deffn} enters the name into the index of functions, -@code{@@defvr} enters it into the index of variables, and so -on.@refill - -A manual need not and should not contain more than one definition for -a given name. An appendix containing a summary should use -@code{@@table} rather than the definition commands.@refill - -@menu -* Def Cmd Template:: How to structure a description using a - definition command. -* Optional Arguments:: How to handle optional and repeated arguments. -* deffnx:: How to group two or more `first' lines. -* Def Cmds in Detail:: All the definition commands. -* Def Cmd Conventions:: Conventions for writing definitions. -* Sample Function Definition:: -@end menu - -@node Def Cmd Template, Optional Arguments, , Definition Commands -@section The Template for a Definition -@cindex Definition template -@cindex Template for a definition - -The @code{@@deffn} command is used for definitions of entities that -resemble functions. To write a definition using the @code{@@deffn} -command, write the @code{@@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 @code{@@end deffn} command -written on a line of its own. (The other definition commands follow -the same format.)@refill - -The template for a definition looks like this: - -@example -@group -@@deffn @var{category} @var{name} @var{arguments}@dots{} -@var{body-of-definition} -@@end deffn -@end group -@end example - -@need 700 -@noindent -For example, - -@example -@group -@@deffn Command forward-word count -This command moves point forward @@var@{count@} words -(or backward if @@var@{count@} is negative). @dots{} -@@end deffn -@end group -@end example - -@noindent -produces - -@quotation -@deffn Command forward-word count -This function moves point forward @var{count} words -(or backward if @var{count} is negative). @dots{} -@end deffn -@end quotation - -Capitalize the category name like a title. If the name of the -category contains spaces, as in the phrase `Interactive Command', -write braces around it. For example:@refill - -@example -@group -@@deffn @{Interactive Command@} isearch-forward -@dots{} -@@end deffn -@end group -@end example - -@noindent -Otherwise, the second word will be mistaken for the name of the -entity.@refill - -Some of the definition commands are more general than others. The -@code{@@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. The @code{@@deffn} command possesses three predefined, -specialized variations, @code{@@defun}, @code{@@defmac}, and -@code{@@defspec}, that specify the category for you: ``Function'', -``Macro'', and ``Special Form'' respectively. The @code{@@defvr} -command also is accompanied by several predefined, specialized -variations for describing particular kinds of variables.@refill - -The template for a specialized definition, such as @code{@@defun}, is -similar to the template for a generalized definition, except that you -do not need to specify the category:@refill - -@example -@group -@@defun @var{name} @var{arguments}@dots{} -@var{body-of-definition} -@@end defun -@end group -@end example - -@noindent -Thus, - -@example -@group -@@defun buffer-end flag -This function returns @@code@{(point-min)@} if @@var@{flag@} -is less than 1, @@code@{(point-max)@} otherwise. -@dots{} -@@end defun -@end group -@end example - -@noindent -produces - -@quotation -@defun buffer-end flag -This function returns @code{(point-min)} if @var{flag} is less than 1, -@code{(point-max)} otherwise. @dots{} -@end defun -@end quotation - -@noindent -@xref{Sample Function Definition, Sample Function Definition, A Sample -Function Definition}, for a more detailed example of a function -definition, including the use of @code{@@example} inside the -definition.@refill - -The other specialized commands work like @code{@@defun}.@refill - -@node Optional Arguments, deffnx, Def Cmd Template, Definition Commands -@section Optional and Repeated Arguments -@cindex Optional and repeated arguments -@cindex Repeated and optional arguments -@cindex Arguments, repeated and optional -@cindex Syntax, optional & repeated arguments -@cindex Meta-syntactic chars for arguments - -Some entities take optional or repeated arguments, which may be -specified by a distinctive glyph that uses square brackets and -ellipses. For @w{example}, a special form often breaks its argument list -into separate arguments in more complicated ways than a -straightforward function.@refill - -@iftex -An argument enclosed within square brackets is optional. -Thus, the phrase -@samp{@code{@r{[}@var{optional-arg}@r{]}}} means that -@var{optional-arg} is optional. -An argument followed by an ellipsis is optional -and may be repeated more than once. -@c This is consistent with Emacs Lisp Reference manual -Thus, @samp{@var{repeated-args}@dots{}} stands for zero or more arguments. -Parentheses are used when several arguments are grouped -into additional levels of list structure in Lisp. -@end iftex -@c The following looks better in Info (no `r', `samp' and `code'): -@ifinfo -An argument enclosed within square brackets is optional. -Thus, [@var{optional-arg}] means that @var{optional-arg} is optional. -An argument followed by an ellipsis is optional -and may be repeated more than once. -@c This is consistent with Emacs Lisp Reference manual -Thus, @var{repeated-args}@dots{} stands for zero or more arguments. -Parentheses are used when several arguments are grouped -into additional levels of list structure in Lisp. -@end ifinfo - -Here is the @code{@@defspec} line of an example of an imaginary -special form:@refill - -@quotation -@defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} -@end defspec -@tex -\vskip \parskip -@end tex -@end quotation - -@noindent -In this example, the arguments @var{from} and @var{to} are optional, -but must both be present or both absent. If they are present, -@var{inc} may optionally be specified as well. These arguments are -grouped with the argument @var{var} into a list, to distinguish them -from @var{body}, which includes all remaining elements of the -form.@refill - -In a Texinfo source file, this @code{@@defspec} line is written like -this (except it would not be split over two lines, as it is in this -example).@refill - -@example -@group -@@defspec foobar (@@var@{var@} [@@var@{from@} @@var@{to@} - [@@var@{inc@}]]) @@var@{body@}@@dots@{@} -@end group -@end example - -@noindent -The function is listed in the Command and Variable Index under -@samp{foobar}.@refill - -@node deffnx, Def Cmds in Detail, Optional Arguments, Definition Commands -@section Two or More `First' Lines -@cindex Two `First' Lines for @code{@@deffn} -@cindex Grouping two definitions together -@cindex Definitions grouped together -@findex deffnx - -To create two or more `first' or header lines for a definition, follow -the first @code{@@deffn} line by a line beginning with @code{@@deffnx}. -The @code{@@deffnx} command works exactly like @code{@@deffn} -except that it does not generate extra vertical white space between it -and the preceding line.@refill - -@need 1000 -For example, - -@example -@group -@@deffn @{Interactive Command@} isearch-forward -@@deffnx @{Interactive Command@} isearch-backward -These two search commands are similar except @dots{} -@@end deffn -@end group -@end example - -@noindent -produces - -@deffn {Interactive Command} isearch-forward -@deffnx {Interactive Command} isearch-backward -These two search commands are similar except @dots{} -@end deffn - -Each of the other definition commands has an `x' form: @code{@@defunx}, -@code{@@defvrx}, @code{@@deftypefunx}, etc. - -The `x' forms work just like @code{@@itemx}; see @ref{itemx, , @code{@@itemx}}. - -@node Def Cmds in Detail, Def Cmd Conventions, deffnx, Definition Commands -@section The Definition Commands - -Texinfo provides more than a dozen definition commands, all of which -are described in this section.@refill - -The definition commands automatically enter the name of the entity in -the appropriate index: for example, @code{@@deffn}, @code{@@defun}, -and @code{@@defmac} enter function names in the index of functions; -@code{@@defvr} and @code{@@defvar} enter variable names in the index -of variables.@refill - -Although the examples that follow mostly illustrate Lisp, the commands -can be used for other programming languages.@refill - -@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. -* Abstract Objects:: Commands for object-oriented programming. -* Data Types:: The definition command for data types. -@end menu - -@node Functions Commands, Variables Commands, , Def Cmds in Detail -@subsection Functions and Similar Entities - -This section describes the commands for describing functions and similar -entities:@refill - -@table @code -@findex deffn -@item @@deffn @var{category} @var{name} @var{arguments}@dots{} -The @code{@@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 @code{@@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 @code{@@end deffn} on a line of its -own.@refill - -@need 750 -For example, here is a definition: - -@example -@group -@@deffn Command forward-char nchars -Move point forward @@var@{nchars@} characters. -@@end deffn -@end group -@end example - -@noindent -This shows a rather terse definition for a ``command'' named -@code{forward-char} with one argument, @var{nchars}. - -@code{@@deffn} prints argument names such as @var{nchars} in italics or -upper case, as if @code{@@var} had been used, because we think of these -names as metasyntactic variables---they stand for the actual argument -values. Within the text of the description, write an argument name -explicitly with @code{@@var} to refer to the value of the argument. In -the example above, we used @samp{@@var@{nchars@}} in this way. - -The template for @code{@@deffn} is: - -@example -@group -@@deffn @var{category} @var{name} @var{arguments}@dots{} -@var{body-of-definition} -@@end deffn -@end group -@end example - -@findex defun -@item @@defun @var{name} @var{arguments}@dots{} -The @code{@@defun} command is the definition command for functions. -@code{@@defun} is equivalent to @samp{@@deffn Function -@dots{}}.@refill - -@need 800 -@noindent -For example, - -@example -@group -@@defun set symbol new-value -Change the value of the symbol @@var@{symbol@} -to @@var@{new-value@}. -@@end defun -@end group -@end example - -@noindent -shows a rather terse definition for a function @code{set} whose -arguments are @var{symbol} and @var{new-value}. The argument names on -the @code{@@defun} line automatically appear in italics or upper case as -if they were enclosed in @code{@@var}. Terminate the definition with -@code{@@end defun} on a line of its own.@refill - -The template is: - -@example -@group -@@defun @var{function-name} @var{arguments}@dots{} -@var{body-of-definition} -@@end defun -@end group -@end example - -@code{@@defun} creates an entry in the index of functions. - -@findex defmac -@item @@defmac @var{name} @var{arguments}@dots{} -The @code{@@defmac} command is the definition command for macros. -@code{@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and -works like @code{@@defun}.@refill - -@findex defspec -@item @@defspec @var{name} @var{arguments}@dots{} -The @code{@@defspec} command is the definition command for special -forms. (In Lisp, a special form is an entity much like a function.) -@code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@} -@dots{}} and works like @code{@@defun}.@refill -@end table - -@node Variables Commands, Typed Functions, Functions Commands, Def Cmds in Detail -@subsection Variables and Similar Entities - -Here are the commands for defining variables and similar -entities:@refill - -@table @code -@findex defvr -@item @@defvr @var{category} @var{name} -The @code{@@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 @code{@@defvr} command at the beginning of a line and -followed it on the same line by the category of the entity and the -name of the entity.@refill - -Capitalize the category name like a title. If the name of the -category contains spaces, as in the name `User Option', write braces -around it. Otherwise, the second word will be mistaken for the name -of the entity, for example: - -@example -@group -@@defvr @{User Option@} fill-column -This buffer-local variable specifies -the maximum width of filled lines. -@dots{} -@@end defvr -@end group -@end example - -Terminate the definition with @code{@@end defvr} on a line of its -own.@refill - -The template is: - -@example -@group -@@defvr @var{category} @var{name} -@var{body-of-definition} -@@end defvr -@end group -@end example - -@code{@@defvr} creates an entry in the index of variables for @var{name}. - -@findex defvar -@item @@defvar @var{name} -The @code{@@defvar} command is the definition command for variables. -@code{@@defvar} is equivalent to @samp{@@defvr Variable -@dots{}}.@refill - -@need 750 -For example: - -@example -@group -@@defvar kill-ring -@dots{} -@@end defvar -@end group -@end example - -The template is: - -@example -@group -@@defvar @var{name} -@var{body-of-definition} -@@end defvar -@end group -@end example - -@code{@@defvar} creates an entry in the index of variables for -@var{name}.@refill - -@findex defopt -@item @@defopt @var{name} -The @code{@@defopt} command is the definition command for user -options. @code{@@defopt} is equivalent to @samp{@@defvr @{User -Option@} @dots{}} and works like @code{@@defvar}.@refill -@end table - -@node Typed Functions, Typed Variables, Variables Commands, Def Cmds in Detail -@subsection Functions in Typed Languages - -The @code{@@deftypefn} command and its variations are for describing -functions in C or any other language in which you must declare types -of variables and functions.@refill - -@table @code -@findex deftypefn -@item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{} -The @code{@@deftypefn} command is the general definition command for -functions and similar entities that may take arguments and that are -typed. The @code{@@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.@refill - -@need 800 -@noindent -For example, - -@example -@group -@@deftypefn @{Library Function@} int foobar - (int @@var@{foo@}, float @@var@{bar@}) -@dots{} -@@end deftypefn -@end group -@end example - -@need 1000 -@noindent -(where the text before the ``@dots{}'', shown above as two lines, would -actually be a single line in a real Texinfo file) produces the following -in Info: - -@smallexample -@group --- Library Function: int foobar (int FOO, float BAR) -@dots{} -@end group -@end smallexample -@iftex - -In a printed manual, it produces: - -@quotation -@deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar}) -@dots{} -@end deftypefn -@end quotation -@end iftex - -This means that @code{foobar} is a ``library function'' that returns an -@code{int}, and its arguments are @var{foo} (an @code{int}) and -@var{bar} (a @code{float}).@refill - -The argument names that you write in @code{@@deftypefn} are not subject -to an implicit @code{@@var}---since the actual names of the arguments in -@code{@@deftypefn} are typically scattered among data type names and -keywords, Texinfo cannot find them without help. Instead, you must write -@code{@@var} explicitly around the argument names. In the example -above, the argument names are @samp{foo} and @samp{bar}.@refill - -The template for @code{@@deftypefn} is:@refill - -@example -@group -@@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{} -@var{body-of-description} -@@end deftypefn -@end group -@end example - -@noindent -Note that if the @var{category} or @var{data type} is more than one -word then it must be enclosed in braces to make it a single argument.@refill - -If you are describing a procedure in a language that has packages, -such as Ada, you might consider using @code{@@deftypefn} in a manner -somewhat contrary to the convention described in the preceding -paragraphs.@refill - -@need 800 -@noindent -For example: - -@example -@group -@@deftypefn stacks private push - (@@var@{s@}:in out stack; - @@var@{n@}:in integer) -@dots{} -@@end deftypefn -@end group -@end example - -@noindent -(The @code{@@deftypefn} arguments are shown split into three lines, but -would be a single line in a real Texinfo file.) - -In this instance, the procedure is classified as belonging to the -package @code{stacks} rather than classified as a `procedure' and its -data type is described as @code{private}. (The name of the procedure -is @code{push}, and its arguments are @var{s} and @var{n}.)@refill - -@code{@@deftypefn} creates an entry in the index of functions for -@var{name}.@refill - -@findex deftypefun -@item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{} -The @code{@@deftypefun} command is the specialized definition command -for functions in typed languages. The command is equivalent to -@samp{@@deftypefn Function @dots{}}.@refill - -@need 800 -@noindent -Thus, - -@smallexample -@group -@@deftypefun int foobar (int @@var@{foo@}, float @@var@{bar@}) -@dots{} -@@end deftypefun -@end group -@end smallexample - -@noindent -produces the following in Info: - -@example -@group --- Function: int foobar (int FOO, float BAR) -@dots{} -@end group -@end example -@iftex - -@need 800 -@noindent -and the following in a printed manual: - -@quotation -@deftypefun int foobar (int @var{foo}, float @var{bar}) -@dots{} -@end deftypefun -@end quotation -@end iftex - -@need 800 -The template is: - -@example -@group -@@deftypefun @var{type} @var{name} @var{arguments}@dots{} -@var{body-of-description} -@@end deftypefun -@end group -@end example - -@code{@@deftypefun} creates an entry in the index of functions for -@var{name}.@refill -@end table - -@node Typed Variables, Abstract Objects, Typed Functions, Def Cmds in Detail -@subsection Variables in Typed Languages - -Variables in typed languages are handled in a manner similar to -functions in typed languages. @xref{Typed Functions}. The general -definition command @code{@@deftypevr} corresponds to -@code{@@deftypefn} and the specialized definition command -@code{@@deftypevar} corresponds to @code{@@deftypefun}.@refill - -@table @code -@findex deftypevr -@item @@deftypevr @var{category} @var{data-type} @var{name} -The @code{@@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.@refill - -The @code{@@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.@refill - -@need 800 -@noindent -For example: - -@example -@group -@@deftypevr @{Global Flag@} int enable -@dots{} -@@end deftypevr -@end group -@end example - -@noindent -produces the following in Info: - -@example -@group --- Global Flag: int enable -@dots{} -@end group -@end example -@iftex - -@noindent -and the following in a printed manual: - -@quotation -@deftypevr {Global Flag} int enable -@dots{} -@end deftypevr -@end quotation -@end iftex - -@need 800 -The template is: - -@example -@@deftypevr @var{category} @var{data-type} @var{name} -@var{body-of-description} -@@end deftypevr -@end example - -@code{@@deftypevr} creates an entry in the index of variables for -@var{name}.@refill - -@findex deftypevar -@item @@deftypevar @var{data-type} @var{name} -The @code{@@deftypevar} command is the specialized definition command -for variables in typed languages. @code{@@deftypevar} is equivalent -to @samp{@@deftypevr Variable @dots{}}.@refill - -@need 800 -@noindent -For example: - -@example -@group -@@deftypevar int fubar -@dots{} -@@end deftypevar -@end group -@end example - -@noindent -produces the following in Info: - -@example -@group --- Variable: int fubar -@dots{} -@end group -@end example -@iftex - -@need 800 -@noindent -and the following in a printed manual: - -@quotation -@deftypevar int fubar -@dots{} -@end deftypevar -@end quotation -@end iftex - -@need 800 -@noindent -The template is: - -@example -@group -@@deftypevar @var{data-type} @var{name} -@var{body-of-description} -@@end deftypevar -@end group -@end example - -@code{@@deftypevar} creates an entry in the index of variables for -@var{name}.@refill -@end table - -@node Abstract Objects, Data Types, Typed Variables, Def Cmds in Detail -@subsection 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.@refill - -In a definition, if the name of a class is truly a name defined in the -programming system for a class, then you should write an @code{@@code} -around it. Otherwise, it is printed in the usual text font.@refill - -@table @code -@findex defcv -@item @@defcv @var{category} @var{class} @var{name} -The @code{@@defcv} command is the general definition command for -variables associated with classes in object-oriented programming. The -@code{@@defcv} command is followed by three arguments: the category of -thing being defined, the class to which it belongs, and its -name. Thus,@refill - -@example -@group -@@defcv @{Class Option@} Window border-pattern -@dots{} -@@end defcv -@end group -@end example - -@noindent -illustrates how you would write the first line of a definition of the -@code{border-pattern} class option of the class @code{Window}.@refill - -The template is - -@example -@group -@@defcv @var{category} @var{class} @var{name} -@dots{} -@@end defcv -@end group -@end example - -@code{@@defcv} creates an entry in the index of variables. - -@findex defivar -@item @@defivar @var{class} @var{name} -The @code{@@defivar} command is the definition command for instance -variables in object-oriented programming. @code{@@defivar} is -equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}@refill - -The template is: - -@example -@group -@@defivar @var{class} @var{instance-variable-name} -@var{body-of-definition} -@@end defivar -@end group -@end example - -@code{@@defivar} creates an entry in the index of variables. - -@findex defop -@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} -The @code{@@defop} command is the general definition command for -entities that may resemble methods in object-oriented programming. -These entities take arguments, as functions do, but are associated -with particular classes of objects.@refill - -For example, some systems have constructs called @dfn{wrappers} that -are associated with classes as methods are, but that act more like -macros than like functions. You could use @code{@@defop Wrapper} to -describe one of these.@refill - -Sometimes it is useful to distinguish methods and @dfn{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 @code{expose}; we would say that this window system -defines an @code{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.@refill - -Often it makes more sense to document operations than methods. For -example, window application developers need to know about the -@code{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:@refill - -@example -@@defop Operation windows expose -@end example - -The @code{@@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.@refill - -@need 800 -@noindent -The template is: - -@example -@group -@@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} -@var{body-of-definition} -@@end defop -@end group -@end example - -@code{@@defop} creates an entry, such as `@code{expose} on -@code{windows}', in the index of functions.@refill - -@findex defmethod -@item @@defmethod @var{class} @var{name} @var{arguments}@dots{} -The @code{@@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. In the Lisp Machine, methods actually were functions, but -they were usually defined with @code{defmethod}. - -@code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}. -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.@refill - -@need 800 -@noindent -For example, - -@example -@group -@@defmethod @code{bar-class} bar-method argument -@dots{} -@@end defmethod -@end group -@end example - -@noindent -illustrates the definition for a method called @code{bar-method} of -the class @code{bar-class}. The method takes an argument.@refill - -The template is: - -@example -@group -@@defmethod @var{class} @var{method-name} @var{arguments}@dots{} -@var{body-of-definition} -@@end defmethod -@end group -@end example - -@c !!! reworded to prevent overfull hbox --bob 26 Mar 93 -@code{@@defmethod} creates an entry in the index of functions, such as -`@code{bar-method} on @code{bar-class}'.@refill -@end table - -@node Data Types, , Abstract Objects, Def Cmds in Detail -@subsection Data Types - -Here is the command for data types:@refill - -@table @code -@findex deftp -@item @@deftp @var{category} @var{name} @var{attributes}@dots{} -The @code{@@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 @code{int} or @code{float}), and then by names of -attributes of objects of that type. Thus, you could use this command -for describing @code{int} or @code{float}, in which case you could use -@code{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.)@refill - -In Lisp, for example, @dfn{pair} names a particular data -type, and an object of that type has two slots called the -@sc{car} and the @sc{cdr}. Here is how you would write the first line -of a definition of @code{pair}.@refill - -@example -@group -@@deftp @{Data type@} pair car cdr -@dots{} -@@end deftp -@end group -@end example - -@need 950 -The template is: - -@example -@group -@@deftp @var{category} @var{name-of-type} @var{attributes}@dots{} -@var{body-of-definition} -@@end deftp -@end group -@end example - -@code{@@deftp} creates an entry in the index of data types. -@end table - -@node Def Cmd Conventions, Sample Function Definition, Def Cmds in Detail, Definition Commands -@section Conventions for Writing Definitions -@cindex Definition conventions -@cindex Conventions for writing definitions - -When you write a definition using @code{@@deffn}, @code{@@defun}, or -one of the other definition commands, please take care to use -arguments that indicate the meaning, as with the @var{count} argument -to the @code{forward-word} function. Also, if the name of an argument -contains the name of a type, such as @var{integer}, take care that the -argument actually is of that type.@refill - -@node Sample Function Definition, , Def Cmd Conventions, Definition Commands -@section A Sample Function Definition -@cindex Function definitions -@cindex Command definitions -@cindex Macro definitions -@cindex Sample function definition - -A function definition uses the @code{@@defun} and @code{@@end defun} -commands. The name of the function follows immediately after the -@code{@@defun} command and it is followed, on the same line, by the -parameter list.@refill - -Here is a definition from @cite{The GNU Emacs Lisp Reference Manual}. -(@xref{Calling Functions, , Calling Functions, elisp, The GNU Emacs -Lisp Reference Manual}.) - -@quotation -@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}.@refill -@end defun -@end quotation - -@need 1200 -In the Texinfo source file, this example looks like this: - -@example -@group -@@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. -@end group - -@group -@@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@}. -@end group - -@group -@@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 -@end group - -@group -An interesting example of using @@code@{apply@} is found -in the description of @@code@{mapcar@}.@@refill -@@end defun -@end group -@end example - -@noindent -In this manual, this function is listed in the Command and Variable -Index under @code{apply}.@refill - -Ordinary variables and user options are described using a format like -that for functions except that variables do not take arguments. - -@node Footnotes, Conditionals, Definition Commands, Top -@comment node-name, next, previous, up -@chapter Footnotes -@cindex Footnotes -@findex footnote - -A @dfn{footnote} is for a reference that documents or elucidates the -primary text.@footnote{A footnote should complement or expand upon -the primary text, but a reader should not need to read a footnote to -understand the primary text. For a thorough discussion of footnotes, -see @cite{The Chicago Manual of Style}, which is published by the -University of Chicago Press.}@refill - -In Texinfo, footnotes are created with the @code{@@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. The template -is: - -@example -@@footnote@{@var{text}@} -@end example - -Footnotes may be of any length, but are usually short.@refill - -For example, this clause is followed by a sample -footnote@footnote{Here is the sample footnote.}; in the Texinfo -source, it looks like this:@refill - -@example -@dots{}a sample footnote @@footnote@{Here is the sample -footnote.@}; in the Texinfo source@dots{} -@end example - -In a printed manual or book, the reference mark for a footnote is a -small, superscripted number; the text of the footnote is written at -the bottom of the page, below a horizontal line.@refill - -In Info, the reference mark for a footnote is a pair of parentheses -with the footnote number between them, like this: @samp{(1)}.@refill - -Info has two footnote styles, which determine where the text of the -footnote is located:@refill - -@itemize @bullet -@cindex @samp{@r{End}} node footnote style -@item -In the `End' node style, all the footnotes for a single node -are placed at the end of that node. The footnotes are separated from -the rest of the node by a line of dashes with the word -@samp{Footnotes} within it. Each footnote begins with an -@samp{(@var{n})} reference mark.@refill - -@need 700 -@noindent -Here is an example of a single footnote in the end of node style:@refill - -@example -@group - --------- Footnotes --------- - -(1) Here is a sample footnote. -@end group -@end example - -@cindex @samp{@r{Separate}} footnote style -@item -In the `Separate' node style, all the footnotes for a single -node are placed in an automatically constructed node of -their own. In this style, a ``footnote reference'' follows -each @samp{(@var{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.@refill - -The name of the node containing the footnotes is constructed -by appending @w{@samp{-Footnotes}} to the name of the node -that contains the footnotes. (Consequently, the footnotes' -node for the @file{Footnotes} node is -@w{@file{Footnotes-Footnotes}}!) The footnotes' node has an -`Up' node pointer that leads back to its parent node.@refill - -@noindent -Here is how the first footnote in this manual looks after being -formatted for Info in the separate node style:@refill - -@smallexample -@group -File: texinfo.info Node: Overview-Footnotes, Up: Overview - -(1) Note that the first syllable of "Texinfo" is -pronounced like "speck", not "hex". @dots{} -@end group -@end smallexample -@end itemize - -A Texinfo file may be formatted into an Info file with either footnote -style.@refill - -@findex footnotestyle -Use the @code{@@footnotestyle} command to specify an Info file's -footnote style. Write this command at the beginning of a line followed -by an argument, either @samp{end} for the end node style or -@samp{separate} for the separate node style. - -@need 700 -For example, - -@example -@@footnotestyle end -@end example -@noindent -or -@example -@@footnotestyle separate -@end example - -Write an @code{@@footnotestyle} command before or shortly after the -end-of-header line at the beginning of a Texinfo file. (If you -include the @code{@@footnotestyle} command between the start-of-header -and end-of-header lines, the region formatting commands will format -footnotes as specified.)@refill - -@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93 -If you do not specify a footnote style, the formatting commands use -their default style. Currently, @code{makeinfo} uses the `end' style, -while @code{texinfo-format-buffer} and @code{texinfo-format-region} -use the `separate' style.@refill - -@c !!! note: makeinfo's --footnote-style option overrides footnotestyle -@ignore -If you use @code{makeinfo} to create the Info file, the -@samp{--footnote-style} option determines which style is used, -@samp{end} for the end of node style or @samp{separate} for the -separate node style. Thus, to format the Texinfo manual in the -separate node style, you would use the following shell command:@refill - -@example -makeinfo --footnote-style=separate texinfo.texi -@end example - -@noindent -To format the Texinfo manual in the end of node style, you would -type:@refill - -@example -makeinfo --footnote-style=end texinfo.texi -@end example -@end ignore -@ignore -If you use @code{texinfo-format-buffer} or -@code{texinfo-format-region} to create the Info file, the value of the -@code{texinfo-footnote-style} variable controls the footnote style. -It can be either @samp{"separate"} for the separate node style or -@samp{"end"} for the end of node style. (You can change the value of -this variable with the @kbd{M-x edit-options} command (@pxref{Edit -Options, , Editing Variable Values, emacs, The GNU Emacs Manual}), or -with the @kbd{M-x set-variable} command (@pxref{Examining, , Examining -and Setting Variables, emacs, The GNU Emacs Manual}).@refill - -The @code{texinfo-footnote-style} variable also controls the style if -you use the @kbd{M-x makeinfo-region} or @kbd{M-x makeinfo-buffer} -command in Emacs.@refill -@end ignore -This chapter contains two footnotes.@refill - -@node Conditionals, Format/Print Hardcopy, Footnotes, Top -@comment node-name, next, previous, up -@chapter Conditionally Visible Text -@cindex Conditionally visible text -@cindex Text, conditionally visible -@cindex Visibility of conditional text -@cindex If text conditionally visible -@findex ifinfo -@findex iftex - -Sometimes it is good to use different text for a printed manual and -its corresponding Info file. In this case, you can use the -@dfn{conditional commands} to specify which text is for the printed manual -and which is for the Info file.@refill - -@menu -* Conditional Commands:: How to specify text for Info or @TeX{}. -* Using Ordinary TeX Commands:: You can use any and all @TeX{} commands. -* set clear value:: How to designate which text to format (for - both Info and @TeX{}); and how to set a - flag to a string that you can insert. -@end menu - -@node Conditional Commands, Using Ordinary TeX Commands, , Conditionals -@ifinfo -@heading Using @code{@@ifinfo} and @code{@@iftex} -@end ifinfo - -@code{@@ifinfo} begins segments of text that should be ignored -by @TeX{} when it -typesets the printed manual. The segment of text appears only -in the Info file. -The @code{@@ifinfo} command should appear on a line by itself; end -the Info-only text with a line containing @code{@@end ifinfo} by -itself. At the beginning of a Texinfo file, the Info permissions are -contained within a region marked by @code{@@ifinfo} and @code{@@end -ifinfo}. (@xref{Info Summary and Permissions}.)@refill - -The @code{@@iftex} and @code{@@end iftex} commands are similar to the -@code{@@ifinfo} and @code{@@end ifinfo} commands, except that they -specify text that will appear in the printed manual but not in the Info -file.@refill - -@need 700 -For example, - -@example -@@iftex -This text will appear only in the printed manual. -@@end iftex - -@@ifinfo -However, this text will appear only in Info. -@@end ifinfo -@end example - -@noindent -The preceding example produces the following line: - -@iftex -This text will appear only in the printed manual. -@end iftex - -@ifinfo -However, this text will appear only in Info. -@end ifinfo - -@noindent -Note how you only see one of the two lines, depending on whether you -are reading the Info version or the printed version of this -manual.@refill - -The @code{@@titlepage} command is a special variant of @code{@@iftex} that -is used for making the title and copyright pages of the printed -manual. (@xref{titlepage, , @code{@@titlepage}}.) @refill - -@node Using Ordinary TeX Commands, set clear value, Conditional Commands, Conditionals -@comment node-name, next, previous, up -@section Using Ordinary @TeX{} Commands -@cindex @TeX{} commands, using ordinary -@cindex Ordinary @TeX{} commands, using -@cindex Commands using ordinary @TeX{} -@cindex Plain@TeX{} - -Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, -you can embed some Plain@TeX{} commands. Info will ignore these -commands since they are only in that part of the file which is seen by -@TeX{}. You can write the @TeX{} commands as you would write them in -a normal @TeX{} file, except that you must replace the @samp{\} used -by @TeX{} with an @samp{@@}. For example, in the @code{@@titlepage} -section of a Texinfo file, you can use the @TeX{} command -@code{@@vskip} to format the copyright page. (The @code{@@titlepage} -command causes Info to ignore the region automatically, as it does -with the @code{@@iftex} command.)@refill - -However, many features of Plain@TeX{} will not work, as they are -overridden by features of Texinfo. - -@findex tex -You can enter Plain@TeX{} completely, and use @samp{\} in the @TeX{} -commands, by delineating a region with the @code{@@tex} and @code{@@end -tex} commands. (The @code{@@tex} command also causes Info to ignore the -region, like the @code{@@iftex} -command.)@refill - -@cindex Mathematical expressions -For example, here is a mathematical expression written in -Plain@TeX{}:@refill - -@example -@@tex -$$ \chi^2 = \sum_@{i=1@}^N - \left (y_i - (a + b x_i) - \over \sigma_i\right)^2 $$ -@@end tex -@end example - -@noindent -The output of this example will appear only in a printed manual. If -you are reading this in Info, you will not see anything after this -paragraph. -@iftex -In a printed manual, the above expression looks like -this: -@end iftex - -@tex -$$ \chi^2 = \sum_{i=1}^N - \left(y_i - (a + b x_i) - \over \sigma_i\right)^2 $$ -@end tex - -@node set clear value, , Using Ordinary TeX Commands, Conditionals -@comment node-name, next, previous, up -@section @code{@@set}, @code{@@clear}, and @code{@@value} - -You can direct the Texinfo formatting commands to format or ignore parts -of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset}, -and @code{@@ifclear} commands.@refill - -In addition, you can use the @code{@@set @var{flag}} command to set the -value of @var{flag} to a string of characters; and use -@code{@@value@{@var{flag}@}} to insert that string. You can use -@code{@@set}, for example, to set a date and use @code{@@value} to -insert the date in several places in the Texinfo file.@refill - -@menu -* ifset ifclear:: Format a region if a flag is set. -* value:: Replace a flag with a string. -* value Example:: An easy way to update edition information. -@end menu - -@node ifset ifclear, value, , set clear value -@subsection @code{@@ifset} and @code{@@ifclear} - -@findex ifset -When a @var{flag} is set, the Texinfo formatting commands format text -between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end -ifset} commands. When the @var{flag} is cleared, the Texinfo formatting -commands do @emph{not} format the text. - -Use the @code{@@set @var{flag}} command to turn on, or @dfn{set}, a -@var{flag}; a @dfn{flag} can be any single word. The format for the -command looks like this:@refill -@findex set - -@example -@@set @var{flag} -@end example - -Write the conditionally formatted text between @code{@@ifset @var{flag}} -and @code{@@end ifset} commands, like this:@refill - -@example -@group -@@ifset @var{flag} -@var{conditional-text} -@@end ifset -@end group -@end example - -For example, you can create one document that has two variants, such as -a manual for a `large' and `small' model:@refill - -@example -You can use this machine to dig up shrubs -without hurting them. - -@@set large - -@@ifset large -It can also dig up fully grown trees. -@@end ifset - -Remember to replant promptly @dots{} -@end example - -@noindent -In the example, the formatting commands will format the text between -@code{@@ifset large} and @code{@@end ifset} because the @code{large} -flag is set.@refill - -@findex clear -Use the @code{@@clear @var{flag}} command to turn off, or @dfn{clear}, -a flag. Clearing a flag is the opposite of setting a flag. The -command looks like this:@refill - -@example -@@clear @var{flag} -@end example - -@noindent -Write the command on a line of its own. - -When @var{flag} is cleared, the Texinfo formatting commands do -@emph{not} format the text between @code{@@ifset @var{flag}} and -@code{@@end ifset}; that text is ignored and does not appear in either -printed or Info output.@refill - -For example, if you clear the flag of the preceding example by writing -an @code{@@clear large} command after the @code{@@set large} command -(but before the conditional text), then the Texinfo formatting commands -ignore the text between the @code{@@ifset large} and @code{@@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 @dots{}''. - -@findex ifclear -If a flag is cleared with an @code{@@clear @var{flag}} command, then -the formatting commands format text between subsequent pairs of -@code{@@ifclear} and @code{@@end ifclear} commands. But if the flag -is set with @code{@@set @var{flag}}, then the formatting commands do -@emph{not} format text between an @code{@@ifclear} and an @code{@@end -ifclear} command; rather, they ignore that text. An @code{@@ifclear} -command looks like this:@refill - -@example -@@ifclear @var{flag} -@end example - -@need 700 -In brief, the commands are:@refill - -@table @code -@item @@set @var{flag} -Tell the Texinfo formatting commands that @var{flag} is set.@refill - -@item @@clear @var{flag} -Tell the Texinfo formatting commands that @var{flag} is cleared.@refill - -@item @@ifset @var{flag} -If @var{flag} is set, tell the Texinfo formatting commands to format -the text up to the following @code{@@end ifset} command.@refill - -If @var{flag} is cleared, tell the Texinfo formatting commands to -ignore text up to the following @code{@@end ifset} command.@refill - -@item @@ifclear @var{flag} -If @var{flag} is set, tell the Texinfo formatting commands to ignore -the text up to the following @code{@@end ifclear} command.@refill - -If @var{flag} is cleared, tell the Texinfo formatting commands to -format the text up to the following @code{@@end ifclear} -command.@refill -@end table - -@node value, value Example, ifset ifclear, set clear value -@subsection @code{@@value} -@findex value - -You can use the @code{@@set} command to specify a value for a flag, -which is expanded by the @code{@@value} command. The value is a string -a characters. - -Write the @code{@@set} command like this: - -@example -@@set foo This is a string. -@end example - -@noindent -This sets the value of @code{foo} to ``This is a string.'' - -The Texinfo formatters replace an @code{@@value@{@var{flag}@}} command with -the string to which @var{flag} is set.@refill - -Thus, when @code{foo} is set as shown above, the Texinfo formatters convert - -@example -@group -@@value@{foo@} -@exdent @r{to} -This is a string. -@end group -@end example - -You can write an @code{@@value} command within a paragraph; but you -must write an @code{@@set} command on a line of its own. - -If you write the @code{@@set} command like this: - -@example -@@set foo -@end example - -@noindent -without specifying a string, the value of @code{foo} is an empty string. - -If you clear a previously set flag with an @code{@@clear @var{flag}} -command, a subsequent @code{@@value@{flag@}} command is invalid and the -string is replaced with an error message that says @samp{@{No value for -"@var{flag}"@}}. - -For example, if you set @code{foo} as follows:@refill - -@example -@@set how-much very, very, very -@end example - -@noindent -then the formatters transform - -@example -@group -It is a @@value@{how-much@} wet day. -@exdent @r{into} -It is a very, very, very wet day. -@end group -@end example - -If you write - -@example -@@clear how-much -@end example - -@noindent -then the formatters transform - -@example -@group -It is a @@value@{how-much@} wet day. -@exdent @r{into} -It is a @{No value for "how-much"@} wet day. -@end group -@end example - -@node value Example, , value, set clear value -@subsection @code{@@value} Example - -You can use the @code{@@value} command to limit the number of places you -need to change when you record an update to a manual. -Here is how it is done in @cite{The GNU Make Manual}: - -@need 1000 -@noindent -Set the flags: - -@example -@group -@@set EDITION 0.35 Beta -@@set VERSION 3.63 Beta -@@set UPDATED 14 August 1992 -@@set UPDATE-MONTH August 1992 -@end group -@end example - -@need 750 -@noindent -Write text for the first @code{@@ifinfo} section, for people reading the -Texinfo file: - -@example -@group -This is Edition @@value@{EDITION@}, -last updated @@value@{UPDATED@}, -of @@cite@{The GNU Make Manual@}, -for @@code@{make@}, Version @@value@{VERSION@}. -@end group -@end example - -@need 1000 -@noindent -Write text for the title page, for people reading the printed manual: -@c List only the month and the year since that looks less fussy on a -@c printed cover than a date that lists the day as well. - -@example -@group -@@title GNU Make -@@subtitle A Program for Directing Recompilation -@@subtitle Edition @@value@{EDITION@}, @dots{} -@@subtitle @@value@{UPDATE-MONTH@} -@end group -@end example - -@noindent -(On a printed cover, a date listing the month and the year looks less -fussy than a date listing the day as well as the month and year.) - -@need 750 -@noindent -Write text for the Top node, for people reading the Info file: - -@example -@group -This is Edition @@value@{EDITION@} -of the @@cite@{GNU Make Manual@}, -last updated @@value@{UPDATED@} -for @@code@{make@} Version @@value@{VERSION@}. -@end group -@end example - -@need 950 -After you format the manual, the text in the first @code{@@ifinfo} -section looks like this: - -@example -@group -This is Edition 0.35 Beta, last updated 14 August 1992, -of `The GNU Make Manual', for `make', Version 3.63 Beta. -@end group -@end example - -When you update the manual, change only the values of the flags; you do -not need to rewrite the three sections. - -@node Format/Print Hardcopy, Create an Info File, Conditionals, Top -@comment node-name, next, previous, up -@chapter Format and Print Hardcopy -@cindex Format and print hardcopy -@cindex Hardcopy, printing it -@cindex Making a printed manual -@cindex Sorting indices -@cindex Indices, sorting -@cindex @TeX{} index sorting -@findex texindex - -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.@refill - -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.@refill - -@menu -* Use TeX:: Use @TeX{} to format for hardcopy. -* Shell Format & Print:: How to format and print a hardcopy manual - with shell commands. -* 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 you need to do to 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 European A4 paper. -* Cropmarks and Magnification:: How to print marks to indicate the size - of pages and how to print scaled up output. -@end menu - -@node Use TeX, Shell Format & Print, , Format/Print Hardcopy -@ifinfo -@heading Use @TeX{} -@end ifinfo - -The typesetting program called @TeX{} is used for formatting a Texinfo -file. @TeX{} is a very powerful typesetting program and, if used right, -does an exceptionally good job. @xref{Obtaining TeX, , How to Obtain -@TeX{}}, for information on how to obtain @TeX{}.@refill - -The @code{makeinfo}, @code{texinfo-format-region}, and -@code{texinfo-format-buffer} commands read the very same @@-commands -in the Texinfo file as does @TeX{}, but process them differently to -make an Info file; see @ref{Create an Info File}.@refill - -@node Shell Format & Print, Within Emacs, Use TeX, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Format and Print Using Shell Commands - -@cindex DVI file -Format the Texinfo file with the shell command @code{tex} followed by -the name of the Texinfo file. This produces a formatted @sc{dvi} file -as well as several auxiliary files containing indices, cross -references, etc. The @sc{dvi} file (for @dfn{DeVice Independent} -file) can be printed on a wide variety of printers.@refill - -The @code{tex} formatting command itself does not sort the indices; it -writes an output file of unsorted index data. This is a misfeature of -@TeX{}. Hence, to generate a printed index, you first need a sorted -index to work from. The @code{texindex} command sorts indices. (The -source file @file{texindex.c} comes as part of the standard GNU -distribution and is usually installed when Emacs is installed.)@refill -@findex texindex -@ignore -Usage: texindex [-k] [-T tempdir] infile [-o outfile] ... - -Each infile arg can optionally be followed by a `-o outfile' arg; -for each infile that is not followed by a -o arg, the infile name with -`s' (for `sorted') appended is used for the outfile. - --T dir is the directory to put temp files in, instead of /tmp. --k means `keep tempfiles', for debugging. -@end ignore - -The @code{tex} formatting command outputs unsorted index files under -names that obey a standard convention. These names are the name of -your main input file to the @code{tex} formatting command, with -everything after the first period thrown away, and the two letter -names of indices added at the end. For example, the raw index output -files for the input file @file{foo.texinfo} would be @file{foo.cp}, -@file{foo.vr}, @file{foo.fn}, @file{foo.tp}, @file{foo.pg} and -@file{foo.ky}. Those are exactly the arguments to give to -@code{texindex}.@refill - -@need 1000 -Or else, you can use @samp{??} as ``wild-cards'' and give the command in -this form:@refill - -@example -texindex foo.?? -@end example - -@noindent -This command will run @code{texindex} on all the unsorted index files, -including any that you have defined yourself using @code{@@defindex} -or @code{@@defcodeindex}. (You may execute @samp{texindex foo.??} -even if there are similarly named files with two letter extensions -that are not index files, such as @samp{foo.el}. The @code{texindex} -command reports but otherwise ignores such files.)@refill - -For each file specified, @code{texindex} generates a sorted index file -whose name is made by appending @samp{s} to the input file name. The -@code{@@printindex} command knows to look for a file of that name. -@code{texindex} does not alter the raw index output file.@refill - -After you have sorted the indices, you need to rerun the @code{tex} -formatting command on the Texinfo file. This regenerates a formatted -@sc{dvi} file with up-to-date index entries.@footnote{If you use more -than one index and have cross references to an index other than the -first, you must run @code{tex} @emph{three times} to get correct output: -once to generate raw index data; again (after @code{texindex}) to output -the text of the indices and determine their true page numbers; and a -third time to output correct page numbers in cross references to them. -However, cross references to indices are rare.}@refill - -To summarize, this is a three step process: - -@enumerate -@item -Run the @code{tex} formatting command on the Texinfo file. This -generates the formatted @sc{dvi} file as well as the raw index files -with two letter extensions.@refill - -@item -Run the shell command @code{texindex} on the raw index files to sort -them. This creates the corresponding sorted index files.@refill - -@item -Rerun the @code{tex} formatting command on the Texinfo file. This -regenerates a formatted @sc{dvi} file with the index entries in the -correct order. This second run also corrects the page numbers for -the cross references. (The tables of contents are always correct.)@refill -@end enumerate - -You need not run @code{texindex} each time after you run the -@code{tex} formatting. If you do not, on the next run, the @code{tex} -formatting command will use whatever sorted index files happen to -exist from the previous use of @code{texindex}. This is usually -@sc{ok} while you are debugging.@refill - -@findex texi2dvi @r{(shell script)} -Rather than type the @code{tex} and @code{texindex} commands yourself, -you can use @code{texi2dvi}. This shell script is designed to -simplify the @code{tex}---@code{texindex}---@code{tex} sequence by -figuring out whether index files and @sc{dvi} files are up-to-date. -It runs @code{texindex} and @code{tex} only when necessary. - -@need 1000 -The syntax for @code{texi2dvi} is like this (where @samp{%} is the -shell prompt):@refill - -@example -% texi2dvi @var{filename}@dots{} -@end example - -@findex lpr @r{(@sc{dvi} print command)} -Finally, you can print the @sc{dvi} file with the @sc{dvi} print command. -The precise command to use depends on the system; @samp{lpr -d} is -common. The @sc{dvi} print command may require a file name without any -extension or with a @samp{.dvi} extension.@refill - -@need 1200 -The following commands, for example, sort the indices, format, and -print the @cite{Bison Manual} (where @samp{%} is the shell -prompt):@refill - -@example -@group -% tex bison.texinfo -% texindex bison.?? -% tex bison.texinfo -% lpr -d bison.dvi -@end group -@end example - -@noindent -(Remember that the shell commands may be different at your site; but -these are commonly used versions.)@refill - -@node Within Emacs, Texinfo Mode Printing, Shell Format & Print, Format/Print Hardcopy -@comment node-name, next, previous, up -@section From an Emacs Shell @dots{} -@cindex Print, format from Emacs shell -@cindex Format, print from Emacs shell -@cindex Shell, format, print from -@cindex Emacs shell, format, print from -@cindex GNU Emacs shell, format, print from - -You can give formatting and printing commands from a shell within GNU -Emacs. To create a shell within Emacs, type @kbd{M-x shell}. In this -shell, you can format and print the document. @xref{Shell Format & Print, , -How to Format and Print Using Shell Commands}, for details.@refill - -You can switch to and from the shell buffer while @code{tex} is -running and do other editing. If you are formatting a long document -on a slow machine, this can be very convenient.@refill - -You can also use @code{texi2dvi} from an Emacs shell. For example, -here is how to use @code{texi2dvi} to format and print @cite{Using and -Porting GNU CC} from a shell within Emacs (where @samp{%} is the shell -prompt):@refill - -@example -@group -% texi2dvi gcc.texinfo -% lpr -d gcc.dvi -@end group -@end example -@ifinfo - -@xref{Texinfo Mode Printing}, for more information about formatting -and printing in Texinfo mode.@refill -@end ifinfo - -@node Texinfo Mode Printing, Compile-Command, Within Emacs, Format/Print Hardcopy -@section Formatting and Printing in Texinfo Mode -@cindex Region printing in Texinfo mode -@cindex Format and print in Texinfo mode -@cindex Print and format 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.@refill - -@table @kbd -@item C-c C-t C-r -@itemx M-x texinfo-tex-region -Run @TeX{} on the current region.@refill - -@item C-c C-t C-b -@itemx M-x texinfo-tex-buffer -Run @TeX{} on the current buffer.@refill - -@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93 -@item C-c C-t C-i -@itemx M-x texinfo-texindex -Sort the indices of a Texinfo file that have been formatted with -@code{texinfo-tex-region} or @code{texinfo-tex-buffer}.@refill - -@item C-c C-t C-p -@itemx M-x texinfo-tex-print -Print a @sc{dvi} file that was made with @code{texinfo-tex-region} or -@code{texinfo-tex-buffer}.@refill - -@item C-c C-t C-q -@itemx M-x texinfo-show-tex-print-queue -Show the print queue.@refill - -@item C-c C-t C-d -@itemx M-x texinfo-delete-from-tex-print-queue -Delete a job from the print queue; you will be prompted for the job -number shown by a preceding @kbd{C-c C-t C-q} command -(@code{texinfo-show-tex-print-queue}).@refill - -@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93 -@item C-c C-t C-k -@itemx M-x texinfo-kill-tex-job -Kill either the currently running @TeX{} job that has been started by -@code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other -process running in the Texinfo shell buffer.@refill - -@item C-c C-t C-x -@itemx M-x texinfo-quit-tex-job -Quit a @TeX{} formatting job that has stopped because of an error by -sending an @key{x} to it. When you do this, @TeX{} preserves a record -of what it did in a @file{.log} file.@refill - -@item C-c C-t C-l -@itemx M-x texinfo-recenter-tex-output-buffer -Redisplay the shell buffer in which the @TeX{} printing and formatting -commands are run to show its most recent output.@refill -@end table - -Thus, the usual sequence of commands for formatting a buffer is as -follows (with comments to the right):@refill - -@example -@group -C-c C-t C-b @r{Run @TeX{} on the buffer.} -C-c C-t C-i @r{Sort the indices.} -C-c C-t C-b @r{Rerun @TeX{} to regenerate indices.} -C-c C-t C-p @r{Print the @sc{dvi} file.} -C-c C-t C-q @r{Display the printer queue.} -@end group -@end example - -The Texinfo mode @TeX{} formatting commands start a subshell in Emacs -called the @file{*texinfo-tex-shell*}. The @code{texinfo-tex-command}, -@code{texinfo-texindex-command}, and @code{tex-dvi-print-command} -commands are all run in this shell. - -You can watch the commands operate in the @samp{*texinfo-tex-shell*} buffer, -and you can switch to and from and use the @samp{*texinfo-tex-shell*} buffer -as you would any other shell buffer.@refill - -@need 1500 -The formatting and print commands depend on the values of several variables. -The default values are:@refill - -@sp 1 -@example -@group - @r{Variable} @r{Default value} - -texinfo-tex-command "tex" -texinfo-texindex-command "texindex" -texinfo-tex-shell-cd-command "cd" -texinfo-tex-dvi-print-command "lpr -d" -texinfo-show-tex-queue-command "lpq" -texinfo-delete-from-print-queue-command "lprm" -texinfo-start-of-header "%**start" -texinfo-end-of-header "%**end" -texinfo-tex-trailer "@@bye" -@end group -@end example - -@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93 -The default values of both the @code{texinfo-tex-command} and the -@code{texinfo-texindex-command} variables are set in the @file{texnfo-tex.el} -file.@refill - -You can change the values of these variables with the @kbd{M-x -edit-options} command (@pxref{Edit Options, , Editing Variable Values, -emacs, The GNU Emacs Manual}), with the @kbd{M-x set-variable} command -(@pxref{Examining, , Examining and Setting Variables, emacs, The GNU -Emacs Manual}), or with your @file{.emacs} initialization file -(@pxref{Init File, , , emacs, The GNU Emacs Manual}).@refill - -@node Compile-Command, Requirements Summary, Texinfo Mode Printing, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Using the Local Variables List -@cindex Local variables -@cindex Compile command for formatting -@cindex Format with the compile command - -Yet another way to apply the @TeX{} formatting command to a Texinfo -file is to put that command in a @dfn{local variables list} at the end -of the Texinfo file. You can then specify the @TeX{} formatting -command as a @code{compile-command} and have Emacs run the @TeX{} -formatting command by typing @kbd{M-x compile}. This creates a -special shell called the @samp{*compilation buffer*} in which Emacs -runs the compile command. For example, at the end of the -@file{gdb.texinfo} file, after the @code{@@bye}, you would put the -following:@refill - -@example -@@c Local Variables: -@@c compile-command: "tex gdb.texinfo" -@@c End: -@end example - -@noindent -This technique is most often used by programmers who also compile programs -this way; see @ref{Compilation, , , emacs, The GNU Emacs Manual}.@refill - -@node Requirements Summary, Preparing for TeX, Compile-Command, Format/Print Hardcopy -@comment node-name, next, previous, up -@section @TeX{} Formatting Requirements Summary -@cindex Requirements for formatting -@cindex Formatting requirements - -Every Texinfo file that is to be input to @TeX{} must begin with a -@code{\input} command and contain an @code{@@settitle} command:@refill - -@example -\input texinfo -@@settitle @var{name-of-manual} -@end example - -@noindent -The first command instructs @TeX{} to load the macros it needs to -process a Texinfo file and the second command specifies the title of -printed manual.@refill - -@need 1000 -Every Texinfo file must end with a line that terminates @TeX{} -processing and forces out unfinished pages:@refill - -@example -@@bye -@end example - -Strictly speaking, these three lines are all a Texinfo file needs for -@TeX{}, besides the body. (The @code{@@setfilename} line is the only -line that a Texinfo file needs for Info formatting.)@refill - -Usually, the file's first line contains an @samp{@@c -*-texinfo-*-} -comment that causes Emacs to switch to Texinfo mode when you edit the -file. In addition, the beginning usually includes an -@code{@@setfilename} for Info formatting, an @code{@@setchapternewpage} -command, a title page, a copyright page, and permissions. Besides an -@code{@@bye}, the end of a file usually includes indices and a table of -contents.@refill - -@iftex -For more information, see -@ref{setchapternewpage, , @code{@@setchapternewpage}}, -@ref{Headings, ,Page Headings}, -@ref{Titlepage & Copyright Page}, -@ref{Printing Indices & Menus}, and -@ref{Contents}. -@end iftex -@noindent -@ifinfo -For more information, see@* -@ref{setchapternewpage, , @code{@@setchapternewpage}},@* -@ref{Headings, ,Page Headings},@* -@ref{Titlepage & Copyright Page},@* -@ref{Printing Indices & Menus}, and@* -@ref{Contents}. -@end ifinfo - -@node Preparing for TeX, Overfull hboxes, Requirements Summary, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Preparing to Use @TeX{} -@cindex Preparing to use @TeX{} -@cindex @TeX{} input initialization -@cindex @code{TEXINPUTS} environment variable -@vindex TEXINPUTS -@cindex @b{.profile} initialization file -@cindex @b{.cshrc} initialization file -@cindex Initialization file for @TeX{} input - -@TeX{} needs to know where to find the @file{texinfo.tex} file -that you have told it to input with the @samp{\input texinfo} command -at the beginning of the first line. The @file{texinfo.tex} file tells -@TeX{} how to handle @@-commands. (@file{texinfo.tex} is -included in the standard GNU distributions.)@refill - -Usually, the @file{texinfo.tex} file is put in the default directory -that contains @TeX{} macros (the @file{/usr/lib/tex/macros} -directory) when GNU Emacs or other GNU software is installed. -In this case, @TeX{} will -find the file and you do not need to do anything special. -Alternatively, you can put @file{texinfo.tex} in the directory in -which the Texinfo source file is located, and @TeX{} will find it -there.@refill - -However, you may want to specify the location of the @code{\input} file -yourself. One way to do this is to write the complete path for the file -after the @code{\input} command. Another way is to set the -@code{TEXINPUTS} environment variable in your @file{.cshrc} or -@file{.profile} file. The @code{TEXINPUTS} environment variable will tell -@TeX{} where to find the @file{texinfo.tex} file and any other file that -you might want @TeX{} to use.@refill - -Whether you use a @file{.cshrc} or @file{.profile} file depends on -whether you use @code{csh}, @code{sh}, or @code{bash} for your shell -command interpreter. When you use @code{csh}, it looks to the -@file{.cshrc} file for initialization information, and when you use -@code{sh} or @code{bash}, it looks to the @file{.profile} file.@refill - -@need 1000 -In a @file{.cshrc} file, you could use the following @code{csh} command -sequence:@refill - -@example -setenv TEXINPUTS .:/usr/me/mylib:/usr/lib/tex/macros -@end example - -@need 1000 -In a @file{.profile} file, you could use the following @code{sh} command -sequence: - -@example -@group -TEXINPUTS=.:/usr/me/mylib:/usr/lib/tex/macros -export TEXINPUTS -@end group -@end example - -@noindent -This would cause @TeX{} to look for @file{\input} file first in the current -directory, indicated by the @samp{.}, then in a hypothetical user's -@file{me/mylib} directory, and finally in the system library.@refill - -@node Overfull hboxes, smallbook, Preparing for TeX, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Overfull ``hboxes'' -@cindex Overfull @samp{hboxes} -@cindex @samp{hboxes}, overfull -@cindex Final output - -@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:@refill - -@example -Overfull \hbox (20.76302pt too wide) -@end example - -@noindent -(In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''. -The backslash, @samp{\}, is the @TeX{} equivalent of @samp{@@}.)@refill - -@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{} knows how to hyphenate words. -@xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting}, -for more information about typesetting errors.@refill - -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.@refill - -@cindex Black rectangle in hardcopy -@cindex Rectangle, ugly, black in hardcopy -However, unless told otherwise, @TeX{} will print a large, ugly, black -rectangle beside the line that contains the overful hbox. This is so -you will notice the location of the problem if you are correcting a -draft.@refill - -@need 1000 -@findex finalout -To prevent such a monstrosity from marring your final printout, write -the following in the beginning of the Texinfo file on a line of its own, -before the @code{@@titlepage} command:@refill - -@example -@@finalout -@end example - -@node smallbook, A4 Paper, Overfull hboxes, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Printing ``Small'' Books -@findex smallbook -@cindex Small book size -@cindex Book, printing small -@cindex Page sizes for books -@cindex Size of printed book - -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:@refill - -@example -@@smallbook -@end example - -@noindent -(Since regular sized books are often about 7 by 9.25 inches, this -command might better have been called the @code{@@regularbooksize} -command, but it came to be called the @code{@@smallbook} command by -comparison to the 8.5 by 11 inch format.)@refill - -If you write the @code{@@smallbook} command between the -start-of-header and end-of-header lines, the Texinfo mode @TeX{} -region formatting command, @code{texinfo-tex-region}, will format the -region in ``small'' book size (@pxref{Start of Header}).@refill - -The Free Software Foundation distributes printed copies of @cite{The GNU -Emacs Manual} and other manuals in the ``small'' book size. -@xref{smallexample & smalllisp, , @code{@@smallexample} and -@code{@@smalllisp}}, for information about commands that make it easier -to produce examples for a smaller manual.@refill - -@node A4 Paper, Cropmarks and Magnification, smallbook, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Printing on A4 Paper -@cindex A4 paper, printing on -@cindex Paper size, European A4 -@cindex European A4 paper -@findex afourpaper - -You can tell @TeX{} to typeset a document for printing on European size -A4 paper with the @code{@@afourpaper} command. Write the command on a -line by itself between @code{@@iftex} and @code{@@end iftex} lines near -the beginning of the Texinfo file, before the title page:@refill - -For example, this is how you would write the header for this manual:@refill - -@example -@group -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename texinfo -@@settitle Texinfo -@@syncodeindex vr fn -@@iftex -@@afourpaper -@@end iftex -@@c %**end of header -@end group -@end example - -@node Cropmarks and Magnification, , A4 Paper, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Cropmarks and Magnification - -@findex cropmarks -@cindex Cropmarks for printing -@cindex Printing cropmarks -You can attempt to direct @TeX{} to print cropmarks at the corners of -pages with the @code{@@cropmarks} command. Write the @code{@@cropmarks} -command on a line by itself between @code{@@iftex} and @code{@@end -iftex} lines near the beginning of the Texinfo file, before the title -page, like this:@refill - -@example -@group -@@iftex -@@cropmarks -@@end iftex -@end group -@end example - -This command is mainly for printers that typeset several pages on one -sheet of film; but you can attempt to use it to mark the corners of a -book set to 7 by 9.25 inches with the @code{@@smallbook} 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 the -@file{texinfo.tex} definitions file.@refill - -@findex mag @r{(@TeX{} command)} -@cindex Magnified printing -@cindex Larger or smaller pages -You can attempt to direct @TeX{} to typeset pages larger or smaller than -usual with the @code{\mag} @TeX{} command. Everything that is typeset -is scaled proportionally larger or smaller. (@code{\mag} stands for -``magnification''.) This is @emph{not} a Texinfo @@-command, but is a -Plain@TeX{} command that is prefixed with a backslash. You have to -write this command between @code{@@tex} and @code{@@end tex} -(@pxref{Using Ordinary TeX Commands, , Using Ordinary @TeX{} -Commands}).@refill - -Follow the @code{\mag} command with an @samp{=} and then a number that -is 1000 times the magnification you desire. For example, to print pages -at 1.2 normal size, write the following near the beginning of the -Texinfo file, before the title page:@refill - -@example -@group -@@tex -\mag=1200 -@@end tex -@end group -@end example - -With some printing technologies, you can print normal-sized copies that -look better than usual by using a larger-than-normal master.@refill - -Depending on your system, @code{\mag} may not work or may work only at -certain magnifications. Be prepared to experiment.@refill - -@node Create an Info File, Install an Info File, Format/Print Hardcopy, Top -@comment node-name, next, previous, up -@chapter Creating an Info File -@cindex Creating an Info file -@cindex Info, creating an on-line file -@cindex Formatting a file for Info - -@code{makeinfo} is a utility that converts a Texinfo file into an Info -file; @code{texinfo-format-region} and @code{texinfo-format-buffer} are -GNU Emacs functions that do the same.@refill - -A Texinfo file must possess an @code{@@setfilename} line near its -beginning, otherwise the Info formatting commands will fail.@refill - -For information on installing the Info file in the Info system, see -@ref{Install an Info File}.@refill - -@menu -* makeinfo advantages:: @code{makeinfo} provides better error checking. -* Invoking makeinfo:: How to run @code{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 @code{makeinfo} from Emacs. -* texinfo-format commands:: Two Info formatting commands written - in Emacs Lisp are an alternative - to @code{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. -@end menu - -@node makeinfo advantages, Invoking makeinfo, , Create an Info File -@ifinfo -@heading @code{makeinfo} Preferred -@end ifinfo - -The @code{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. @code{makeinfo} is a -C program that is independent of Emacs. You do not need to run Emacs to -use @code{makeinfo}, which means you can use @code{makeinfo} on machines -that are too small to run Emacs. You can run @code{makeinfo} in -any one of three ways: from an operating system shell, from a shell -inside Emacs, or by typing a key command in Texinfo mode in Emacs. -@refill - -The @code{texinfo-format-region} and the @code{texinfo-format-buffer} -commands are useful if you cannot run @code{makeinfo}. Also, in some -circumstances, they format short regions or buffers more quickly than -@code{makeinfo}.@refill - -@node Invoking makeinfo, makeinfo options, makeinfo advantages, Create an Info File -@section Invoking @code{makeinfo} from a Shell - -To create an Info file from a Texinfo file, type @code{makeinfo} -followed by the name of the Texinfo file. Thus, to create the Info -file for Bison, type the following at the shell prompt (where @samp{%} -is the prompt):@refill - -@example -% makeinfo bison.texinfo -@end example - -(You can run a shell inside Emacs by typing @kbd{M-x -shell}.)@refill - -@ifinfo -Sometimes you will want to specify options. For example, if you wish -to discover which version of @code{makeinfo} you are using, -type:@refill - -@example -% makeinfo --version -@end example - -@xref{makeinfo options}, for more information. -@end ifinfo - -@node makeinfo options, Pointer Validation, Invoking makeinfo, Create an Info File -@comment node-name, next, previous, up -@section Options for @code{makeinfo} -@cindex @code{makeinfo} options -@cindex Options for @code{makeinfo} - -The @code{makeinfo} command takes a number of options. Most often, -options are used to set the value of the fill column and specify the -footnote style. Each command line option is a word preceded by -@samp{--}@footnote{@samp{--} has replaced @samp{+}, the old introductory -character, to maintain POSIX.2 compatibility without losing long-named -options.} or a letter preceded by @samp{-}. You can use abbreviations -for the option names as long as they are unique.@refill - -For example, you could use the following command to create an Info -file for @file{bison.texinfo} in which each line is filled to only 68 -columns (where @samp{%} is the prompt):@refill - -@example -% makeinfo --fill-column=68 bison.texinfo -@end example - -You can write two or more options in sequence, like this:@refill - -@example -% makeinfo --no-split --fill-column=70 @dots{} -@end example - -@noindent -This would keep the Info file together as one possibly very long -file and would also set the fill column to 70.@refill - -@iftex -If you wish to discover which version of @code{makeinfo} -you are using, type:@refill - -@example -% makeinfo --version -@end example -@end iftex - -The options are:@refill - -@need 100 -@table @code -@item -D @var{var} -Cause @var{var} to be defined. This is equivalent to -@code{@@set @var{var}} in the Texinfo file. - -@need 150 -@item --error-limit @var{limit} -Set the maximum number of errors that @code{makeinfo} will report -before exiting (on the assumption that continuing would be useless). -The default number of errors that can be reported before -@code{makeinfo} gives up is 100.@refill - -@need 150 -@item --fill-column @var{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 -for @code{fill-column} is 72. -@refill - -@item --footnote-style @var{style} -Set the footnote style to @var{style}, either @samp{end} for the end -node style or @samp{separate} for the separate node style. The value -set by this option overrides the value set in a Texinfo file by an -@code{@@footnotestyle} command. When the footnote style is -@samp{separate}, @code{makeinfo} makes a new node containing the -footnotes found in the current node. When the footnote style is -@samp{end}, @code{makeinfo} places the footnote references at the end -of the current node.@refill - -@need 150 -@item -I @var{dir} -Add @code{dir} to the directory search list for finding files that are -included using the @code{@@include} command. By default, -@code{makeinfo} searches only the current directory. - -@need 150 -@item --no-headers -Do not include menus or node lines in the output. This results in an -@sc{ascii} file that you cannot read in Info since it does not contain -the requisite nodes or menus; but you can print such a file in a -single, typewriter-like font and produce acceptable output. - -@need 150 -@item --no-split -Suppress the splitting stage of @code{makeinfo}. Normally, large -output files (where the size is greater than 70k bytes) are split into -smaller subfiles, each one approximately 50k bytes. If you specify -@samp{--no-split}, @code{makeinfo} will not split up the output -file.@refill - -@need 100 -@item --no-pointer-validate -@item --no-validate -Suppress the pointer-validation phase of @code{makeinfo}. Normally, -after a Texinfo file is processed, some consistency checks are made to -ensure that cross references can be resolved, etc. -@xref{Pointer Validation}.@refill - -@need 150 -@item --no-warn -Suppress the output of warning messages. This does @emph{not} -suppress the output of error messages, only warnings. You might -want this if the file you are creating has examples of Texinfo cross -references within it, and the nodes that are referenced do not actually -exist.@refill - -@item --no-number-footnotes -Supress automatic footnote numbering. By default, @code{makeinfo} -numbers each footnote sequentially in a single node, resetting the -current footnote number to 1 at the start of each node. - -@need 150 -@item --output @var{file} -@itemx -o @var{file} -Specify that the output should be directed to @var{file} and not to the -file name specified in the @code{@@setfilename} command found in the Texinfo -source. @var{file} can be the special token @samp{-}, which specifies -standard output. - -@need 150 -@item --paragraph-indent @var{indent} -Set the paragraph indentation style to @var{indent}. The value set by -this option overrides the value set in a Texinfo file by an -@code{@@paragraphindent} command. The value of @var{indent} is -interpreted as follows:@refill - -@itemize @bullet -@item -If the value of @var{indent} is @samp{asis}, do not change the -existing indentation at the starts of paragraphs.@refill - -@item -If the value of @var{indent} is zero, delete any existing -indentation.@refill - -@item -If the value of @var{indent} is greater than zero, indent each -paragraph by that number of spaces.@refill -@end itemize - -@need 100 -@item --reference-limit @var{limit} -Set the value of the number of references to a node that -@code{makeinfo} will make without reporting a warning. If a node has more -than this number of references in it, @code{makeinfo} will make the -references but also report a warning.@refill - -@need 150 -@item -U @var{var} -Cause @var{var} to be undefined. This is equivalent to -@code{@@clear @var{var}} in the Texinfo file. - -@need 100 -@item --verbose -Cause @code{makeinfo} to display messages saying what it is doing. -Normally, @code{makeinfo} only outputs messages if there are errors or -warnings.@refill - -@need 100 -@item --version -Report the version number of this copy of @code{makeinfo}.@refill -@end table - -@node Pointer Validation, makeinfo in Emacs, makeinfo options, Create an Info File -@section Pointer Validation -@cindex Pointer validation with @code{makeinfo} -@cindex Validation of pointers - -@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93 -@code{makeinfo} will check the validity of the final Info file unless -you suppress pointer-validation by using the -@samp{--no-pointer-validation} option. Mostly, this means ensuring -that nodes you have referenced really exist. Here is a complete list -of what is checked:@refill - -@enumerate -@item -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 -@file{(dir)}, then the referenced node must exist.@refill - -@item -In every node, if the `Previous' node is different from the `Up' node, -then the `Previous' node must also be pointed to by a `Next' node.@refill - -@item -Every node except the `Top' node must have an `Up' pointer.@refill - -@item -The node referenced by an `Up' pointer must contain a reference to the -current node in some manner other than through a `Next' reference. -This includes menu entries and cross references.@refill - -@item -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.@refill -@end enumerate - -@node makeinfo in Emacs, texinfo-format commands, Pointer Validation, Create an Info File -@section Running @code{makeinfo} inside Emacs -@cindex Running @code{makeinfo} in Emacs -@cindex @code{makeinfo} inside Emacs -@cindex Shell, running @code{makeinfo} in - -You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the -@code{makeinfo-region} or the @code{makeinfo-buffer} commands. In -Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c -C-m C-b} by default.@refill - -@table @kbd -@item C-c C-m C-r -@itemx M-x makeinfo-region -Format the current region for Info.@refill -@findex makeinfo-region - -@item C-c C-m C-b -@itemx M-x makeinfo-buffer -Format the current buffer for Info.@refill -@findex makeinfo-buffer -@end table - -When you invoke either @code{makeinfo-region} or -@code{makeinfo-buffer}, Emacs prompts for a file name, offering the -name of the visited file as the default. You can edit the default -file name in the minibuffer if you wish, before typing @key{RET} to -start the @code{makeinfo} process.@refill - -The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands -run the @code{makeinfo} program in a temporary shell buffer. If -@code{makeinfo} finds any errors, Emacs displays the error messages in -the temporary buffer.@refill - -@cindex Errors, parsing -@cindex Parsing errors -@findex next-error -You can parse the error messages by typing @kbd{C-x `} -(@code{next-error}). This causes Emacs to go to and position the -cursor on the line in the Texinfo source that @code{makeinfo} thinks -caused the error. @xref{Compilation, , Running @code{make} or -Compilers Generally, emacs, The GNU Emacs Manual}, for more -information about using the @code{next-error} command.@refill - -In addition, you can kill the shell in which the @code{makeinfo} -command is running or make the shell buffer display its most recent -output.@refill - - -@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93 -@table @kbd -@item C-c C-m C-k -@itemx M-x makeinfo-kill-job -@findex makeinfo-kill-job -Kill the currently running job created by -@code{makeinfo-region} or @code{makeinfo-buffer}.@refill - -@item C-c C-m C-l -@itemx M-x makeinfo-recenter-output-buffer -@findex makeinfo-recenter-output-buffer -Redisplay the @code{makeinfo} shell buffer to display its most recent -output.@refill -@end table - -@noindent -(Note that the parallel commands for killing and recentering a @TeX{} -job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode -Printing}.)@refill - -You can specify options for @code{makeinfo} by setting the -@code{makeinfo-options} variable with either the @kbd{M-x -edit-options} or the @kbd{M-x set-variable} command, or by setting the -variable in your @file{.emacs} initialization file.@refill - -For example, you could write the following in your @file{.emacs} file:@refill - -@example -@group -(setq makeinfo-options - "--paragraph-indent=0 --no-split - --fill-column=70 --verbose") -@end group -@end example - -@c If you write these three cross references using xref, you see -@c three references to the same named manual, which looks strange. -@iftex -For more information, see @ref{makeinfo options, , Options for -@code{makeinfo}}, as well as ``Editing Variable Values,''``Examining and -Setting Variables,'' and ``Init File'' in the @cite{The GNU Emacs -Manual}. -@end iftex -@noindent -@ifinfo -For more information, see@* -@ref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs Manual},@* -@ref{Examining, , Examining and Setting Variables, emacs, The GNU Emacs Manual},@* -@ref{Init File, , , emacs, The GNU Emacs Manual}, and@* -@ref{makeinfo options, , Options for @code{makeinfo}}. -@end ifinfo - -@node texinfo-format commands, Batch Formatting, makeinfo in Emacs, Create an Info File -@comment node-name, next, previous, up -@section The @code{texinfo-format@dots{}} Commands -@findex texinfo-format-region -@findex texinfo-format-buffer - -In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo -file with the @code{texinfo-format-region} command. This formats the -current region and displays the formatted text in a temporary buffer -called @samp{*Info Region*}.@refill - -Similarly, you can format a buffer with the -@code{texinfo-format-buffer} command. This command creates a new -buffer and generates the Info file in it. Typing @kbd{C-x C-s} will -save the Info file under the name specified by the -@code{@@setfilename} line which must be near the beginning of the -Texinfo file.@refill - -@table @kbd -@item C-c C-e C-r -@itemx @code{texinfo-format-region} -Format the current region for Info. -@findex texinfo-format-region - -@item C-c C-e C-b -@itemx @code{texinfo-format-buffer} -Format the current buffer for Info. -@findex texinfo-format-buffer -@end table - -The @code{texinfo-format-region} and @code{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 @ref{Catching Mistakes}. -However, the @code{makeinfo} program is often faster and -provides better error checking (@pxref{makeinfo in Emacs}).@refill - -@node Batch Formatting, Tag and Split Files, texinfo-format commands, Create an Info File -@comment node-name, next, previous, up -@section Batch Formatting -@cindex Batch formatting for Info -@cindex Info batch formatting - -You can format Texinfo files for Info using @code{batch-texinfo-format} -and Emacs Batch mode. You can run Emacs in Batch mode from any shell, -including a shell inside of Emacs. (@xref{Command Switches, , Command -Line Switches and Arguments, emacs, The GNU Emacs Manual}.)@refill - -Here is the command to format all the files that end in @file{.texinfo} -in the current directory (where @samp{%} is the shell prompt):@refill - -@example -% emacs -batch -funcall batch-texinfo-format *.texinfo -@end example - -@noindent -Emacs processes all the files listed on the command line, even if an -error occurs while attempting to format some of them.@refill - -Run @code{batch-texinfo-format} only with Emacs in Batch mode as shown; -it is not interactive. It kills the Batch mode Emacs on completion.@refill - -@code{batch-texinfo-format} is convenient if you lack @code{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 -@code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot -use that Emacs for anything else until the command finishes.)@refill - -@node Tag and Split Files, , Batch Formatting, Create an Info File -@comment node-name, next, previous, up -@section Tag Files and Split Files -@cindex Making a tag table automatically -@cindex Tag table, making automatically - -If a Texinfo file has more than 30,000 bytes, -@code{texinfo-format-buffer} automatically creates a tag table -for its Info file; @code{makeinfo} always creates a tag table. With -a @dfn{tag table}, Info can jump to new nodes more quickly than it can -otherwise.@refill - -@cindex Indirect subfiles -In addition, if the Texinfo file contains more than about 70,000 -bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the -large Info file into shorter @dfn{indirect} subfiles of about 50,000 -bytes each. Big files are split into smaller files so that Emacs does -not need to make a large buffer to hold the whole of a large Info -file; instead, Emacs allocates just enough memory for the small, split -off file that is needed at the time. This way, Emacs avoids wasting -memory when you run Info. (Before splitting was implemented, Info -files were always kept short and @dfn{include files} were designed as -a way to create a single, large printed manual out of the smaller Info -files. @xref{Include Files}, for more information. Include files are -still used for very large documents, such as @cite{The Emacs Lisp -Reference Manual}, in which each chapter is a separate file.)@refill - -When a file is split, Info itself makes use of a shortened version of -the original file that contains just the tag table and references to -the files that were split off. The split off files are called -@dfn{indirect} files.@refill - -The split off files have names that are created by appending @w{@samp{-1}}, -@w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the -@code{@@setfilename} command. The shortened version of the original file -continues to have the name specified by @code{@@setfilename}.@refill - -At one stage in writing this document, for example, the Info file was saved -as @file{test-texinfo} and that file looked like this:@refill - -@example -@group -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 -@dots{} -@end group -@end example - -@noindent -(But @file{test-texinfo} had far more nodes than are shown here.) Each of -the split off, indirect files, @file{test-texinfo-1}, -@file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file -after the line that says @samp{Indirect:}. The tag table is listed after -the line that says @samp{Tag table:}. @refill - -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.@refill - -If you are using @code{texinfo-format-buffer} to create Info files, -you may want to run the @code{Info-validate} command. (The -@code{makeinfo} command does such a good job on its own, you do not -need @code{Info-validate}.) However, you cannot run the @kbd{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 @ref{Using -Info-validate}.@refill - -@node Install an Info File, Command List, Create an Info File, Top -@comment node-name, next, previous, up -@chapter Installing an Info File -@cindex Installing an Info file -@cindex Info file installation -@cindex @file{dir} directory for Info installation - -Info files are usually kept in the @file{info} -directory. (You can find the location of this directory within Emacs -by typing @kbd{C-h i} to enter Info and then typing @kbd{C-x C-f} to -see the full pathname to the @file{info} directory.) - -@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. -@end menu - -@node Directory file, New Info File, , Install an Info File -@ifinfo -@heading The @file{dir} File -@end ifinfo - -For Info to work, the @file{info} directory must contain a file that -serves as a top level directory for the Info system. By convention, -this file is called @file{dir}. The @file{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:@refill - -@example -* Menu: - -* Info: (info). Documentation browsing system. -* Emacs: (emacs). The extensible, self-documenting - text editor. -* Texinfo: (texinfo). With one source file, make - either a printed manual using - TeX or an Info file. -@dots{} -@end example - -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. @xref{Other Info Files, , Nodes in Other Info -Files}.)@refill - -Thus, the @samp{Info} entry points to the `Top' node of the -@file{info} file and the @samp{Emacs} entry points to the `Top' node -of the @file{emacs} file.@refill - -In each of the Info files, the `Up' pointer of the `Top' node refers -back to the @code{dir} file. For example, the line for the `Top' -node of the Emacs manual looks like this in Info:@refill - -@example -File: emacs Node: Top, Up: (DIR), Next: Distrib -@end example - -@noindent -(Note that in this case, the @file{dir} file name is written in upper -case letters---it can be written in either upper or lower case. Info -has a feature that it will change the case of the file name to lower -case if it cannot find the name as written.)@refill - -@c !!! Can any file name be written in upper or lower case, -@c or is dir a special case? -@c Yes, apparently so, at least with Gillespie's Info. --rjc 24mar92 -@c -@node New Info File, Other Info Directories, Directory file, Install an Info File -@section Listing a New Info File -@cindex Adding a new info file -@cindex Listing a new info file -@cindex New info file, listing it in @file{dir} file -@cindex Info file, listing new one -@cindex @file{dir} file listing - -To add a new Info file to your system, write a menu entry for it in the -menu in the @file{dir} file in the @file{info} directory. Also, move -the new Info file itself to the @file{info} directory. For example, if -you were adding documentation for GDB, you would write the following new -entry:@refill - -@example -* GDB: (gdb). The source-level C debugger. -@end example - -@noindent -The first part of the menu entry is the menu entry name, followed by a -colon. The second part is the name of the Info file, in parentheses, -followed by a period. The third part is the description.@refill - -Conventionally, the name of an Info file has a @file{.info} extension. -Thus, you might list the name of the file like this: - -@example -* GDB: (gdb.info). The source-level C debugger. -@end example - -@noindent -However, Info will look for a file with a @file{.info} extension if it -does not find the file under the name given in the menu. This means -that you can refer to the file @file{gdb.info} as @file{gdb}, as shown -in the first example. This looks better. - -@node Other Info Directories, , New Info File, Install an Info File -@comment node-name, next, previous, up -@section Info Files in Other Directories -@cindex Installing Info in another directory -@cindex Info installed in another directory -@cindex Another Info directory - -If an Info file is not in the @file{info} directory, there are two -ways to specify its location:@refill - -@itemize @bullet -@item -Write the pathname as the menu's second part, or;@refill - -@item -Specify the @file{info} directory name in an environment variable in -your @file{.profile} or @file{.cshrc} initialization file. (Only you -and others with the same environment variable will be able to find Info -files whose location is specified this way.)@refill -@end itemize - -For example, to reach a test file in the @file{~bob/manuals} -directory, you could add an entry like this to the menu in the -@file{dir} file:@refill - -@example -* Test: (~bob/manuals/info-test). Bob's own test file. -@end example - -@noindent -In this case, the absolute file name of the @file{info-test} file is -written as the second part of the menu entry.@refill - -@vindex INFOPATH -Alternatively, you can tell Info where to look by setting the -@code{INFOPATH} environment variable in your @file{.cshrc} or -@file{.profile} file.@refill - -If you use @code{sh} or @code{bash} for your shell command interpreter, -you must set the @code{INFOPATH} environment variable in the -@file{.profile} initialization file; but if you use @code{csh}, you must -set the variable in the @file{.cshrc} initialization file. The two -files require slightly different command formats.@refill - -@itemize @bullet -@item -In a @file{.cshrc} file, you could set the @code{INFOPATH} -variable as follows:@refill - -@smallexample -setenv INFOPATH .:~bob/manuals:/usr/local/emacs/info -@end smallexample - -@item -In a @file{.profile} file, you would achieve the same effect by -writing:@refill - -@smallexample -INFOPATH=.:~bob/manuals:/usr/local/emacs/info -export INFOPATH -@end smallexample -@end itemize - -@noindent -Either form would cause Info to look first in the current directory, -indicated by the @samp{.}, then in the @file{~bob/manuals} directory, -and finally in the @file{/usr/local/emacs/info} directory (which is -a common location for the standard Info directory).@refill - -@c ================ Appendix starts here ================ - -@node Command List, Tips, Install an Info File, Top -@appendix @@-Command List -@cindex Alphabetical @@-command list -@cindex List of @@-commands -@cindex @@-command list - -Here is an alphabetical list of the @@-commands in Texinfo. Square -brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis, -@samp{@dots{}}, indicates repeated text.@refill - -@sp 1 -@table @code -@item @@* -Force a line break. Do not end a paragraph that uses @code{@@*} with -an @code{@@refill} command. @xref{Line Breaks}.@refill - -@item @@. -Stands for a period that really does end a sentence (usually after an -end-of-sentence capital letter). @xref{Controlling Spacing}.@refill - -@item @@: -Indicate to @TeX{} that an immediately preceding period, question -mark, exclamation mark, or colon does not end a sentence. Prevent -@TeX{} from inserting extra whitespace as it does at the end of a -sentence. The command has no effect on the Info file output. -@xref{Controlling Spacing}.@refill - -@item @@@@ -Stands for @samp{@@}. @xref{Braces Atsigns Periods, , Inserting -@samp{@@}}.@refill - -@item @@@{ -Stands for a left-hand brace, @samp{@{}. -@xref{Braces Atsigns Periods, , Inserting @@ braces and periods}.@refill - -@item @@@} -Stands for a right-hand brace, @samp{@}}. -@xref{Braces Atsigns Periods, , Inserting @@ braces and periods}.@refill - -@item @@appendix @var{title} -Begin an appendix. The title appears in the table -of contents of a printed manual. In Info, the title is -underlined with asterisks. @xref{unnumbered & appendix, , The -@code{@@unnumbered} and @code{@@appendix} Commands}.@refill - -@item @@appendixsec @var{title} -@itemx @@appendixsection @var{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. @code{@@appendixsection} is a longer -spelling of the @code{@@appendixsec} command. @xref{unnumberedsec -appendixsec heading, , Section Commands}.@refill - -@item @@appendixsubsec @var{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. @xref{unnumberedsubsec appendixsubsec -subheading, , Subsection Commands}.@refill - -@item @@appendixsubsubsec @var{title} -Begin an appendix subsubsection within a subappendix. The title -appears in the table of contents of a printed manual. In Info, the -title is underlined with periods. @xref{subsubsection,, The `subsub' -Commands}.@refill - -@item @@asis -Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to -print the table's first column without highlighting (``as is''). -@xref{Two-column Tables, , Making a Two-column Table}.@refill - -@item @@author @var{author} -Typeset @var{author} flushleft and underline it. @xref{title -subtitle author, , The @code{@@title} and @code{@@author} -Commands}.@refill - -@item @@b@{@var{text}@} -Print @var{text} in @b{bold} font. No effect in Info. @xref{Fonts}.@refill - -@ignore -@item @@br -Force a paragraph break. If used within a line, follow @code{@@br} -with braces. @xref{br, , @code{@@br}}.@refill -@end ignore - -@item @@bullet@{@} -Generate a large round dot, or the closest possible -thing to one. @xref{bullet, , @code{@@bullet}}.@refill - -@item @@bye -Stop formatting a file. The formatters do not see the contents of a -file following an @code{@@bye} command. @xref{Ending a File}.@refill - -@item @@c @var{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 -@code{@@comment}. @xref{Conventions, , General Syntactic -Conventions}.@refill - -@item @@cartouche -Highlight an example or quotation by drawing a box with rounded -corners around it. Pair with @code{@@end cartouche}. No effect in -Info. @xref{cartouche, , Drawing Cartouches Around Examples}.)@refill - -@item @@center @var{line-of-text} -Center the line of text following the command. -@xref{titlefont center sp, , @code{@@center}}.@refill - -@item @@chapheading @var{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. @xref{majorheading & chapheading, , @code{@@majorheading} -and @code{@@chapheading}}.@refill - -@item @@chapter @var{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. @xref{chapter, , @code{@@chapter}}.@refill - -@item @@cindex @var{entry} -Add @var{entry} to the index of concepts. @xref{Index Entries, , -Defining the Entries of an Index}.@refill - -@item @@cite@{@var{reference}@} -Highlight the name of a book or other reference that lacks a -companion Info file. @xref{cite, , @code{@@cite}}.@refill - -@item @@clear @var{flag} -Unset @var{flag}, preventing the Texinfo formatting commands from -formatting text between subsequent pairs of @code{@@ifset @var{flag}} -and @code{@@end ifset} commands, and preventing -@code{@@value@{@var{flag}@}} from expanding to the value to which -@var{flag} is set. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@item @@code@{@var{sample-code}@} -Highlight text that is an expression, a syntactically complete token -of a program, or a program name. @xref{code, , @code{@@code}}.@refill - -@item @@comment @var{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 @code{@@c}. -@xref{Conventions, , General Syntactic Conventions}.@refill - -@item @@contents -Print a complete table of contents. Has no effect in Info, which uses -menus instead. @xref{Contents, , Generating a Table of -Contents}.@refill - -@item @@copyright@{@} -Generate a copyright symbol. @xref{copyright symbol, , -@code{@@copyright}}.@refill - -@ignore -@item @@ctrl@{@var{ctrl-char}@} -Describe an @sc{ascii} control character. Insert actual control character -into Info file. @xref{ctrl, , @code{@@ctrl}}.@refill -@end ignore - -@item @@defcodeindex @var{index-name} -Define a new index and its indexing command. Print entries in an -@code{@@code} font. @xref{New Indices, , Defining New -Indices}.@refill - -@item @@defcv @var{category} @var{class} @var{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. -@xref{Definition Commands}.@refill - -@item @@deffn @var{category} @var{name} @var{arguments}@dots{} -Format a description for a function, interactive command, or similar -entity that may take arguments. @code{@@deffn} takes as arguments the -category of entity being described, the name of this particular -entity, and its arguments, if any. @xref{Definition Commands}.@refill - -@item @@defindex @var{index-name} -Define a new index and its indexing command. Print entries in a roman -font. @xref{New Indices, , Defining New Indices}.@refill - -@item @@defivar @var{class} @var{instance-variable-name} -Format a description for an instance variable in object-oriented -programming. The command is equivalent to @samp{@@defcv @{Instance -Variable@} @dots{}}. @xref{Definition Commands}.@refill - -@item @@defmac @var{macro-name} @var{arguments}@dots{} -Format a description for a macro. The command is equivalent to -@samp{@@deffn Macro @dots{}}. @xref{Definition Commands}.@refill - -@item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{} -Format a description for a method in object-oriented programming. The -command is equivalent to @samp{@@defop Method @dots{}}. Takes as -arguments the name of the class of the method, the name of the -method, and its arguments, if any. @xref{Definition Commands}.@refill - -@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} -Format a description for an operation in object-oriented programming. -@code{@@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. @xref{Definition -Commands}.@refill - -@need 100 -@item @@defopt @var{option-name} -Format a description for a user option. The command is equivalent to -@samp{@@defvr @{User Option@} @dots{}}. @xref{Definition Commands}.@refill - -@need 100 -@item @@defspec @var{special-form-name} @var{arguments}@dots{} -Format a description for a special form. The command is equivalent to -@samp{@@deffn @{Special Form@} @dots{}}. @xref{Definition Commands}.@refill - -@need 200 -@item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{} -Format a description for a data type. @code{@@deftp} takes as -arguments the category, the name of the type (which is a word like -@samp{int} or @samp{float}), and then the names of attributes of -objects of that -type. @xref{Definition Commands}.@refill - -@item @@deftypefn @var{classification} @var{data-type} @var{name} @var{arguments}@dots{} -Format a description for a function or similar entity that may take -arguments and that is typed. @code{@@deftypefn} takes as arguments -the classification of entity being described, the type, the name of -the entity, and its arguments, if any. @xref{Definition -Commands}.@refill - -@item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{} -Format a description for a function in a typed language. -The command is equivalent to @samp{@@deftypefn Function @dots{}}. -@xref{Definition Commands}.@refill - -@item @@deftypevr @var{classification} @var{data-type} @var{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. @xref{Definition Commands}.@refill - -@item @@deftypevar @var{data-type} @var{variable-name} -Format a description for a variable in a typed language. The command is -equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition -Commands}.@refill - -@item @@defun @var{function-name} @var{arguments}@dots{} -Format a description for functions. The command is equivalent to -@samp{@@deffn Function @dots{}}. @xref{Definition Commands}.@refill - -@item @@defvar @var{variable-name} -Format a description for variables. The command is equivalent to -@samp{@@defvr Variable @dots{}}. @xref{Definition Commands}.@refill - -@item @@defvr @var{category} @var{name} -Format a description for any kind of variable. @code{@@defvr} takes -as arguments the category of the entity and the name of the entity. -@xref{Definition Commands}.@refill - -@item @@dfn@{@var{term}@} -Highlight the introductory or defining use of a term. -@xref{dfn, , @code{@@dfn}}.@refill - -@need 100 -@item @@display -Begin a kind of example. Indent text, do not fill, do not select a -new font. Pair with @code{@@end display}. @xref{display, , -@code{@@display}}.@refill - -@need 100 -@item @@dmn@{@var{dimension}@} -Format a dimension. Cause @TeX{} to insert a narrow space before -@var{dimension}. No effect in Info. Use for writing a number -followed by an abbreviation of a dimension name, such as -@samp{12@dmn{pt}}, written as @samp{12@@dmn@{pt@}}, with no space -between the number and the @code{@@dmn} command. @xref{dmn, , -@code{@@dmn}}.@refill - -@need 100 -@item @@dots@{@} -Insert an ellipsis: @samp{@dots{}}. -@xref{dots, , @code{@@dots}}.@refill - -@need 100 -@item @@emph@{@var{text}@} -Highlight @var{text}; text is displayed in @emph{italics} in printed -output, and surrounded by asterisks in Info. @xref{Emphasis, , Emphasizing Text}.@refill - -@need 100 -@item @@enumerate [@var{number-or-letter}] -Begin a numbered list, using @code{@@item} for each entry. -Optionally, start list with @var{number-or-letter}. Pair with -@code{@@end enumerate}. @xref{enumerate, , -@code{@@enumerate}}.@refill - -@need 100 -@item @@equiv@{@} -Indicate to the reader the exact equivalence of two forms with a -glyph: @samp{@equiv{}}. @xref{Equivalence}.@refill - -@item @@error@{@} -Indicate to the reader with a glyph that the following text is -an error message: @samp{@error{}}. @xref{Error Glyph}.@refill - -@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] -Specify page footings for even-numbered (left-hand) pages. Not relevant to -Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill - -@item @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}] -Specify page headings for even-numbered (left-hand) pages. Not relevant to -Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill - -@item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] -Specify page footings for every page. Not relevant to Info. @xref{Custom -Headings, , How to Make Your Own Headings}.@refill - -@item @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}] -Specify page headings for every page. Not relevant to Info. @xref{Custom -Headings, , How to Make Your Own Headings}.@refill - -@item @@example -Begin an example. Indent text, do not fill, and select fixed-width font. -Pair with @code{@@end example}. @xref{example, , -@code{@@example}}.@refill - -@item @@exdent @var{line-of-text} -Remove any indentation a line might have. @xref{exdent, , -Undoing the Indentation of a Line}.@refill - -@item @@expansion@{@} -Indicate the result of a macro expansion to the reader with a special -glyph: @samp{@expansion{}}. -@xref{expansion, , @expansion{} Indicating an Expansion}.@refill - -@item @@file@{@var{filename}@} -Highlight the name of a file, buffer, node, or directory. @xref{file, , -@code{@@file}}.@refill - -@item @@finalout -Prevent @TeX{} from printing large black warning rectangles beside -over-wide lines. @xref{Overfull hboxes}.@refill - -@need 100 -@item @@findex @var{entry} -Add @var{entry} to the index of functions. @xref{Index Entries, , -Defining the Entries of an Index}.@refill - -@need 200 -@item @@flushleft -Left justify every line but leave the right end ragged. -Leave font as is. Pair with @code{@@end flushleft}. -@xref{flushleft & flushright, , @code{@@flushleft} and -@code{@@flushright}}.@refill - -@need 200 -@item @@flushright -Right justify every line but leave the left end ragged. -Leave font as is. Pair with @code{@@end flushright}. -@xref{flushleft & flushright, , @code{@@flushleft} and -@code{@@flushright}}.@refill - -@need 200 -@item @@footnote@{@var{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. -@xref{Footnotes}.@refill - -@item @@footnotestyle @var{style} -Specify an Info file's footnote style, either @samp{end} for the end -node style or @samp{separate} for the separate node style. -@xref{Footnotes}.@refill - -@item @@format -Begin a kind of example. Like @code{@@example} or @code{@@display}, -but do not narrow the margins and do not select the fixed-width font. -Pair with @code{@@end format}. @xref{example, , -@code{@@example}}.@refill - -@item @@ftable @var{formatting-command} -Begin a two-column table, using @code{@@item} for each entry. -Automatically enter each of the items in the first column into the -index of functions. Pair with @code{@@end ftable}. The same as -@code{@@table}, except for indexing. @xref{ftable vtable, , -@code{@@ftable} and @code{@@vtable}}.@refill - -@item @@group -Hold text together that must appear on one printed page. Pair with -@code{@@end group}. Not relevant to Info. @xref{group, , -@code{@@group}}.@refill - -@item @@heading @var{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. @xref{unnumberedsec appendixsec heading, -, Section Commands}.@refill - -@item @@headings @var{on-off-single-double} -Turn page headings on or off, or specify single-sided or double-sided -page headings for printing. @code{@@headings on} is synonymous with -@code{@@headings double}. @xref{headings on off, , The -@code{@@headings} Command}.@refill - -@item @@i@{@var{text}@} -Print @var{text} in @i{italic} font. No effect in Info. -@xref{Fonts}.@refill - -@item @@ifclear @var{flag} -If @var{flag} is cleared, the Texinfo formatting commands format text -between @code{@@ifclear @var{flag}} and the following @code{@@end -ifclear} command. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@item @@ifinfo -Begin a stretch of text that will be ignored by @TeX{} when it -typesets the printed manual. The text appears only in the Info file. -Pair with @code{@@end ifinfo}. @xref{Conditionals, , Conditionally -Visible Text}.@refill - -@item @@ifset @var{flag} -If @var{flag} is set, the Texinfo formatting commands format text -between @code{@@ifset @var{flag}} and the following @code{@@end ifset} -command. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@item @@iftex -Begin a stretch of text that will not appear in the Info file, but -will be processed only by @TeX{}. Pair with @code{@@end iftex}. -@xref{Conditionals, , Conditionally Visible Text}.@refill - -@item @@ignore -Begin a stretch of text that will not appear in either the Info file -or the printed output. Pair with @code{@@end ignore}. -@xref{Comments, , Comments and Ignored Text}.@refill - -@item @@include @var{filename} -Incorporate the contents of the file @var{filename} into the Info file -or printed document. @xref{Include Files}.@refill - -@item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@} -Make a cross reference to an Info file for which there is no printed -manual. @xref{inforef, , Cross references using -@code{@@inforef}}.@refill - -@item \input @var{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 -@file{texinfo} macro definitions file. The backslash in @code{\input} -is used instead of an @code{@@} because @TeX{} does not properly -recognize @code{@@} until after it has read the definitions file. -@xref{Header, , The Texinfo File Header}.@refill - -@item @@item -Indicate the beginning of a marked paragraph for @code{@@itemize} and -@code{@@enumerate}; indicate the beginning of the text of a first column -entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}. -@xref{Lists and Tables}.@refill - -@item @@itemize @var{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 @code{@@end -itemize}. @xref{itemize, , @code{@@itemize}}.@refill - -@item @@itemx -Like @code{@@item} but do not generate extra vertical space above the -item text. @xref{itemx, , @code{@@itemx}}.@refill - -@item @@kbd@{@var{keyboard-characters}@} -Indicate text that consists of characters of input to be typed by -users. @xref{kbd, , @code{@@kbd}}.@refill - -@item @@key@{@var{key-name}@} -Highlight @var{key-name}, a conventional name for a key on a keyboard. -@xref{key, , @code{@@key}}.@refill - -@item @@kindex @var{entry} -Add @var{entry} to the index of keys. @xref{Index Entries, , Defining the -Entries of an Index}.@refill - -@item @@lisp -Begin an example of Lisp code. Indent text, do not fill, and select -fixed-width font. Pair with @code{@@end lisp}. @xref{Lisp Example, , -@code{@@lisp}}.@refill - -@item @@majorheading @var{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 @code{@@chapheading} command. In Info, the chapter -heading line is underlined with asterisks. @xref{majorheading & -chapheading, , @code{@@majorheading} and @code{@@chapheading}}.@refill - -@item @@menu -Mark the beginning of a menu of nodes in Info. No effect in a printed -manual. Pair with @code{@@end menu}. @xref{Menus}.@refill - -@item @@minus@{@} -Generate a minus sign. @xref{minus, , @code{@@minus}}.@refill - -@item @@need @var{n} -Start a new page in a printed manual if fewer than @var{n} mils -(thousandths of an inch) remain on the current page. @xref{need, , -@code{@@need}}.@refill - -@item @@node @var{name, next, previous, up} -Define the beginning of a new node in Info, and serve as a locator for -references for @TeX{}. @xref{node, , @code{@@node}}.@refill - -@need 200 -@item @@noindent -Prevent text from being indented as if it were a new paragraph. -@xref{noindent, , @code{@@noindent}}.@refill - -@item @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] -Specify page footings for odd-numbered (right-hand) pages. Not relevant to -Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill - -@item @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}] -Specify page headings for odd-numbered (right-hand) pages. Not relevant to -Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill - -@item @@page -Start a new page in a printed manual. No effect in Info. -@xref{page, , @code{@@page}}.@refill - -@item @@paragraphindent @var{indent} -Indent paragraphs by @var{indent} number of spaces; delete indentation -if the value of @var{indent} is 0; and do not change indentation if -@var{indent} is @code{asis}. @xref{paragraphindent, , Paragraph -Indenting}.@refill - -@item @@pindex @var{entry} -Add @var{entry} to the index of programs. @xref{Index Entries, , Defining -the Entries of an Index}.@refill - -@item @@point@{@} -Indicate the position of point in a buffer to the reader with a -glyph: @samp{@point{}}. @xref{Point Glyph, , Indicating -Point in a Buffer}.@refill - -@item @@print@{@} -Indicate printed output to the reader with a glyph: -@samp{@print{}}. @xref{Print Glyph}.@refill - -@item @@printindex @var{index-name} -Print an alphabetized two-column index in a printed manual or generate -an alphabetized menu of index entries for Info. @xref{Printing -Indices & Menus}.@refill - -@item @@pxref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{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, which is why you do not need to -insert punctuation. Only the first argument is mandatory. -@xref{pxref, , @code{@@pxref}}.@refill - -@item @@quotation -Narrow the margins to indicate text that is quoted from another real -or imaginary work. Write command on a line of its own. Pair with -@code{@@end quotation}. @xref{quotation, , -@code{@@quotation}}.@refill - -@need 100 -@item @@r@{@var{text}@} -Print @var{text} in @r{roman} font. No effect in Info. -@xref{Fonts}.@refill - -@need 300 -@item @@ref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{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. @xref{ref, , @code{@@ref}}.@refill - -@need 300 -@item @@refill -In Info, refill and indent the paragraph after all the other processing -has been done. No effect on @TeX{}, which always refills. This command -is no longer needed, since all formatters now automatically refill. -@xref{Refilling Paragraphs}.@refill - -@need 300 -@item @@result@{@} -Indicate the result of an expression to the reader with a special -glyph: @samp{@result{}}. @xref{result, , @code{@@result}}.@refill - -@item @@samp@{@var{text}@} -Highlight @var{text} that is a literal example of a sequence of -characters. Used for single characters, for statements, and often for -entire shell commands. @xref{samp, , @code{@@samp}}.@refill - -@item @@sc@{@var{text}@} -Set @var{text} in a printed output in @sc{the small caps font} and -set text in the Info file in uppercase letters. -@xref{Smallcaps}.@refill - -@item @@section @var{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. @xref{section, , -@code{@@section}}.@refill - -@item @@set @var{flag} [@var{string}] -Make @var{flag} active, causing the Texinfo formatting commands to -format text between subsequent pairs of @code{@@ifset @var{flag}} and -@code{@@end ifset} commands. Optionally, set value of @var{flag} to -@var{string}. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@item @@setchapternewpage @var{on-off-odd} -Specify whether chapters start on new pages, and if so, whether on -odd-numbered (right-hand) new pages. @xref{setchapternewpage, , -@code{@@setchapternewpage}}.@refill - -@item @@setfilename @var{info-file-name} -Provide a name for the Info file. @xref{Conventions, , General -Syntactic Conventions}.@refill - -@item @@settitle @var{title} -Provide a title for page headers in a printed manual. -@xref{Conventions, , General Syntactic Conventions}.@refill - -@item @@shortcontents -Print a short table of contents. Not relevant to Info, which uses -menus rather than tables of contents. A synonym for -@code{@@summarycontents}. @xref{Contents, , Generating a Table of -Contents}.@refill - -@need 400 -@item @@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. @xref{smallbook, , -Printing Small Books}. Also, see @ref{smallexample & smalllisp, , -@code{@@smallexample} and @code{@@smalllisp}}.@refill - -@need 400 -@item @@smallexample -Indent text to indicate an example. Do not fill, select fixed-width -font. In @code{@@smallbook} format, print text in a smaller font than -with @code{@@example}. Pair with @code{@@end smallexample}. -@xref{smallexample & smalllisp, , @code{@@smallexample} and -@code{@@smalllisp}}.@refill - -@need 400 -@item @@smalllisp -Begin an example of Lisp code. Indent text, do not fill, select -fixed-width font. In @code{@@smallbook} format, print text in a -smaller font. Pair with @code{@@end smalllisp}. @xref{smallexample & -smalllisp, , @code{@@smallexample} and @code{@@smalllisp}}.@refill - -@need 700 -@item @@sp @var{n} -Skip @var{n} blank lines. @xref{sp, , @code{@@sp}}.@refill - -@need 700 -@item @@strong @var{text} -Emphasize @var{text} by typesetting it in a @strong{bold} font for the -printed manual and by surrounding it with asterisks for Info. -@xref{emph & strong, , Emphasizing Text}.@refill - -@item @@subheading @var{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. @xref{unnumberedsubsec appendixsubsec -subheading, , @code{@@unnumberedsubsec} @code{@@appendixsubsec} -@code{@@subheading}}.@refill - -@item @@subsection @var{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. @xref{subsection, , -@code{@@subsection}}.@refill - -@item @@subsubheading @var{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. @xref{subsubsection, , The `subsub' -Commands}.@refill - -@item @@subsubsection @var{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. -@xref{subsubsection, , The `subsub' Commands}.@refill - -@item @@subtitle @var{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. @xref{title subtitle author, , @code{@@title} -@code{@@subtitle} and @code{@@author} Commands}.@refill - -@item @@summarycontents -Print a short table of contents. Not relevant to Info, which uses -menus rather than tables of contents. A synonym for -@code{@@shortcontents}. @xref{Contents, , Generating a Table of -Contents}.@refill - -@need 300 -@item @@syncodeindex @var{from-index} @var{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{@@code} font. @xref{Combining Indices}.@refill - -@need 300 -@item @@synindex @var{from-index} @var{into-index} -Merge the index named in the first argument into the index named in -the second argument. Do not change the font of @var{from-index} -entries. @xref{Combining Indices}.@refill - -@need 100 -@item @@t@{@var{text}@} -Print @var{text} in a @t{fixed-width}, typewriter-like font. -No effect in Info. @xref{Fonts}.@refill - -@need 400 -@item @@table @var{formatting-command} -Begin a two-column table, using @code{@@item} for each entry. Write -each first column entry on the same line as @code{@@item}. First -column entries are printed in the font resulting from -@var{formatting-command}. Pair with @code{@@end table}. -@xref{Two-column Tables, , Making a Two-column Table}. -Also see @ref{ftable vtable, , @code{@@ftable} and @code{@@vtable}}, -and @ref{itemx, , @code{@@itemx}}.@refill - -@item @@TeX@{@} -Insert the logo @TeX{}. @xref{TeX and copyright, , Inserting @TeX{} -and @copyright{}}.@refill - -@item @@tex -Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Using -Ordinary TeX Commands, , Using Ordinary @TeX{} Commands}.@refill - -@item @@thischapter -In a heading or footing, stands for the number and name of the current -chapter, in the format `Chapter 1: Title'. @xref{Custom -Headings, , How to Make Your Own Headings}.@refill - -@item @@thischaptername -In a heading or footing, stands for the name of the current chapter. -@xref{Custom Headings, , How to Make Your Own Headings}.@refill - -@item @@thisfile -In a heading or footing, stands for the name of the current -@code{@@include} file. Does not insert anything if not within an -@code{@@include} file. @xref{Custom Headings, , How to Make Your Own -Headings}.@refill - -@item @@thispage -In a heading or footing, stands for the current page number. -@xref{Custom Headings, , How to Make Your Own Headings}.@refill - -@ignore -@item @@thissection -In a heading or footing, stands for the title of the current section. -@xref{Custom Headings, , How to Make Your Own Headings}.@refill -@end ignore - -@item @@thistitle -In a heading or footing, stands for the name of the document, as specified -by the @code{@@settitle} command. @xref{Custom Headings, , How to -Make Your Own Headings}.@refill - -@item @@tindex @var{entry} -Add @var{entry} to the index of data types. @xref{Index Entries, , -Defining the Entries of an Index}.@refill - -@item @@title @var{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. @xref{title -subtitle author, , The @code{@@title} @code{@@subtitle} and -@code{@@author} Commands}.@refill - -@need 400 -@item @@titlefont@{@var{text}@} -In a printed manual, print @var{text} in a larger than normal font. -Not relevant to Info, which does not have title pages. -@xref{titlefont center sp, , The @code{@@titlefont} @code{@@center} -and @code{@@sp} Commands}.@refill - -@need 300 -@item @@titlepage -Indicate to Texinfo the beginning of the title page. Write command on -a line of its own. Pair with @code{@@end titlepage}. Nothing between -@code{@@titlepage} and @code{@@end titlepage} appears in Info. -@xref{titlepage, , @code{@@titlepage}}.@refill - -@need 150 -@item @@today@{@} -Insert the current date, in `1 Jan 1900' style. @xref{Custom -Headings, , How to Make Your Own Headings}.@refill - -@item @@top @var{title} -In a Texinfo file to be formatted with @code{makeinfo}, identify the -topmost @code{@@node} line in the file, which must be written on the line -immediately preceding the @code{@@top} command. Used for -@code{makeinfo}'s node pointer insertion feature. The title is -underlined with asterisks. Both the @code{@@node} line and the @code{@@top} -line normally should be enclosed by @code{@@ifinfo} and @code{@@end -ifinfo}. In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top} -command is merely a synonym for @code{@@unnumbered}. @xref{makeinfo -Pointer Creation, , Creating Pointers with @code{makeinfo}}. - -@item @@unnumbered @var{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. -@xref{unnumbered & appendix, , @code{@@unnumbered} and -@code{@@appendix}}.@refill - -@item @@unnumberedsec @var{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. -@xref{unnumberedsec appendixsec heading, , Section Commands}.@refill - -@item @@unnumberedsubsec @var{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. -@xref{unnumberedsubsec appendixsubsec subheading, , -@code{@@unnumberedsubsec} @code{@@appendixsubsec} -@code{@@subheading}}.@refill - -@item @@unnumberedsubsubsec @var{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. -@xref{subsubsection, , The `subsub' Commands}.@refill - -@item @@value@{@var{flag}@} -Replace @var{flag} with the value to which it is set by @code{@@set -@var{flag}}. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@item @@var@{@var{metasyntactic-variable}@} -Highlight a metasyntactic variable, which is something that stands for -another piece of text. @xref{var, , Indicating Metasyntactic -Variables}.@refill - -@need 400 -@item @@vindex @var{entry} -Add @var{entry} to the index of variables. @xref{Index Entries, , -Defining the Entries of an Index}.@refill - -@need 400 -@item @@vskip @var{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 @samp{0pt plus -1filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used -only in contexts ignored for Info. @xref{Copyright & Permissions, , -The Copyright Page and Printed Permissions}.@refill - -@need 400 -@item @@vtable @var{formatting-command} -Begin a two-column table, using @code{@@item} for each entry. -Automatically enter each of the items in the first column into the -index of variables. Pair with @code{@@end vtable}. The same as -@code{@@table}, except for indexing. @xref{ftable vtable, , -@code{@@ftable} and @code{@@vtable}}.@refill - -@need 400 -@item @@w@{@var{text}@} -Prevent @var{text} from being split across two lines. Do not end a -paragraph that uses @code{@@w} with an @code{@@refill} command. -In the Texinfo file, keep @var{text} on one line. -@xref{w, , @code{@@w}}.@refill - -@need 400 -@item @@xref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@} -Make a reference that starts with `See' in a printed manual. Follow -command with a punctuation mark. Only the first argument is -mandatory. @xref{xref, , @code{@@xref}}.@refill -@end table - -@node Tips, Sample Texinfo File, Command List, Top -@comment node-name, next, previous, up -@appendix Tips and Hints - -Here are some tips for writing Texinfo documentation:@refill - -@cindex Tips -@cindex Usage tips -@cindex Hints -@itemize @bullet -@item -Write in the present tense, not in the past or the future. - -@item -Write actively! For example, write ``We recommend that @dots{}'' rather -than ``It is recommended that @dots{}''. - -@item -Use 70 or 72 as your fill column. Longer lines are hard to read. - -@item -Include a copyright notice and copying permissions. -@end itemize - -@subsubheading 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: - -@itemize @bullet -@item -Write each index entry differently, so each entry refers to a different -place in the document. The index of an Info file lists only one -location for each entry. - -@item -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. - -@item -Consistently capitalize the first word of every index entry, or else use -lower case. According to convention, you should capitalize the first -word of an index entry. However, this practice may make an index look -crowded. Some writers prefer lower case. Regardless of which you -prefer, choose one style and stick to it. Mixing the two styles looks -bad. - -@item -Always capitalize or use upper case for those words in an index for -which this is proper, such as names of countries or acronyms. - -@item -Write the indexing commands that refer to a whole section immediately -after the section command, and write the indexing commands that refer to -the paragraph before the paragraph. - -@need 1000 -In the example that follows, a blank line comes after the index -entry for ``Leaping'': - -@example -@group -@@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. -@end group -@end example - -@noindent -(Note that the example shows entries for the same concept that are -written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so -readers can look up the concept in different ways.) -@end itemize - -@subsubheading Blank lines - -@itemize @bullet -@item -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. - -@item -Always insert a blank line before an @code{@@table} command and after an -@code{@@end table} command; but never insert a blank line after an -@code{@@table} command or before an @code{@@end table} command. - -@need 1000 -For example, - -@example -@group -Types of fox: - -@@table @@samp -@@item Quick -Jump over lazy dogs. -@end group - -@group -@@item Brown -Also jump over lazy dogs. -@@end table - -@end group -@group -@@noindent -On the other hand, @dots{} -@end group -@end example - -Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end -itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the -same way. -@end itemize - -@subsubheading Complete phrases - -Complete phrases are easier to read than @dots{} - -@itemize @bullet -@item -Write entries in an itemized list as complete sentences; or at least, as -complete phrases. Incomplete expressions @dots{} awkward @dots{} like -this. - -@item -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. -@end itemize - -@subsubheading Editions, dates and versions - -Write the edition and version numbers and date in three places in every -manual: - -@enumerate -@item -In the first @code{@@ifinfo} section, for people reading the Texinfo file. - -@item -In the @code{@@titlepage} section, for people reading the printed manual. - -@item -In the `Top' node, for people reading the Info file. -@end enumerate - -@noindent -Also, it helps to write a note before the first @code{@@ifinfo} -section to explain what you are doing. - -@need 800 -@noindent -For example: - -@example -@group -@@c ===> NOTE! <== -@@c Specify the edition and version numbers and date -@@c in *three* places: -@@c 1. First ifinfo section 2. title page 3. top node -@@c To find the locations, search for !!set -@end group - -@group -@@ifinfo -@@c !!set edition, date, version -This is Edition 4.03, January 1992, -of the @@cite@{GDB Manual@} for GDB Version 4.3. -@dots{} -@end group -@end example - -@noindent ----or use @code{@@set} and @code{@@value} -(@pxref{value Example, , @code{@@value} Example}). - -@subsubheading Definition Commands - -Definition commands are @code{@@deffn}, @code{@@defun}, -@code{@@defmac}, and the like, and enable you to write descriptions in -a uniform format.@refill - -@itemize @bullet -@item -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. - -@item -Use @code{@@table} @dots{} @code{@@end table} in an appendix that -contains a summary of functions, not @code{@@deffn} or other definition -commands. -@end itemize - -@subsubheading Capitalization - -@itemize @bullet -@item -Capitalize @samp{Texinfo}; it is a name. Do not write the @samp{x} or -@samp{i} in upper case. - -@item -Capitalize @samp{Info}; it is a name. - -@item -Write @TeX{} using the @code{@@TeX@{@}} command. Note the uppercase -@samp{T} and @samp{X}. This command causes the formatters to -typeset the name according to the wishes of Donald Knuth, who wrote -@TeX{}. -@end itemize - -@subsubheading Spaces - -Do not use spaces to format a Texinfo file, except inside of -@code{@@example} @dots{} @code{@@end example} and similar commands. - -@need 700 -For example, @TeX{} fills the following: - -@example -@group - @@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. -@end group -@end example - -@need 950 -@noindent -so it looks like this: - -@iftex -@quotation - @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. -@end quotation -@end iftex -@ifinfo -@quotation -`C-x v' `M-x vc-next-action' Perform the next logical operation on the -version-controlled file corresponding to the current buffer. -@end quotation -@end ifinfo - -@noindent -In this case, the text should be formatted with -@code{@@table}, @code{@@item}, and @code{@@itemx}, to create a table. - -@subsubheading @@code, @@samp, @@var, and @samp{---} - -@itemize @bullet -@item -Use @code{@@code} around Lisp symbols, including command names. -For example, - -@example -The main function is @@code@{vc-next-action@}, @dots{} -@end example - -@item -Avoid putting letters such as @samp{s} immediately after an -@samp{@@code}. Such letters look bad. - -@item -Use @code{@@var} around meta-variables. Do not write angle brackets -around them. - -@item -Use three hyphens in a row, @samp{---}, to indicate a long dash. @TeX{} -typesets these as a long dash and the Info formatters reduce three -hyphens to two. -@end itemize - -@subsubheading Periods Outside of Quotes - -Place periods and other punctuation marks @emph{outside} of quotations, -unless the punctuation is part of the quotation. This practice goes against -convention, 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: - -@example -Evidently, @samp{au} is an abbreviation for ``author''. -@end example - -@noindent -since @samp{au} does @emph{not} serve as an abbreviation for -@samp{author.} (with a period following the word). - -@subsubheading Introducing New Terms - -@itemize @bullet -@item -Introduce new terms so that a user 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. - -@quotation -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. -@end quotation - -@item -Use the @code{@@dfn} command around a word being introduced, to indicate -that the user should not expect to know the meaning already, and should -expect to learn the meaning from this passage. -@end itemize - -@subsubheading @@pxref - -@c !!! maybe include this in the tips on pxref -@ignore -By the way, it is okay to use pxref with something else in front of -it within the parens, as long as the pxref is followed by the close -paren, and the material inside the parents is not part of a larger -sentence. Also, you can use xref inside parens as part of a complete -sentence so long as you terminate the cross reference with punctuation. -@end ignore -Absolutely never use @code{@@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. - -@subsubheading 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, readers find it hard to search for the -section.@refill - -Name such sections with a phrase beginning with the word -@w{`Invoking @dots{}'}, as in `Invoking Emacs'; this way -users can find the section easily. - -@subsubheading @sc{ansi c} Syntax - -When you use @code{@@example} to describe a C function's calling -conventions, use the @sc{ansi c} syntax, like this:@refill - -@example -void dld_init (char *@@var@{path@}); -@end example - -@noindent -And in the subsequent discussion, refer to the argument values by -writing the same argument names, again highlighted with -@code{@@var}.@refill - -@need 800 -Avoid the obsolete style that looks like this:@refill - -@example -#include <dld.h> - -dld_init (path) -char *path; -@end example - -Also, it is best to avoid writing @code{#include} above the -declaration just to indicate that the function is declared in a -header file. The practice may give the misimpression that the -@code{#include} 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.@refill - -@subsubheading Bad Examples - -Here are several examples of bad writing to avoid: - -In this example, say, `` @dots{} you must @code{@@dfn}@{check -in@} the new version.'' That flows better. - -@quotation -When you are done editing the file, you must perform a -@code{@@dfn}@{check in@}. -@end quotation - -In the following example, say, ``@dots{} makes a unified interface such as VC -mode possible.'' - -@quotation -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). -@end quotation - -And in this example, you should specify what `it' refers to: - -@quotation -If you are working with other people, it assists in coordinating -everyone's changes so they do not step on each other. -@end quotation - -@subsubheading And Finally @dots{} - -@itemize @bullet -@item -Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last -sound in the name `Bach'. But pronounce Texinfo as in `speck': -@samp{teckinfo}. - -@item -Write notes for yourself at the very end of a Texinfo file after the -@code{@@bye}. None of the formatters process text after the -@code{@@bye}; it is as if the text were within @code{@@ignore} @dots{} -@code{@@end ignore}. -@end itemize - -@node Sample Texinfo File, Sample Permissions, Tips, Top -@comment node-name, next, previous, up -@appendix A Sample Texinfo File -@cindex Sample Texinfo file, no comments - -Here is a complete, short sample Texinfo file, without any commentary. -You can see this file, with comments, in the first chapter. -@xref{Short Sample, , A Short Sample Texinfo File}. - -@sp 1 -@example -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename sample.info -@@settitle Sample Document -@@c %**end of header - -@@setchapternewpage odd - -@@ifinfo -This is a short example of a complete Texinfo file. - -Copyright 1990 Free Software Foundation, Inc. -@@end ifinfo - -@@titlepage -@@sp 10 -@@comment The title is printed in a large font. -@@center @@titlefont@{Sample Title@} - -@@c The following two commands start the copyright page. -@@page -@@vskip 0pt plus 1filll -Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. -@@end titlepage - -@@node Top, First Chapter, (dir), (dir) -@@comment node-name, next, previous, up - -@@menu -* First Chapter:: The first chapter is the - only chapter in this sample. -* Concept Index:: This index has two entries. -@@end menu - -@@node First Chapter, Concept Index, Top, Top -@@comment node-name, next, previous, up -@@chapter First Chapter -@@cindex Sample index entry - -This is the contents of the first chapter. -@@cindex Another sample index entry - -Here is a numbered list. - -@@enumerate -@@item -This is the first item. - -@@item -This is the second item. -@@end enumerate - -The @@code@{makeinfo@} and @@code@{texinfo-format-buffer@} -commands transform a Texinfo file such as this into -an Info file; and @@TeX@{@} typesets it for a printed -manual. - -@@node Concept Index, , First Chapter, Top -@@comment node-name, next, previous, up -@@unnumbered Concept Index - -@@printindex cp - -@@contents -@@bye -@end example - -@node Sample Permissions, Include Files, Sample Texinfo File, Top -@appendix Sample Permissions -@cindex Permissions -@cindex Copying permissions - -Texinfo files should contain sections that tell the readers that they -have the right to copy and distribute the Texinfo file, the Info file, -and the printed manual.@refill - -Also, if you are writing a manual about software, you should explain -that the software is free and either include the GNU General Public -License (GPL) or provide a reference to it. @xref{Distrib, , -Distribution, emacs, The GNU Emacs Manual}, for an example of the text -that could be used in the software ``Distribution'', ``General Public -License'', and ``NO WARRANTY'' sections of a document. @xref{Copying, -, Texinfo Copying Conditions}, for an example of a brief explanation -of how the copying conditions provide you with rights. @refill - -@menu -* Inserting Permissions:: How to put permissions in your document. -* ifinfo Permissions:: Sample @samp{ifinfo} copying permissions. -* Titlepage Permissions:: Sample Titlepage copying permissions. -@end menu - -@node Inserting Permissions, ifinfo Permissions, , Sample Permissions -@ifinfo -@appendixsec Inserting Permissions -@end ifinfo - -In a Texinfo file, the first @code{@@ifinfo} section usually begins -with a line that says what the file documents. This is what a person -reading the unprocessed Texinfo file or using the advanced Info -command @kbd{g *} sees first. @inforef{Expert, Advanced Info -commands, info}, for more information. (A reader using the regular -Info commands usually starts reading at the first node and skips -this first section, which is not in a node.)@refill - -In the @code{@@ifinfo} section, the summary sentence is followed by a -copyright notice and then by the copying permission notice. One of -the copying permission paragraphs is enclosed in @code{@@ignore} and -@code{@@end ignore} commands. This paragraph states that the Texinfo -file can be processed through @TeX{} and printed, provided the printed -manual carries the proper copying permission notice. This paragraph -is not made part of the Info file since it is not relevant to the Info -file; but it is a mandatory part of the Texinfo file since it permits -people to process the Texinfo file in @TeX{} and print the -results.@refill - -In the printed manual, the Free Software Foundation copying permission -notice follows the copyright notice and publishing information and is -located within the region delineated by the @code{@@titlepage} and -@code{@@end titlepage} commands. The copying permission notice is exactly -the same as the notice in the @code{@@ifinfo} section except that the -paragraph enclosed in @code{@@ignore} and @code{@@end ignore} commands is -not part of the notice.@refill - -To make it simple to insert a permission notice into each section of -the Texinfo file, sample permission notices for each section are -reproduced in full below.@refill - -Note that you may need to specify the correct name of a section -mentioned in the permission notice. For example, in @cite{The GDB -Manual}, the name of the section referring to the General Public -License is called the ``GDB General Public License'', but in the -sample shown below, that section is referred to generically as the -``GNU General Public License''. If the Texinfo file does not carry a -copy of the General Public License, leave out the reference to it, but -be sure to include the rest of the sentence.@refill - -@node ifinfo Permissions, Titlepage Permissions, Inserting Permissions, Sample Permissions -@comment node-name, next, previous, up -@appendixsec @samp{ifinfo} Copying Permissions -@cindex @samp{ifinfo} permissions - -In the @code{@@ifinfo} section of a Texinfo file, the standard Free -Software Foundation permission notice reads as follows:@refill - -@example -This file documents @dots{} - -Copyright 1992 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. - -@@ignore -Permission is granted to process this file through TeX -and print the results, provided the printed document -carries a copying permission notice identical to this -one except for the removal of this paragraph (this -paragraph not being relevant to the printed manual). - -@@end ignore -Permission is granted to copy and distribute modified -versions of this manual under the conditions for -verbatim copying, provided also that the sections -entitled ``Copying'' and ``GNU General Public License'' -are included exactly as in the original, and 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 Free Software Foundation. -@end example - -@node Titlepage Permissions, , ifinfo Permissions, Sample Permissions -@comment node-name, next, previous, up -@appendixsec Titlepage Copying Permissions -@cindex Titlepage permissions - -In the @code{@@titlepage} section of a Texinfo file, the standard Free -Software Foundation copying permission notice follows the copyright -notice and publishing information. The standard phrasing is as -follows:@refill - -@example -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 also that the sections -entitled ``Copying'' and ``GNU General Public License'' -are included exactly as in the original, and 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 Free Software Foundation. -@end example - -@node Include Files, Headings, Sample Permissions, Top -@comment node-name, next, previous, up -@appendix Include Files -@cindex Include files - -When @TeX{} or an Info formatting command sees an @code{@@include} -command in a Texinfo file, it processes the contents of the file named -by the command and incorporates them into the @sc{dvi} or Info file being -created. Index entries from the included file are incorporated into -the indices of the output file.@refill - -Include files let you keep a single large document as a collection of -conveniently small parts.@refill - -@menu -* Using Include Files:: How to use the @code{@@include} command. -* texinfo-multiple-files-update:: How to create and update nodes and - menus when using included files. -* Include File Requirements:: What @code{texinfo-multiple-files-update} expects. -* Sample Include File:: A sample outer file with included files - within it; and a sample included file. -* Include Files Evolution:: How use of the @code{@@include} command - has changed over time. -@end menu - -@node Using Include Files, texinfo-multiple-files-update, , Include Files -@appendixsec How to Use Include Files -@findex include - -To include another file within a Texinfo file, write the -@code{@@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:@refill - -@example -@@include buffers.texi -@end example - -An included file should simply be a segment of text that you expect to -be included as is into the overall or @dfn{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 @samp{\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 @code{@@bye} command; nothing after @code{@@bye} is -formatted.@refill - -In the past, you were required to write an @code{@@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 @code{@@setfilename} line exists -in an included file, it is ignored.@refill - -Conventionally, an included file begins with an @code{@@node} line that -is followed by an @code{@@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 @code{@@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, @code{texinfo-multiple-files-update}, that is -designed for @code{@@include} files.@refill - -@node texinfo-multiple-files-update, Include File Requirements, Using Include Files, Include Files -@appendixsec @code{texinfo-multiple-files-update} -@findex texinfo-multiple-files-update - -@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93 -GNU Emacs Texinfo mode provides a command to handle included files -called @code{texinfo-multiple-files-update}. This command creates or -updates `Next', `Previous', and `Up' pointers of included files as -well as those in the outer or overall Texinfo file, and it creates or -updates a main menu in the outer file. Depending whether you call it -with optional arguments, the command updates only the pointers in the -first @code{@@node} line of the included files or all of them:@refill - -@table @kbd -@item M-x texinfo-multiple-files-update -Called without any arguments:@refill - -@itemize @minus -@item -Create or update the `Next', `Previous', and `Up' pointers of the -first @code{@@node} line in each file included in an outer or overall -Texinfo file.@refill - -@item -Create or update the `Top' level node pointers of the outer or -overall file.@refill - -@item -Create or update a main menu in the outer file.@refill -@end itemize - -@item C-u M-x texinfo-multiple-files-update -Called with @kbd{C-u} as a prefix argument: - -@itemize @minus{} -@item -Create or update pointers in the first @code{@@node} line in each -included file. - -@item -Create or update the `Top' level node pointers of the outer file. - -@item -Create and insert a master menu in the outer file. The master menu -is made from all the menus in all the included files.@refill -@end itemize - -@item C-u 8 M-x texinfo-multiple-files-update -Called with a numeric prefix argument, such as @kbd{C-u 8}: - -@itemize @minus -@item -Create or update @strong{all} the `Next', `Previous', and `Up' pointers -of all the included files.@refill - -@item -Create or update @strong{all} the menus of all the included -files.@refill - -@item -Create or update the `Top' level node pointers of the outer or -overall file.@refill - -@item -And then create a master menu in the outer file. This is similar to -invoking @code{texinfo-master-menu} with an argument when you are -working with just one file.@refill -@end itemize -@end table - -Note the use of the prefix argument in interactive use: with a regular -prefix argument, just @w{@kbd{C-u}}, the -@code{texinfo-multiple-files-update} command inserts a master menu; -with a numeric prefix argument, such as @kbd{C-u 8}, the command -updates @strong{every} pointer and menu in @strong{all} the files and then inserts a -master menu.@refill - -@node Include File Requirements, Sample Include File, texinfo-multiple-files-update, Include Files -@appendixsec Include File Requirements -@cindex Include file requirements -@cindex Requirements for include files - -If you plan to use the @code{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 @code{@@include} commands listing the included files. It -should not even include indices, which should be listed in an included -file of their own.@refill - -Moreover, each of the included files must contain exactly one highest -level node (conventionally, @code{@@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 @code{@@chapter}, an @code{@@appendix}, or an -@code{@@unnumbered} node. Thus, normally, each included file contains -one, and only one, chapter or equivalent-level node.@refill - -The outer file should contain only @emph{one} node, the `Top' node. It -should @emph{not} contain any nodes besides the single `Top' node. The -@code{texinfo-multiple-files-update} command will not process -them.@refill - -@node Sample Include File, Include Files Evolution, Include File Requirements, Include Files -@appendixsec Sample File with @code{@@include} -@cindex Sample @code{@@include} file -@cindex Include file sample -@cindex @code{@@include} file sample - -Here is an example of a complete outer Texinfo file with @code{@@include} files -within it before running @code{texinfo-multiple-files-update}, which -would insert a main or master menu:@refill - -@example -@group -\input texinfo @@c -*-texinfo-*- -@c %**start of header -@@setfilename include-example.info -@@settitle Include Example -@c %**end of header -@end group - -@group -@@setchapternewpage odd -@@titlepage -@@sp 12 -@@center @@titlefont@{Include Example@} -@@sp 2 -@@center by Whom Ever -@end group - -@group -@@page -@@vskip 0pt plus 1filll -Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. -@@end titlepage -@end group - -@group -@@ifinfo -@@node Top, First, (dir), (dir) -@@top Master Menu -@@end ifinfo -@end group - -@group -@@include foo.texinfo -@@include bar.texinfo -@@include concept-index.texinfo -@end group - -@group -@@summarycontents -@@contents - -@@bye -@end group -@end example - -An included file, such as @file{foo.texinfo}, might look like -this:@refill - -@example -@group -@@node First, Second, , Top -@@chapter First Chapter - -Contents of first chapter @dots{} -@end group -@end example - -The full contents of @file{concept-index.texinfo} might be as simple as this: - -@example -@group -@@node Concept Index, , Second, Top -@@unnumbered Concept Index - -@@printindex cp -@end group -@end example - -The outer Texinfo source file for @cite{The GNU Emacs Lisp Reference -Manual} is named @file{elisp.texi}. This outer file contains a master -menu with 417 entries and a list of 41 @code{@@include} -files.@refill - -@node Include Files Evolution, , Sample Include File, Include Files -@comment node-name, next, previous, up -@appendixsec 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.@refill - -References from one file to another were made by referring to the file -name as well as the node name. (@xref{Other Info Files, , Referring to -Other Info Files}. Also, see @ref{Four and Five Arguments, , -@code{@@xref} with Four and Five Arguments}.)@refill - -Include files were designed primarily as a way to create a single, -large printed manual out of several smaller Info files. In a printed -manual, all the references were within the same document, so @TeX{} -could automatically determine the references' page numbers. The Info -formatting commands used include files only for creating joint -indices; each of the individual Texinfo files had to be formatted for -Info individually. (Each, therefore, required its own -@code{@@setfilename} line.)@refill - -However, because large Info files are now split automatically, it is -no longer necessary to keep them small.@refill - -Nowadays, multiple Texinfo files are used mostly for large documents, -such as @cite{The GNU Emacs Lisp Reference Manual}, and for projects -in which several different people write different sections of a -document simultaneously.@refill - -In addition, the Info formatting commands have been extended to work -with the @code{@@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.@refill - -@node Headings, Catching Mistakes, Include Files, Top -@comment node-name, next, previous, up -@appendix Page Headings -@cindex Headings -@cindex Footings -@cindex Page numbering -@cindex Page headings -@cindex Formatting headings and footings - -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.)@refill - -@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. -@end menu - -@node Headings Introduced, Heading Format, , Headings -@ifinfo -@heading Headings Introduced -@end ifinfo - -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. Usually, you will use one or other of these -formats, but you can specify your own format, if you wish.@refill - -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.@refill - -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.@refill - -The @code{@@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.@refill - -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.@refill - -@node Heading Format, Heading Choice, Headings Introduced, Headings -@comment node-name, next, previous, up -@appendixsec 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.@refill - -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.@refill - -@need 950 -A single-sided page looks like this: - -@example -@group - _______________________ - | | - | chapter page number | - | | - | Start of text ... | - | ... | - | | - -@end group -@end example - -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.)@refill - -In the standard double-sided format, the left part of the left-hand -(even-numbered) page contains the page number, the central part is -blank, and the right part contains the title (specified by the -@code{@@settitle} 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.@refill - -@need 750 -Two pages, side by side as in an open book, look like this:@refill - -@example -@group - _______________________ _______________________ - | | | | - | page number title | | chapter page number | - | | | | - | Start of text ... | | More text ... | - | ... | | ... | - | | | | - -@end group -@end example - -@noindent -The chapter name is preceded by the word @samp{Chapter}, the chapter -number and a colon. This makes it easier to keep track of where you -are in the manual.@refill - -@node Heading Choice, Custom Headings, Heading Format, Headings -@comment node-name, next, previous, up -@appendixsec Specifying the Type of Heading - -@TeX{} does not begin to generate page headings for a standard Texinfo -file until it reaches the @code{@@end titlepage} command. Thus, the -title and copyright pages are not numbered. The @code{@@end -titlepage} command causes @TeX{} to begin to generate page headings -according to a standard format specified by the -@code{@@setchapternewpage} command that precedes the -@code{@@titlepage} section.@refill - -@need 1000 -There are four possibilities:@refill - -@table @asis -@item No @code{@@setchapternewpage} command -Cause @TeX{} to specify the single-sided heading format, with chapters -on new pages. This is the same as @code{@@setchapternewpage on}.@refill - -@item @code{@@setchapternewpage on} -Specify the single-sided heading format, with chapters on new pages.@refill - -@item @code{@@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 @code{@@headings double} command; see -@ref{headings on off, , The @code{@@headings} Command}.)@refill - -@item @code{@@setchapternewpage odd} -Specify the double-sided heading format, with chapters on new pages.@refill -@end table - -@noindent -Texinfo lacks an @code{@@setchapternewpage even} command.@refill - -@node Custom Headings, , Heading Choice, Headings -@comment node-name, next, previous, up -@appendixsec How to Make Your Own Headings - -You can use the standard headings provided with Texinfo or specify -your own.@refill - -@c Following paragraph is verbose to prevent overfull hboxes. -Texinfo provides six commands for specifying headings and -footings. The @code{@@everyheading} command and -@code{@@everyfooting} command generate page headers and footers -that are the same for both even- and odd-numbered pages. -The @code{@@evenheading} command and @code{@@evenfooting} -command generate headers and footers for even-numbered -(left-hand) pages; and the @code{@@oddheading} command and -@code{@@oddfooting} command generate headers and footers for -odd-numbered (right-hand) pages.@refill - -Write custom heading specifications in the Texinfo file immediately -after the @code{@@end titlepage} command. Enclose your specifications -between @code{@@iftex} and @code{@@end iftex} commands since the -@code{texinfo-format-buffer} command may not recognize them. Also, -you must cancel the predefined heading commands with the -@code{@@headings off} command before defining your own -specifications.@refill - -@need 1000 -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:@refill - -@example -@group -@@iftex -@@headings off -@@everyheading @@thischapter @@| @@thispage @@| @@today@{@} -@@end iftex -@end group -@end example - -@noindent -You need to divide the left part from the central part and the central -part from the right had part by inserting @samp{@@|} between parts. -Otherwise, the specification command will not be able to tell where -the text for one part ends and the next part begins.@refill - -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.@refill - -@need 950 -Here are the six heading and footing commands:@refill - -@findex everyheading -@findex everyfooting -@table @code -@item @@everyheading @var{left} @@| @var{center} @@| @var{right} -@itemx @@everyfooting @var{left} @@| @var{center} @@| @var{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.@refill - -@findex evenheading -@findex evenfooting -@findex oddheading -@findex oddfooting -@item @@evenheading @var{left} @@| @var{center} @@| @var{right} -@itemx @@oddheading @var{left} @@| @var{center} @@| @var{right} - -@itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right} -@itemx @@oddfooting @var{left} @@| @var{center} @@| @var{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.@refill -@end table - -Use the @samp{@@this@dots{}} series of @@-commands to -provide the names of chapters -and sections and the page number. You can use the -@samp{@@this@dots{}} commands in the left, center, or right portions -of headers and footers, or anywhere else in a Texinfo file so long as -they are between @code{@@iftex} and @code{@@end iftex} commands.@refill - -@need 1000 -Here are the @samp{@@this@dots{}} commands:@refill - -@table @code -@findex thispage -@item @@thispage -Expands to the current page number.@refill -@c !!! Karl Berry says that `thissection' fails on page breaks. -@ignore -@item @@thissection -Expands to the name of the current section.@refill -@end ignore - -@findex thischaptername -@item @@thischaptername -Expands to the name of the current chapter.@refill - -@findex thischapter -@item @@thischapter -Expands to the number and name of the current -chapter, in the format `Chapter 1: Title'.@refill - -@findex thistitle -@item @@thistitle -Expands to the name of the document, as specified by the -@code{@@settitle} command.@refill - -@findex thisfile -@item @@thisfile -For @code{@@include} files only: expands to the name of the current -@code{@@include} file. If the current Texinfo source file is not an -@code{@@include} file, this command has no effect. This command does -@emph{not} provide the name of the current Texinfo source file unless -it is an @code{@@include} file. (@xref{Include Files}, for more -information about @code{@@include} files.)@refill -@end table - -@noindent -You can also use the @code{@@today@{@}} command, which expands to the -current date, in `1 Jan 1900' format.@refill -@findex today - -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:@refill - -@example -@group -@@iftex -@@headings off -@@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter -@@everyfooting @@| @@| Version: 0.27: @@today@{@} -@@end iftex -@end group -@end example - -Beware of overlong titles: they may overlap another part of the -header or footer and blot it out.@refill - -@node Catching Mistakes, Refilling Paragraphs, Headings, Top -@comment node-name, next, previous, up -@appendix Formatting Mistakes -@cindex Structure, catching mistakes in -@cindex Nodes, catching mistakes -@cindex Catching mistakes -@cindex Correcting mistakes -@cindex Mistakes, catching -@cindex Problems, catching -@cindex Debugging the Texinfo structure - -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.@refill - -Emacs has two tools for catching the @@-command mistakes and two for -catching structuring mistakes.@refill - -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.@refill - -For finding problems with the structure of nodes and chapters, you can use -@kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur} -command and you can use the @kbd{M-x Info-validate} command.@refill - -@menu -* makeinfo preferred:: @code{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 @code{texinfo-show-structure}. -* Using occur:: How to list all lines containing a pattern. -* Running Info-Validate:: How to find badly referenced nodes. -@end menu - -@node makeinfo preferred, Debugging with Info, , Catching Mistakes -@ifinfo -@heading @code{makeinfo} Find Errors -@end ifinfo - -@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93 -The @code{makeinfo} program does an excellent job of catching errors -and reporting them---far better than either the -@code{texinfo-format-region} or the @code{texinfo-format-buffer} -command. In addition, the various functions for automatically -creating and updating node pointers and menus remove many -opportunities for human error.@refill - -If you can, use the updating commands to create and insert pointers -and menus. These prevent many errors. Then use @code{makeinfo} (or -its Texinfo mode manifestations, @code{makeinfo-region} and -@code{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 @code{makeinfo}, or your problem is very puzzling, then you -may want to use the tools described in this appendix.@refill - -@node Debugging with Info, Debugging with TeX, makeinfo preferred, Catching Mistakes -@comment node-name, next, previous, up -@appendixsec Catching Errors with Info Formatting -@cindex Catching errors with Info formatting -@cindex Debugging with Info formatting - -After you have written part of a Texinfo file, you can use the -@code{texinfo-format-region} or the @code{makeinfo-region} command to -see whether the region formats properly.@refill - -Most likely, however, you are reading this section because for some -reason you cannot use the @code{makeinfo-region} command; therefore, the -rest of this section presumes that you are using -@code{texinfo-format-region}.@refill - -@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93 -If you make a mistake with an @@-command, -@code{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 @samp{*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).@refill - -For example, if you accidentally end a menu with the command @code{@@end -menus} with an `s' on the end, instead of with @code{@@end menu}, you -will see an error message that says:@refill - -@example -@@end menus is not handled by texinfo -@end example - -@noindent -The cursor will stop at the point in the buffer where the error -occurs, or not long after it. The buffer will look like this:@refill - -@example -@group ----------- 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 -@point{} ----------- Buffer: *Info Region* ---------- -@end group -@end example - -The @code{texinfo-format-region} command sometimes provides slightly -odd error messages. For example, the following cross reference fails to format:@refill - -@example -(@@xref@{Catching Mistakes, for more info.) -@end example - -@noindent -In this case, @code{texinfo-format-region} detects the missing closing -brace but displays a message that says @samp{Unbalanced parentheses} -rather than @samp{Unbalanced braces}. This is because the formatting -command looks for mismatches between braces as if they were -parentheses.@refill - -Sometimes @code{texinfo-format-region} fails to detect mistakes. For -example, in the following, the closing brace is swapped with the -closing parenthesis:@refill - -@example -(@@xref@{Catching Mistakes), for more info.@} -@end example - -@noindent -Formatting produces: -@example -(*Note for more info.: Catching Mistakes) -@end example - -The only way for you to detect this error is to realize that the -reference should have looked like this:@refill - -@example -(*Note Catching Mistakes::, for more info.) -@end example - -Incidentally, if you are reading this node in Info and type @kbd{f -@key{RET}} (@code{Info-follow-reference}), you will generate an error -message that says: - -@example -No such node: "Catching Mistakes) The only way @dots{} -@end example - -@noindent -This is because Info perceives the example of the error as the first -cross reference in this node and if you type a @key{RET} immediately -after typing the Info @kbd{f} command, Info will attempt to go to the -referenced node. If you type @kbd{f catch @key{TAB} @key{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 @kbd{l} -(@code{Info-last}).) - -@c !!! section on using Elisp debugger ignored. -@ignore -Sometimes @code{texinfo-format-region} will stop long after the -original error; this is because it does not discover the problem until -then. In this case, you will need to backtrack.@refill - -@c menu -@c * Using the Emacs Lisp Debugger:: How to use the Emacs Lisp debugger. -@c end menu - -@c node Using the Emacs Lisp Debugger -@c appendixsubsec Using the Emacs Lisp Debugger -@c index Using the Emacs Lisp debugger -@c index Emacs Lisp debugger -@c index Debugger, using the Emacs Lisp - -If an error is especially elusive, you can turn on the Emacs Lisp -debugger and look at the backtrace; this tells you where in the -@code{texinfo-format-region} function the problem occurred. You can -turn on the debugger with the command:@refill - -@example -M-x set-variable @key{RET} debug-on-error @key{RET} t @key{RET} -@end example - -@noindent -and turn it off with - -@example -M-x set-variable @key{RET} debug-on-error @key{RET} nil @key{RET} -@end example - -Often, when you are using the debugger, it is easier to follow what is -going on if you use the Emacs Lisp files that are not byte-compiled. -The byte-compiled sources send octal numbers to the debugger that may -look mysterious. To use the uncompiled source files, load -@file{texinfmt.el} and @file{texinfo.el} with the @kbd{M-x load-file} -command.@refill - -The debugger will not catch an error if @code{texinfo-format-region} -does not detect one. In the example shown above, -@code{texinfo-format-region} did not find the error when the whole -list was formatted, but only when part of the list was formatted. -When @code{texinfo-format-region} did not find an error, the debugger -did not find one either. @refill - -However, when @code{texinfo-format-region} did report an error, it -invoked the debugger. This is the backtrace it produced:@refill - -@example ----------- Buffer: *Backtrace* ---------- -Signalling: (search-failed "[@},]") - re-search-forward("[@},]") - (while ...) - (let ...) - texinfo-format-parse-args() - (let ...) - texinfo-format-xref() - funcall(texinfo-format-xref) - (if ...) - (let ...) - (if ...) - (while ...) - texinfo-format-scan() - (save-excursion ...) - (let ...) - texinfo-format-region(103370 103631) -* call-interactively(texinfo-format-region) ----------- Buffer: *Backtrace* ---------- -@end example - -The backtrace is read from the bottom up. -@code{texinfo-format-region} was called interactively; and it, in -turn, called various functions, including @code{texinfo-format-scan}, -@code{texinfo-format-xref} and @code{texinfo-format-parse-args}. -Inside the function @code{texinfo-format-parse-args}, the function -@code{re-search-forward} was called; it was this function that could -not find the missing right-hand brace.@refill - -@xref{Lisp Debug, , Debugging Emacs Lisp, emacs, The GNU Emacs -Manual}, for more information.@refill -@end ignore - -@node Debugging with TeX, Using texinfo-show-structure, Debugging with Info, Catching Mistakes -@comment node-name, next, previous, up -@appendixsec Catching Errors with @TeX{} Formatting -@cindex Catching errors with @TeX{} formatting -@cindex Debugging with @TeX{} formatting - -You can also catch mistakes when you format a file with @TeX{}.@refill - -@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93 -Usually, you do this after you have run -@code{texinfo-format-buffer} (or, better, @code{makeinfo-buffer}) on -the same file, because @code{texinfo-format-buffer} sometimes displays -error messages that make more sense than @TeX{}. (@xref{Debugging -with Info}, for more information.)@refill - -For example, @TeX{} was run on a Texinfo file, part of which is shown -here:@refill - -@example ----------- Buffer: texinfo.texi ---------- -name of the texinfo file as an extension. The -@@samp@{??@} are `wildcards' that cause the shell to -substitute all the raw index files. (@@xref@{sorting -indices, for more information about sorting -indices.)@@refill ----------- Buffer: texinfo.texi ---------- -@end example - -@noindent -(The cross reference lacks a closing brace.) -@TeX{} produced the following output, after which it stopped:@refill - -@example ----------- Buffer: *texinfo-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: *texinfo-tex-shell* ---------- -@end example - -In this case, @TeX{} produced an accurate and -understandable error message: - -@example -Paragraph ended before @@xref was complete. -@end example - -@noindent -@samp{@@par} is an internal @TeX{} command of no relevance to Texinfo. -@samp{l.27} means that @TeX{} detected the problem on line 27 of the -Texinfo file. The @samp{?} is the prompt @TeX{} uses in this -circumstance.@refill - -Unfortunately, @TeX{} is not always so helpful, and sometimes you must -truly be a Sherlock Holmes to discover what went wrong.@refill - -In any case, if you run into a problem like this, you can do one of three -things.@refill - -@enumerate -@item -You can tell @TeX{} to continue running and ignore just this error by -typing @key{RET} at the @samp{?} prompt.@refill - -@item -You can tell @TeX{} to continue running and to ignore all errors as best -it can by typing @kbd{r @key{RET}} at the @samp{?} prompt.@refill - -This is often the best thing to do. However, beware: the one error -may produce a cascade of additional error messages as its consequences -are felt through the rest of the file. (To stop @TeX{} when it is -producing such an avalanche of error messages, type @kbd{C-d} (or -@kbd{C-c C-d}, if you are running a shell inside Emacs Version 18.))@refill - -@item -You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}} -at the @samp{?} prompt.@refill -@end enumerate - -Please note that if you are running @TeX{} inside Emacs, you need to -switch to the shell buffer and line at which @TeX{} offers the @samp{?} -prompt.@refill - -Sometimes @TeX{} will format a file without producing error messages even -though there is a problem. This usually occurs if a command is not ended -but @TeX{} is able to continue processing anyhow. For example, if you fail -to end an itemized list with the @code{@@end itemize} command, @TeX{} will -write a @sc{dvi} file that you can print out. The only error message that -@TeX{} will give you is the somewhat mysterious comment that@refill - -@example -(@@end occurred inside a group at level 1) -@end example - -@noindent -However, if you print the @sc{dvi} file, you will find that the text -of the file that follows the itemized list is entirely indented as if -it were part of the last item in the itemized list. The error message -is the way @TeX{} says that it expected to find an @code{@@end} -command somewhere in the file; but that it could not determine where -it was needed.@refill - -Another source of notoriously hard-to-find errors is a missing -@code{@@end group} command. If you ever are stumped by -incomprehensible errors, look for a missing @code{@@end group} command -first.@refill - -If the Texinfo file lacks header lines, -@TeX{} may stop in the -beginning of its run and display output that looks like the following. -The @samp{*} indicates that @TeX{} is waiting for input.@refill - -@example -This is TeX, Version 2.0 for Berkeley UNIX -(preloaded format=plain-cm 87.10.25) -(test.texinfo [1]) -* -@end example - -@noindent -In this case, simply type @kbd{\end @key{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, @samp{\}. @TeX{} uses @samp{\} -instead of @samp{@@}; and in this circumstance, you are working -directly with @TeX{}, not with Texinfo.)@refill - -@node Using texinfo-show-structure, Using occur, Debugging with TeX, Catching Mistakes -@comment node-name, next, previous, up -@appendixsec Using @code{texinfo-show-structure} -@cindex Showing the structure of a file -@findex 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.@refill - -In GNU Emacs, in Texinfo mode, the @code{texinfo-show-structure} -command lists all the lines that begin with the @@-commands that -specify the structure: @code{@@chapter}, @code{@@section}, -@code{@@appendix}, and so on. With an argument (@w{@kbd{C-u}} -as prefix argument, if interactive), -the command also shows the @code{@@node} lines. The -@code{texinfo-show-structure} command is bound to @kbd{C-c C-s} in -Texinfo mode, by default.@refill - -The lines are displayed in a buffer called the @samp{*Occur*} buffer. -For example, when @code{texinfo-show-structure} was run on an earlier -version of this appendix, it produced the following:@refill - -@smallexample -Lines matching "^@@\\(chapter \\|sect\\|sub\\|unnum\\|major\\| -heading \\|appendix\\)" in buffer texinfo.texi. - 4:@@appendix Formatting Mistakes - 52:@@appendixsec Catching Errors with Info Formatting -222:@@appendixsec Catching Errors with @@TeX@{@} Formatting -338:@@appendixsec Using @@code@{texinfo-show-structure@} -407:@@appendixsubsec Using @@code@{occur@} -444:@@appendixsec Finding Badly Referenced Nodes -513:@@appendixsubsec Running @@code@{Info-validate@} -573:@@appendixsubsec Splitting a File Manually -@end smallexample - -This says that lines 4, 52, and 222 of @file{texinfo.texi} begin with -the @code{@@appendix}, @code{@@appendixsec}, and @code{@@appendixsec} -commands respectively. If you move your cursor into the @samp{*Occur*} -window, you can position the cursor over one of the lines and use the -@kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to -the corresponding spot in the Texinfo file. @xref{Other Repeating -Search, , Using Occur, emacs, The GNU Emacs Manual}, for more -information about @code{occur-mode-goto-occurrence}.@refill - -The first line in the @samp{*Occur*} window describes the @dfn{regular -expression} specified by @var{texinfo-heading-pattern}. This regular -expression is the pattern that @code{texinfo-show-structure} looks for. -@xref{Regexps, , Using Regular Expressions, emacs, The GNU Emacs Manual}, -for more information.@refill - -When you invoke the @code{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 @kbd{C-x n} (@code{narrow-to-region}) command to mark the -region. (@xref{Narrowing, , , emacs, The GNU Emacs Manual}.) This is -how the example used above was generated. (To see the whole buffer -again, use @kbd{C-x w} (@code{widen}).)@refill - -If you call @code{texinfo-show-structure} with a prefix argument by -typing @w{@kbd{C-u C-c C-s}}, it will list lines beginning with -@code{@@node} as well as the lines beginning with the @@-sign commands -for @code{@@chapter}, @code{@@section}, and the like.@refill - -You can remind yourself of the structure of a Texinfo file by looking at -the list in the @samp{*Occur*} window; and if you have mis-named a node -or left out a section, you can correct the mistake.@refill - -@node Using occur, Running Info-Validate, Using texinfo-show-structure, Catching Mistakes -@comment node-name, next, previous, up -@appendixsec Using @code{occur} -@cindex Occurrences, listing with @code{@@occur} -@findex occur - -Sometimes the @code{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 -@code{texinfo-show-structure}. In this case, you can use the @code{occur} -command directly. To do this, type@refill - -@example -@kbd{M-x occur} -@end example - -@noindent -and then, when prompted, type a @dfn{regexp}, a regular expression for -the pattern you want to match. (@xref{Regexps, , Regular Expressions, -emacs, The GNU Emacs Manual}.) The @code{occur} command works from -the current location of the cursor in the buffer to the end of the -buffer. If you want to run @code{occur} on the whole buffer, place -the cursor at the beginning of the buffer.@refill - -For example, to see all the lines that contain the word -@samp{@@chapter} in them, just type @samp{@@chapter}. This will -produce a list of the chapters. It will also list all the sentences -with @samp{@@chapter} in the middle of the line.@refill - -If you want to see only those lines that start with the word -@samp{@@chapter}, type @samp{^@@chapter} when prompted by -@code{occur}. If you want to see all the lines that end with a word -or phrase, end the last word with a @samp{$}; for example, -@samp{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.@refill - -@xref{Other Repeating Search, , Using Occur, emacs , The GNU Emacs Manual}, -for more information.@refill - -@node Running Info-Validate, , Using occur, Catching Mistakes -@comment node-name, next, previous, up -@appendixsec Finding Badly Referenced Nodes -@findex Info-validate -@cindex Nodes, checking for badly referenced -@cindex Checking for badly referenced nodes -@cindex Looking for badly referenced nodes -@cindex Finding badly referenced nodes -@cindex Badly referenced nodes - -You can use the @code{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 @code{Info-validate} command works only on Info -files, not on Texinfo files.@refill - -The @code{makeinfo} program validates pointers automatically, so you -do not need to use the @code{Info-validate} command if you are using -@code{makeinfo}. You only may need to use @code{Info-validate} if you -are unable to run @code{makeinfo} and instead must create an Info file -using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or -if you write an Info file from scratch.@refill - -@menu -* Using Info-validate:: How to run @code{Info-validate}. -* Unsplit:: How to create an unsplit file. -* Tagifying:: How to tagify a file. -* Splitting:: How to split a file manually. -@end menu - -@node Using Info-validate, Unsplit, , Running Info-Validate -@appendixsubsec Running @code{Info-validate} -@cindex Running @code{Info-validate} -@cindex Info validating a large file -@cindex Validating a large file - -To use @code{Info-validate}, visit the Info file you wish to check and -type:@refill - -@example -M-x Info-validate -@end example - -@noindent -(Note that the @code{Info-validate} command requires an upper case -`I'. You may also need to create a tag table before running -@code{Info-validate}. @xref{Tagifying}.)@refill - -If your file is valid, you will receive a message that says ``File appears -valid''. However, if you have a pointer that does not point to a node, -error messages will be displayed in a buffer called @samp{*problems in -info file*}.@refill - -For example, @code{Info-validate} was run on a test file that contained -only the first node of this manual. One of the messages said:@refill - -@example -In node "Overview", invalid Next: Texinfo Mode -@end example - -@noindent -This meant that the node called @samp{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).@refill - -Now suppose we add a node named @samp{Texinfo Mode} to our test case -but we do not specify a `Previous' for this node. Then we will get -the following error message:@refill - -@example -In node "Texinfo Mode", should have Previous: Overview -@end example - -@noindent -This is because every `Next' pointer should be matched by a -`Previous' (in the node where the `Next' points) which points back.@refill - -@code{Info-validate} also checks that all menu entries and cross references -point to actual nodes.@refill - -Note that @code{Info-validate} requires a tag table and does not work -with files that have been split. (The @code{texinfo-format-buffer} -command automatically splits large files.) In order to use -@code{Info-validate} on a large file, you must run -@code{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.@refill - -@node Unsplit, Tagifying, Using Info-validate, Running Info-Validate -@comment node-name, next, previous, up -@appendixsubsec Creating an Unsplit File -@cindex Creating an unsplit file -@cindex Unsplit file creation - -You can run @code{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 70,000 bytes or so), you need to run the -@code{texinfo-format-buffer} or @code{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 @code{Info-validate} and look for badly referenced -nodes.@refill - -@c !!! broke into two paragraphs to prevent overfull hbox --bob 26 Mar 93 -The first step is to create an unsplit Info file. - -To prevent @code{texinfo-format-buffer} from splitting a Texinfo file -into smaller Info files, give a prefix to the @kbd{M-x -texinfo-format-buffer} command:@refill - -@example -C-u M-x texinfo-format-buffer -@end example - -@noindent -or else - -@example -C-u C-c C-e C-b -@end example - -@noindent -When you do this, Texinfo will not split the file and will not create -a tag table for it. @refill -@cindex Making a tag table manually -@cindex Tag table, making manually - -@node Tagifying, Splitting, Unsplit, Running Info-Validate -@appendixsubsec 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:@refill - -@example -M-x Info-tagify -@end example - -@noindent -(Note the upper case @key{I} in @code{Info-tagify}.) This creates an -Info file with a tag table that you can validate.@refill - -The third step is to validate the Info file:@refill - -@example -M-x Info-validate -@end example - -@noindent -(Note the upper case @key{I} in @code{Info-validate}.) -In brief, the steps are:@refill - -@example -@group -C-u M-x texinfo-format-buffer -M-x Info-tagify -M-x Info-validate -@end group -@end example - -@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93 -After you have validated the node structure, you will be able to rerun -@code{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.@refill - -@node Splitting, , Tagifying, Running Info-Validate -@comment node-name, next, previous, up -@appendixsubsec Splitting a File Manually -@cindex Splitting an Info file manually -@cindex Info file, splitting manually - -You should split a large file or else let the -@code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it -for you automatically. (Generally you will let one of the formatting -commands do this job for you. @xref{Create an Info File}.)@refill - -The split-off files are called the indirect subfiles.@refill - -Info files are split to save memory. With smaller files, Emacs does not -have make such a large buffer to hold the information.@refill - -If an Info file has more than 30 nodes, you should also make a tag -table for it. @xref{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 -@code{Info-validate}.)@refill - -@c Info-split is autoloaded in `loaddefs.el' in Emacs 18.51 -@ignore -Before running @code{Info-split}, you need to load the @code{info} library -into Emacs by giving the command @kbd{M-x load-library @key{RET} info -@key{RET}}. -@end ignore - -Visit the Info file you wish to tagify and split and type the two -commands:@refill - -@example -M-x Info-tagify -M-x Info-split -@end example - -@noindent -(Note that the @samp{I} in @samp{Info} is upper case.)@refill - -When you use the @code{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 @samp{-} and a number to the original file name.@refill - -The primary file still functions as an Info file, but it contains just -the tag table and a directory of subfiles.@refill - -@node Refilling Paragraphs, Command Syntax, Catching Mistakes, Top -@comment node-name, next, previous, up -@appendix Refilling Paragraphs -@cindex Refilling paragraphs -@cindex Filling paragraphs -@findex refill - -The @code{@@refill} command refills and, optionally, indents the first -line of a paragraph.@footnote{Perhaps the command should have been -called the @code{@@refillandindent} command, but @code{@@refill} is -shorter and the name was chosen before indenting was possible.} The -@code{@@refill} command is no longer important, but we describe it here -because you once needed it. You will see it in many old Texinfo -files.@refill - -@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93 -Without refilling, paragraphs containing long @@-constructs may look -bad after formatting because the formatter removes @@-commands and -shortens some lines more than others. In the past, neither -@code{texinfo-format-region} nor -@code{texinfo-format-buffer} refilled paragraphs -automatically. The @code{@@refill} command had to be written at the -end of every paragraph to cause these formatters to fill them. (Both -@TeX{} and @code{makeinfo} have always refilled paragraphs -automatically.) Now, all the Info formatters automatically fill and -indent those paragraphs that need to be filled and indented.@refill - -@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93 -The @code{@@refill} command causes both the @code{texinfo-format-region} -command and the -@code{texinfo-format-buffer} command to refill a paragraph in the Info file -@emph{after} all the other processing has been done. For this reason, -you can not use @code{@@refill} with a paragraph containing either -@code{@@*} or @code{@@w@{ @dots{} @}} since the refilling action will -override those two commands.@refill - -The @code{texinfo-format-region} and @code{texinfo-format-buffer} -commands now automatically append @code{@@refill} to the end of each -paragraph that should be filled. They do not append @code{@@refill} to -the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}} -and therefore do not refill or indent them.@refill - -@node Command Syntax, Obtaining TeX, Refilling Paragraphs, Top -@comment node-name, next, previous, up -@appendix @@-Command Syntax -@cindex @@-command syntax - -The character @samp{@@} is used to start special Texinfo commands. -(It has the same meaning that @samp{\} has in Plain@TeX{}.) Texinfo -has four types of @@-command:@refill - -@table @asis -@item 1. Non-alphabetic commands. -These commands consist of an @@ followed by a punctuation mark or other -character that is not part of the alphabet. Non-alphabetic commands -are almost always part of the text within a paragraph, and never take -any argument. The two characters (@@ and the other one) are complete -in themselves; none is followed by braces. The non-alphabetic -commands are: @code{@@.}, @code{@@:}, @code{@@*}, @code{@@@@}, -@code{@@@{}, and @code{@@@}}.@refill - -@item 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, -@code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}} -@result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}', -and @code{@@bullet@{@}} @result{} @samp{@bullet{}}.@refill - -@item 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 @code{@@dfn} indicates -the introductory or defining use of a term; it is used as follows: @samp{In -Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.}@refill - -@item 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, @code{@@center} -or @code{@@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.@refill -@end table - -@cindex Braces and argument syntax -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.@refill - -The purpose of having a different syntax for commands of classes 3 and -4 is to make Texinfo files easier to read, and also to help the GNU -Emacs paragraph and filling commands work properly. There is only one -exception to this rule: the command @code{@@refill}, which is always -used at the end of a paragraph immediately following the final period -or other punctuation character. @code{@@refill} takes no argument and -does @emph{not} require braces. @code{@@refill} never confuses the -Emacs paragraph commands because it cannot appear at the beginning of -a line.@refill - -@node Obtaining TeX, New Features, Command Syntax, Top -@appendix How to Obtain @TeX{} -@cindex Obtaining @TeX{} -@cindex @TeX{}, how to obtain - -@c !!! Here is information about obtaining TeX. Update it whenever. -@c Last updated by RJC on 6 October 1992 -@c based on message from elisabet@@.u.washington.edu -@TeX{} is freely redistributable. You can obtain @TeX{} for Unix -systems from the University of Washington for a distribution -fee.@refill - -To order a full distribution, send $200.00 for a 1/2-inch 9-track 1600 -bpi (@code{tar} or @code{cpio}) tape reel, or $210.00 for a 1/4-inch -4-track QIC-24 (@code{tar} or @code{cpio}) cartridge, to:@refill - -@display -Northwest Computing Support Center -DR-10, Thomson Hall 35 -University of Washington -Seattle, Washington 98195 -@end display - -@noindent -Please make checks payable to the University of Washington.@refill - -Prepaid orders are preferred but purchase orders are acceptable; -however, purchase orders carry an extra charge of $10.00, to pay for -processing.@refill - -Overseas sites: please add to the base cost $20.00 for shipment via -air parcel post, or $30.00 for shipment via courier.@refill - -Please check with the Northwest Computing Support Center at the -University of Washington for current prices and formats:@refill - -@example -@group -@r{telephone:} (206) 543-6259 -@r{email:} elisabet@@u.washington.edu -@end group -@end example - -@node New Features, Command and Variable Index, Obtaining TeX, Top -@appendix Second Edition Features - -@tex -% Widen the space for the first column so three control-character -% strings fit in the first column. Switched back to default .8in -% value at end of chapter. -\global\tableindent=1.0in -@end tex - -The second edition of the Texinfo manual describes more than 20 new -Texinfo mode commands and more than 50 previously undocumented Texinfo -@@-commands. This edition is more than twice the length of the first -edition.@refill - -Here is a brief description of the new commands.@refill - -@menu -* New Texinfo Mode Commands:: The updating commands are especially useful. -* New Commands:: Many newly described @@-commands. -@end menu - -@node New Texinfo Mode Commands, New Commands, , New Features -@appendixsec New Texinfo Mode Commands - -Texinfo mode provides commands and features especially designed for -working with Texinfo files. More than 20 new commands have been -added, including commands for automatically creating and updating -both nodes and menus. This is a tedious task when done by hand.@refill - -The keybindings are intended to be somewhat mnemonic.@refill - -@subheading Update all nodes and menus - -The @code{texinfo-master-menu} command is the primary command: - -@table @kbd -@item C-c C-u m -@itemx M-x texinfo-master-menu -Create or update a master menu. -With @kbd{C-u} as a prefix argument, -first create or update all nodes -and regular menus. -@end table - -@subheading Update Pointers - -@noindent -Create or update `Next', `Previous', and `Up' node pointers.@refill - -@noindent -@xref{Updating Nodes and Menus}. - -@table @kbd -@item C-c C-u C-n -@itemx M-x texinfo-update-node -Update a node. - -@item C-c C-u C-e -@itemx M-x texinfo-every-node-update -Update every node in the buffer. -@end table - -@subheading Update Menus - -@noindent -Create or update menus.@refill - -@noindent -@xref{Updating Nodes and Menus}. - -@table @kbd -@item C-c C-u C-m -@itemx M-x texinfo-make-menu -Make or update a menu. - -@item C-c C-u C-a -@itemx M-x texinfo-all-menus-update -Make or update all the menus in a buffer. -With @kbd{C-u} as a prefix argument, -first update all the nodes. -@end table - -@subheading Insert Title as Description - -@noindent -Insert a node's chapter or section title in the space for the -description in a menu entry line; position point so you can edit the -insert. (This command works somewhat differently than the other -insertion commands, which insert only a predefined string.)@refill - -@noindent -@xref{Inserting, Inserting Frequently Used Commands}. - -@table @kbd -@item C-c C-c C-d -Insert title. -@end table - -@subheading Format for Info - -@noindent -Provide keybindings both for the Info formatting commands that are -written in Emacs Lisp and for @code{makeinfo} that is written in -C.@refill - -@noindent -@xref{Info Formatting}. - -@noindent -Use the Emacs lisp @code{texinfo-format@dots{}} commands: - -@table @kbd -@item C-c C-e C-r -Format the region. - -@item C-c C-e C-b -Format the buffer. -@end table - -@noindent -Use @code{makeinfo}: - -@table @kbd -@item C-c C-m C-r -Format the region. - -@item C-c C-m C-b -Format the buffer. - -@item C-c C-m C-l -Recenter the @code{makeinfo} output buffer. - -@item C-c C-m C-k -Kill the @code{makeinfo} formatting job. -@end table - -@subheading Typeset and Print - -@noindent -Typeset and print Texinfo documents from within Emacs.@refill - -@ifinfo -@noindent -@xref{Printing}. -@end ifinfo -@iftex -@noindent -@xref{Printing, , Formatting and Printing}. -@end iftex - -@table @kbd -@item C-c C-t C-r -Run @TeX{} on the region. - -@item C-c C-t C-b -Run @TeX{} on the buffer. - -@item C-c C-t C-i -Run @code{texindex}. - -@item C-c C-t C-p -Print the @sc{dvi} file. - -@item C-c C-t C-q -Show the print queue. - -@item C-c C-t C-d -Delete a job from the print queue. - -@item C-c C-t C-k -Kill the current @TeX{} formatting job. - -@item C-c C-t C-x -Quit a currently stopped @TeX{} formatting job. - -@item C-c C-t C-l -Recenter the output buffer. -@end table - -@subheading Other Updating Commands - -@noindent -The ``other updating commands'' do not have standard keybindings because -they are used less frequently.@refill - -@noindent -@xref{Other Updating Commands}. - -@table @kbd -@item M-x texinfo-insert-node-lines -Insert missing @code{@@node} lines using -section titles as node names. - -@item M-x texinfo-multiple-files-update -Update a multi-file document. -With a numeric prefix, such as @kbd{C-u 8}, -update @strong{every} pointer and -menu in @strong{all} the files and -then insert a master menu. - -@item M-x texinfo-indent-menu-description -Indent descriptions in menus. - -@item M-x texinfo-sequential-node-update -Insert node pointers in strict sequence. -@end table - -@node New Commands, , New Texinfo Mode Commands, New Features -@appendixsec New Texinfo @@-Commands - -The second edition of the Texinfo manual describes more than 50 -commands that were not described in the first edition. A third or so -of these commands existed in Texinfo but were not documented in the -manual; the others are new. Here is a listing, with brief -descriptions of them:@refill - -@subheading Indexing - -@noindent -Create your own index, and merge indices.@refill - -@noindent -@xref{Indices}. - -@table @kbd -@item @@defindex @var{index-name} -Define a new index and its indexing command. -See also the @code{@@defcodeindex} command. - -@c written verbosely to avoid overful hbox -@item @@synindex @var{from-index} @var{into-index} -Merge the @var{from-index} index into the @var{into-index} index. -See also the @code{@@syncodeindex} command. -@end table - -@subheading Definitions - -@noindent -Describe functions, variables, macros, -commands, user options, special forms, and other such artifacts in a -uniform format.@refill - -@noindent -@xref{Definition Commands}. - -@table @kbd -@item @@deffn @var{category} @var{name} @var{arguments}@dots{} -Format a description for functions, interactive -commands, and similar entities. - -@item @@defvr, @@defop, @dots{} -15 other related commands. -@end table - -@subheading Glyphs - -@noindent -Indicate the results of evaluation, expansion, -printed output, an error message, equivalence of expressions, and the -location of point.@refill - -@noindent -@xref{Glyphs}. - -@table @kbd -@item @@equiv@{@} -@itemx @equiv{} -Equivalence: - -@item @@error@{@} -@itemx @error{} -Error message - -@item @@expansion@{@} -@itemx @expansion{} -Macro expansion - -@item @@point@{@} -@itemx @point{} -Position of point - -@item @@print@{@} -@itemx @print{} -Printed output - -@item @@result@{@} -@itemx @result{} -Result of an expression -@end table - -@subheading Page Headings - -@noindent -Customize page headings. - -@noindent -@xref{Headings}. - -@table @kbd -@item @@headings @var{on-off-single-double} -Headings on or off, single, or double-sided. - -@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] -Footings for even-numbered (left-hand) pages. - -@item @@evenheading, @@everyheading, @@oddheading, @dots{} -Five other related commands. - -@item @@thischapter -Insert name of chapter and chapter number. - -@item @@thischaptername, @@thisfile, @@thistitle, @@thispage -Related commands. -@end table - -@subheading Formatting - -@noindent -Format blocks of text. - -@noindent -@xref{Quotations and Examples}, and@* -@ref{Lists and Tables, , Making Lists and Tables}. - -@table @kbd -@item @@cartouche -Draw rounded box surrounding text (not in Info). - -@item @@enumerate @var{optional-arg} -Enumerate a list with letters or numbers. - -@item @@exdent @var{line-of-text} -Remove indentation. - -@item @@flushleft -Left justify. - -@item @@flushright -Right justify. - -@item @@format -Do not narrow nor change font. - -@item @@ftable @var{formatting-command} -@itemx @@vtable @var{formatting-command} -Two-column table with indexing. - -@item @@lisp -For an example of Lisp code. - -@item @@smallexample -@itemx @@smalllisp -Like @@table and @@lisp @r{but for} @@smallbook. -@end table - -@subheading Conditionals - -@noindent -Conditionally format text. - -@noindent -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@table @kbd -@item @@set @var{flag} [@var{string}] -Set a flag. Optionally, set value -of @var{flag} to @var{string}. - -@item @@clear @var{flag} -Clear a flag. - -@item @@value@{@var{flag}@} -Replace with value to which @var{flag} is set. - -@item @@ifset @var{flag} -Format, if @var{flag} is set. - -@item @@ifclear @var{flag} -Ignore, if @var{flag} is set. -@end table - -@subheading @@heading series for Titles - -@noindent -Produce unnumbered headings that do not appear in a table of contents. - -@noindent -@xref{Structuring}. - -@table @kbd -@item @@heading @var{title} -Unnumbered section-like heading not listed -in the table of contents of a printed manual. - -@item @@chapheading, @@majorheading, @@subheading, @@subsubheading -Related commands. -@end table - -@need 1000 -@subheading Font commands - -@need 1000 -@noindent -@xref{Smallcaps}, and @* -@ref{Fonts}. - -@table @kbd -@item @@r@{@var{text}@} -Print in roman font. - -@item @@sc@{@var{text}@} -Print in @sc{small caps} font. -@end table - -@subheading Miscellaneous - -@noindent -See @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author} Commands},@* -see @ref{Overfull hboxes},@* -see @ref{Footnotes},@* -see @ref{dmn, , Format a Dimension},@* -see @ref{minus, , Inserting a Minus Sign},@* -see @ref{paragraphindent, , Paragraph Indenting},@* -see @ref{Cross Reference Commands},@* -see @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author}}, and@* -see @ref{Custom Headings, , How to Make Your Own Headings}. - -@need 700 -@table @kbd -@item @@author @var{author} -Typeset author's name. - -@item @@finalout -Produce cleaner printed output. - -@item @@footnotestyle -Specify footnote style. - -@item @@dmn@{@var{dimension}@} -Format a dimension. - -@item @@minus@{@} -Generate a minus sign. - -@item @@paragraphindent -Specify paragraph indentation. - -@item @@ref@{@var{node-name}, @r{[}@var{entry}@r{]}, @r{[}@var{topic-or-title}@r{]}, @r{[}@var{info-file}@r{]}, @r{[}@var{manual}@r{]}@} -Make a reference. In the printed manual, the -reference does not start with the word `see'. - -@item @@title @var{title} -Typeset @var{title} in the alternative -title page format. - -@item @@subtitle @var{subtitle} -Typeset @var{subtitle} in the alternative -title page format. - -@item @@today@{@} -Insert the current date. -@end table -@tex -% Switch width of first column of tables back to default value -\global\tableindent=.8in -@end tex - -@node Command and Variable Index, Concept Index, New Features, Top -@comment node-name, next, previous, up -@unnumbered Command and Variable Index - -This is an alphabetical list of all the @@-commands and several -variables. To make the list easier to use, the commands are listed -without their preceding @samp{@@}.@refill - -@printindex fn - -@node Concept Index, , Command and Variable Index, Top -@comment node-name, next, previous, up -@unnumbered Concept Index - -@printindex cp - -@summarycontents -@contents -@bye diff --git a/gnu/usr.bin/texinfo/info-files/texi-files/userdoc.texi b/gnu/usr.bin/texinfo/info-files/texi-files/userdoc.texi deleted file mode 100644 index 4ebeae8..0000000 --- a/gnu/usr.bin/texinfo/info-files/texi-files/userdoc.texi +++ /dev/null @@ -1,1263 +0,0 @@ -@c This file is meant to be included in any arbitrary piece of -@c documentation that wishes to describe the info program. Some day -@c info-stnd.texi should probably use this file instead of duplicating -@c its contents. -@c -@c This file documents the use of the standalone GNU Info program, -@c versions 2.7 and later. - -@ifclear InfoProgVer -@set InfoProgVer 2.9 -@end ifclear -@synindex vr cp -@synindex fn cp -@synindex ky cp - -@heading What is Info? - -This text documents the use of the GNU Info program, version -@value{InfoProgVer}. - -@dfn{Info} is a program which is used to view info files on an ASCII -terminal. @dfn{info files} are the result of processing texinfo files -with the program @code{makeinfo} or with the Emacs command @code{M-x -texinfo-format-buffer}. Finally, @dfn{texinfo} is a documentation -language which allows a printed manual and online documentation (an info -file) to be produced from a single source file. - -@menu -* Options:: Options you can pass on the command line. -* Cursor Commands:: Commands which move the cursor within a node. -* Scrolling Commands:: Commands for moving the node around in a window. -* 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 behaviour of Info. -* Info for Sys Admins:: How to setup Info. Using special options. -@ifset STANDALONE -* GNU Info Global Index:: Global index containing keystrokes, command names, - variable names, and general concepts. -@end ifset -@end menu - -@node Options -@chapter Command Line Options -@cindex command line options -@cindex arguments, command line - -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: - -@example -info [--@var{option-name} @var{option-value}] @var{menu-item}@dots{} -@end example - -The following @var{option-names} are available when invoking Info from -the shell: - -@table @code -@cindex directory path -@item --directory @var{directory-path} -@itemx -d @var{directory-path} -Adds @var{directory-path} to the list of directory paths searched when -Info needs to find a file. You may issue @code{--directory} multiple -times; once for each directory which contains info files. -Alternatively, you may specify a value for the environment variable -@code{INFOPATH}; if @code{--directory} is not given, the value of -@code{INFOPATH} is used. The value of @code{INFOPATH} is a colon -separated list of directory names. If you do not supply -@code{INFOPATH} or @code{--directory-path} a default path is used. - -@item --file @var{filename} -@itemx -f @var{filename} -@cindex info file, selecting -Specifies a particular info file to visit. Instead of visiting the file -@code{dir}, Info will start with @code{(@var{filename})Top} as the first -file and node. - -@item --node @var{nodename} -@itemx -n @var{nodename} -@cindex node, selecting -Specifies a particular node to visit in the initial file loaded. This -is especially useful in conjunction with @code{--file}@footnote{Of -course, you can specify both the file and node in a @code{--node} -command; but don't forget to escape the open and close parentheses from -the shell as in: @code{info --node '(emacs)Buffers'}}. You may specify -@code{--node} multiple times; for an interactive Info, each -@var{nodename} is visited in its own window, for a non-interactive Info -(such as when @code{--output} is given) each @var{nodename} is processed -sequentially. - -@item --output @var{filename} -@itemx -o @var{filename} -@cindex file, outputting to -@cindex outputting to a file -Specify @var{filename} as the name of a file to output to. Each node -that Info visits will be output to @var{filename} instead of -interactively viewed. A value of @code{-} for @var{filename} specifies -the standard output. - -@item --subnodes -@cindex @code{--subnodes}, command line option -This option only has meaning when given in conjunction with -@code{--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. - -@item --help -@itemx -h -Produces a relatively brief description of the available Info options. - -@item --version -@cindex version information -Prints the version information of Info and exits. - -@item @var{menu-item} -@cindex menu, following -Remaining arguments to Info are treated as the names of menu items. The -first argument would be a menu item in the initial node visited, while -the second argument would be a menu item in the first argument's node. -You can easily move to the node of your choice by specifying the menu -names which describe the path to that node. For example, - -@example -info emacs buffers -@end example - -first selects the menu item @samp{Emacs} in the node @samp{(dir)Top}, -and then selects the menu item @samp{Buffers} in the node -@samp{(emacs)Top}. - -@end table - -@node Cursor Commands -@chapter Moving the Cursor -@cindex cursor, moving -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. @xref{Characters, , Character -Conventions, emacs, the GNU Emacs Manual}, if you are unfamilar with the -notation. - -The following table lists the basic cursor movement commands in Info. -Each entry consists of the key sequence you should type to execute the -cursor movement, the @code{M-x}@footnote{@code{M-x} is also a command; it -invokes @code{execute-extended-command}. @xref{M-x, , Executing an -extended command, emacs, the GNU Emacs Manual}, for more detailed -information.} command name (displayed in parentheses), and a short -description of what the command does. All of the cursor motion commands -can take an @dfn{numeric} argument (@pxref{Miscellaneous Commands, -@code{universal-argument}}), to find out how to supply them. With a -numeric argument, the motion commands are simply executed that -many times; for example, a numeric argument of 4 given to -@code{next-line} causes the cursor to move down 4 lines. With a -negative numeric argument, the motion is reversed; an argument of -4 -given to the @code{next-line} command would cause the cursor to move -@emph{up} 4 lines. - -@table @asis -@item @code{C-n} (@code{next-line}) -@kindex C-n -@findex next-line -Moves the cursor down to the next line. - -@item @code{C-p} (@code{prev-line}) -@kindex C-p -@findex prev-line -Move the cursor up to the previous line. - -@item @code{C-a} (@code{beginning-of-line}) -@kindex C-a, in Info windows -@findex beginning-of-line -Move the cursor to the start of the current line. - -@item @code{C-e} (@code{end-of-line}) -@kindex C-e, in Info windows -@findex end-of-line -Moves the cursor to the end of the current line. - -@item @code{C-f} (@code{forward-char}) -@kindex C-f, in Info windows -@findex forward-char -Move the cursor forward a character. - -@item @code{C-b} (@code{backward-char}) -@kindex C-b, in Info windows -@findex backward-char -Move the cursor backward a character. - -@item @code{M-f} (@code{forward-word}) -@kindex M-f, in Info windows -@findex forward-word -Moves the cursor forward a word. - -@item @code{M-b} (@code{backward-word}) -@kindex M-b, in Info winows -@findex backward-word -Moves the cursor backward a word. - -@item @code{M-<} (@code{beginning-of-node}) -@itemx @code{b} -@kindex b, in Info winows -@kindex M-< -@findex beginning-of-node -Moves the cursor to the start of the current node. - -@item @code{M->} (@code{end-of-node}) -@kindex M-> -@findex end-of-node -Moves the cursor to the end of the current node. - -@item @code{M-r} (@code{move-to-window-line}) -@kindex M-r -@findex move-to-window-line -Moves the cursor to a specific line of the window. Without a numeric -argument, @code{M-r} moves the cursor to the start of the line in the -center of the window. With a numeric argument of @var{n}, @code{M-r} -moves the cursor to the start of the @var{n}th line in the window. -@end table - -@node Scrolling Commands -@chapter Moving Text Within a Window -@cindex scrolling - -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. - -@table @asis -@item @code{SPC} (@code{scroll-forward}) -@itemx @code{C-v} -@kindex SPC, in Info windows -@kindex C-v -@findex 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, @key{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. - -@item @code{DEL} (@code{scroll-backward}) -@itemx @code{M-v} -@kindex DEL, in Info windows -@kindex M-v -@findex scroll-backward -Shift the text in this window down. The inverse of -@code{scroll-forward}. - -@end table - -@cindex scrolling through node structure -The @code{scroll-forward} and @code{scroll-backward} commands can also -move forward and backward through the node structure of the file. If -you press @key{SPC} while viewing the end of a node, or @key{DEL} while -viewing the beginning of a node, what happens is controlled by the -variable @code{scroll-behaviour}. @xref{Variables, -@code{scroll-behaviour}}, for more information. - -@table @asis -@item @code{C-l} (@code{redraw-display}) -@kindex C-l -@findex redraw-display -Redraw the display from scratch, or shift the line containing the cursor -to a specified location. With no numeric argument, @samp{C-l} clears -the screen, and then redraws its entire contents. Given a numeric -argument of @var{n}, the line containing the cursor is shifted so that -it is on the @var{n}th line of the window. - -@item @code{C-x w} (@code{toggle-wrap}) -@kindex C-w -@findex toggle-wrap -Toggles the state of line wrapping in the current window. Normally, -lines which are longer than the screen width @dfn{wrap}, i.e., they are -continued on the next line. Lines which wrap have a @samp{\} appearing -in the rightmost column of the screen. You can cause such lines to be -terminated at the rightmost column by changing the state of line -wrapping in the window with @code{C-x w}. When a line which needs more -space than one screen width to display is displayed, a @samp{$} appears -in the rightmost column of the screen, and the remainder of the line is -invisible. -@end table - -@node Node Commands -@chapter Selecting a New Node -@cindex nodes, selection of - -This section details the numerous Info commands which select a new node -to view in the current window. - -The most basic node commands are @samp{n}, @samp{p}, @samp{u}, and -@samp{l}. - -When you are viewing a node, the top line of the node contains some Info -@dfn{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: - -@table @asis -@item @code{n} (@code{next-node}) -@kindex n -@findex next-node -Selects the `Next' node. - -@item @code{p} (@code{prev-node}) -@kindex p -@findex prev-node -Selects the `Prev' node. - -@item @code{u} (@code{up-node}) -@kindex u -@findex up-node -Selects the `Up' node. -@end table - -You can easily select a node that you have already viewed in this window -by using the @samp{l} command -- this name stands for "last", and -actually moves through the list of already visited nodes for this -window. @samp{l} with a negative numeric argument moves forward through -the history of nodes for this window, so you can quickly step between -two adjacent (in viewing history) nodes. - -@table @asis -@item @code{l} (@code{history-node}) -@kindex l -@findex history-node -Selects the most recently selected node in this window. -@end table - -Two additional commands make it easy to select the most commonly -selected nodes; they are @samp{t} and @samp{d}. - -@table @asis -@item @code{t} (@code{top-node}) -@kindex t -@findex top-node -Selects the node @samp{Top} in the current info file. - -@item @code{d} (@code{dir-node}) -@kindex d -@findex dir-node -Selects the directory node (i.e., the node @samp{(dir)}). -@end table - -Here are some other commands which immediately result in the selection -of a different node in the current window: - -@table @asis -@item @code{<} (@code{first-node}) -@kindex < -@findex first-node -Selects the first node which appears in this file. This node is most -often @samp{Top}, but it doesn't have to be. - -@item @code{>} (@code{last-node}) -@kindex > -@findex last-node -Selects the last node which appears in this file. - -@item @code{]} (@code{global-next-node}) -@kindex ] -@findex global-next-node -Moves forward or down through node structure. If the node that you are -currently viewing has a @samp{Next} pointer, that node is selected. -Otherwise, if this node has a menu, the first menu item is selected. If -there is no @samp{Next} and no menu, the same process is tried with the -@samp{Up} node of this node. - -@item @code{[} (@code{global-prev-node}) -@kindex [ -@findex global-prev-node -Moves backward or up through node structure. If the node that you are -currently viewing has a @samp{Prev} pointer, that node is selected. -Otherwise, if the node has an @samp{Up} pointer, that node is selected, -and if it has a menu, the last item in the menu is selected. -@end table - -You can get the same behaviour as @code{global-next-node} and -@code{global-prev-node} while simply scrolling through the file with -@key{SPC} and @key{DEL}; @xref{Variables, @code{scroll-behaviour}}, for -more information. - -@table @asis -@item @code{g} (@code{goto-node}) -@kindex g -@findex goto-node -Reads the name of a node and selects it. No completion is done while -reading the node name, since the desired node may reside in a separate -file. The node must be typed exactly as it appears in the info file. A -file name may be included as with any node specification, for example - -@example -@code{g(emacs)Buffers} -@end example - -finds the node @samp{Buffers} in the info file @file{emacs}. - -@item @code{C-x k} (@code{kill-node}) -@kindex C-x k -@findex kill-node -Kills a node. The node name is prompted for in the echo area, with a -default of the current node. @dfn{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. - -@item @code{C-x C-f} (@code{view-file}) -@kindex C-x C-f -@findex view-file -Reads the name of a file and selects the entire file. The command -@example -@code{C-x C-f @var{filename}} -@end example -is equivalent to typing -@example -@code{g(@var{filename})*} -@end example - -@item @code{C-x C-b} (@code{list-visited-nodes}) -@kindex C-x C-b -@findex list-visited-nodes -Makes 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. - -@item @code{C-x b} (@code{select-visited-node}) -@kindex C-x b -@findex select-visited-node -Selects a node which has been previously visited in a visible window. -This is similar to @samp{C-x C-b} followed by @samp{m}, but no window is -created. -@end table - -@node Searching Commands -@chapter Searching an Info File -@cindex searching - -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. - -@table @asis -@item @code{s} (@code{search}) -@kindex s -@findex search -Reads a string in the echo area and searches for it. - -@item @code{C-s} (@code{isearch-forward}) -@kindex C-s -@findex isearch-forward -Interactively searches forward through the info file for a string as you -type it. - -@item @code{C-r} (@code{isearch-backward}) -@kindex C-r -@findex isearch-backward -Interactively searches backward through the info file for a string as -you type it. - -@item @code{i} (@code{index-search}) -@kindex i -@findex index-search -Looks up a string in the indices for this info file, and selects a node -where the found index entry points to. - -@item @code{,} (@code{next-index-match}) -@kindex , -@findex next-index-match -Moves to the node containing the next matching index item from the last -@samp{i} command. -@end table - -The most basic searching command is @samp{s} (@code{search}). The -@samp{s} command prompts you for a string in the echo area, and then -searches the remainder of the info file for an ocurrence of that string. -If the string is found, the node containing it is selected, and the -cursor is left positioned at the start of the found string. Subsequent -@samp{s} commands show you the default search string within @samp{[} and -@samp{]}; pressing @key{RET} instead of typing a new string will use the -default search string. - -@dfn{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. - -@node Xref Commands -@chapter Selecting Cross References - -We have already discussed the @samp{Next}, @samp{Prev}, and @samp{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 -@dfn{cross references}, or @dfn{xrefs} for short. - -@menu -* Parts of an Xref:: What a cross reference is made of. -* Selecting Xrefs:: Commands for selecting menu or note items. -@end menu - -@node Parts of an Xref -@section Parts of an Xref - -Cross references have two major parts: the first part is called the -@dfn{label}; it is the name that you can use to refer to the cross -reference, and the second is the @dfn{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 @samp{:}; first the -label appears, and then the target. For example, in the sample menu -cross reference below, the single colon separates the label from the -target. - -@example -* Foo Label: Foo Target. More information about Foo. -@end example - -Note the @samp{.} which ends the name of the target. The @samp{.} 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: - -@example -* Foo Commands:: Commands pertaining to Foo. -@end example - -In the above example, the name of the target is the same as the name of -the label, in this case @code{Foo Commands}. - -You will normally see two types of cross references while viewing nodes: -@dfn{menu} references, and @dfn{note} references. Menu references -appear within a node's menu; they begin with a @samp{*} at the beginning -of a line, and continue with a label, a target, and a comment which -describes what the contents of the node pointed to contains. - -Note references appear within the body of the node text; they begin with -@code{*Note}, and continue with a label and a target. - -Like @samp{Next}, @samp{Prev} and @samp{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: @xref{xref, , Writing an Xref, texinfo, the Texinfo -Manual}, for more information on creating your own texinfo cross -references. - -@node Selecting Xrefs -@section Selecting Xrefs - -The following table lists the Info commands which operate on menu items. - -@table @asis -@item @code{1} (@code{menu-digit}) -@itemx @code{2} @dots{} @code{9} -@cindex 1 @dots{} 9, in Info windows -@kindex 1 @dots{} 9, in Info windows -@findex menu-digit -Within an Info window, pressing a single digit, (such as @samp{1}), -selects that menu item, and places its node in the current window. -For convenience, there is one exception; pressing @samp{0} selects the -@emph{last} item in the node's menu. - -@item @code{0} (@code{last-menu-item}) -@kindex 0, in Info windows -@findex last-menu-item -Select the last item in the current node's menu. - -@item @code{m} (@code{menu-item}) -@kindex m -@findex 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. - -@item @code{M-x find-menu} -@findex find-menu -Moves the cursor to the start of this node's menu. -@end table - -This table lists the Info commands which operate on note cross references. - -@table @asis -@item @code{f} (@code{xref-item}) -@itemx @code{r} -@kindex f -@kindex r -@findex xref-item -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. -@end table - -Finally, the next few commands operate on menu or note references alike: - -@table @asis -@item @code{TAB} (@code{move-to-next-xref}) -@kindex TAB, in Info windows -@findex move-to-next-xref -Moves the cursor to the start of the next nearest menu item or note -reference in this node. You can then use @key{RET} -(@code{select-reference-this-line} to select the menu or note reference. - -@item @code{M-TAB} (@code{move-to-prev-xref}) -@kindex M-TAB, in Info windows -@findex move-to-prev-xref -Moves the cursor the start of the nearest previous menu item or note -reference in this node. - -@item @code{RET} (@code{select-reference-this-line}) -@kindex RET, in Info windows -@findex select-reference-this-line -Selects the menu item or note reference appearing on this line. -@end table - -@node Window Commands -@chapter Manipulating Multiple Windows -@cindex windows, manipulating - -A @dfn{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 -@dfn{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 @dfn{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. -@end menu - -@node The Mode Line -@section The Mode Line - -A @dfn{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 @file{dir}, showing the node @samp{Top}. - -@example ------Info: (dir)Top, 40 lines --Top--------------------------------------- - ^^ ^ ^^^ ^^ - (file)Node #lines where -@end example - -When a node comes from a file which is compressed on disk, this is -indicated in the mode line with two small @samp{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: - -@example ---zz-Info: (emacs)Top, 291 lines --Top-- Subfile: emacs-1.Z--------------- -@end example - -When Info makes a node internally, such that there is no corresponding -info file on disk, the name of the node is surrounded by asterisks -(@samp{*}). 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: - -@example ------Info: *Completions*, 7 lines --All----------------------------------- -@end example - -@node Basic Windows -@section Window Commands - -It can be convenient to view more than one node at a time. To allow -this, Info can display more than one @dfn{window}. Each window has its -own mode line (@pxref{The Mode Line}) and history of nodes viewed in that -window (@pxref{Node Commands, , @code{history-node}}). - -@table @asis -@item @code{C-x o} (@code{next-window}) -@cindex windows, selecting -@kindex C-x o -@findex next-window -Selects the next window on the screen. Note that the echo area can only be -selected if it is already in use, and you have left it temporarily. -Normally, @samp{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, @samp{C-x o} moves over -that many windows. A negative argument causes @samp{C-x o} to select -the previous window on the screen. - -@item @code{M-x prev-window} -@findex prev-window -Selects the previous window on the screen. This is identical to -@samp{C-x o} with a negative argument. - -@item @code{C-x 2} (@code{split-window}) -@cindex windows, creating -@kindex C-x 2 -@findex split-window -Splits the current window into two windows, both showing the same node. -Each window is one half the size of the original window, and the cursor -remains in the original window. The variable @code{automatic-tiling} -can cause all of the windows on the screen to be resized for you -automatically, please @pxref{Variables, , automatic-tiling} for more -information. - -@item @code{C-x 0} (@code{delete-window}) -@cindex windows, deleting -@kindex C-x 0 -@findex delete-window -Deletes 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. - -@item @code{C-x 1} (@code{keep-one-window}) -@kindex C-x 1 -@findex keep-one-window -Deletes all of the windows excepting the current one. - -@item @code{ESC C-v} (@code{scroll-other-window}) -@kindex ESC C-v, in Info windows -@findex scroll-other-window -Scrolls the other window, in the same fashion that @samp{C-v} might -scroll the current window. Given a negative argument, the "other" -window is scrolled backward. - -@item @code{C-x ^} (@code{grow-window}) -@kindex C-x ^ -@findex grow-window -Grows (or shrinks) the current window. Given a numeric argument, grows -the current window that many lines; with a negative numeric argument, -the window is shrunk instead. - -@item @code{C-x t} (@code{tile-windows}) -@cindex tiling -@kindex C-x t -@findex tile-windows -Divides the available screen space among all of the visible windows. -Each window is given an equal portion of the screen in which to display -its contents. The variable @code{automatic-tiling} can cause -@code{tile-windows} to be called when a window is created or deleted. -@xref{Variables, , @code{automatic-tiling}}. -@end table - -@node The Echo Area -@section The Echo Area -@cindex echo area - -The @dfn{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: - -@table @asis -@item @code{C-f} (@code{echo-area-forward}) -@kindex C-f, in the echo area -@findex echo-area-forward -Moves forward a character. - -@item @code{C-b} (@code{echo-area-backward}) -@kindex C-b, in the echo area -@findex echo-area-backward -Moves backward a character. - -@item @code{C-a} (@code{echo-area-beg-of-line}) -@kindex C-a, in the echo area -@findex echo-area-beg-of-line -Moves to the start of the input line. - -@item @code{C-e} (@code{echo-area-end-of-line}) -@kindex C-e, in the echo area -@findex echo-area-end-of-line -Moves to the end of the input line. - -@item @code{M-f} (@code{echo-area-forward-word}) -@kindex M-f, in the echo area -@findex echo-area-forward-word -Moves forward a word. - -@item @code{M-b} (@code{echo-area-backward-word}) -@kindex M-b, in the echo area -@findex echo-area-backward-word -Moves backward a word. - -@item @code{C-d} (@code{echo-area-delete}) -@kindex C-d, in the echo area -@findex echo-area-delete -Deletes the character under the cursor. - -@item @code{DEL} (@code{echo-area-rubout}) -@kindex DEL, in the echo area -@findex echo-area-rubout -Deletes the character behind the cursor. - -@item @code{C-g} (@code{echo-area-abort}) -@kindex C-g, in the echo area -@findex echo-area-abort -Cancels or quits the current operation. If completion is being read, -@samp{C-g} discards the text of the input line which does not match any -completion. If the input line is empty, @samp{C-g} aborts the calling -function. - -@item @code{RET} (@code{echo-area-newline}) -@kindex RET, in the echo area -@findex echo-area-newline -Accepts (or forces completion of) the current input line. - -@item @code{C-q} (@code{echo-area-quoted-insert}) -@kindex C-q, in the echo area -@findex echo-area-quoted-insert -Inserts the next character verbatim. This is how you can insert control -characters into a search string, for example. - -@item @var{printing character} (@code{echo-area-insert}) -@kindex printing characters, in the echo area -@findex echo-area-insert -Inserts the character. - -@item @code{M-TAB} (@code{echo-area-tab-insert}) -@kindex M-TAB, in the echo area -@findex echo-area-tab-insert -Inserts a TAB character. - -@item @code{C-t} (@code{echo-area-transpose-chars}) -@kindex C-t, in the echo area -@findex echo-area-transpose-chars -Transposes the characters at the cursor. -@end table - -The next group of commands deal with @dfn{killing}, and @dfn{yanking} -text. For an in depth discussion of killing and yanking, -@pxref{Killing, , Killing and Deleting, emacs, the GNU Emacs Manual} - -@table @asis -@item @code{M-d} (@code{echo-area-kill-word}) -@kindex M-d, in the echo area -@findex echo-area-kill-word -Kills the word following the cursor. - -@item @code{M-DEL} (@code{echo-area-backward-kill-word}) -@kindex M-DEL, in the echo area -@findex echo-area-backward-kill-word -Kills the word preceding the cursor. - -@item @code{C-k} (@code{echo-area-kill-line}) -@kindex C-k, in the echo area -@findex echo-area-kill-line -Kills the text from the cursor to the end of the line. - -@item @code{C-x DEL} (@code{echo-area-backward-kill-line}) -@kindex C-x DEL, in the echo area -@findex echo-area-backward-kill-line -Kills the text from the cursor to the beginning of the line. - -@item @code{C-y} (@code{echo-area-yank}) -@kindex C-y, in the echo area -@findex echo-area-yank -Yanks back the contents of the last kill. - -@item @code{M-y} (@code{echo-area-yank-pop}) -@kindex M-y, in the echo area -@findex echo-area-yank-pop -Yanks back a previous kill, removing the last yanked text first. -@end table - -Sometimes when reading input in the echo area, the command that needed -input will only accept one of a list of several choices. The choices -represent the @dfn{possible completions}, and you must respond with one -of them. Since there are a limited number of responses you can make, -Info allows you to abbreviate what you type, only typing as much of the -response as is necessary to uniquely identify it. In addition, you can -request Info to fill in as much of the response as is possible; this -is called @dfn{completion}. - -The following commands are available when completing in the echo area: - -@table @asis -@item @code{TAB} (@code{echo-area-complete}) -@itemx @code{SPC} -@kindex TAB, in the echo area -@kindex SPC, in the echo area -@findex echo-area-complete -Inserts as much of a completion as is possible. - -@item @code{?} (@code{echo-area-possible-completions}) -@kindex ?, in the echo area -@findex echo-area-possible-completions -Displays a window containing a list of the possible completions of what -you have typed so far. For example, if the available choices are: -@example -bar -foliate -food -forget -@end example -and you have typed an @samp{f}, followed by @samp{?}, the possible -completions would contain: -@example -foliate -food -forget -@end example -i.e., all of the choices which begin with @samp{f}. Pressing @key{SPC} -or @key{TAB} would result in @samp{fo} appearing in the echo area, since -all of the choices which begin with @samp{f} continue with @samp{o}. -Now, typing @samp{l} followed by @samp{TAB} results in @samp{foliate} -appearing in the echo area, since that is the only choice which begins -with @samp{fol}. - -@item @code{ESC C-v} (@code{echo-area-scroll-completions-window}) -@kindex ESC C-v, in the echo area -@findex echo-area-scroll-completions-window -Scrolls the completions window, if that is visible, or the "other" -window if not. -@end table - -@node Printing Nodes -@chapter Printing Out Nodes -@cindex printing - -You may wish to print out the contents of a node as a quick reference -document for later use. Info provides you with a command for doing -this. In general, we recommend that you use @TeX{} to format the -document and print sections of it, by running @code{tex} on the texinfo -source file. - -@table @asis -@item @code{M-x print-node} -@findex print-node -@cindex INFO_PRINT_COMMAND, environment variable -Pipes the contents of the current node through the command in the -environment variable @code{INFO_PRINT_COMMAND}. If the variable doesn't -exist, the node is simply piped to @code{lpr}. -@end table - -@node Miscellaneous Commands -@chapter Miscellaneous Commands - -GNU Info contains several commands which self-document GNU Info: - -@table @asis -@item @code{M-x describe-command} -@cindex functions, describing -@cindex commands, describing -@findex describe-command -Reads the name of an Info command in the echo area and then displays a -brief description of what that command does. - -@item @code{M-x describe-key} -@cindex keys, describing -@findex describe-key -Reads a key sequence in the echo area, and then displays the name and -documentation of the Info command that the key sequence invokes. - -@item @code{M-x describe-variable} -Reads the name of a variable in the echo area and then displays a brief -description of what the variable affects. - -@item @code{M-x where-is} -@findex where-is -Reads the name of an Info command in the echo area, and then displays -a key sequence which can be typed in order to invoke that command. - -@item @code{C-h} (@code{get-help-window}) -@itemx @code{?} -@kindex C-h -@kindex ?, in Info windows -@findex get-help-window -Creates (or moves into) the window displaying @code{*Help*}, and places -a node containing a quick reference card into it. This window displays -the most concise information about GNU Info available. - -@item @code{h} (@code{get-info-help-node}) -@kindex h -@findex get-info-help-node -Tries hard to visit the node @code{(info)Help}. The info file -@file{info.texi} distributed with GNU Info contains this node. Of -course, the file must first be processed with @code{makeinfo}, and then -placed into the location of your info directory. -@end table - -Here are the commands for creating a numeric argument: - -@table @asis -@item @code{C-u} (@code{universal-argument}) -@cindex numeric arguments -@kindex C-u -@findex universal-argument -Starts (or multiplies by 4) the current numeric argument. @samp{C-u} is -a good way to give a small numeric argument to cursor movement or -scrolling commands; @samp{C-u C-v} scrolls the screen 4 lines, while -@samp{C-u C-u C-n} moves the cursor down 16 lines. - -@item @code{M-1} (@code{add-digit-to-numeric-arg}) -@itemx @code{M-2} @dots{} @code{M-9} -@kindex M-1 @dots{} M-9 -@findex add-digit-to-numeric-arg -Adds the digit value of the invoking key to the current numeric -argument. Once Info is reading a numeric argument, you may just type -the digits of the argument, without the Meta prefix. For example, you -might give @samp{C-l} a numeric argument of 32 by typing: - -@example -@kbd{C-u 3 2 C-l} -@end example -or -@example -@kbd{M-3 2 C-l} -@end example -@end table - -@samp{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. - -@table @asis -@item @code{C-g} (@code{abort-key}) -@cindex cancelling typeahead -@cindex cancelling the current operation -@kindex C-g, in Info windows -@findex abort-key -Cancels current operation. -@end table - -The @samp{q} command of Info simply quits running Info. - -@table @asis -@item @code{q} (@code{quit}) -@cindex quitting -@kindex q -@findex quit -Exits GNU Info. -@end table - -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. - -@table @asis -@item @code{M-x set-screen-height} -@findex set-screen-height -@cindex screen, changing the height of -Reads a height value in the echo area and sets the height of the -displayed screen to that value. -@end table - -Finally, Info provides a convenient way to display footnotes which might -be associated with the current node that you are viewing: - -@table @asis -@item @code{ESC C-f} (@code{show-footnotes}) -@kindex ESC C-f -@findex show-footnotes -@cindex footnotes, displaying -Shows the footnotes (if any) associated with the current node in another -window. You can have Info automatically display the footnotes -associated with a node when the node is selected by setting the variable -@code{automatic-footnotes}. @xref{Variables, , @code{automatic-footnotes}}. -@end table - -@node Variables -@chapter Manipulating Variables - -GNU Info contains several @dfn{variables} whose values are looked at by various -Info commands. You can change the values of these variables, and thus -change the behaviour of Info to more closely match your environment and -info file reading manner. - -@table @asis -@item @code{M-x set-variable} -@cindex variables, setting -@findex set-variable -Reads the name of a variable, and the value for it, in the echo area and -then sets the variable to that value. Completion is available when -reading the variable name; often, completion is available when reading -the value to give to the variable, but that depends on the variable -itself. If a variable does @emph{not} supply multiple choices to -complete over, it expects a numeric value. - -@item @code{M-x describe-variable} -@cindex variables, describing -@findex describe-variable -Reads the name of a variable in the echo area and then displays a brief -description of what the variable affects. -@end table - -Here is a list of the variables that you can set in Info. - -@table @code -@item automatic-footnotes -@vindex automatic-footnotes -When set to @code{On}, footnotes appear and disappear automatically. -This variable is @code{On} by default. When a node is selected, a -window containing the footnotes which appear in that node is created, -and the footnotes are displayed within the new window. The window that -Info creates to contain the footnotes is called @samp{*Footnotes*}. If -a node is selected which contains no footnotes, and a @samp{*Footnotes*} -window is on the screen, the @samp{*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. - -@item automatic-tiling -@vindex automatic-tiling -When set to @code{On}, creating or deleting a window resizes other -windows. This variable is @code{Off} by default. Normally, typing -@samp{C-x 2} divides the current window into two equal parts. When -@code{automatic-tiling} is set to @code{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 @samp{*Completions*} and @samp{*Footnotes*} are @emph{not} -resized through automatic tiling; they remain their original size. - -@item visible-bell -@vindex visible-bell -When set to @code{On}, GNU Info attempts to flash the screen instead of -ringing the bell. This variable is @code{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 -@code{errors-ring-bell} variable to @code{Off}. - -@item errors-ring-bell -@vindex errors-ring-bell -When set to @code{On}, errors cause the bell to ring. The default -setting of this variable is @code{On}. - -@item gc-compressed-files -@vindex gc-compressed-files -When set to @code{On}, Info garbage collects files which had to be -uncompressed. The default value of this variable is @code{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. -@code{gc-compressed-files} tells Info it is okay to garbage collect the -text of the nodes of a file which was compressed on disk. - -@item show-index-match -@vindex show-index-match -When set to @code{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 @code{On}. -When Info displays the location where an index match was found, -(@pxref{Searching Commands, , @code{next-index-match}}), the portion of the -string that you had typed is highlighted by displaying it in the inverse -case from its surrounding characters. - -@item scroll-behaviour -@vindex scroll-behaviour -Controls what happens when forward scrolling is requested at the end of -a node, or when backward scrolling is requested at the beginning of a -node. The default value for this variable is @code{Continuous}. There -are three possible values for this variable: - -@table @code -@item Continuous -Tries to get the first item in this node's menu, or failing that, the -@samp{Next} node, or failing that, the @samp{Next} of the @samp{Up}. -This behaviour is identical to using the @samp{]} -(@code{global-next-node}) and @samp{[} (@code{global-prev-node}) -commands. - -@item Next Only -Only tries to get the @samp{Next} node. - -@item Page Only -Simply gives up, changing nothing. If @code{scroll-behaviour} is -@code{Page Only}, no scrolling command can change the node that is being -viewed. -@end table - -@item scroll-step -@vindex 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 @code{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. - -@item ISO-Latin -@cindex ISO Latin characters -@vindex ISO-Latin -When set to @code{On}, Info accepts and displays ISO Latin characters. -By default, Info assumes an ASCII character set. @code{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. -@end table - -@node Info for Sys Admins -@chapter Info for System Administrators - -This text describes some common ways of setting up an Info heierarchy -from scratch, and details the various options that are available when -installing Info. This text is designed for the person who is installing -GNU Info on the system; although users may find the information present -in this section interesting, none of it is vital to understanding how to -use GNU Info. - -@menu -* Setting the INFOPATH:: Where are my Info files kept? -* Editing the DIR node:: What goes in `DIR', and why? -* Storing Info files:: Alternate formats allow flexibilty in setups. -* Using `localdir':: Building DIR on the fly. -* Example setups:: Some common ways to origanize Info files. -@end menu - -@node Setting the INFOPATH -@section Setting the INFOPATH -Where are my Info files kept? - -@node Editing the DIR node -@section Editing the DIR node -What goes in `DIR', and why? - -@node Storing Info files -@section Storing Info files -Alternate formats allow flexibilty in setups. - -@node Using `localdir' -@section Using `localdir' -Building DIR on the fly. - -@node Example setups -@section Example setups -Some common ways to origanize Info files. - -@ifset STANDALONE -@node GNU Info Global Index -@appendix Global Index -@printindex cp -@end ifset diff --git a/gnu/usr.bin/texinfo/info-files/texi.info b/gnu/usr.bin/texinfo/info-files/texi.info deleted file mode 100644 index cd677e8..0000000 --- a/gnu/usr.bin/texinfo/info-files/texi.info +++ /dev/null @@ -1,297 +0,0 @@ -This is Info file texi.info, produced by Makeinfo-1.55 from the input -file texi.texi. - - This file documents Texinfo, a documentation system that uses a -single source file to produce both on-line information and a printed -manual. - - Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation, -Inc. - - This is the second edition of the Texinfo documentation, -and is consistent with version 2 of `texinfo.tex'. - - 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 Free Software Foundation. - - -Indirect: -texi.info-1: 1096 -texi.info-2: 50585 -texi.info-3: 100344 -texi.info-4: 149083 -texi.info-5: 197497 -texi.info-6: 247275 -texi.info-7: 296490 -texi.info-8: 346023 -texi.info-9: 387598 -texi.info-10: 433598 -texi.info-11: 476101 - -Tag Table: -(Indirect) -Node: Top1096 -Node: Copying21758 -Node: Overview23766 -Node: Using Texinfo25673 -Node: Info Files28165 -Node: Printed Books32225 -Node: Formatting Commands35110 -Node: Conventions38551 -Node: Comments40811 -Node: Minimum42233 -Node: Six Parts44386 -Node: Short Sample45896 -Node: Acknowledgements50027 -Node: Texinfo Mode50585 -Node: Texinfo Mode Overview51956 -Node: Emacs Editing52709 -Node: Inserting54839 -Node: Showing the Structure59115 -Node: Updating Nodes and Menus61634 -Node: Updating Commands62706 -Node: Updating Requirements68741 -Node: Other Updating Commands71042 -Node: Info Formatting74311 -Node: Printing75635 -Node: Texinfo Mode Summary77399 -Node: Beginning a File82167 -Node: Four Parts83056 -Node: Sample Beginning84502 -Node: Header86125 -Node: First Line87476 -Node: Start of Header88448 -Node: setfilename89163 -Node: settitle90763 -Node: setchapternewpage92646 -Node: paragraphindent95412 -Node: End of Header96877 -Node: Info Summary and Permissions97717 -Node: Titlepage & Copyright Page98738 -Node: titlepage100344 -Node: titlefont center sp102665 -Node: title subtitle author103895 -Node: Copyright & Permissions106171 -Node: end titlepage108176 -Node: headings on off109881 -Node: The Top Node111707 -Node: Title of Top Node112862 -Node: Master Menu Parts114099 -Node: Software Copying Permissions116150 -Node: Ending a File117318 -Node: Printing Indices & Menus118165 -Node: Contents120448 -Node: File End122790 -Node: Structuring123462 -Node: Tree Structuring125043 -Node: Structuring Command Types126467 -Node: makeinfo top128792 -Node: chapter129323 -Node: unnumbered & appendix130147 -Node: majorheading & chapheading130986 -Node: section131808 -Node: unnumberedsec appendixsec heading132573 -Node: subsection133560 -Node: unnumberedsubsec appendixsubsec subheading134131 -Node: subsubsection135083 -Node: Nodes136603 -Node: Two Paths137538 -Node: Node Menu Illustration138810 -Node: node142510 -Node: Node Names145206 -Node: Writing a Node146271 -Node: Node Line Tips148291 -Node: Node Line Requirements149083 -Node: First Node150691 -Node: makeinfo top command151811 -Node: Top Node Summary153591 -Node: makeinfo Pointer Creation154728 -Node: Menus155977 -Node: Menu Location157220 -Node: Writing a Menu158884 -Node: Menu Parts159850 -Node: Less Cluttered Menu Entry160848 -Node: Menu Example161473 -Node: Other Info Files162995 -Node: Cross References164855 -Node: References165734 -Node: Cross Reference Commands167458 -Node: Cross Reference Parts168509 -Node: xref171238 -Node: Reference Syntax172035 -Node: One Argument173679 -Node: Two Arguments174690 -Node: Three Arguments175804 -Node: Four and Five Arguments178189 -Node: Top Node Naming180602 -Node: ref181610 -Node: pxref182998 -Node: inforef185382 -Node: Marking Text186662 -Node: Indicating187283 -Node: Useful Highlighting189014 -Node: code190199 -Node: kbd193243 -Node: key194431 -Node: samp195985 -Node: var197497 -Node: file199287 -Node: dfn199893 -Node: cite200802 -Node: Emphasis201243 -Node: emph & strong202071 -Node: Smallcaps203041 -Node: Fonts204371 -Node: Quotations and Examples205427 -Node: Block Enclosing Commands207048 -Node: quotation209043 -Node: example210132 -Node: noindent212190 -Node: Lisp Example213657 -Node: smallexample & smalllisp214488 -Node: display216516 -Node: format217146 -Node: exdent217605 -Node: flushleft & flushright218684 -Node: cartouche219946 -Node: Lists and Tables220716 -Node: Introducing Lists221311 -Node: itemize222953 -Node: enumerate225104 -Node: Two-column Tables227594 -Node: table228287 -Node: ftable vtable230601 -Node: itemx231644 -Node: Indices232604 -Node: Index Entries233753 -Node: Predefined Indices234870 -Node: Indexing Commands235865 -Node: Combining Indices239873 -Node: syncodeindex241235 -Node: synindex242874 -Node: New Indices243398 -Node: Insertions245227 -Node: Braces Atsigns Periods245985 -Node: Inserting An Atsign247275 -Node: Inserting Braces247533 -Node: Controlling Spacing247932 -Node: dmn249490 -Node: Dots Bullets250719 -Node: dots251525 -Node: bullet251920 -Node: TeX and copyright252297 -Node: tex252861 -Node: copyright symbol253233 -Node: minus253479 -Node: Glyphs254350 -Node: Glyphs Summary255461 -Node: result255973 -Node: expansion256430 -Node: Print Glyph257352 -Node: Error Glyph258203 -Node: Equivalence259021 -Node: Point Glyph259683 -Node: Breaks261206 -Node: Break Commands262558 -Node: Line Breaks263246 -Node: w264248 -Node: sp265066 -Node: page265474 -Node: group265851 -Node: need267596 -Node: Definition Commands268326 -Node: Def Cmd Template269897 -Node: Optional Arguments272807 -Node: deffnx274396 -Node: Def Cmds in Detail275352 -Node: Functions Commands276462 -Node: Variables Commands279391 -Node: Typed Functions281340 -Node: Typed Variables284875 -Node: Abstract Objects286856 -Node: Data Types291752 -Node: Def Cmd Conventions293005 -Node: Sample Function Definition293566 -Node: Footnotes296490 -Node: Conditionals300343 -Node: Conditional Commands301099 -Node: Using Ordinary TeX Commands302508 -Node: set clear value303956 -Node: ifset ifclear304761 -Node: value307921 -Node: value Example309339 -Node: Format/Print Hardcopy310917 -Node: Use TeX312719 -Node: Shell Format & Print313310 -Node: Within Emacs317908 -Node: Texinfo Mode Printing318896 -Node: Compile-Command322646 -Node: Requirements Summary323554 -Node: Preparing for TeX324974 -Node: Overfull hboxes326989 -Node: smallbook328549 -Node: A4 Paper329782 -Node: Cropmarks and Magnification330484 -Node: Create an Info File332460 -Node: makeinfo advantages333764 -Node: Invoking makeinfo334651 -Node: makeinfo options335363 -Node: Pointer Validation340823 -Node: makeinfo in Emacs342207 -Node: texinfo-format commands344752 -Node: Batch Formatting346023 -Node: Tag and Split Files347269 -Node: Install an Info File350626 -Node: Directory file351276 -Node: New Info File352956 -Node: Other Info Directories354095 -Node: Command List355961 -Node: Tips387598 -Node: Sample Texinfo File399031 -Node: Sample Permissions401147 -Node: Inserting Permissions402188 -Node: ifinfo Permissions404469 -Node: Titlepage Permissions406088 -Node: Include Files407348 -Node: Using Include Files408434 -Node: texinfo-multiple-files-update410368 -Node: Include File Requirements412759 -Node: Sample Include File414004 -Node: Include Files Evolution415532 -Node: Headings417509 -Node: Headings Introduced418144 -Node: Heading Format420033 -Node: Heading Choice422489 -Node: Custom Headings423860 -Node: Catching Mistakes428069 -Node: makeinfo preferred429359 -Node: Debugging with Info430260 -Node: Debugging with TeX433598 -Node: Using texinfo-show-structure437940 -Node: Using occur441040 -Node: Running Info-Validate442579 -Node: Using Info-validate443639 -Node: Unsplit445454 -Node: Tagifying446502 -Node: Splitting447361 -Node: Refilling Paragraphs448981 -Node: Command Syntax450800 -Node: Obtaining TeX453731 -Node: New Features454842 -Node: New Texinfo Mode Commands455424 -Node: New Commands458894 -Node: Command and Variable Index463543 -Node: Concept Index476101 - -End Tag Table diff --git a/gnu/usr.bin/texinfo/info-files/texi.info-1 b/gnu/usr.bin/texinfo/info-files/texi.info-1 deleted file mode 100644 index 28b4895..0000000 --- a/gnu/usr.bin/texinfo/info-files/texi.info-1 +++ /dev/null @@ -1,1131 +0,0 @@ -This is Info file texi.info, produced by Makeinfo-1.55 from the input -file texi.texi. - - This file documents Texinfo, a documentation system that uses a -single source file to produce both on-line information and a printed -manual. - - Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation, -Inc. - - This is the second edition of the Texinfo documentation, -and is consistent with version 2 of `texinfo.tex'. - - 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 Free Software Foundation. - - -File: texi.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir) - -Texinfo -******* - - Texinfo is a documentation system that uses a single source file to -produce both on-line information and printed output. - - 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. - - This is Edition 2.18 of the Texinfo documentation, 26 March 1993, -for Texinfo Version 2. - -* Menu: - -* Copying:: Your rights. -* Overview:: Texinfo in brief. -* Texinfo Mode:: How to use 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:: How to create chapters, sections, subsections, - appendices, and other parts. -* Nodes:: How to write nodes. -* Menus:: How to write menus. -* Cross References:: How to write cross references. -* Marking Text:: How to mark words and phrases as code, - keyboard input, meta-syntactic - variables, and the like. -* Quotations and Examples:: How to write quotations, examples, etc. -* Lists and Tables:: How to write lists and tables. -* Indices:: How to create indices. -* Insertions:: How to insert @-signs, braces, etc. -* Glyphs:: How to indicate results of evaluation, - expansion of macros, errors, etc. -* Breaks:: How to force and prevent line and page breaks. -* Definition Commands:: How to describe functions and the like - in a uniform manner. -* Footnotes:: How to write footnotes. -* Conditionals:: How to specify text for either TeX or Info. -* Format/Print Hardcopy:: How to convert a Texinfo file to a file - for printing and how to print that file. -* Create an Info File:: Convert a Texinfo file into an Info file. -* Install an Info File:: Make an Info file accessible to users. -* Command List:: All the Texinfo @-commands. -* Tips:: Hints on how to write a Texinfo document. -* Sample Texinfo File:: A sample Texinfo file to look at. -* Sample Permissions:: Tell readers they have the right to copy - and distribute. -* Include Files:: How to incorporate other Texinfo files. -* Headings:: How to write page headings and footings. -* Catching Mistakes:: How to find formatting mistakes. -* Refilling Paragraphs:: All about paragraph refilling. -* Command Syntax:: A description of @-Command syntax. -* Obtaining TeX:: How to Obtain TeX. -* New Features:: Texinfo second edition features. -* Command and Variable Index:: A menu containing commands and variables. -* Concept Index:: A menu covering many topics. - - -- The Detailed Node Listing -- - -Overview of Texinfo - -* Using Texinfo:: Create a conventional printed book - or an Info file. -* 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:: How to write comments and mark regions that - the formatting commands will ignore. -* Minimum:: What a Texinfo file must have. -* Six Parts:: Usually, a Texinfo file has six parts. -* Short Sample:: A short sample Texinfo file. -* Acknowledgements:: - -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 - -* Four Parts:: Four parts begin a Texinfo file. -* Sample Beginning:: Here is a sample beginning for a Texinfo file. -* Header:: The very beginning of a Texinfo file. -* Info Summary and Permissions:: Summary and copying permissions for Info. -* Titlepage & Copyright Page:: Creating the title and copyright pages. -* The Top Node:: Creating the `Top' node and master menu. -* Software Copying Permissions:: Ensure that you and others continue to - have the right to use and share software. - -The 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. -* setchapternewpage:: Start chapters on right-hand pages. -* paragraphindent:: An option to specify paragraph indentation. -* End of Header:: Formatting a region requires this. - -The 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 & Permissions:: 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 - -* Title of Top Node:: Sketch what the file is about. -* Master Menu Parts:: A master menu has three or more parts. - -Ending a Texinfo File - -* Printing Indices & Menus:: How to print an index in hardcopy and - generate index menus in Info. -* Contents:: How to create a table of contents. -* 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. - -Nodes - -* Two Paths:: Different commands to structure - Info output and printed output. -* Node Menu Illustration:: A diagram, and sample nodes and menus. -* node:: How to write a node, in detail. -* makeinfo Pointer Creation:: How to create node pointers with `makeinfo'. - -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. -* Top Node Summary:: Write a brief description for readers. - -Menus - -* Menu Location:: Put a menu in a short node. -* 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. - -`@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:: How to indicate code. -* kbd:: How to show keyboard input. -* key:: How to specify keys. -* samp:: How to show a literal sequence of characters. -* var:: How to indicate a metasyntactic variable. -* file:: How to indicate the name of a file. -* dfn:: How to specify a definition. -* cite:: How to refer to a book that is not in Info. - -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:: Use different constructs for - different purposes. -* quotation:: How to write a quotation. -* example:: How to write an example in a fixed-width font. -* noindent:: How to prevent paragraph indentation. -* Lisp Example:: How to illustrate Lisp code. -* smallexample & smalllisp:: Forms for the `@smallbook' option. -* display:: How to write an example in the current font. -* format:: How to write an example that does not narrow - the margins. -* exdent:: How to undo the indentation of a line. -* flushleft & flushright:: How to push text flushleft or flushright. -* cartouche:: How to draw cartouches around examples. - -Making 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. - -Making a Two-column Table - -* table:: How to construct a two-column table. -* ftable vtable:: How to construct a two-column table - with automatic indexing. -* itemx:: How to put more entries in the first column. - -Creating Indices - -* Index Entries:: Choose different words for index entries. -* Predefined Indices:: Use different indices for different kinds - of entry. -* 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 - -* Braces Atsigns Periods:: How to insert braces, `@' and periods. -* dmn:: How to format a dimension. -* Dots Bullets:: How to insert dots and bullets. -* TeX and copyright:: How to insert the TeX logo - and the copyright symbol. -* minus:: How to insert a minus sign. - -Inserting `@', Braces, and Periods - -* Inserting An Atsign:: -* Inserting Braces:: How to insert `{' and `}' -* Controlling Spacing:: How to insert the right amount of space - after punctuation within a sentence. - -Inserting Ellipsis, Dots, and Bullets - -* dots:: How to insert dots ... -* bullet:: How to insert a bullet. - -Inserting TeX and the Copyright Symbol - -* tex:: How to insert the TeX logo. -* copyright symbol:: How to use `@copyright'{}. - -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. - -Making and Preventing Breaks - -* Break Commands:: Cause and prevent splits. -* Line Breaks:: How to force a single line to use two lines. -* w:: How to prevent unwanted line breaks. -* sp:: How to insert blank lines. -* page:: How to force the start of a new page. -* group:: How to prevent unwanted page breaks. -* need:: Another way to prevent unwanted page breaks. - -Definition Commands - -* Def Cmd Template:: How to structure a description using a - definition command. -* Optional Arguments:: How to handle optional and repeated arguments. -* deffnx:: How to group two or more `first' lines. -* Def Cmds in Detail:: All the definition commands. -* Def Cmd Conventions:: Conventions for writing definitions. -* Sample Function Definition:: - -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. -* Abstract Objects:: Commands for object-oriented programming. -* Data Types:: The definition command for data types. - -Conditionally Visible Text - -* Conditional Commands:: How to specify text for Info or TeX. -* Using Ordinary TeX Commands:: You can use any and all TeX commands. -* set clear value:: How to designate which text to format (for - both Info and TeX); and how to set a - flag to a string that you can insert. - -`@set', `@clear', and `@value' - -* ifset ifclear:: Format a region if a flag is set. -* value:: Replace a flag with a string. -* value Example:: An easy way to update edition information. - -Format and Print Hardcopy - -* Use TeX:: Use TeX to format for hardcopy. -* Shell Format & Print:: How to format and print a hardcopy manual - with shell commands. -* 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 you need to do to 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 European A4 paper. -* Cropmarks and Magnification:: How to print marks to indicate the size - of pages and how to print scaled up output. - -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. - -Sample Permissions - -* Inserting Permissions:: How to put permissions in your document. -* ifinfo Permissions:: Sample `ifinfo' copying permissions. -* Titlepage Permissions:: Sample Titlepage copying permissions. - -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 File Requirements:: What `texinfo-multiple-files-update' expects. -* 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. - -Second Edition Features - -* New Texinfo Mode Commands:: The updating commands are especially useful. -* New Commands:: Many newly described @-commands. - - -File: texi.info, Node: Copying, Next: Overview, Prev: Top, Up: Top - -Texinfo Copying Conditions -************************** - - The programs currently being distributed that relate to Texinfo -include portions of GNU Emacs, plus other separate programs (including -`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. - - -File: texi.info, Node: Overview, Next: Texinfo Mode, Prev: Copying, Up: Top - -Overview of Texinfo -******************* - - "Texinfo"(1) is a documentation system that uses a single source -file to produce both on-line information and printed output. This -means that instead of writing two different documents, one for the -on-line help or other on-line information and the other for a typeset -manual or other printed work, you need write only one document. When -the work is revised, you need revise only one document. (You can read -the on-line information, known as an "Info file", with an Info -documentation-reading program.) - -* Menu: - -* Using Texinfo:: Create a conventional printed book - or an Info file. -* 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:: How to write comments and mark regions that - the formatting commands will ignore. -* Minimum:: What a Texinfo file must have. -* Six Parts:: Usually, a Texinfo file has six parts. -* Short Sample:: A short sample Texinfo file. -* Acknowledgements:: - - ---------- Footnotes ---------- - - (1) Note that 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 write the other letters in lower case. - - -File: texi.info, Node: Using Texinfo, Next: Info Files, Up: Overview - -Using Texinfo -============= - - Using Texinfo, you can create a printed document with the normal -features of a book, including chapters, sections, cross references, and -indices. From the same Texinfo source file, you can create a -menu-driven, on-line Info file with nodes, menus, cross references, and -indices. You can, if you wish, make the chapters and sections of the -printed document correspond to the nodes of the on-line information; -and you use the same cross references and indices for both the Info -file and the printed work. `The GNU Emacs Manual' is a good example of -a Texinfo file, as is this manual. - - To make a printed document, you process a Texinfo source file with -the TeX typesetting program. This creates a DVI file that you can -typeset and print as a book or report. (Note that the Texinfo language -is completely different from TeX's usual language, PlainTeX, which -Texinfo replaces.) If you do not have TeX, but do have `troff' or -`nroff', you can use the `texi2roff' program instead. - - To make an Info file, you process a Texinfo source file with the -`makeinfo' utility or Emacs's `texinfo-format-buffer' command; this -creates an Info file that you can install on-line. - - TeX and `texi2roff' work with many types of printer; similarly, Info -works with almost every type of computer terminal. This power makes -Texinfo a general purpose system, but brings with it a constraint, -which is that a Texinfo file may contain only the customary -"typewriter" characters (letters, numbers, spaces, and punctuation -marks) but no special graphics. - - A Texinfo file is a plain ASCII file containing text and -"@-commands" (words preceded by an `@') that tell the typesetting and -formatting programs what to do. You may 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::.) - - Before writing a Texinfo source file, you should become familiar with -the Info documentation reading program and learn about nodes, menus, -cross references, and the rest. (*note info: (info)Top, for more -information.) - - You can use Texinfo to create both on-line help and printed manuals; -moreover, Texinfo is freely redistributable. For these reasons, Texinfo -is the format in which documentation for GNU utilities and libraries is -written. - - -File: texi.info, Node: Info Files, Next: Printed Books, Prev: Using Texinfo, Up: Overview - -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 info: (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 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 called `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. - - If you want to read through an Info file in sequence, as if it were a -printed manual, you can get the whole file with the advanced Info -command `g* RET'. (*note Advanced Info commands: (info)Expert.) - - 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. - - ---------- 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: texi.info, Node: Printed Books, Next: Formatting Commands, Prev: Info Files, Up: Overview - -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 on-line 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 called `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. - - Most often, documents are 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 -European A4 size paper (`@afourpaper'). (*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 dialect 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. - - *Note How to Obtain TeX: Obtaining TeX. - - ---------- Footnotes ---------- - - (1) You can also use the `texi2roff' program if you do not have -TeX; since Texinfo is designed for use with TeX, `texi2roff' is not -described here. `texi2roff' is part of the standard GNU distribution. - - -File: texi.info, Node: Formatting Commands, Next: Conventions, Prev: Printed Books, Up: Overview - -@-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. - - *Please note:* All the @-commands, with the exception of the - `@TeX{}' command, must be written entirely in 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 `@noindent' at the beginning of a line as - the only text on the line. (`@noindent' prevents the beginning of - the next line from being indented as the beginning of a paragraph.) - - * 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 dots ...) - - * 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' at the beginning of a line of - its own; write the body-text on following lines; and write the - matching `@end' command, `@end example' in this case, at the - beginning of a line of its own after the body-text. (`@example' - ... `@end example' indents and typesets body-text as an example.) - -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 make -it easier to write and read Texinfo files than if all commands followed -exactly the same syntax. (For details about @-command syntax, see -*Note @-Command Syntax: Command Syntax.) - - ---------- Footnotes ---------- - - (1) The word "argument" comes from the way it is used in -mathematics and does not refer to a disputation 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 disputation. - - -File: texi.info, Node: Conventions, Next: Comments, Prev: Formatting Commands, Up: Overview - -General Syntactic Conventions -============================= - - All ASCII printing characters except `@', `{' and `}' can appear in -a Texinfo file and stand for themselves. `@' is the escape character -which introduces commands. `{' and `}' should be used only 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 `@}'. - - It is customary in TeX to use doubled single-quote characters to -begin and end quotations: ` ` and ' ' (but without a space between the -two single-quote characters). This convention should be followed in -Texinfo files. TeX converts doubled single-quote characters to left- -and right-hand doubled quotation marks and Info converts doubled -single-quote characters to ASCII double-quotes: ` ` and ' ' to " . - - Use three hyphens in a row, `---', for a dash--like this. In TeX, a -single or even a double hyphen produces a printed dash that is shorter -than the usual typeset dash. Info reduces three hyphens to two for -display on the screen. - - To prevent a paragraph from being indented in the printed manual, put -the command `@noindent' on a line by itself before the paragraph. - - If you mark off a region of the Texinfo file with the `@iftex' and -`@end iftex' commands, that region will appear only in the printed -copy; in that region, you can use certain commands borrowed from -PlainTeX that you cannot use in Info. Likewise, if you mark off a -region with the `@ifinfo' and `@end ifinfo' commands, that region will -appear only in the Info file; in that region, you can use Info commands -that you cannot use in TeX. (*Note Conditionals::.) - - *Caution:* Do not use tabs in a Texinfo file! TeX uses - variable-width fonts, which means that it cannot predefine a tab - to work in all circumstances. Consequently, TeX treats tabs like - single spaces, and that is not what they look like. - - To avoid this problem, Texinfo mode causes GNU Emacs to insert - multiple spaces when you press the TAB key. - - Also, you can run `untabify' in Emacs to convert tabs in a region - to multiple spaces. - - -File: texi.info, Node: Comments, Next: Minimum, Prev: Conventions, Up: Overview - -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 reads 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. Often, `@ignore' and -`@end ignore' is used to enclose a part of the copying permissions that -applies to the Texinfo source file of a document, but not to the Info -or printed version of the document. - - -File: texi.info, Node: Minimum, Next: Six Parts, Prev: Comments, Up: Overview - -What a Texinfo File Must Have -============================= - - By convention, the names of Texinfo files end with one of the -extensions `.texinfo', `.texi', or `.tex'. The longer extension is -preferred since it describes 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 - -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 the `@settitle' line specifies a title for the page headers (or -footers) of the printed manual. - - 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. - - Usually, 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::, for more information.) - - Furthermore, you will usually provide a Texinfo file with a title -page, indices, and the like. 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: texi.info, Node: Six Parts, Next: Short Sample, Prev: Minimum, Up: Overview - -Six Parts of a Texinfo File -=========================== - - Generally, a Texinfo file contains more than the minimal beginning -and end--it usually contains six parts: - -1. Header - The "Header" names the file, tells TeX which definitions' file to - use, and performs other "housekeeping" tasks. - -2. Summary Description and Copyright - The "Summary Description and Copyright" segment describes the - document and contains the copyright notice and copying permissions - for the Info file. The segment must be enclosed between `@ifinfo' - and `@end ifinfo' commands so that the formatters place it only in - the Info file. - -3. Title and Copyright - The "Title and Copyright" segment contains the title and copyright - pages and copying permissions 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 "Master Menu" contains a complete menu of all the nodes in the - whole Info file. It appears only in the Info file, in the `Top' - node. - -5. Body - The "Body" of the document may be structured like a traditional - book or encyclopedia or it may be free form. - -6. End - The "End" contains commands for printing indices and generating - the table of contents, and the `@bye' command on a line of its own. - - -File: texi.info, Node: Short Sample, Next: Acknowledgements, Prev: Six Parts, Up: Overview - -A Short Sample Texinfo File -=========================== - - Here is a complete but very short Texinfo file, in 6 parts. 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 you write a manual, simply insert the -names for your own manual in this segment. (*Note Beginning a File::.) - -In the following, the sample text is *indented*; comments on it are -not. The complete file, without any comments, is shown in *Note 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 Document - @c %**end of header - - @setchapternewpage odd - -Part 2: Summary Description and Copyright ------------------------------------------ - -The summary description and copyright segment does not -appear in the printed document. - - @ifinfo - This is a short example of a complete Texinfo file. - - Copyright @copyright{} 1990 Free Software Foundation, Inc. - @end ifinfo - -Part 3: Titlepage and Copyright -------------------------------- - -The titlepage segment does not appear in the Info file. - - @titlepage - @sp 10 - @comment The title is printed in a large font. - @center @titlefont{Sample Title} - - @c The following two commands start the copyright page. - @page - @vskip 0pt plus 1filll - Copyright @copyright{} 1990 Free Software Foundation, Inc. - @end titlepage - -Part 4: `Top' Node and Master Menu ----------------------------------- - -The `Top' node contains the master menu for the Info file. -Since a printed manual uses a table of contents rather than -a menu, the master menu appears only in the Info file. - - @node Top, First Chapter, (dir), (dir) - @comment node-name, next, previous, up - - @menu - * First Chapter:: The first chapter is the - only chapter in this sample. - * Concept Index:: This index has two entries. - @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, Concept Index, Top, Top - @comment node-name, next, previous, up - @chapter First Chapter - @cindex Sample index entry - - This is the contents of the first chapter. - @cindex Another sample index entry - - Here is a numbered list. - - @enumerate - @item - This is the first item. - - @item - This is the second item. - @end enumerate - - The @code{makeinfo} and @code{texinfo-format-buffer} - commands transform a Texinfo file such as this into - an Info file; and @TeX{} typesets it for a printed - manual. - -Part 6: The End of the Document -------------------------------- - -The end segment contains commands both for generating an index in a node -and unnumbered chapter of its own and for generating the table of -contents; and it contains the `@bye' command that marks the end of the -document. - - @node Concept Index, , First Chapter, Top - @comment node-name, next, previous, up - @unnumbered Concept Index - - @printindex cp - - @contents - @bye - -The Results ------------ - - Here is what the contents of the first chapter of the sample look -like: - - This is the contents of the first chapter. - - Here is a numbered list. - - 1. This is the first item. - - 2. This is the second item. - - The `makeinfo' and `texinfo-format-buffer' commands transform a - Texinfo file such as this into an Info file; and TeX typesets it - for a printed manual. - - -File: texi.info, Node: Acknowledgements, Prev: Short Sample, Up: Overview - -Acknowledgements -================ - - Richard M. Stallman wrote Edition 1.0 of this manual. -Robert J. Chassell revised and extended it, starting with Edition 1.1. - - Our thanks go out to all who helped improve this work, particularly -to Francois Pinard and David D. Zuhn, who tirelessly recorded and -reported mistakes and obscurities; our special thanks go to -Melissa Weisshaus for her frequent and often tedious reviews of nearly -similar editions. Our mistakes are our own. - diff --git a/gnu/usr.bin/texinfo/info-files/texi.info-10 b/gnu/usr.bin/texinfo/info-files/texi.info-10 deleted file mode 100644 index f28ff2e..0000000 --- a/gnu/usr.bin/texinfo/info-files/texi.info-10 +++ /dev/null @@ -1,1165 +0,0 @@ -This is Info file texi.info, produced by Makeinfo-1.55 from the input -file texi.texi. - - This file documents Texinfo, a documentation system that uses a -single source file to produce both on-line information and a printed -manual. - - Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation, -Inc. - - This is the second edition of the Texinfo documentation, -and is consistent with version 2 of `texinfo.tex'. - - 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 Free Software Foundation. - - -File: texi.info, Node: Debugging with TeX, Next: Using texinfo-show-structure, Prev: Debugging with Info, Up: Catching Mistakes - -Catching Errors with TeX Formatting -=================================== - - You can also catch mistakes when you format a file with TeX. - - Usually, you 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: *texinfo-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: *texinfo-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-d' (or `C-c C-d', if you are running a shell inside Emacs - Version 18.)) - - 3. You can tell TeX to stop this run by typing `x RET' at the `?' - prompt. - - Please note that 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 2.0 for Berkeley UNIX - (preloaded format=plain-cm 87.10.25) - (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: texi.info, Node: Using texinfo-show-structure, Next: Using occur, Prev: Debugging with TeX, Up: Catching Mistakes - -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. -For example, when `texinfo-show-structure' was run on an earlier -version of this appendix, it produced the following: - - Lines matching "^@\\(chapter \\|sect\\|sub\\|unnum\\|major\\| - heading \\|appendix\\)" in buffer texinfo.texi. - 4:@appendix Formatting Mistakes - 52:@appendixsec Catching Errors with Info Formatting - 222:@appendixsec Catching Errors with @TeX{} Formatting - 338:@appendixsec Using @code{texinfo-show-structure} - 407:@appendixsubsec Using @code{occur} - 444:@appendixsec Finding Badly Referenced Nodes - 513:@appendixsubsec Running @code{Info-validate} - 573:@appendixsubsec Splitting a File Manually - - This says that lines 4, 52, and 222 of `texinfo.texi' begin with the -`@appendix', `@appendixsec', and `@appendixsec' 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' (`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 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: texi.info, Node: Using occur, Next: Running Info-Validate, Prev: Using texinfo-show-structure, Up: Catching Mistakes - -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: texi.info, Node: Running Info-Validate, Prev: Using occur, Up: Catching Mistakes - -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: texi.info, Node: Using Info-validate, Next: Unsplit, Up: Running Info-Validate - -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. - - Note that `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: texi.info, Node: Unsplit, Next: Tagifying, Prev: Using Info-validate, Up: Running Info-Validate - -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 70,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: texi.info, Node: Tagifying, Next: Splitting, Prev: Unsplit, Up: Running Info-Validate - -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 will be able to -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: texi.info, Node: Splitting, Prev: Tagifying, Up: Running Info-Validate - -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 Create 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: texi.info, Node: Refilling Paragraphs, Next: Command Syntax, Prev: Catching Mistakes, Up: Top - -Refilling Paragraphs -******************** - - The `@refill' command refills and, optionally, indents the first -line of a paragraph.(1) The `@refill' command is no longer important, -but we describe it here because you once needed it. You will see it in -many old Texinfo files. - - Without refilling, paragraphs containing long @-constructs may look -bad after formatting because the formatter removes @-commands and -shortens some lines more than others. In the past, neither -`texinfo-format-region' nor `texinfo-format-buffer' refilled paragraphs -automatically. The `@refill' command had to be written at the end of -every paragraph to cause these formatters to fill them. (Both TeX and -`makeinfo' have always refilled paragraphs automatically.) Now, all -the Info formatters automatically fill and indent those paragraphs that -need to be filled and indented. - - The `@refill' command causes both the `texinfo-format-region' -command and the `texinfo-format-buffer' command to refill a paragraph -in the Info file *after* all the other processing has been done. For -this reason, you can not use `@refill' with a paragraph containing -either `@*' or `@w{ ... }' since the refilling action will override -those two commands. - - The `texinfo-format-region' and `texinfo-format-buffer' commands now -automatically append `@refill' to the end of each paragraph that should -be filled. They do not append `@refill' to the ends of paragraphs that -contain `@*' or `@w{ ...}' and therefore do not refill or indent them. - - ---------- Footnotes ---------- - - (1) Perhaps the command should have been called the -`@refillandindent' command, but `@refill' is shorter and the name was -chosen before indenting was possible. - - -File: texi.info, Node: Command Syntax, Next: Obtaining TeX, Prev: Refilling Paragraphs, Up: Top - -@-Command Syntax -**************** - - The character `@' is used to start special Texinfo commands. (It -has the same meaning that `\' has in PlainTeX.) Texinfo has four types -of @-command: - -1. Non-alphabetic commands. - These commands consist of an @ followed by a punctuation mark or - other character that is not part of the alphabet. Non-alphabetic - commands are almost always part of the text within a paragraph, - and never take any argument. The two characters (@ and the other - one) are complete in themselves; none is followed by braces. The - non-alphabetic commands are: `@.', `@:', `@*', `@@', `@{', and - `@}'. - -2. Alphabetic commands that do not require arguments. - These commands start with @ followed by a word followed by left- - and right-hand braces. These commands insert special symbols in - the document; they do not require arguments. For example, - `@dots{}' => `...', `@equiv{}' => `==', `@TeX{}' => `TeX', and - `@bullet{}' => `*'. - -3. Alphabetic commands that require arguments within braces. - These commands start with @ followed by a letter or a word, - followed by an argument within braces. For example, the command - `@dfn' indicates the introductory or defining use of a term; it is - used as follows: `In Texinfo, @@-commands are @dfn{mark-up} - commands.' - -4. Alphabetic commands that occupy an entire line. - These commands occupy an entire line. The line starts with @, - followed by the name of the command (a word); for example, - `@center' or `@cindex'. If no argument is needed, the word is - followed by the end of the line. If there is an argument, it is - separated from the command name by a space. Braces are not used. - - Thus, the alphabetic commands fall into classes that have different -argument syntaxes. You cannot tell to which class a command belongs by -the appearance of its name, but you can tell by the command's meaning: -if the command stands for a glyph, it is in class 2 and does not -require an argument; if it makes sense to use the command together with -other text as part of a paragraph, the command is in class 3 and must -be followed by an argument in braces; otherwise, it is in class 4 and -uses the rest of the line as its argument. - - The purpose of having a different syntax for commands of classes 3 -and 4 is to make Texinfo files easier to read, and also to help the GNU -Emacs paragraph and filling commands work properly. There is only one -exception to this rule: the command `@refill', which is always used at -the end of a paragraph immediately following the final period or other -punctuation character. `@refill' takes no argument and does *not* -require braces. `@refill' never confuses the Emacs paragraph commands -because it cannot appear at the beginning of a line. - - -File: texi.info, Node: Obtaining TeX, Next: New Features, Prev: Command Syntax, Up: Top - -How to Obtain TeX -***************** - - TeX is freely redistributable. You can obtain TeX for Unix systems -from the University of Washington for a distribution fee. - - To order a full distribution, send $200.00 for a 1/2-inch 9-track -1600 bpi (`tar' or `cpio') tape reel, or $210.00 for a 1/4-inch 4-track -QIC-24 (`tar' or `cpio') cartridge, to: - - Northwest Computing Support Center - DR-10, Thomson Hall 35 - University of Washington - Seattle, Washington 98195 - -Please make checks payable to the University of Washington. - - Prepaid orders are preferred but purchase orders are acceptable; -however, purchase orders carry an extra charge of $10.00, to pay for -processing. - - Overseas sites: please add to the base cost $20.00 for shipment via -air parcel post, or $30.00 for shipment via courier. - - Please check with the Northwest Computing Support Center at the -University of Washington for current prices and formats: - - telephone: (206) 543-6259 - email: elisabet@u.washington.edu - - -File: texi.info, Node: New Features, Next: Command and Variable Index, Prev: Obtaining TeX, Up: Top - -Second Edition Features -*********************** - - The second edition of the Texinfo manual describes more than 20 new -Texinfo mode commands and more than 50 previously undocumented Texinfo -@-commands. This edition is more than twice the length of the first -edition. - - Here is a brief description of the new commands. - -* Menu: - -* New Texinfo Mode Commands:: The updating commands are especially useful. -* New Commands:: Many newly described @-commands. - - -File: texi.info, Node: New Texinfo Mode Commands, Next: New Commands, Up: New Features - -New Texinfo Mode Commands -========================= - - Texinfo mode provides commands and features especially designed for -working with Texinfo files. More than 20 new commands have been added, -including commands for automatically creating and updating both nodes -and menus. This is a tedious task when done by hand. - - The keybindings are intended to be somewhat mnemonic. - -Update all nodes and menus --------------------------- - - 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. With `C-u' as a prefix argument, - first create or update all nodes and regular menus. - -Update Pointers ---------------- - -Create or update `Next', `Previous', and `Up' node pointers. - -*Note Updating Nodes and Menus::. - -`C-c C-u C-n' -`M-x texinfo-update-node' - Update a node. - -`C-c C-u C-e' -`M-x texinfo-every-node-update' - Update every node in the buffer. - -Update Menus ------------- - -Create or update menus. - -*Note Updating Nodes and Menus::. - -`C-c C-u C-m' -`M-x texinfo-make-menu' - Make or update a menu. - -`C-c C-u C-a' -`M-x texinfo-all-menus-update' - Make or update all the menus in a buffer. With `C-u' as a prefix - argument, first update all the nodes. - -Insert Title as Description ---------------------------- - -Insert a node's chapter or section title in the space for the -description in a menu entry line; position point so you can edit the -insert. (This command works somewhat differently than the other -insertion commands, which insert only a predefined string.) - -*Note Inserting Frequently Used Commands: Inserting. - -`C-c C-c C-d' - Insert title. - -Format for Info ---------------- - -Provide keybindings both for the Info formatting commands that are -written in Emacs Lisp and for `makeinfo' that is written in C. - -*Note Info Formatting::. - -Use the Emacs lisp `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 ------------------ - -Typeset and print Texinfo documents from within Emacs. - -*Note Printing::. - -`C-c C-t C-r' - Run TeX on the region. - -`C-c C-t C-b' - Run TeX 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 "other updating commands" do not have standard keybindings because -they are used less frequently. - -*Note Other Updating Commands::. - -`M-x texinfo-insert-node-lines' - Insert missing `@node' lines using section titles as node names. - -`M-x texinfo-multiple-files-update' - Update a multi-file document. With a numeric prefix, such as `C-u - 8', update *every* pointer and menu in *all* the files and then - insert a master menu. - -`M-x texinfo-indent-menu-description' - Indent descriptions in menus. - -`M-x texinfo-sequential-node-update' - Insert node pointers in strict sequence. - - -File: texi.info, Node: New Commands, Prev: New Texinfo Mode Commands, Up: New Features - -New Texinfo @-Commands -====================== - - The second edition of the Texinfo manual describes more than 50 -commands that were not described in the first edition. A third or so -of these commands existed in Texinfo but were not documented in the -manual; the others are new. Here is a listing, with brief descriptions -of them: - -Indexing --------- - -Create your own index, and merge indices. - -*Note Indices::. - -`@defindex INDEX-NAME' - Define a new index and its indexing command. See also the - `@defcodeindex' command. - -`@synindex FROM-INDEX INTO-INDEX' - Merge the FROM-INDEX index into the INTO-INDEX index. See also - the `@syncodeindex' command. - -Definitions ------------ - -Describe functions, variables, macros, commands, user options, special -forms, and other such artifacts in a uniform format. - -*Note Definition Commands::. - -`@deffn CATEGORY NAME ARGUMENTS...' - Format a description for functions, interactive commands, and - similar entities. - -`@defvr, @defop, ...' - 15 other related commands. - -Glyphs ------- - -Indicate the results of evaluation, expansion, printed output, an error -message, equivalence of expressions, and the location of point. - -*Note Glyphs::. - -`@equiv{}' -`==' - Equivalence: - -`@error{}' -`error-->' - Error message - -`@expansion{}' -`==>' - Macro expansion - -`@point{}' -`-!-' - Position of point - -`@print{}' -`-|' - Printed output - -`@result{}' -`=>' - Result of an expression - -Page Headings -------------- - -Customize page headings. - -*Note Headings::. - -`@headings ON-OFF-SINGLE-DOUBLE' - Headings on or off, single, or double-sided. - -`@evenfooting [LEFT] @| [CENTER] @| [RIGHT]' - Footings for even-numbered (left-hand) pages. - -`@evenheading, @everyheading, @oddheading, ...' - Five other related commands. - -`@thischapter' - Insert name of chapter and chapter number. - -`@thischaptername, @thisfile, @thistitle, @thispage' - Related commands. - -Formatting ----------- - -Format blocks of text. - -*Note Quotations and Examples::, and -*Note Making Lists and Tables: Lists and Tables. - -`@cartouche' - Draw rounded box surrounding text (not in Info). - -`@enumerate OPTIONAL-ARG' - Enumerate a list with letters or numbers. - -`@exdent LINE-OF-TEXT' - Remove indentation. - -`@flushleft' - Left justify. - -`@flushright' - Right justify. - -`@format' - Do not narrow nor change font. - -`@ftable FORMATTING-COMMAND' -`@vtable FORMATTING-COMMAND' - Two-column table with indexing. - -`@lisp' - For an example of Lisp code. - -`@smallexample' -`@smalllisp' - Like @table and @lisp but for @smallbook. - -Conditionals ------------- - -Conditionally format text. - -*Note `@set' `@clear' `@value': set clear value. - -`@set FLAG [STRING]' - Set a flag. Optionally, set value of FLAG to STRING. - -`@clear FLAG' - Clear a flag. - -`@value{FLAG}' - Replace with value to which FLAG is set. - -`@ifset FLAG' - Format, if FLAG is set. - -`@ifclear FLAG' - Ignore, if FLAG is set. - -@heading series for Titles --------------------------- - -Produce unnumbered headings that do not appear in a table of contents. - -*Note Structuring::. - -`@heading TITLE' - Unnumbered section-like heading not listed in the table of - contents of a printed manual. - -`@chapheading, @majorheading, @subheading, @subsubheading' - Related commands. - -Font commands -------------- - -*Note Smallcaps::, and -*Note Fonts::. - -`@r{TEXT}' - Print in roman font. - -`@sc{TEXT}' - Print in SMALL CAPS font. - -Miscellaneous -------------- - -See *Note `@title' `@subtitle' and `@author' Commands: title subtitle -author, -see *Note Overfull hboxes::, -see *Note Footnotes::, -see *Note Format a Dimension: dmn, -see *Note Inserting a Minus Sign: minus, -see *Note Paragraph Indenting: paragraphindent, -see *Note Cross Reference Commands::, -see *Note `@title' `@subtitle' and `@author': title subtitle author, and -see *Note How to Make Your Own Headings: Custom Headings. - -`@author AUTHOR' - Typeset author's name. - -`@finalout' - Produce cleaner printed output. - -`@footnotestyle' - Specify footnote style. - -`@dmn{DIMENSION}' - Format a dimension. - -`@minus{}' - Generate a minus sign. - -`@paragraphindent' - Specify paragraph indentation. - -`@ref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}' - Make a reference. In the printed manual, the reference does not - start with the word `see'. - -`@title TITLE' - Typeset TITLE in the alternative title page format. - -`@subtitle SUBTITLE' - Typeset SUBTITLE in the alternative title page format. - -`@today{}' - Insert the current date. - - -File: texi.info, Node: Command and Variable Index, Next: Concept Index, Prev: New Features, Up: Top - -Command and Variable Index -************************** - - This is an alphabetical list of all the @-commands and several -variables. To make the list easier to use, the commands are listed -without their preceding `@'. - -* Menu: - -* * (force line break): Line Breaks. -* . (true end of sentence): Controlling Spacing. -* : (suppress widening): Controlling Spacing. -* @ (single @): Inserting An Atsign. -* { (single {): Inserting Braces. -* } (single }): Inserting Braces. -* afourpaper: A4 Paper. -* appendix: unnumbered & appendix. -* appendixsec: unnumberedsec appendixsec heading. -* appendixsection: unnumberedsec appendixsec heading. -* appendixsubsec: unnumberedsubsec appendixsubsec subheading. -* appendixsubsubsec: subsubsection. -* apply: Sample Function Definition. -* author: title subtitle author. -* b (bold font): Fonts. -* buffer-end: Def Cmd Template. -* bullet: bullet. -* bye: Ending a File. -* bye: File End. -* c (comment): Comments. -* cartouche: cartouche. -* center: titlefont center sp. -* chapheading: majorheading & chapheading. -* chapter: chapter. -* cindex: Indexing Commands. -* cite: cite. -* clear: ifset ifclear. -* code: code. -* comment: Comments. -* contents: Contents. -* copyright: copyright symbol. -* copyright: Copyright & Permissions. -* cropmarks: Cropmarks and Magnification. -* defcodeindex: New Indices. -* defcv: Abstract Objects. -* deffn: Functions Commands. -* deffnx: deffnx. -* defindex: New Indices. -* defivar: Abstract Objects. -* defmac: Functions Commands. -* defmethod: Abstract Objects. -* defop: Abstract Objects. -* defopt: Variables Commands. -* defspec: Functions Commands. -* deftp: Data Types. -* deftypefn: Typed Functions. -* deftypefun: Typed Functions. -* deftypevar: Typed Variables. -* deftypevr: Typed Variables. -* defun: Functions Commands. -* defvar: Variables Commands. -* defvr: Variables Commands. -* dfn: dfn. -* display: display. -* dmn: dmn. -* dots: dots. -* emph: emph & strong. -* end: Quotations and Examples. -* end: Introducing Lists. -* end titlepage: end titlepage. -* enumerate: enumerate. -* evenfooting: Custom Headings. -* evenheading: Custom Headings. -* everyfooting: Custom Headings. -* everyheading: Custom Headings. -* example: example. -* exdent: exdent. -* file: file. -* filll: Copyright & Permissions. -* finalout: Overfull hboxes. -* findex: Indexing Commands. -* flushleft: flushleft & flushright. -* flushright: flushleft & flushright. -* foobar: Optional Arguments. -* footnote: Footnotes. -* footnotestyle: Footnotes. -* format: format. -* forward-word: Def Cmd Template. -* ftable: ftable vtable. -* group: group. -* heading: unnumberedsec appendixsec heading. -* headings: headings on off. -* i (italic font): Fonts. -* ifclear: ifset ifclear. -* ifinfo: Conditionals. -* ifset: ifset ifclear. -* iftex: Conditionals. -* ignore: Comments. -* include: Using Include Files. -* Info-validate: Running Info-Validate. -* INFOPATH: Other Info Directories. -* inforef: inforef. -* input (TeX command): Minimum. -* isearch-backward: deffnx. -* isearch-forward: deffnx. -* item: itemize. -* item: table. -* itemize: itemize. -* itemx: itemx. -* kbd: kbd. -* key: key. -* kindex: Indexing Commands. -* lisp: Lisp Example. -* lpr (DVI print command): Shell Format & Print. -* mag (TeX command): Cropmarks and Magnification. -* majorheading: majorheading & chapheading. -* makeinfo-buffer: makeinfo in Emacs. -* makeinfo-kill-job: makeinfo in Emacs. -* makeinfo-recenter-output-buffer: makeinfo in Emacs. -* makeinfo-region: makeinfo in Emacs. -* menu: Menus. -* minus: minus. -* need: need. -* next-error: makeinfo in Emacs. -* noindent: noindent. -* occur: Using occur. -* occur-mode-goto-occurrence: Showing the Structure. -* oddfooting: Custom Headings. -* oddheading: Custom Headings. -* page: page. -* page-delimiter: Showing the Structure. -* paragraphindent: paragraphindent. -* pindex: Indexing Commands. -* printindex: Printing Indices & Menus. -* pxref: pxref. -* quotation: quotation. -* r (Roman font): Fonts. -* ref: ref. -* refill: Refilling Paragraphs. -* samp: samp. -* sc (small caps font): Smallcaps. -* section: section. -* set: ifset ifclear. -* setchapternewpage: setchapternewpage. -* setfilename: setfilename. -* settitle: settitle. -* shortcontents: Contents. -* smallbook: smallbook. -* smallexample: smallexample & smalllisp. -* smalllisp: smallexample & smalllisp. -* sp (line spacing): sp. -* sp (titlepage line spacing): titlefont center sp. -* strong: emph & strong. -* subheading: unnumberedsubsec appendixsubsec subheading. -* subsection: subsection. -* subsubheading: subsubsection. -* subsubsection: subsubsection. -* subtitle: title subtitle author. -* summarycontents: Contents. -* syncodeindex: syncodeindex. -* syncodeindex: syncodeindex. -* synindex: synindex. -* t (typewriter font): Fonts. -* table: Two-column Tables. -* tex: Using Ordinary TeX Commands. -* tex (command): tex. -* texi2dvi (shell script): Shell Format & Print. -* texindex: Format/Print Hardcopy. -* texindex: Shell Format & Print. -* texinfo-all-menus-update: Updating Commands. -* texinfo-every-node-update: Updating Commands. -* texinfo-format-buffer: Info Formatting. -* texinfo-format-buffer: texinfo-format commands. -* texinfo-format-buffer: texinfo-format commands. -* texinfo-format-region: texinfo-format commands. -* texinfo-format-region: texinfo-format commands. -* texinfo-format-region: Info Formatting. -* texinfo-indent-menu-description: Other Updating Commands. -* texinfo-insert-@code: Inserting. -* texinfo-insert-@dfn: Inserting. -* texinfo-insert-@end: Inserting. -* texinfo-insert-@example: Inserting. -* texinfo-insert-@item: Inserting. -* texinfo-insert-@kbd: Inserting. -* texinfo-insert-@node: Inserting. -* texinfo-insert-@noindent: Inserting. -* texinfo-insert-@samp: Inserting. -* texinfo-insert-@table: Inserting. -* texinfo-insert-@var: Inserting. -* texinfo-insert-braces: Inserting. -* texinfo-insert-node-lines: Other Updating Commands. -* texinfo-make-menu: Updating Commands. -* texinfo-master-menu: Updating Commands. -* texinfo-multiple-files-update: texinfo-multiple-files-update. -* texinfo-multiple-files-update (in brief): Other Updating Commands. -* texinfo-sequential-node-update: Other Updating Commands. -* texinfo-show-structure: Using texinfo-show-structure. -* texinfo-show-structure: Showing the Structure. -* texinfo-start-menu-description: Inserting. -* texinfo-tex-buffer: Printing. -* texinfo-tex-print: Printing. -* texinfo-tex-region: Printing. -* texinfo-update-node: Updating Commands. -* TEXINPUTS: Preparing for TeX. -* thischapter: Custom Headings. -* thischaptername: Custom Headings. -* thisfile: Custom Headings. -* thispage: Custom Headings. -* thistitle: Custom Headings. -* tindex: Indexing Commands. -* title: title subtitle author. -* titlefont: titlefont center sp. -* titlepage: titlepage. -* today: Custom Headings. -* top (@-command): makeinfo top command. -* unnumbered: unnumbered & appendix. -* unnumberedsec: unnumberedsec appendixsec heading. -* unnumberedsubsec: unnumberedsubsec appendixsubsec subheading. -* unnumberedsubsubsec: subsubsection. -* up-list: Inserting. -* value: value. -* var: var. -* vindex: Indexing Commands. -* vskip: Copyright & Permissions. -* vtable: ftable vtable. -* w (prevent line break): w. -* xref: xref. - diff --git a/gnu/usr.bin/texinfo/info-files/texi.info-11 b/gnu/usr.bin/texinfo/info-files/texi.info-11 deleted file mode 100644 index f960227..0000000 --- a/gnu/usr.bin/texinfo/info-files/texi.info-11 +++ /dev/null @@ -1,451 +0,0 @@ -This is Info file texi.info, produced by Makeinfo-1.55 from the input -file texi.texi. - - This file documents Texinfo, a documentation system that uses a -single source file to produce both on-line information and a printed -manual. - - Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation, -Inc. - - This is the second edition of the Texinfo documentation, -and is consistent with version 2 of `texinfo.tex'. - - 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 Free Software Foundation. - - -File: texi.info, Node: Concept Index, Prev: Command and Variable Index, Up: Top - -Concept Index -************* - -* Menu: - -* @-command in nodename: Node Line Requirements. -* @-command list: Command List. -* @-command syntax: Command Syntax. -* @-commands: Formatting Commands. -* .cshrc initialization file: Preparing for TeX. -* .profile initialization file: Preparing for TeX. -* @include file sample: Sample Include File. -* @menu parts: Menu Parts. -* @node line writing: Writing a Node. -* makeinfo inside Emacs: makeinfo in Emacs. -* makeinfo options: makeinfo options. -* TEXINPUTS environment variable: Preparing for TeX. -* dir directory for Info installation: Install an Info File. -* dir file listing: New Info File. -* End node footnote style: Footnotes. -* Separate footnote style: Footnotes. -* Top node: The Top Node. -* Top node is first: First Node. -* Top node naming for references: Top Node Naming. -* Top node summary: Top Node Summary. -* hboxes, overfull: Overfull hboxes. -* ifinfo permissions: ifinfo Permissions. -* TeX commands, using ordinary: Using Ordinary TeX Commands. -* TeX index sorting: Format/Print Hardcopy. -* TeX input initialization: Preparing for TeX. -* TeX, how to obtain: Obtaining TeX. -* A4 paper, printing on: A4 Paper. -* Abbreviations for keys: key. -* Adding a new info file: New Info File. -* Alphabetical @-command list: Command List. -* Another Info directory: Other Info Directories. -* Apostrophe in nodename: Node Line Requirements. -* Arguments, repeated and optional: Optional Arguments. -* Automatic pointer creation with makeinfo: makeinfo Pointer Creation. -* Automatically insert nodes, menus: Updating Nodes and Menus. -* Badly referenced nodes: Running Info-Validate. -* Batch formatting for Info: Batch Formatting. -* Beginning a Texinfo file: Beginning a File. -* Beginning line of a Texinfo file: First Line. -* Black rectangle in hardcopy: Overfull hboxes. -* Blank lines: sp. -* Book characteristics, printed: Printed Books. -* Book, printing small: smallbook. -* Box with rounded corners: cartouche. -* Braces and argument syntax: Command Syntax. -* Braces, inserting: Braces Atsigns Periods. -* Braces, when to use: Formatting Commands. -* Breaks in a line: Line Breaks. -* Buffer formatting and printing: Printing. -* Bullets, inserting: Dots Bullets. -* Capitalizing index entries: Indexing Commands. -* Case in nodename: Node Line Requirements. -* Catching errors with TeX formatting: Debugging with TeX. -* Catching errors with Info formatting: Debugging with Info. -* Catching mistakes: Catching Mistakes. -* Chapter structuring: Structuring. -* Characteristics, printed books or manuals: Printed Books. -* Checking for badly referenced nodes: Running Info-Validate. -* Colon in nodename: Node Line Requirements. -* Combining indices: Combining Indices. -* Comma in nodename: Node Line Requirements. -* Command definitions: Sample Function Definition. -* Commands to insert single characters: Braces Atsigns Periods. -* Commands using ordinary TeX: Using Ordinary TeX Commands. -* Commands, inserting them: Inserting. -* Comments: Comments. -* Compile command for formatting: Compile-Command. -* Conditionally visible text: Conditionals. -* Conditions for copying Texinfo: Copying. -* Contents, Table of: Contents. -* Contents-like outline of file structure: Showing the Structure. -* Conventions for writing definitions: Def Cmd Conventions. -* Conventions, syntactic: Conventions. -* Copying conditions: Copying. -* Copying permissions: Sample Permissions. -* Copying software: Software Copying Permissions. -* Copyright page: Copyright & Permissions. -* Correcting mistakes: Catching Mistakes. -* Create nodes, menus automatically: Updating Nodes and Menus. -* Creating an Info file: Create an Info File. -* Creating an unsplit file: Unsplit. -* Creating index entries: Indexing Commands. -* Creating indices: Indices. -* Creating pointers with makeinfo: makeinfo Pointer Creation. -* Cropmarks for printing: Cropmarks and Magnification. -* Cross reference parts: Cross Reference Parts. -* Cross references: Cross References. -* Cross references using @inforef: inforef. -* Cross references using @pxref: pxref. -* Cross references using @ref: ref. -* Cross references using @xref: xref. -* Debugging the Texinfo structure: Catching Mistakes. -* Debugging with TeX formatting: Debugging with TeX. -* Debugging with Info formatting: Debugging with Info. -* Defining indexing entries: Indexing Commands. -* Defining new indices: New Indices. -* Definition commands: Definition Commands. -* Definition conventions: Def Cmd Conventions. -* Definition template: Def Cmd Template. -* Definitions grouped together: deffnx. -* Description for menu, start: Inserting. -* Different cross reference commands: Cross Reference Commands. -* Dimension formatting: dmn. -* Display formatting: display. -* Distribution: Software Copying Permissions. -* Dots, inserting: dots. -* Dots, inserting: Dots Bullets. -* Double-colon menu entries: Less Cluttered Menu Entry. -* DVI file: Shell Format & Print. -* Ellipsis, inserting: Dots Bullets. -* Emacs: Texinfo Mode. -* Emacs shell, format, print from: Within Emacs. -* Emphasizing text: Emphasis. -* Emphasizing text, font for: emph & strong. -* End of header line: End of Header. -* End titlepage starts headings: end titlepage. -* Ending a Texinfo file: Ending a File. -* Entries for an index: Indexing Commands. -* Entries, making index: Index Entries. -* Enumeration: enumerate. -* Equivalence, indicating it: Equivalence. -* Error message, indicating it: Error Glyph. -* Errors, parsing: makeinfo in Emacs. -* European A4 paper: A4 Paper. -* Evaluation glyph: result. -* Example for a small book: smallexample & smalllisp. -* Example menu: Menu Example. -* Examples, formatting them: example. -* Expansion, indicating it: expansion. -* File beginning: Beginning a File. -* File ending: Ending a File. -* File section structure, showing it: Showing the Structure. -* Filling paragraphs: Refilling Paragraphs. -* Final output: Overfull hboxes. -* Finding badly referenced nodes: Running Info-Validate. -* First line of a Texinfo file: First Line. -* First node: First Node. -* Fonts for indices: syncodeindex. -* Fonts for printing, not for Info: Fonts. -* Footings: Headings. -* Footnotes: Footnotes. -* Format a dimension: dmn. -* Format and print hardcopy: Format/Print Hardcopy. -* Format and print in Texinfo mode: Texinfo Mode Printing. -* Format with the compile command: Compile-Command. -* Format, print from Emacs shell: Within Emacs. -* Formatting a file for Info: Create an Info File. -* Formatting commands: Formatting Commands. -* Formatting examples: example. -* Formatting for Info: Info Formatting. -* Formatting for printing: Printing. -* Formatting headings and footings: Headings. -* Formatting requirements: Requirements Summary. -* Frequently used commands, inserting: Inserting. -* Function definitions: Sample Function Definition. -* General syntactic conventions: Conventions. -* Generating menus with indices: Printing Indices & Menus. -* Glyphs: Glyphs. -* GNU Emacs: Texinfo Mode. -* GNU Emacs shell, format, print from: Within Emacs. -* Going to other Info files' nodes: Other Info Files. -* Group (hold text together vertically): group. -* Grouping two definitions together: deffnx. -* Hardcopy, printing it: Format/Print Hardcopy. -* Header for Texinfo files: Header. -* Header of a Texinfo file: First Line. -* Headings: Headings. -* Headings, page, begin to appear: end titlepage. -* Highlighting text: Indicating. -* Hints: Tips. -* Holding text together vertically: group. -* If text conditionally visible: Conditionals. -* Ignored text: Comments. -* Include file requirements: Include File Requirements. -* Include file sample: Sample Include File. -* Include files: Include Files. -* Indentation undoing: exdent. -* Indenting paragraphs: paragraphindent. -* Index entries: Indexing Commands. -* Index entries, making: Index Entries. -* Index entry capitalization: Indexing Commands. -* Index font types: Indexing Commands. -* Indexing commands, predefined: Indexing Commands. -* Indexing table entries automatically: ftable vtable. -* Indicating commands, definitions, etc.: Indicating. -* Indicating evaluation: result. -* Indices: Indices. -* Indices, combining them: Combining Indices. -* Indices, defining new: New Indices. -* Indices, printing and menus: Printing Indices & Menus. -* Indices, sorting: Format/Print Hardcopy. -* Indices, two letter names: syncodeindex. -* Indirect subfiles: Tag and Split Files. -* Info batch formatting: Batch Formatting. -* Info file installation: Install an Info File. -* Info file requires @setfilename: setfilename. -* Info file, listing new one: New Info File. -* Info file, splitting manually: Splitting. -* Info files: Info Files. -* Info formatting: Info Formatting. -* Info installed in another directory: Other Info Directories. -* Info validating a large file: Using Info-validate. -* Info, creating an on-line file: Create an Info File. -* Info; other files' nodes: Other Info Files. -* Initialization file for TeX input: Preparing for TeX. -* Insert nodes, menus automatically: Updating Nodes and Menus. -* Inserting @, braces, and periods: Braces Atsigns Periods. -* Inserting dots: Dots Bullets. -* Inserting dots: dots. -* Inserting ellipsis: Dots Bullets. -* Inserting frequently used commands: Inserting. -* Inserting special characters and symbols: Insertions. -* Installing an Info file: Install an Info File. -* Installing Info in another directory: Other Info Directories. -* Introduction, as part of file: Software Copying Permissions. -* Itemization: itemize. -* Keys, recommended names: key. -* Larger or smaller pages: Cropmarks and Magnification. -* Less cluttered menu entry: Less Cluttered Menu Entry. -* License agreement: Software Copying Permissions. -* Line breaks: Line Breaks. -* Line breaks, preventing: w. -* Line spacing: sp. -* Lisp example: Lisp Example. -* Lisp example for a small book: smallexample & smalllisp. -* List of @-commands: Command List. -* Listing a new info file: New Info File. -* Lists and tables, making them: Lists and Tables. -* Local variables: Compile-Command. -* Location of menus: Menu Location. -* Looking for badly referenced nodes: Running Info-Validate. -* Macro definitions: Sample Function Definition. -* Magnified printing: Cropmarks and Magnification. -* Making a printed manual: Format/Print Hardcopy. -* Making a tag table automatically: Tag and Split Files. -* Making a tag table manually: Unsplit. -* Making cross references: Cross References. -* Making line and page breaks: Breaks. -* Making lists and tables: Lists and Tables. -* Manual characteristics, printed: Printed Books. -* Marking text within a paragraph: Marking Text. -* Marking words and phrases: Marking Text. -* Master menu: The Top Node. -* Master menu parts: Master Menu Parts. -* Mathematical expressions: Using Ordinary TeX Commands. -* Menu description, start: Inserting. -* Menu entries with two colons: Less Cluttered Menu Entry. -* Menu example: Menu Example. -* Menu location: Menu Location. -* Menu parts: Menu Parts. -* Menu writing: Writing a Menu. -* Menus: Menus. -* Menus generated with indices: Printing Indices & Menus. -* META key: key. -* Meta-syntactic chars for arguments: Optional Arguments. -* Minimal Texinfo file (requirements): Minimum. -* Mistakes, catching: Catching Mistakes. -* Mode, using Texinfo: Texinfo Mode. -* Must have in Texinfo file: Minimum. -* Names for indices: syncodeindex. -* Names recommended for keys: key. -* Naming a `Top' Node in references: Top Node Naming. -* Need space at page bottom: need. -* New index defining: New Indices. -* New info file, listing it in dir file: New Info File. -* Node line requirements: Node Line Requirements. -* Node line writing: Writing a Node. -* Node, defined: node. -* Node, `Top': The Top Node. -* Nodename must be unique: Node Line Requirements. -* Nodename, cannot contain: Node Line Requirements. -* Nodes for menus are short: Menu Location. -* Nodes in other Info files: Other Info Files. -* Nodes, catching mistakes: Catching Mistakes. -* Nodes, checking for badly referenced: Running Info-Validate. -* Obtaining TeX: Obtaining TeX. -* Occurrences, listing with @occur: Using occur. -* Optional and repeated arguments: Optional Arguments. -* Options for makeinfo: makeinfo options. -* Ordinary TeX commands, using: Using Ordinary TeX Commands. -* Other Info files' nodes: Other Info Files. -* Outline of file structure, showing it: Showing the Structure. -* Overfull hboxes: Overfull hboxes. -* Overview of Texinfo: Overview. -* Page breaks: page. -* Page delimiter in Texinfo mode: Showing the Structure. -* Page headings: Headings. -* Page numbering: Headings. -* Page sizes for books: smallbook. -* Pages, starting odd: setchapternewpage. -* Paper size, European A4: A4 Paper. -* Paragraph indentation: paragraphindent. -* Paragraph, marking text within: Marking Text. -* Parsing errors: makeinfo in Emacs. -* Part of file formatting and printing: Printing. -* Parts of a cross reference: Cross Reference Parts. -* Parts of a master menu: Master Menu Parts. -* Parts of a menu: Menu Parts. -* Periods, inserting: Braces Atsigns Periods. -* Permissions: Sample Permissions. -* Permissions, printed: Copyright & Permissions. -* PlainTeX: Using Ordinary TeX Commands. -* Point, indicating it in a buffer: Point Glyph. -* Pointer creation with makeinfo: makeinfo Pointer Creation. -* Pointer validation with makeinfo: Pointer Validation. -* Predefined indexing commands: Indexing Commands. -* Predefined names for indices: syncodeindex. -* Preparing to use TeX: Preparing for TeX. -* Preventing line and page breaks: Breaks. -* Print and format in Texinfo mode: Texinfo Mode Printing. -* Print, format from Emacs shell: Within Emacs. -* Printed book and manual characteristics: Printed Books. -* Printed output, indicating it: Print Glyph. -* Printed permissions: Copyright & Permissions. -* Printing a region or buffer: Printing. -* Printing an index: Printing Indices & Menus. -* Printing cropmarks: Cropmarks and Magnification. -* Problems, catching: Catching Mistakes. -* Quotations: quotation. -* Recommended names for keys: key. -* Rectangle, ugly, black in hardcopy: Overfull hboxes. -* References: Cross References. -* References using @inforef: inforef. -* References using @pxref: pxref. -* References using @ref: ref. -* References using @xref: xref. -* Referring to other Info files: Other Info Files. -* Refilling paragraphs: Refilling Paragraphs. -* Region formatting and printing: Printing. -* Region printing in Texinfo mode: Texinfo Mode Printing. -* Repeated and optional arguments: Optional Arguments. -* Required in Texinfo file: Minimum. -* Requirements for formatting: Requirements Summary. -* Requirements for include files: Include File Requirements. -* Requirements for updating commands: Updating Requirements. -* Result of an expression: result. -* Running Info-validate: Using Info-validate. -* Running makeinfo in Emacs: makeinfo in Emacs. -* Running an Info formatter: Info Formatting. -* Sample @include file: Sample Include File. -* Sample function definition: Sample Function Definition. -* Sample Texinfo file: Short Sample. -* Sample Texinfo file, no comments: Sample Texinfo File. -* Section structure of a file, showing it: Showing the Structure. -* Shell, format, print from: Within Emacs. -* Shell, running makeinfo in: makeinfo in Emacs. -* Short nodes for menus: Menu Location. -* Showing the section structure of a file: Showing the Structure. -* Showing the structure of a file: Using texinfo-show-structure. -* Single characters, commands to insert: Braces Atsigns Periods. -* Size of printed book: smallbook. -* Small book example: smallexample & smalllisp. -* Small book size: smallbook. -* Small caps font: Smallcaps. -* Software copying permissions: Software Copying Permissions. -* Sorting indices: Format/Print Hardcopy. -* Spaces (blank lines): sp. -* Special insertions: Insertions. -* Special typesetting commands: Dots Bullets. -* Specifying index entries: Indexing Commands. -* Splitting an Info file manually: Splitting. -* Start of header line: Start of Header. -* Starting chapters: setchapternewpage. -* Structure of a file, showing it: Showing the Structure. -* Structure, catching mistakes in: Catching Mistakes. -* Structuring of chapters: Structuring. -* Subsection-like commands: unnumberedsubsec appendixsubsec subheading. -* Subsub commands: subsubsection. -* Syntactic conventions: Conventions. -* Syntax, optional & repeated arguments: Optional Arguments. -* Table of contents: Contents. -* Tables and lists, making them: Lists and Tables. -* Tables with indexes: ftable vtable. -* Tables, making two-column: Two-column Tables. -* Tabs; don't use!: Conventions. -* Tag table, making automatically: Tag and Split Files. -* Tag table, making manually: Unsplit. -* Template for a definition: Def Cmd Template. -* Texinfo file beginning: Beginning a File. -* Texinfo file ending: Ending a File. -* Texinfo file header: Header. -* Texinfo file minimum: Minimum. -* Texinfo file section structure, showing it: Showing the Structure. -* Texinfo mode: Texinfo Mode. -* Texinfo overview: Overview. -* Texinfo printed book characteristics: Printed Books. -* Text, conditionally visible: Conditionals. -* Thin space between number, dimension: dmn. -* Tips: Tips. -* Title page: titlepage. -* Titlepage end starts headings: end titlepage. -* Titlepage permissions: Titlepage Permissions. -* Tree structuring: Tree Structuring. -* Two letter names for indices: syncodeindex. -* Two named items for @table: itemx. -* Two part menu entry: Less Cluttered Menu Entry. -* Two `First' Lines for @deffn: deffnx. -* Typesetting commands for dots, etc.: Dots Bullets. -* Uncluttered menu entry: Less Cluttered Menu Entry. -* Unique nodename requirement: Node Line Requirements. -* Unprocessed text: Comments. -* Unsplit file creation: Unsplit. -* Updating nodes and menus: Updating Nodes and Menus. -* Updating requirements: Updating Requirements. -* Usage tips: Tips. -* Validating a large file: Using Info-validate. -* Validation of pointers: Pointer Validation. -* Value of an expression, indicating: result. -* Vertical whitespace (vskip): Copyright & Permissions. -* Vertically holding text together: group. -* Visibility of conditional text: Conditionals. -* Words and phrases, marking them: Marking Text. -* Writing a menu: Writing a Menu. -* Writing an @node line: Writing a Node. - - diff --git a/gnu/usr.bin/texinfo/info-files/texi.info-2 b/gnu/usr.bin/texinfo/info-files/texi.info-2 deleted file mode 100644 index 6ad094d..0000000 --- a/gnu/usr.bin/texinfo/info-files/texi.info-2 +++ /dev/null @@ -1,1289 +0,0 @@ -This is Info file texi.info, produced by Makeinfo-1.55 from the input -file texi.texi. - - This file documents Texinfo, a documentation system that uses a -single source file to produce both on-line information and a printed -manual. - - Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation, -Inc. - - This is the second edition of the Texinfo documentation, -and is consistent with version 2 of `texinfo.tex'. - - 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 Free Software Foundation. - - -File: texi.info, Node: Texinfo Mode, Next: Beginning a File, Prev: Overview, Up: Top - -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. 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: texi.info, Node: Texinfo Mode Overview, Next: Emacs Editing, Up: Texinfo Mode - -Texinfo Mode Overview -===================== - - Texinfo mode provides special features for working with Texinfo -files: - - * 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: texi.info, Node: Emacs Editing, Next: Inserting, Prev: Texinfo Mode Overview, Up: Texinfo Mode - -The Usual GNU Emacs Editing Commands -==================================== - - In most cases, the usual Text mode commands work the same in Texinfo -mode as they do in Text mode. Texinfo mode adds new editing commands -and tools to GNU Emacs' general purpose editing features. The major -difference concerns filling. In Texinfo mode, the paragraph separation -variable and syntax table are redefined so that Texinfo commands that -should be on lines of their own are not inadvertently included in -paragraphs. Thus, the `M-q' (`fill-paragraph') command will refill a -paragraph but not mix an indexing command on a line adjacent to it into -the paragraph. - - In addition, Texinfo mode sets the `page-delimiter' variable to the -value of `texinfo-chapter-level-regexp'; by default, this is a regular -expression matching the commands for chapters and their equivalents, -such as appendices. With this value for the page delimiter, you can -jump from chapter title to chapter title with the `C-x ]' -(`forward-page') and `C-x [' (`backward-page') commands and narrow to a -chapter with the `C-x p' (`narrow-to-page') command. (*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 three extensions `.texinfo', -`.texi', 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' or `.texi' -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: texi.info, Node: Inserting, Next: Showing the Structure, Prev: Emacs Editing, Up: Texinfo Mode - -Inserting Frequently Used Commands -================================== - - Texinfo mode provides commands to insert various frequently used -@-commands into the buffer. You can use these commands to save -keystrokes. - - The insert commands are invoked by typing `C-c' twice and then the -first letter of the @-command: - -`C-c C-c c' -`M-x texinfo-insert-@code' - Insert `@code{}' and put the cursor between the braces. - -`C-c C-c d' -`M-x texinfo-insert-@dfn' - Insert `@dfn{}' and put the cursor between the braces. - -`C-c C-c e' -`M-x texinfo-insert-@end' - Insert `@end' and attempt to insert the correct following word, - such as `example' or `table'. (This command does not handle - nested lists correctly, but inserts the word appropriate to the - immediately preceding list.) - -`C-c C-c i' -`M-x texinfo-insert-@item' - Insert `@item' and put the cursor at the beginning of the next - line. - -`C-c C-c k' -`M-x texinfo-insert-@kbd' - Insert `@kbd{}' and put the cursor between the braces. - -`C-c C-c n' -`M-x texinfo-insert-@node' - Insert `@node' and a comment line listing the sequence for the - `Next', `Previous', and `Up' nodes. Leave point after the `@node'. - -`C-c C-c o' -`M-x texinfo-insert-@noindent' - Insert `@noindent' and put the cursor at the beginning of the next - line. - -`C-c C-c s' -`M-x texinfo-insert-@samp' - Insert `@samp{}' and put the cursor between the braces. - -`C-c C-c t' -`M-x texinfo-insert-@table' - Insert `@table' followed by a SPC and leave the cursor after the - SPC. - -`C-c C-c v' -`M-x texinfo-insert-@var' - Insert `@var{}' and put the cursor between the braces. - -`C-c C-c x' -`M-x texinfo-insert-@example' - Insert `@example' and put the cursor at the beginning of the next - line. - -`C-c C-c {' -`M-x texinfo-insert-braces' - Insert `{}' and put the cursor between the braces. - -`C-c C-c }' -`C-c C-c ]' -`M-x up-list' - Move from between a pair of braces forward past the closing brace. - Typing `C-c C-c ]' is easier than typing `C-c C-c }', which is, - however, more mnemonic; hence the two keybindings. (Also, you can - move out from between braces by typing `C-f'.) - - To put a command such as `@code{...}' around an *existing* word, -position the cursor in front of the word and type `C-u 1 C-c C-c c'. -This makes it easy to edit existing plain text. The value of the -prefix argument tells Emacs how many words following point to include -between braces--1 for one word, 2 for two words, and so on. Use a -negative argument to enclose the previous word or words. If you do not -specify a prefix argument, Emacs inserts the @-command string and -positions the cursor between the braces. This feature works only for -those @-commands that operate on a word or words within one line, such -as `@kbd' and `@var'. - - This set of insert commands was created after analyzing the frequency -with which different @-commands are used in the `GNU Emacs Manual' and -the `GDB Manual'. If you wish to add your own insert commands, you can -bind a keyboard macro to a key, use abbreviations, or extend the code -in `texinfo.el'. - - `C-c C-c C-d' (`texinfo-start-menu-description') is an insert -command that works differently from the other insert commands. It -inserts a node's section or chapter title in the space for the -description in a menu entry line. (A menu entry has three parts, the -entry name, the node name, and the description. Only the node name is -required, but a description helps explain what the node is about. -*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: texi.info, Node: Showing the Structure, Next: Updating Nodes and Menus, Prev: Inserting, Up: Texinfo Mode - -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. (This is how the `texinfo-show-structure' command -worked without an argument in the first version of Texinfo. It was -changed because `@node' lines clutter up the `*Occur*' buffer and are -usually not needed.) 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 with the `C-x -n' (`narrow-to-region') command and `texinfo-show-structure' will work -on only that region. To see the whole buffer again, use `C-x 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 p' (`narrow-to-page') -command to narrow to a chapter. *Note Pages: (emacs)Pages, for more -information about the page commands. - - -File: texi.info, Node: Updating Nodes and Menus, Next: Info Formatting, Prev: Showing the Structure, Up: Texinfo Mode - -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: texi.info, Node: Updating Commands, Next: Updating Requirements, Up: Updating Nodes and Menus - -The Updating Commands ---------------------- - - You can use the updating commands - - * to insert or update the `Next', `Previous', and `Up' pointers of a - node, - - * to insert or update the menu for a section, and - - * to 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. -Note that 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 is often useful to reduce it to as low as 24. You can set -the variable with the `M-x edit-options' command (*note Editing -Variable Values: (emacs)Edit Options.) 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: texi.info, Node: Updating Requirements, Next: Other Updating Commands, Prev: Updating Commands, Up: Updating Nodes and Menus - -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 - -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 can 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: Create 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: texi.info, Node: Other Updating Commands, Prev: Updating Requirements, Up: Updating Nodes and Menus - -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 - - (Note that 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* RET' - 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: texi.info, Node: Info Formatting, Next: Printing, Prev: Updating Nodes and Menus, Up: Texinfo Mode - -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 the Info formatting commands to work, the file *must* include a -line that has `@setfilename' in its header. - - Not all systems support the `makeinfo'-based formatting commands. - - *Note Create an Info File::, for details about Info formatting. - - -File: texi.info, Node: Printing, Next: Texinfo Mode Summary, Prev: Info Formatting, Up: Texinfo Mode - -Formatting and 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. - - 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-r' -`M-x texinfo-tex-region' - Run TeX on the region. - -`C-c C-t C-b' -`M-x texinfo-tex-buffer' - Run TeX on the buffer. - -`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' or `texinfo-tex-buffer'. You must run the - `tex' command a second time after sorting the raw index files. - -`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 Format/Print Hardcopy::, for a description of the other TeX -related commands, such as `tex-show-print-queue'. - - -File: texi.info, Node: Texinfo Mode Summary, Prev: Printing, Up: Texinfo Mode - -Texinfo Mode Summary -==================== - - In Texinfo mode, each set of commands has default keybindings that -begin with the same keys. All the commands that are custom-created for -Texinfo mode begin with `C-c'. The keys are somewhat mnemonic. - -Insert Commands ---------------- - - The insert commands are invoked by typing `C-c' twice and then the -first letter of the @-command to be inserted. (It might make more -sense mnemonically to use `C-c C-i', for `custom insert', but `C-c C-c' -is quick to type.) - - C-c C-c c Insert `@code'. - C-c C-c d Insert `@dfn'. - C-c C-c e Insert `@end'. - C-c C-c i Insert `@item'. - C-c C-c n Insert `@node'. - C-c C-c s Insert `@samp'. - C-c C-c v Insert `@var'. - C-c C-c { Insert braces. - C-c C-c ] - C-c C-c } Move out of enclosing braces. - - C-c C-c C-d Insert a node's section title - in the space for the description - in a menu entry line. - -Show Structure --------------- - - The `texinfo-show-structure' command is often used within a narrowed -region. - - C-c C-s List all the headings. - -The Master Update Command -------------------------- - - The `texinfo-master-menu' command creates a master menu; and can be -used to update every node and menu in a file as well. - - C-c C-u m - M-x texinfo-master-menu - Create or update a master menu. - - C-u C-c C-u m With `C-u' as a prefix argument, first - create or update all nodes and regular - menus, and then create a master menu. - -Update Pointers ---------------- - - The update pointer commands are invoked by typing `C-c C-u' and then -either typing `C-n' for `texinfo-update-node' or typing `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 TeX 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 `other 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: texi.info, Node: Beginning a File, Next: Ending a File, Prev: Texinfo Mode, Up: Top - -Beginning a Texinfo File -************************ - - Certain pieces of information must be provided at the beginning of a -Texinfo file, such as the name of the file and the title of the -document. - -* Menu: - -* Four Parts:: Four parts begin a Texinfo file. -* Sample Beginning:: Here is a sample beginning for a Texinfo file. -* Header:: The very beginning of a Texinfo file. -* Info Summary and Permissions:: Summary and copying permissions for Info. -* Titlepage & Copyright Page:: Creating the title and copyright pages. -* The Top Node:: Creating the `Top' node and master menu. -* Software Copying Permissions:: Ensure that you and others continue to - have the right to use and share software. - - -File: texi.info, Node: Four Parts, Next: Sample Beginning, Up: Beginning a File - -Four Parts Begin a File -======================= - - Generally, the beginning of a Texinfo file has four parts: - - 1. The header, delimited by special comment lines, that includes the - commands for naming the Texinfo file and telling TeX what - definitions' file to use when processing the Texinfo file. - - 2. A short statement of what the file is about, with a copyright - notice and copying permissions. This is enclosed in `@ifinfo' and - `@end ifinfo' commands so that the formatters place it only in the - Info file. - - 3. A title page and copyright page, with a copyright notice and - copying permissions. This is enclosed between `@titlepage' and - `@end titlepage' commands. The title and copyright page appear - only in the printed manual. - - 4. The `Top' node that contains a menu for the whole Info file. The - contents of this node appear only in the Info file. - - Also, optionally, you may include the copying conditions for a -program and a warranty disclaimer. The copying section will be -followed by an introduction or else by the first chapter of the manual. - - Since the copyright notice and copying permissions for the Texinfo -document (in contrast to the copying permissions for a program) are in -parts that appear only in the Info file or only in the printed manual, -this information must be given twice. - - -File: texi.info, Node: Sample Beginning, Next: Header, Prev: Four Parts, Up: Beginning a File - -Sample Texinfo File Beginning -============================= - - The following sample shows what is needed. - - \input texinfo @c -*-texinfo-*- - @c %**start of header - @setfilename NAME-OF-INFO-FILE - @settitle NAME-OF-MANUAL - @setchapternewpage odd - @c %**end of header - - @ifinfo - This file documents ... - - Copyright YEAR COPYRIGHT-OWNER - - Permission is granted to ... - @end ifinfo - - @c This title page illustrates only one of the - @c two methods of forming a title page. - - @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 - Copyright @copyright{} YEAR COPYRIGHT-OWNER - - Published by ... - - Permission is granted to ... - @end titlepage - - @node Top, Overview, (dir), (dir) - - @ifinfo - This document describes ... - - This document applies to version ... - of the program named ... - @end ifinfo - - @menu - * Copying:: Your rights and freedoms. - * First Chapter:: Getting started ... - * Second Chapter:: ... - ... - ... - @end menu - - @node First Chapter, Second Chapter, top, top - @comment node-name, next, previous, up - @chapter First Chapter - @cindex Index entry for First Chapter - - -File: texi.info, Node: Header, Next: Info Summary and Permissions, Prev: Sample Beginning, Up: Beginning a File - -The 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. If you want to run -TeX on just a part of the Texinfo File, you must write the `@settitle' -and `@setfilename' lines between start-of-header and end-of-header -lines. - - Thus, the beginning of a Texinfo file looks like this: - - \input texinfo @c -*-texinfo-*- - @setfilename sample.info - @settitle Sample Document - -or else like this: - - \input texinfo @c -*-texinfo-*- - @c %**start of header - @setfilename sample.info - @settitle Sample Document - @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. -* setchapternewpage:: Start chapters on right-hand pages. -* paragraphindent:: An option to specify paragraph indentation. -* End of Header:: Formatting a region requires this. - - -File: texi.info, Node: First Line, Next: Start of Header, Up: Header - -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 is usually located - in the `/usr/lib/tex/macros' directory. TeX uses the backslash, - `\', to mark the beginning of a command, just 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: texi.info, Node: Start of Header, Next: setfilename, Prev: First Line, Up: Header - -Start of Header ---------------- - - Write a 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 command lines, such as `@smallbook' -or `@footnotestyle'; and then by an end-of-header line (*note End of -Header::.). - - With these lines, you can format part of a Texinfo file for Info or -typeset part for printing. - - A start-of-header line looks like this: - - @c %**start of header - - The odd string of characters, `%**', is to ensure that no other -comment is accidentally taken for a start-of-header line. - - -File: texi.info, Node: setfilename, Next: settitle, Prev: Start of Header, Up: Header - -`@setfilename' --------------- - - In order to be made into an Info file, 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 a comment. - - The `@setfilename' line specifies the name of the Info file to be -generated. This name should be different from the name of the Texinfo -file. The convention is to write a name with a `.info' extension, to -produce an Info file name such as `texinfo.info'. - - 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 -Files and Split Files: Tag and Split Files.) The subfile name -`texinfo.info-10', for example, is too long for some systems; so the -Info file name for this document is actually `texinfo' rather than -`texinfo.info'. - - 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 need to be commented out. The `@setfilename' -line is ignored when you typeset a printed manual. - - -File: texi.info, Node: settitle, Next: setchapternewpage, Prev: setfilename, Up: Header - -`@settitle' ------------ - - 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 a -comment. - - Conventionally, TeX formats a Texinfo file for double-sided output -so as to print the title in the left-hand (even-numbered) page headings -and the current chapter titles in the right-hand (odd-numbered) page -headings. (TeX learns the title of each chapter from each `@chapter' -command.) Page footers are not 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. - - The `@settitle' command should precede everything that generates -actual output in TeX. - - Although the title in the `@settitle' command is usually the same as -the title on the title page, it does not affect the title as it appears -on the title page. Thus, the two do not need not match exactly; and -the title in the `@settitle' command can be a shortened or expanded -version of the title as it appears on the title page. (*Note -`@titlepage': titlepage.) - - 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 Page Headings: Headings, for a detailed discussion of -this process. - - -File: texi.info, Node: setchapternewpage, Next: paragraphindent, Prev: settitle, Up: Header - -`@setchapternewpage' --------------------- - - In a book or a manual, 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 typeset -pages 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. (You can - override the headers format with the `@headings double' command; - see *Note The `@headings' Command: headings on off.) - -`@setchapternewpage on' - Cause TeX to start new chapters on new pages and to typeset page - headers for single-sided printing. This is the form most often - used for short reports. - - This alternative 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. - -(You can countermand or modify an `@setchapternewpage' command with an -`@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 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. - - Usually, you do not write an `@setchapternewpage' command for -single-sided printing, but accept the default which is to typeset for -single-sided printing and to start new chapters on new pages. Usually, -you write an `@setchapternewpage odd' command for double-sided printing. - - -File: texi.info, Node: paragraphindent, Next: End of Header, Prev: setchapternewpage, Up: Header - -Paragraph Indenting -------------------- - - The Info formatting commands may insert spaces at the beginning of -the first line of each paragraph, thereby indenting that paragraph. You -can use the `@paragraphindent' command to specify the indentation. -Write an `@paragraphindent' command at the beginning of a line followed -by either `asis' or a number. The template is: - - @paragraphindent INDENT - - The Info formatting commands indent according to the value of INDENT: - - * If the value of INDENT is `asis', the Info formatting commands do - not change the existing indentation. - - * If the value of INDENT is 0, the Info formatting commands delete - existing indentation. - - * If the value of INDENT is greater than 0, the Info formatting - commands indent the paragraph by that number of spaces. - - The default value of INDENT is `asis'. - - Write the `@paragraphindent' command before or shortly after the -end-of-header line at the beginning of a Texinfo file. (If you write -the command between the start-of-header and end-of-header lines, the -region formatting commands indent paragraphs as specified.) - - A peculiarity of `texinfo-format-buffer' and `texinfo-format-region' -is that they do not indent (nor fill) paragraphs that contain `@w' or -`@*' commands. *Note Refilling Paragraphs::, for a detailed -description of what goes on. - - -File: texi.info, Node: End of Header, Prev: paragraphindent, Up: Header - -End of Header -------------- - - Follow the header lines with an end-of-header line. An -end-of-header line looks like this: - - @c %**end of header - - If you include the `@setchapternewpage' command between the -start-of-header and end-of-header lines, TeX will typeset a region as -that command specifies. Similarly, if you include an `@smallbook' -command between the start-of-header and end-of-header lines, TeX will -typeset a region in the "small" book format. - - The reason for the odd string of characters (`%**') is so that the -`texinfo-tex-region' command does not accidentally find something that -it should not when it is looking for the header. - - The start-of-header line and the end-of-header line are Texinfo mode -variables that you can change. - - -File: texi.info, Node: Info Summary and Permissions, Next: Titlepage & Copyright Page, Prev: Header, Up: Beginning a File - -Summary and Copying Permissions for Info -======================================== - - The title page and the copyright page appear only in the printed -copy of the manual; therefore, the same information must be inserted in -a section that appears only in the Info file. This section usually -contains a brief description of the contents of the Info file, a -copyright notice, and copying permissions. - - The copyright notice should read: - - Copyright YEAR COPYRIGHT-OWNER - -and be put on a line by itself. - - Standard text for the copyright permissions is contained in an -appendix to this manual; see *Note `ifinfo' Copying Permissions: ifinfo -Permissions, for the complete text. - - The permissions text appears in an Info file *before* the first -node. This mean that a reader does *not* see this text when reading -the file using Info, except when using the advanced Info command `g *'. - - -File: texi.info, Node: Titlepage & Copyright Page, Next: The Top Node, Prev: Info Summary and Permissions, Up: Beginning a File - -The Title and Copyright Pages -============================= - - A manual's name and author are usually printed on a title page. -Sometimes copyright information is printed on the title page as well; -more often, copyright information is 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 will appear in the -printed manual. - - *Note Titlepage Copying Permissions: Titlepage Permissions, for the -standard text for the copyright permissions. - -* 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 & Permissions:: 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. - diff --git a/gnu/usr.bin/texinfo/info-files/texi.info-3 b/gnu/usr.bin/texinfo/info-files/texi.info-3 deleted file mode 100644 index 1058a1a..0000000 --- a/gnu/usr.bin/texinfo/info-files/texi.info-3 +++ /dev/null @@ -1,1262 +0,0 @@ -This is Info file texi.info, produced by Makeinfo-1.55 from the input -file texi.texi. - - This file documents Texinfo, a documentation system that uses a -single source file to produce both on-line information and a printed -manual. - - Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation, -Inc. - - This is the second edition of the Texinfo documentation, -and is consistent with version 2 of `texinfo.tex'. - - 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 Free Software Foundation. - - -File: texi.info, Node: titlepage, Next: titlefont center sp, Up: Titlepage & Copyright Page - -`@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 of page headings.) All the material that you want to appear -on unnumbered pages should be put between the `@titlepage' and `@end -titlepage' commands. 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 `@top': makeinfo top.) - - Texinfo provides two 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. - - ---------- Footnotes ---------- - - (1) We have found that it is helpful to refer to versions of -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: texi.info, Node: titlefont center sp, Next: title subtitle author, Prev: titlepage, Up: Titlepage & Copyright Page - -`@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. - - 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 1/2 by 11 inch manual. - - -File: texi.info, Node: title subtitle author, Next: Copyright & Permissions, Prev: titlefont center sp, Up: Titlepage & Copyright Page - -`@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. - - 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. - - 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 - -Contrast this form with the form of a title page written using the -`@sp', `@center', and `@titlefont' commands: - - @titlepage - @sp 10 - @center @titlefont{Name of Manual When Printed} - @sp 2 - @center Subtitle, If Any - @sp 1 - @center Second subtitle - @sp 2 - @center Author - @page - ... - @end titlepage - - -File: texi.info, Node: Copyright & Permissions, Next: end titlepage, Prev: title subtitle author, Up: Titlepage & Copyright Page - -Copyright Page and Permissions ------------------------------- - - By international treaty, the copyright notice for a book should be -either on the title page or on the back of the title page. The -copyright notice should include the year followed by the name of the -organization or person who owns the copyright. - - 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, you can write a somewhat mysterious line after the -`@page' command that reads like this: - - @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 the correct usage in TeX. - - In a printed manual, the `@copyright{}' command generates a `c' -inside a circle. (In Info, it generates `(C)'.) The copyright notice -itself has the following legally defined sequence: - - Copyright (C) YEAR COPYRIGHT-OWNER - - It is customary to put information on how to get a manual after the -copyright notice, followed by the copying permissions for the manual. - - Note that permissions must be given here as well as in the summary -segment within `@ifinfo' and `@end ifinfo' that immediately follows the -header since this text appears only in the printed manual and the -`ifinfo' text appears only in the Info file. - - *Note Sample Permissions::, for the standard text. - - -File: texi.info, Node: end titlepage, Next: headings on off, Prev: Copyright & Permissions, Up: Titlepage & Copyright Page - -Heading Generation ------------------- - - An `@end titlepage' command on a line by itself 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). (*Note `@setchapternewpage': setchapternewpage.) 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': 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: texi.info, Node: headings on off, Prev: end titlepage, Up: Titlepage & Copyright Page - -The `@headings' Command ------------------------ - - The `@headings' command is rarely used. It specifies what kind of -page headings and footings to print on each page. Usually, this is -controlled by the `@setchapternewpage' command. You need the -`@headings' command only if the `@setchapternewpage' command does not -do what you want, or if you want to turn off pre-defined page headings -prior to defining your own. Write an `@headings' command immediately -after the `@end titlepage' command. - - There are four ways to use the `@headings' command: - -`@headings off' - Turn off printing of page headings. - -`@headings single' - Turn on page headings appropriate for single-sided printing. - -`@headings double' -`@headings on' - Turn on page headings appropriate for double-sided printing. The - two commands, `@headings on' and `@headings double', are - synonymous. - - 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: texi.info, Node: The Top Node, Next: Software Copying Permissions, Prev: Titlepage & Copyright Page, Up: Beginning a File - -The `Top' Node and Master Menu -============================== - - The `Top' node is the node from which you enter an Info file. - - A `Top' node should contain a brief description of the Info file and -an extensive, master menu for the whole Info file. This helps the -reader understand what the Info file is about. Also, you should write -the version number of the program to which the Info file applies; or, -at least, the edition number. - - The contents of the `Top' node should appear only in the Info file; -none of it should appear in printed output, so enclose it between -`@ifinfo' and `@end ifinfo' 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 `@ifinfo' and `@end -ifinfo', but it is simplest to do so. *Note Conditionally Visible -Text: Conditionals.) - -* Menu: - -* Title of Top Node:: Sketch what the file is about. -* Master Menu Parts:: A master menu has three or more parts. - - -File: texi.info, Node: Title of Top Node, Next: Master Menu Parts, Up: The Top Node - -`Top' Node Title ----------------- - - Sometimes, you will want to place 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., for -more information). - - For example, the beginning of the Top node of this manual contains an -`@top' sectioning command, a short description, and edition and version -information. It looks like this: - - ... - @end titlepage - - @ifinfo - @node Top, Copying, (dir), (dir) - @top Texinfo - - Texinfo is a documentation system... - - This is edition... - ... - @end ifinfo - - @menu - * Copying:: Texinfo is freely - redistributable. - * Overview:: What is Texinfo? - ... - @end menu - - In a `Top' node, the `Previous', and `Up' nodes usually refer to the -top level directory of the whole Info system, which is called `(dir)'. -The `Next' node refers to the first node that follows the main or master -menu, which is usually the copying permissions, introduction, or first -chapter. - - -File: texi.info, Node: Master Menu Parts, Prev: Title of Top Node, Up: The Top Node - -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. - - 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:: Texinfo is freely - redistributable. - * Overview:: What is Texinfo? - * Texinfo Mode:: Special features in GNU Emacs. - ... - ... - * Command and Variable Index:: - An entry for each @-command. - * Concept Index:: An entry for each concept. - - --- The Detailed Node Listing --- - - Overview of Texinfo - - * Info Files:: What is an Info file? - * Printed Manuals:: Characteristics of - a printed manual. - ... - ... - - Using Texinfo Mode - - * Info on a Region:: Formatting part of a file - for Info. - ... - ... - @end menu - - -File: texi.info, Node: Software Copying Permissions, Prev: The Top Node, Up: Beginning a File - -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, this section usually follows 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. -Usually, an introduction is put in an `@unnumbered' section. (*Note -The `@unnumbered' and `@appendix' Commands: unnumbered & appendix.) - - -File: texi.info, Node: Ending a File, Next: Structuring, Prev: Beginning a File, Up: Top - -Ending a Texinfo File -********************* - - The end of a Texinfo file should include the commands that create -indices and generate detailed and summary tables of contents. And it -must include the `@bye' command that marks the last line processed by -TeX. - - For example: - - @node Concept Index, , Variables Index, Top - @c node-name, next, previous, up - @unnumbered Concept Index - - @printindex cp - - @contents - @bye - -* Menu: - -* Printing Indices & Menus:: How to print an index in hardcopy and - generate index menus in Info. -* Contents:: How to create a table of contents. -* File End:: How to mark the end of a file. - - -File: texi.info, Node: Printing Indices & Menus, Next: Contents, Up: Ending a File - -Index Menus and Printing an Index -================================= - - 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 Format/Print 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 different types of predefined index: the concept -index, the function index, the variables index, the keystroke index, the -program index, and the data type index (*note Predefined Indices::.). -Each index type has a two-letter name: `cp', `fn', `vr', `ky', `pg', -and `tp'. You may merge indices, or put them into separate sections -(*note Combining Indices::.); or you may define your own indices (*note -Defining New Indices: New Indices.). - - The `@printindex' command takes a two-letter index name, reads the -corresponding sorted index file and formats it appropriately into an -index. - - The `@printindex' command does not generate a chapter heading for -the index. Consequently, you should precede the `@printindex' command -with a suitable section or chapter command (usually `@unnumbered') to -supply the chapter heading and put the index into the table of -contents. Precede the `@unnumbered' command with an `@node' line. - - For example: - - @node Variable Index, Concept Index, Function Index, Top - @comment node-name, next, previous, up - @unnumbered Variable Index - - @printindex vr - - @node Concept Index, , Variable Index, Top - @comment node-name, next, previous, up - @unnumbered Concept Index - - @printindex cp - - @summarycontents - @contents - @bye - -(Readers often prefer that the concept index come last in a book, since -that makes it easiest to find.) - - -File: texi.info, Node: Contents, Next: File End, Prev: Printing Indices & Menus, Up: Ending a File - -Generating a Table of Contents -============================== - - The `@chapter', `@section', and other structuring commands 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 `@summarycontents' commands: - -`@contents' - Generate a table of contents in a printed manual, including all - chapters, sections, subsections, etc., as well as appendices and - unnumbered chapters. (Headings generated by the `@heading' series - of commands do not appear in the table of contents.) The - `@contents' command should be written on a line by itself. - -`@shortcontents' -`@summarycontents' - (`@summarycontents' is a synonym for `@shortcontents'; the two - commands are exactly the same.) - - Generate a short or summary table of contents that lists only the - chapters (and appendices and unnumbered chapters). Omit sections, - subsections and subsubsections. Only a long manual needs a short - table of contents in addition to the full table of contents. - - Write the `@shortcontents' command on a line by itself right - *before* the `@contents' command. - - The table of contents commands automatically generate a chapter-like -heading at the top of the first table of contents page. Write the table -of contents commands at the very end of a Texinfo file, just before the -`@bye' command, following any index sections--anything in the Texinfo -file after the table of contents commands will be omitted from the -table of contents. - - When you print a manual with a table of contents, the table of -contents are printed last and numbered with roman numerals. You need -to place those pages in their proper place, after the title page, -yourself. (This is the only collating you need to do for a printed -manual. The table of contents is printed last because it is generated -after the rest of the manual is typeset.) - - Here is an example of where to write table of contents commands: - - INDICES... - @shortcontents - @contents - @bye - - Since an Info file uses menus instead of tables of contents, the Info -formatting commands ignore the `@contents' and `@shortcontents' -commands. - - -File: texi.info, Node: File End, Prev: Contents, Up: Ending a File - -`@bye' File Ending -================== - - An `@bye' command terminates TeX or Info formatting. None of the -formatting commands see any of the file 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. *Note Using Local Variables and the Compile Command: -Compile-Command, for more information. - - -File: texi.info, Node: Structuring, Next: Nodes, Prev: Ending a File, Up: Top - -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. - - -File: texi.info, Node: Tree Structuring, Next: Structuring Command Types, Up: Structuring - -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: texi.info, Node: Structuring Command Types, Next: makeinfo top, Prev: Tree Structuring, Up: Structuring - -Types of Structuring Command -============================ - - 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.). - - * The `@heading' series of commands produce unnumbered headings that - do not appear in a table of contents. The heading commands never - start a new page. - - * The `@majorheading' command produces results similar to using the - `@chapheading' command but 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 pages - Numbered Unnumbered Lettered and 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: texi.info, Node: makeinfo top, Next: chapter, Prev: Structuring Command Types, Up: Structuring - -`@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. It has the same typesetting effect as `@unnumbered' (*note -`@unnumbered': (`@appendix')unnumbered & appendix.). For detailed -information, see *Note The `@top' Command: makeinfo top command. - - -File: texi.info, Node: chapter, Next: unnumbered & appendix, Prev: makeinfo top, Up: Structuring - -`@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 - ******************* - - -File: texi.info, Node: unnumbered & appendix, Next: majorheading & chapheading, Prev: chapter, Up: Structuring - -`@unnumbered', `@appendix' -========================== - - Use the `@unnumbered' command to create a chapter that appears in a -printed manual without chapter numbers of any kind. Use the -`@appendix' command to create an appendix in a printed manual that is -labelled by letter instead of by number. - - For Info file output, the `@unnumbered' and `@appendix' commands are -equivalent to `@chapter': the title is printed on a line by itself with -a line of asterisks underneath. (*Note `@chapter': chapter.) - - To create an appendix or an unnumbered chapter, write an `@appendix' -or `@unnumbered' command at the beginning of a line and follow it on -the same line by the title, as you would if you were creating a chapter. - - -File: texi.info, Node: majorheading & chapheading, Next: section, Prev: unnumbered & appendix, Up: Structuring - -`@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: texi.info, Node: section, Next: unnumberedsec appendixsec heading, Prev: majorheading & chapheading, Up: Structuring - -`@section' -========== - - In a printed manual, an `@section' command identifies a numbered -section within a chapter. The section title appears in the table of -contents. In Info, an `@section' command provides a title for a -segment of text, underlined with `='. - - This section is headed with an `@section' command and looks like -this in the Texinfo file: - - @section @code{@@section} - - To create a section, write the `@section' command at the beginning -of a line and follow it on the same line by the section title. - - Thus, - - @section This is a section - -produces - - This is a section - ================= - -in Info. - - -File: texi.info, Node: unnumberedsec appendixsec heading, Next: subsection, Prev: section, Up: Structuring - -`@unnumberedsec', `@appendixsec', `@heading' -============================================ - - The `@unnumberedsec', `@appendixsec', and `@heading' commands are, -respectively, the unnumbered, appendix-like, and heading-like -equivalents of the `@section' command. (*Note `@section': 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. - - -File: texi.info, Node: subsection, Next: unnumberedsubsec appendixsubsec subheading, Prev: unnumberedsec appendixsec heading, Up: Structuring - -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 - - This is a subsection - -------------------- - - In a printed manual, subsections are listed in the table of contents -and are numbered three levels deep. - - -File: texi.info, Node: unnumberedsubsec appendixsubsec subheading, Next: subsubsection, Prev: subsection, Up: Structuring - -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. - - -File: texi.info, Node: subsubsection, Prev: unnumberedsubsec appendixsubsec subheading, Up: Structuring - -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. - - In Info, `subsub' titles are underlined with periods. For example, - - @subsubsection This is a subsubsection - -produces - - This is a subsubsection - ....................... - - -File: texi.info, Node: Nodes, Next: Menus, Prev: Structuring, Up: Top - -Nodes -***** - - "Nodes" are the primary segments of a Texinfo file. They do not -themselves impose a hierarchic 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. - -* Menu: - -* Two Paths:: Different commands to structure - Info output and printed output. -* Node Menu Illustration:: A diagram, and sample nodes and menus. -* node:: How to write a node, in detail. -* makeinfo Pointer Creation:: How to create node pointers with `makeinfo'. - - -File: texi.info, Node: Two Paths, Next: Node Menu Illustration, Up: Nodes - -Two Paths -========= - - The node and menu commands and the chapter structuring commands are -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, most Texinfo -files are written such that the structure for the Info output -corresponds to the structure for the printed output. It is not -convenient 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: texi.info, Node: Node Menu Illustration, Next: node, Prev: Two Paths, Up: Nodes - -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. - - Note that 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 - - Write the beginning of the node for Chapter 2 like 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". - - *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 may follow a - chapter-level node, and a subsection-level node may follow a - section-level node. `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: texi.info, Node: node, Next: makeinfo Pointer Creation, Prev: Node Menu Illustration, Up: Nodes - -The `@node' Command -=================== - - A "node" is a segment of text that begins at an `@node' command and -continues until the next `@node' command. The definition of node is -different from that for chapter or section. A chapter may contain -sections and a section may contain subsections; but a node cannot -contain subnodes; the text of a node continues only until the next -`@node' command in the file. A node usually contains only one chapter -structuring command, the one that follows the `@node' line. On the -other hand, in printed output nodes are used only for cross references, -so a chapter or section may contain any number of nodes. Indeed, a -chapter usually contains several nodes, one for each section, -subsection, and subsubsection. - - To create a node, write an `@node' command at the beginning of a -line, and follow it with four arguments, separated by commas, on the -rest of the same line. These arguments are the name of the node, and -the names of the `Next', `Previous', and `Up' pointers, in that order. -You may insert spaces before each pointer if you wish; the spaces are -ignored. You must write the name of the node, and 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 Types of Structuring Command: Structuring -Command Types.) - - *Please note:* The GNU Emacs Texinfo mode updating commands work - only with Texinfo files in which `@node' lines are followed by - chapter structuring lines. *Note Updating Requirements::. - - TeX uses `@node' lines to identify the names to use for cross -references. For this reason, you must write `@node' lines in a Texinfo -file that you intend to format for printing, even if you do not intend -to format it for Info. (Cross references, such as the one at the end -of this sentence, are made with `@xref' and its 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. -* Top Node Summary:: Write a brief description for readers. - - -File: texi.info, Node: Node Names, Next: Writing a Node, Up: node - -Choosing Node and Pointer Names -------------------------------- - - The name of a node identifies the node. The pointers enable you to -reach other nodes and consist of the names of those nodes. - - Normally, a node's `Up' pointer contains the name of the node whose -menu mentions that node. The node's `Next' pointer contains the name -of the node that follows that node in that menu and its `Previous' -pointer contains the name of the node that precedes it in that menu. -When a node's `Previous' node is the same as its `Up' node, both node -pointers name the same node. - - Usually, the first node of a Texinfo file is the `Top' node, and its -`Up' and `Previous' pointers point to the `dir' file, which contains -the main menu for all of Info. - - The `Top' node itself contains the main or master menu for the -manual. Also, it is helpful to include a brief description of the -manual in the `Top' node. *Note First Node::, for information on how -to write the first node of a Texinfo file. - - -File: texi.info, Node: Writing a Node, Next: Node Line Tips, Prev: Node Names, Up: node - -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 node line with `Next', `Previous', and `Up' -pointers looks like this: - - @node NODE-NAME, NEXT, PREVIOUS, UP - - If you wish, you can ignore `@node' lines altogether in your first -draft and then use the `texinfo-insert-node-lines' command to create -`@node' lines for you. However, we do not recommend this practice. It -is better to name the node itself at the same time that you write a -segment so you can easily make cross references. A large number of -cross references are an especially important feature of a good Info -file. - - After you have inserted an `@node' line, you should immediately -write an @-command for the chapter or section and insert its name. -Next (and this is important!), put in several index entries. Usually, -you will find at least two and often as many as four or five ways of -referring to the node in the index. Use them all. This will make it -much easier for people to find the node. - - -File: texi.info, Node: Node Line Tips, Next: Node Line Requirements, Prev: Writing a Node, Up: node - -`@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. - diff --git a/gnu/usr.bin/texinfo/info-files/texi.info-4 b/gnu/usr.bin/texinfo/info-files/texi.info-4 deleted file mode 100644 index 8698ab6..0000000 --- a/gnu/usr.bin/texinfo/info-files/texi.info-4 +++ /dev/null @@ -1,1412 +0,0 @@ -This is Info file texi.info, produced by Makeinfo-1.55 from the input -file texi.texi. - - This file documents Texinfo, a documentation system that uses a -single source file to produce both on-line information and a printed -manual. - - Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation, -Inc. - - This is the second edition of the Texinfo documentation, -and is consistent with version 2 of `texinfo.tex'. - - 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 Free Software Foundation. - - -File: texi.info, Node: Node Line Requirements, Next: First Node, Prev: Node Line Tips, Up: node - -`@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. - - * You cannot use any of the Texinfo @-commands in a node name; - @-commands confuse Info. - - Thus, the beginning of the section called `@chapter' looks like - this: - - @node chapter, unnumbered & appendix, makeinfo top, Structuring - @comment node-name, next, previous, up - @section @code{@@chapter} - @findex chapter - - * You cannot use commas, colons, or apostrophes within a node name; - these confuse TeX or the Info formatters. - - For example, the following is a section title: - - @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading} - - The corresponding node name is: - - unnumberedsec appendixsec heading - - * Case is significant. - - -File: texi.info, Node: First Node, Next: makeinfo top command, Prev: Node Line Requirements, Up: node - -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 (which must be named `top' or `Top') should have as -its `Up' and `Previous' nodes the name of a node in another file, where -there is a menu that leads to this file. Specify the file name in -parentheses. If the file is to be installed directly in the Info -directory file, 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 Info. For example, the `@node Top' -line of this manual looks like this: - - @node Top, Overview, (dir), (dir) - -(You may use the Texinfo updating commands or the `makeinfo' utility to -insert these `Next' and `(dir)' pointers automatically.) - - *Note Install an Info File::, for more information about installing -an Info file in the `info' directory. - - The `Top' node contains the main or master menu for the document. - - -File: texi.info, Node: makeinfo top command, Next: Top Node Summary, Prev: First Node, Up: node - -The `@top' Sectioning Command ------------------------------ - - A special sectioning command, `@top', has been created for use 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. - - 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. - - Whatever sectioning command follows an `@node Top' line, whether it -be `@top' or `@chapter', the `@node Top' line and the immediately -following line and any additional text must be enclosed between -`@ifinfo' and `@end ifinfo' commands. (*Note Conditionals::.) This -prevents the title and the accompanying text from appearing in printed -output. Write the `@ifinfo' command before the `@node' line and write -the `@end ifinfo' command after the `@top' or other sectioning command -and after any additional text. (You can write the `@end ifinfo' -command after the `@end menu' command if you like.) - - -File: texi.info, Node: Top Node Summary, Prev: makeinfo top command, Up: node - -The `Top' Node Summary ----------------------- - - You can help readers by writing a summary in the `Top' node, after -the `@top' line, before the main or master menu. The summary should -briefly describe the Info file. You should also write the version -number of the program to which the manual applies in this section. This -helps the reader keep track of which manual is for which version of the -program. If the manual changes more frequently than the program or is -independent of it, you should also include an edition number for the -manual. (The title page should also contain this information: see -*Note `@titlepage': titlepage.) - - Put the whole of the `Top' node, including the `@top' sectioning -command line if you have one, between `@ifinfo' and `@end ifinfo' so -none of the text appears in the printed output (*note Conditionally -Visible Text: Conditionals.). (You may want to repeat the brief -description from the `Top' node within `@iftex' ... `@end iftex' at the -beginning of the first chapter, for those who read the printed manual.) - - -File: texi.info, Node: makeinfo Pointer Creation, Prev: node, Up: Nodes - -Creating Pointers with `makeinfo' -================================= - - The `makeinfo' program has a feature for automatically creating node -pointers for a hierarchically organized file that lacks them. - - 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. You cannot write a comment line after a node line; the section -line must follow it immediately. - - 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. - - This node pointer insertion feature in `makeinfo' is an alternative -to the menu and pointer creation and update commands in Texinfo mode. -(*Note Updating Nodes and Menus::.) It is especially helpful to people -who do not use GNU Emacs for writing Texinfo documents. - - -File: texi.info, Node: Menus, Next: Cross References, Prev: Nodes, Up: Top - -Menus -***** - - "Menus" contain pointers to subordinate nodes.(1) In Info, you use -menus to go to such nodes. Menus have no effect in printed manuals and -do not appear in them. - - By convention, a menu is put at the end of a node since a reader who -uses the menu may not see text that follows it. - - A node that has a menu should *not* contain much text. If you have -a lot of text and a menu, move most of the text into a new subnode--all -but a few lines. - -* Menu: - -* Menu Location:: Put a menu in a short node. -* 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. - - ---------- Footnotes ---------- - - (1) Menus can carry you to any node, regardless of the hierarchical -structure; even to nodes in a different Info file. However, the GNU -Emacs Texinfo mode updating commands work only to create menus of -subordinate nodes. Conventionally, cross references are used to refer -to other nodes. - - -File: texi.info, Node: Menu Location, Next: Writing a Menu, Up: Menus - -Menus Need Short Nodes -====================== - - A reader can easily see a menu that is close to the beginning of the -node. The node should be short. As a practical matter, you should -locate a menu within 20 lines of the beginning of the node. Otherwise, -a reader with a terminal that displays only a few lines may miss the -menu and its associated text. - - The short text before a menu may look awkward in a printed manual. -To avoid this, you can write a menu near the beginning of its node and -follow the menu by an `@node' line, and then an `@heading' line located -within `@ifinfo' and `@end ifinfo'. This way, the menu, `@node' line, -and title appear only in the Info file, not the printed document. - - For example, the preceding two paragraphs follow an Info-only menu, -`@node' line, and heading, and look like this: - - @menu - * Menu Location:: Put a menu in a short node. - * 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 entries. - * Other Info Files:: How to refer to a different - Info file. - @end menu - - @node Menu Location, Writing a Menu, , Menus - @ifinfo - @heading Menus Need Short Nodes - @end ifinfo - - The Texinfo file for this document contains more than a dozen -examples of this procedure. One is at the beginning of this chapter; -another is at the beginning of the "Cross References" chapter. - - -File: texi.info, Node: Writing a Menu, Next: Menu Parts, Prev: Menu Location, Up: Menus - -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. - - -File: texi.info, Node: Menu Parts, Next: Less Cluttered Menu Entry, Prev: Writing a Menu, Up: Menus - -The Parts of a Menu -=================== - - A menu entry has three parts, only the second of which is required: - - 1. The menu entry name. - - 2. The name of the node (required). - - 3. A description of the item. - - 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. The description, which -is optional, can spread over two or more lines. A useful description -complements the node name rather than repeats it. - - -File: texi.info, Node: Less Cluttered Menu Entry, Next: Menu Example, Prev: Menu Parts, Up: Menus - -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: texi.info, Node: Menu Example, Next: Other Info Files, Prev: Less Cluttered Menu Entry, Up: Menus - -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: texi.info, Node: Other Info Files, Prev: Menu Example, Up: Menus - -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 Install 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.) - - Note that 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: texi.info, Node: Cross References, Next: Marking Text, Prev: Menus, Up: Top - -Cross References -**************** - - "Cross references" are used to refer the reader to other parts of the -same or different Texinfo files. In Texinfo, nodes 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. - - -File: texi.info, Node: References, Next: Cross Reference Commands, Up: Cross References - -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 on-line 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 Some advanced Info commands: -(info)Help-Adv.) - - The various cross reference commands use nodes to define cross -reference locations. This is evident in Info, in which a cross -reference takes you to the specified node. TeX also uses nodes to -define cross reference locations, but the action is less obvious. When -TeX generates a DVI file, it records nodes' page numbers 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 on-line, you must -nonetheless write `@node' lines to name the places to which you make -cross references. - - -File: texi.info, Node: Cross Reference Commands, Next: Cross Reference Parts, Prev: References, Up: Cross References - -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 entry in the Info file saying `*Note ...'. - -`@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: texi.info, Node: Cross Reference Parts, Next: xref, Prev: Cross Reference Commands, Up: Cross References - -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 name (required). This is the node to which the cross - reference takes you. In a printed document, the location of the - node provides the page reference only for references within the - same document. - - 2. The cross reference name for the Info reference, if it is to be - different from the node name. If you include this argument, it - argument becomes the first part of the cross reference. It is - usually omitted. - - 3. A topic description or section name. Often, this is the title of - the section. This is used as the name of the reference in the - printed manual. If omitted, the node name is used. - - 4. The name of the Info file in which the reference is located, if it - is different from the current file. - - 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: texi.info, Node: xref, Next: Top Node Naming, Prev: Cross Reference Parts, Up: Cross References - -`@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: texi.info, Node: Reference Syntax, Next: One Argument, Up: xref - -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.) - - *Please note:* 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. - - *Please 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: texi.info, Node: One Argument, Next: Two Arguments, Prev: Reference Syntax, Up: xref - -`@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. - - 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: texi.info, Node: Two Arguments, Next: Three Arguments, Prev: One Argument, Up: xref - -`@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: texi.info, Node: Three Arguments, Next: Four and Five Arguments, Prev: Two Arguments, Up: xref - -`@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 -a `@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 GAWK Manual': - - @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: texi.info, Node: Four and Five Arguments, Prev: Three Arguments, Up: xref - -`@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: texi.info, Node: Top Node Naming, Next: ref, Prev: xref, Up: Cross References - -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: texi.info, Node: ref, Next: pxref, Prev: Top Node Naming, Up: Cross References - -`@ref' -====== - - `@ref' is nearly the same as `@xref' except that it does not -generate a `See' in the printed output, just the reference itself. -This makes it useful as the last part of a sentence. - -For example, - - For more information, see @ref{Hurricanes}. - -produces - - For more information, see *Note Hurricanes. - -and - - For more information, see Section 8.2 [Hurricanes], page 123. - - The `@ref' command sometimes leads 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}. - -produces - - Sea surges are described in Section 6.7 [Hurricanes], page 72. - -in a printed document, and the following in Info: - - Sea surges are described in *Note Hurricanes::. - - *Caution:* You *must* write a period or comma immediately after an - `@ref' command with two or more arguments. Otherwise, Info will - not find the end of the cross reference entry and its attempt to - follow the cross reference will fail. As a general rule, you - should write a period or comma after every `@ref' command. This - looks best in both the printed and the Info output. - - -File: texi.info, Node: pxref, Next: inforef, Prev: ref, Up: Cross References - -`@pxref' -======== - - The parenthetical reference command, `@pxref', is nearly the same as -`@xref', but you use it *only* inside parentheses and you do *not* type -a comma or period after the command's closing brace. The command -differs from `@xref' in two ways: - - 1. TeX typesets the reference for the printed manual with a lower case - `see' rather than an upper case `See'. - - 2. The Info formatting commands automatically end the reference with a - closing colon or period. - - Because one type of formatting automatically inserts closing -punctuation and the other does not, you should use `@pxref' *only* -inside parentheses as part of another sentence. Also, you yourself -should not insert punctuation after the reference, as you do with -`@xref'. - - `@pxref' is designed so that the output looks right and works right -between parentheses both in printed output and in an Info file. In a -printed manual, a closing comma or period should not follow a cross -reference within parentheses; such punctuation is wrong. But in an -Info file, suitable closing punctuation must follow the cross reference -so Info can recognize its end. `@pxref' spares you the need to use -complicated methods to put a terminator into one form of the output and -not the other. - -With one argument, a parenthetical cross reference looks like this: - - ... storms cause flooding (@pxref{Hurricanes}) ... - -which produces - - ... storms cause flooding (*Note Hurricanes::) ... - -and - - ... storms cause flooding (see Section 6.7 [Hurricanes], page 72) - ... - - With two arguments, a parenthetical cross reference has this -template: - - ... (@pxref{NODE-NAME, CROSS-REFERENCE-NAME}) ... - -which produces - - ... (*Note CROSS-REFERENCE-NAME: NODE-NAME.) ... - -and - - ... (see Section NNN [NODE-NAME], page PPP) ... - - `@pxref' can be used with up to five arguments just like `@xref' -(*note `@xref': xref.). - - *Please note:* Use `@pxref' only as a parenthetical reference. Do - not try to use `@pxref' as a clause in a sentence. It will look - bad in either the Info file, the printed output, or both. - - Also, parenthetical cross references look best at the ends of - sentences. Although you may write them in the middle of a - sentence, that location breaks up the flow of text. - - -File: texi.info, Node: inforef, Prev: pxref, Up: Cross References - -`@inforef' -========== - - `@inforef' is used for cross references to Info files for which -there are no printed manuals. Even in a printed manual, `@inforef' -generates a reference directing the user to look in an Info file. - - The command takes either two or three arguments, in the following -order: - - 1. The node name. - - 2. The cross reference name (optional). - - 3. The Info file name. - -Separate the arguments with commas, as with `@xref'. Also, you must -terminate the reference with a comma or period after the `}', as you do -with `@xref'. - -The template is: - - @inforef{NODE-NAME, CROSS-REFERENCE-NAME, INFO-FILE-NAME}, - -Thus, - - @inforef{Expert, Advanced Info commands, info}, - for more information. - -produces - - *Note Advanced Info commands: (info)Expert, - for more information. - -and - - See Info file `info', node `Expert', for more information. - -Similarly, - - @inforef{Expert, , info}, for more information. - -produces - - *Note (info)Expert::, for more information. - -and - - See Info file `info', node `Expert', for more information. - - The converse of `@inforef' is `@cite', which is used to refer to -printed works for which no Info form exists. *Note `@cite': cite. - - -File: texi.info, Node: Marking Text, Next: Quotations and Examples, Prev: Cross References, Up: Top - -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. - -* Menu: - -* Indicating:: How to indicate definitions, files, etc. -* Emphasis:: How to emphasize text. - - -File: texi.info, Node: Indicating, Next: Emphasis, Up: Marking Text - -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 effect 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:: How to indicate code. -* kbd:: How to show keyboard input. -* key:: How to specify keys. -* samp:: How to show a literal sequence of characters. -* var:: How to indicate a metasyntactic variable. -* file:: How to indicate the name of a file. -* dfn:: How to specify a definition. -* cite:: How to refer to a book that is not in Info. - - -File: texi.info, Node: Useful Highlighting, Next: code, Up: Indicating - -Highlighting Commands are Useful --------------------------------- - - The highlighting commands can be used to generate useful information -from the file, such as lists of functions or file names. It is -possible, for example, to write a program in Emacs Lisp (or a keyboard -macro) to insert an index entry after every paragraph that contains -words or phrases marked by a specified command. You could do this to -construct an index of functions if you had not already made the entries. - - The commands serve a variety of purposes: - -`@code{SAMPLE-CODE}' - Indicate text that is a literal example of a piece of a program. - -`@kbd{KEYBOARD-CHARACTERS}' - Indicate keyboard input. - -`@key{KEY-NAME}' - Indicate the conventional name for a key on a keyboard. - -`@samp{TEXT}' - Indicate text that is a literal example of a sequence of - characters. - -`@var{METASYNTACTIC-VARIABLE}' - Indicate a metasyntactic variable. - -`@file{FILE-NAME}' - Indicate the name of a file. - -`@dfn{TERM}' - Indicate the introductory or defining use of a term. - -`@cite{REFERENCE}' - Indicate the name of a book. - - -File: texi.info, Node: code, Next: kbd, Prev: Useful Highlighting, Up: Indicating - -`@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. -Also, you should use `@code' for the name of a program, such as `diff', -that is a name used in the machine. (You should write the name of a -program in the ordinary text font if you regard it as a new English -word, such as `Emacs' or `Bison'.) - - Use `@code' for environment variables such as `TEXINPUTS', and other -variables. - - Use `@code' for command names in command languages that resemble -programming languages, such as Texinfo or the shell. For example, -`@code' and `@samp' are produced by writing `@code{@@code}' and -`@code{@@samp}' in the Texinfo source, respectively. - - Note, however, that you should not use `@code' for shell options -such as `-c' when such options stand alone. (Use `@samp'.) 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. - - 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 written all in lower case, you should rearrange the -sentence. - - Do not use the `@code' command for a string of characters shorter -than a syntactic token. If you are writing about `TEXINPU', which is -just a part of the name for the `TEXINPUTS' environment variable, you -should use `@samp'. - - In particular, you should not use the `@code' command when writing -about the characters used in a token; do not, for example, 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. - - 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, - - Use @code{diff} to compare two files. - -produces this in the printed manual: - - Use `diff' to compare two files. - - -File: texi.info, Node: kbd, Next: key, Prev: code, Up: Indicating - -`@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} - - The `@kbd' command has the same effect as `@code' in Info, but may -produce a different font in a printed manual. - - 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 an `r' and then press the -RET key": - - @kbd{r @key{RET}} - -This produces: `r RET' - - 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 really want to mention a space character as one of the characters of -input, write `@key{SPC}' for it.) - - -File: texi.info, Node: key, Next: samp, Prev: kbd, Up: Indicating - -`@key'{KEY-NAME} ----------------- - - Use the `@key' command for the conventional name for a key on a -keyboard, as in: - - @key{RET} - - You can use the `@key' command within the argument of an `@kbd' -command when the sequence of characters to be typed includes one or -more keys that are described by name. - - For example, to produce `C-x ESC' you would type: - - @kbd{C-x @key{ESC}} - - Here is a list of the recommended names for keys; they are all in -upper case: - - SPC - Space - - RET - Return - - LFD - Linefeed - - TAB - Tab - - BS - Backspace - - ESC - Escape - - DEL - Delete - - SFT - Shift - - CTL - Control - - META - Meta - - There are subtleties to handling words like `meta' or `ctl' that are -names of shift keys. When mentioning a character in which the shift -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 shift key in -isolation, use the `@key' command. For example, write `@kbd{Meta-a}' -to produce `Meta-a' and `@key{META}' to produce META. This is because -`Meta-a' refers to keys that you press on a keyboard, but META refers -to a key without implying that you press it. In short, use `@kbd' for -what you do, and use `@key' for what you talk about: "Press `@kbd{M-a}' -to move point to the beginning of the sentence. The `@key{META}' key -is often in the lower left of the keyboard." - - -File: texi.info, Node: samp, Next: var, Prev: key, Up: Indicating - -`@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' is more appropriate. Use `@samp' for the names -of command-line options. 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'. - diff --git a/gnu/usr.bin/texinfo/info-files/texi.info-5 b/gnu/usr.bin/texinfo/info-files/texi.info-5 deleted file mode 100644 index 84b7295..0000000 --- a/gnu/usr.bin/texinfo/info-files/texi.info-5 +++ /dev/null @@ -1,1433 +0,0 @@ -This is Info file texi.info, produced by Makeinfo-1.55 from the input -file texi.texi. - - This file documents Texinfo, a documentation system that uses a -single source file to produce both on-line information and a printed -manual. - - Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation, -Inc. - - This is the second edition of the Texinfo documentation, -and is consistent with version 2 of `texinfo.tex'. - - 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 Free Software Foundation. - - -File: texi.info, Node: var, Next: file, Prev: samp, Up: Indicating - -`@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. For example, the Lisp variable -`texinfo-tex-command' is not a metasyntactic variable; it is properly -formatted using `@code'. - - The effect of `@var' in the Info file is to change the case of the -argument to all upper case; in the printed manual, to italicize it. - - For example, - - To delete file @var{filename}, - type @code{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 TeX and the Info formatting commands to output -the `<...>' format if you wish.) - - -File: texi.info, Node: file, Next: dfn, Prev: var, Up: Indicating - -`@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: texi.info, Node: dfn, Next: cite, Prev: file, Up: Indicating - -`@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: texi.info, Node: cite, Prev: dfn, Up: Indicating - -`@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: texi.info, Node: Emphasis, Prev: Indicating, Up: Marking Text - -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 affect 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: texi.info, Node: emph & strong, Next: Smallcaps, Up: Emphasis - -`@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, - - @quotation - @strong{Caution:} @code{rm * .[^.]*} removes @emph{all} - files in the directory. - @end quotation - -produces: - - *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 file, both `@emph' and `@strong' put asterisks around -the text. - - *Caution:* Do not use `@emph' or `@strong' with the word `Note'; - Info will mistake the combination for a cross reference. Use a - phrase such as *Please note* or *Caution* instead. - - -File: texi.info, Node: Smallcaps, Next: Fonts, Prev: emph & strong, Up: Emphasis - -`@sc'{TEXT}: The Small Caps Font --------------------------------- - - Use the `@sc' command to set text in the printed output in a small -caps font and set text in the Info file in upper case letters. - - Write the text between braces in lower case, like this: - - The @sc{acm} and @sc{ieee} are technical societies. - -This produces: - - The ACM and IEEE are technical societies. - - TeX typesets the small caps font in a manner that prevents the -letters from `jumping out at you on the page'. This makes small caps -text easier to read than text in all upper case. The Info formatting -commands set all small caps text in upper case. - - If the text between the braces of an `@sc' command is upper case, -TeX typesets in full-size capitals. Use full-size capitals sparingly. - - You may also use the small caps font for a jargon word such as ATO -(a NASA word meaning `abort to orbit'). - - There are subtleties to using the small caps font with a jargon word -such as CDR, a word used in Lisp programming. In this case, you should -use the small caps font when the word refers to the second and -subsequent elements of a list (the CDR of the list), but you should use -`@code' when the word refers to the Lisp function of the same spelling. - - -File: texi.info, Node: Fonts, Prev: Smallcaps, Up: Emphasis - -Fonts for Printing, Not Info ----------------------------- - - Texinfo provides four font commands that specify font changes in the -printed manual but have no effect in the Info file. `@i' requests -italic font (in some versions of TeX, a slanted font is used), `@b' -requests bold face, `@t' requests the fixed-width, typewriter-style -font used by `@code', and `@r' requests a roman font, which is the -usual font in which text is printed. All four commands apply to an -argument that follows, surrounded by braces. - - Only the `@r' command has much use: in example programs, you can use -the `@r' command to convert code comments from the fixed-width font to -a roman font. This looks better in printed output. - - For example, - - @lisp - (+ 2 2) ; @r{Add two plus two.} - @end lisp - -produces - - (+ 2 2) ; Add two plus two. - - If possible, you should avoid using the other three font commands. -If you need to use one, it probably indicates a gap in the Texinfo -language. - - -File: texi.info, Node: Quotations and Examples, Next: Lists and Tables, Prev: Marking Text, Up: Top - -Quotations and Examples -*********************** - - Quotations and examples are blocks of text consisting of one or more -whole paragraphs that are set off from the bulk of the text and treated -differently. They are usually indented. - - In Texinfo, you always begin a quotation or example by writing an -@-command at the beginning of a line by itself, and end it by writing -an `@end' command that is also at the beginning of a line by itself. -For instance, you begin an example by writing `@example' by itself at -the beginning of a line and end the example by writing `@end example' -on a line by itself, at the beginning of that line. - -* Menu: - -* Block Enclosing Commands:: Use different constructs for - different purposes. -* quotation:: How to write a quotation. -* example:: How to write an example in a fixed-width font. -* noindent:: How to prevent paragraph indentation. -* Lisp Example:: How to illustrate Lisp code. -* smallexample & smalllisp:: Forms for the `@smallbook' option. -* display:: How to write an example in the current font. -* format:: How to write an example that does not narrow - the margins. -* exdent:: How to undo the indentation of a line. -* flushleft & flushright:: How to push text flushleft or flushright. -* cartouche:: How to draw cartouches around examples. - - -File: texi.info, Node: Block Enclosing Commands, Next: quotation, Up: Quotations and Examples - -The Block Enclosing Commands -============================ - - Here are commands for quotations and examples: - -`@quotation' - Indicate text that is quoted. The text is filled, indented, 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. - -`@lisp' - Illustrate Lisp code. The text is printed in a fixed-width font, - and indented but not filled. - -`@smallexample' - Illustrate code, commands, and the like. Similar to `@example', - except that in TeX this command typesets text in a smaller font - for the smaller `@smallbook' format than for the 8.5 by 11 inch - format. - -`@smalllisp' - Illustrate Lisp code. Similar to `@lisp', except that in TeX this - command typesets text in a smaller font for the smaller - `@smallbook' format than for the 8.5 by 11 inch format. - -`@display' - Display illustrative text. The text is indented but not filled, - and no font is specified (so, by default, the font is roman). - -`@format' - Print illustrative text. The text is not indented and not filled - and no font is specified (so, by default, the font is roman). - - 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' command within one of the above -constructs to highlight the example or quotation by drawing a box with -rounded corners around it. (The `@cartouche' command affects only the -printed manual; it has no effect in the Info file; see *Note Drawing -Cartouches Around Examples: cartouche.) - - -File: texi.info, Node: quotation, Next: example, Prev: Block Enclosing Commands, Up: Quotations and Examples - -`@quotation' -============ - - The text of a quotation is processed normally except that: - - * the margins are closer to the center of the page, so the whole of - the quotation is indented; - - * the first lines of paragraphs are indented no more than other - lines; - - * in the printed output, interparagraph spacing is reduced. - - 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. Thus, -the following, - - @quotation - This is - a foo. - @end quotation - -produces - - This is a foo. - - -File: texi.info, Node: example, Next: noindent, Prev: quotation, Up: Quotations and Examples - -`@example' -========== - - The `@example' command is used to indicate an example that is not -part of the running text, such as computer input or output. - - This is an example of text written between an - `@example' command - and an `@end example' command. - The text is indented but not filled. - - In the printed manual, the text is typeset in a - fixed-width font, and extra spaces and blank lines are - significant. In the Info file, an analogous result is - obtained by indenting each line with five spaces. - - Write an `@example' command at the beginning of a line by itself. -This line will disappear from the output. Mark the end of the example -with an `@end example' command, also written at the beginning of a line -by itself. The `@end example' will disappear from the output. - - For example, - - @example - mv foo bar - @end example - -produces - - mv foo bar - - Since the lines containing `@example' and `@end example' will -disappear, you should put a blank line before the `@example' and -another blank line after the `@end example'. (Remember that blank -lines between the beginning `@example' and the ending `@end example' -will appear in the output.) - - *Caution:* Do not use tabs in the lines of an example (or anywhere - else in Texinfo, for that matter)! TeX treats tabs as single - spaces, and that is not what they look like. This is a problem - with TeX. (If necessary, 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 continues after an example should not be -indented. The `@noindent' command prevents a piece of text from being -indented as if it were a new paragraph. (*Note noindent::.) - - (The `@code' command is used for examples of code that are embedded -within sentences, not set off from preceding and following text. *Note -`@code': code.) - - -File: texi.info, Node: noindent, Next: Lisp Example, Prev: example, Up: Quotations and Examples - -`@noindent' -=========== - - An example or other inclusion can break a paragraph into segments. -Ordinarily, the formatters indent text that follows an example as a new -paragraph. However, you can prevent this by writing `@noindent' at the -beginning of a line by itself preceding the continuation text. - - 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 a line containing `@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: texi.info, Node: Lisp Example, Next: smallexample & smalllisp, Prev: noindent, Up: Quotations and Examples - -`@lisp' -======= - - 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' so as 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: texi.info, Node: smallexample & smalllisp, Next: display, Prev: Lisp Example, Up: Quotations and Examples - -`@smallexample' and `@smalllisp' -================================ - - In addition to the regular `@example' and `@lisp' commands, Texinfo -has two other "example-style" commands. These are the `@smallexample' -and `@smalllisp' commands. Both these commands are designed for use -with the `@smallbook' command that causes TeX to produce a printed -manual in a 7 by 9.25 inch format rather than the regular 8.5 by 11 -inch format. - - In TeX, the `@smallexample' and `@smalllisp' commands typeset text -in a smaller font for the smaller `@smallbook' format than for the 8.5 -by 11 inch format. Consequently, many examples containing long lines -fit in a narrower, `@smallbook' page without needing to be shortened. -Both commands typeset in the normal font size when you format for the -8.5 by 11 inch size; indeed, in this situation, the `@smallexample' and -`@smalllisp' commands are defined to be the `@example' and `@lisp' -commands. - - In Info, the `@smallexample' and `@smalllisp' commands are -equivalent to the `@example' and `@lisp' commands, and work exactly the -same. - - Mark the end of `@smallexample' or `@smalllisp' with `@end -smallexample' or `@end smalllisp', respectively. - - This is an example of text written between `@smallexample' and - `@end smallexample'. In Info and in an 8.5 by 11 inch manual, - this text appears in its normal size; but in a 7 by 9.25 inch manual, - this text appears in a smaller font. - - The `@smallexample' and `@smalllisp' commands make it easier to -prepare smaller format manuals without forcing you to edit examples by -hand to fit them onto narrower pages. - - As a general rule, a printed document looks better if you write all -the examples in a chapter consistently in `@example' or in -`@smallexample'. Only occasionally should you mix the two formats. - - *Note Printing "Small" Books: smallbook, for more information about -the `@smallbook' command. - - -File: texi.info, Node: display, Next: format, Prev: smallexample & smalllisp, Up: Quotations and Examples - -`@display' -========== - - The `@display' command begins a kind of example. It is like the -`@example' command except that, in a printed manual, `@display' does -not select the fixed-width font. In fact, it does not specify the font -at all, so that the text appears in the same font it would have -appeared in without the `@display' command. - - This is an example of text written between an `@display' command - and an `@end display' command. The `@display' command - indents the text, but does not fill it. - - -File: texi.info, Node: format, Next: exdent, Prev: display, Up: Quotations and Examples - -`@format' -========= - - 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. - - -File: texi.info, Node: exdent, Next: flushleft & flushright, Prev: format, Up: Quotations and Examples - -`@exdent': Undoing a Line's Indentation -======================================= - - The `@exdent' command removes any indentation a line might have. -The command is written at the beginning of a line and applies only to -the text that follows the command that is on the same line. Do not use -braces around the text. In a printed manual, the text on an `@exdent' -line is printed in the roman font. - - `@exdent' is usually used within examples. Thus, - - @example - This line follows an @@example command. - @exdent This line is exdented. - This line follows the exdented line. - The @@end example comes on the next line. - @end group - -produces - - This line follows an @example command. -This line is exdented. - This line follows the exdented line. - The @end example comes on the next line. - - In practice, the `@exdent' command is rarely used. Usually, you -un-indent text by ending the example and returning the page to its -normal width. - - -File: texi.info, Node: flushleft & flushright, Next: cartouche, Prev: exdent, Up: Quotations and Examples - -`@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: texi.info, Node: cartouche, Prev: flushleft & flushright, Up: Quotations and Examples - -Drawing Cartouches Around Examples -================================== - - In a printed manual, the `@cartouche' command draws a box with -rounded corners around its contents. 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. - - The `@cartouche' command affects only the printed manual; it has no -effect in the Info file. - - For example, - - @example - @cartouche - % pwd - /usr/local/lib/emacs/info - @end cartouche - @end example - -surrounds the two-line example with a box with rounded corners, in the -printed manual. - - -File: texi.info, Node: Lists and Tables, Next: Indices, Prev: Quotations and Examples, Up: Top - -Making Lists and Tables -*********************** - - Texinfo has several ways of making lists and two-column tables. -Lists can be bulleted or numbered, while two-column tables can -highlight the items in the first column. - -* 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. - - -File: texi.info, Node: Introducing Lists, Next: itemize, Up: Lists and Tables - -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 with highlighting. - - -File: texi.info, Node: itemize, Next: enumerate, Prev: Introducing Lists, Up: Lists and Tables - -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 character -or any special symbol that results in a single character in the Info -file. (When you write `@bullet' or `@minus' after an `@itemize' -command, you may omit the `{}'.) - - Write the text of the indented paragraphs themselves after the -`@itemize', up to another line that says `@end itemize'. - - Before each paragraph for which a mark in the margin is desired, -write a line that says just `@item'. Do not write any other text on -this line. - - 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. Note that `@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: texi.info, Node: enumerate, Next: Two-column Tables, Prev: itemize, Up: Lists and Tables - -Making a Numbered or Lettered List -================================== - - `@enumerate' is like `@itemize' except that the marks in the left -margin contain successive integers or letters. (*Note `@itemize': -itemize.) - - 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 you write an -itemized list: put `@item' on a line of its own before the start of -each paragraph that you want enumerated. Do not write any other text on -the line beginning with `@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: texi.info, Node: Two-column Tables, Prev: enumerate, Up: Lists and Tables - -Making a Two-column Table -========================= - - `@table' is similar to `@itemize', but the command allows you to -specify a name or heading line for each item. (*Note `@itemize': -itemize.) The `@table' command is used to produce two-column tables, -and is especially useful for glossaries and explanatory exhibits. - -* Menu: - -* table:: How to construct a two-column table. -* ftable vtable:: How to construct a two-column table - with automatic indexing. -* itemx:: How to put more entries in the first column. - - -File: texi.info, Node: table, Next: ftable vtable, Up: Two-column Tables - -Using the `@table' Command --------------------------- - - Use the `@table' command to produce two-column tables. - - Write the `@table' command at the beginning of a line and follow it -on the same line with an argument that is a Texinfo command such as -`@code', `@samp', `@var', or `@kbd'. Although these commands are -usually followed by arguments in braces, in this case you use the -command name without an argument because `@item' will supply the -argument. This command will be applied to the text that goes into the -first column of each item and determines how it will be highlighted. -For example, `@samp' will cause the text in the first column to be -highlighted with an `@samp' command. - - You may also choose to use the `@asis' command as an argument to -`@table'. `@asis' is a command that does nothing; if you use this -command after `@table', TeX and the Info formatting commands output the -first column entries without added highlighting (`as is'). - - (The `@table' command may work with other commands besides those -listed here. However, you can only use commands that normally take -arguments in braces.) - - 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 text on the same line as the `@item' will be placed in the first -column. - - Normally, you should put a blank line before an `@item' line. This -puts a blank like in the Info file. Except when the entries are very -brief, a blank line looks better. - - 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: texi.info, Node: ftable vtable, Next: itemx, Prev: table, Up: Two-column Tables - -`@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 Creating Indices: 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. - - -File: texi.info, Node: itemx, Prev: ftable vtable, Up: Two-column Tables - -`@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 `@itemx' for all but the first entry. The -`@itemx' command works exactly like `@item' except that it does not -generate extra vertical space above the first column text. - - 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: texi.info, Node: Indices, Next: Insertions, Prev: Lists and Tables, Up: Top - -Creating 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. If you wish, you can define your own indices. - -* Menu: - -* Index Entries:: Choose different words for index entries. -* Predefined Indices:: Use different indices for different kinds - of entry. -* Indexing Commands:: How to make an index entry. -* Combining Indices:: How to combine indices. -* New Indices:: How to define your own indices. - - -File: texi.info, Node: Index Entries, Next: Predefined Indices, Up: Indices - -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: texi.info, Node: Predefined Indices, Next: Indexing Commands, Prev: Index Entries, Up: Indices - -Predefined Indices -================== - - Texinfo provides six predefined indices: - - * A "concept index" listing concepts that are discussed. - - * A "function index" listing functions (such as entry points of - libraries). - - * A "variables index" listing variables (such as global variables of - libraries). - - * A "keystroke index" listing keyboard commands. - - * A "program index" listing names of programs. - - * A "data type index" listing data types (such as structures defined - in header files). - -Not every manual needs all of these, and most manuals use two or three -of them. This manual 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). Two or more indices can be combined -into one using the `@synindex' or `@syncodeindex' commands. *Note -Combining Indices::. - - -File: texi.info, Node: Indexing Commands, Next: Combining Indices, Prev: Predefined Indices, Up: Indices - -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 - @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. - - The usual convention is to capitalize the first word of each index -entry, unless that word is the name of a function, variable, or other -such entity that should not be capitalized. Thus, if you are -documenting Emacs Lisp, you should usually capitalize entries in the -concept index, but not those in the function index. However, if your -concept index entries are consistently short (one or two words each) it -may look better for each regular entry to start with a lower case -letter. Whichever convention you adapt, please be consistent! - - 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 and `@emph' for -emphasis (*note Marking Text::.). - - The six indexing commands for predefined indices are: - -`@cindex CONCEPT' - Make an entry in the concept index for CONCEPT. - -`@findex FUNCTION' - Make an entry in the function index for FUNCTION. - -`@vindex VARIABLE' - Make an entry in the variable index for VARIABLE. - -`@kindex KEYSTROKE' - Make an entry in the key index for KEYSTROKE. - -`@pindex PROGRAM' - Make an entry in the program index for PROGRAM. - -`@tindex DATA TYPE' - Make an entry in the data type index for DATA TYPE. - - *Caution:* Do not use a colon in an index entry. In Info, a colon - separates the menu entry name from the node name. An extra colon - confuses Info. *Note The Parts of a Menu: Menu Parts, for more - information about the structure of a menu entry. - - If you write several identical index entries in different places in a -Texinfo file, the index in the printed manual will list all the pages to -which those entries refer. However, the index in the Info file will -list *only* the node that references the *first* of those index -entries. Therefore, it is best to write indices in which each entry -refers to only one place in the Texinfo file. Fortunately, this -constraint is a feature rather than a loss since it means that the index -will be easy to use. Otherwise, you could create an index that lists -several pages for one entry and your reader would not know to which page -to turn. If you have two identical entries for one topic, change the -topics slightly, or qualify them to indicate the difference. - - You are not actually required to use the predefined indices 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. Or you could put the macros in with the -data types by writing `@tindex' commands for them, and give that index -a suitable title so the reader will understand. (*Note Printing -Indices & Menus::.) - - -File: texi.info, Node: Combining Indices, Next: New Indices, Prev: Indexing Commands, Up: Indices - -Combining Indices -================= - - Sometimes you will want to combine two disparate indices such as -functions and concepts, perhaps because you have few enough of one of -them that a separate index for them 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: texi.info, Node: syncodeindex, Next: synindex, Up: Combining Indices - -`@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: texi.info, Node: synindex, Prev: syncodeindex, Up: Combining Indices - -`@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: texi.info, Node: New Indices, Prev: Combining Indices, Up: Indices - -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 the 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".) Texinfo -constructs the new indexing command by concatenating the name of the -index with `index'; thus, defining an `au' index leads to the automatic -creation of an `@auindex' command. - - Use the `@printindex' command to print the index, as you do with the -predefined indices. For example: - - @node Author Index, Subject Index, , Top - @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 instead of a -roman font. Thus, it parallels the `@findex' command rather than the -`@cindex' command. - - You should define new indices within or right after the end-of-header -line of a Texinfo file, before any `@synindex' or `@syncodeindex' -commands (*note Header::.). - - -File: texi.info, Node: Insertions, Next: Glyphs, Prev: Indices, Up: Top - -Special Insertions -****************** - - Texinfo provides several commands for formatting dimensions, for -inserting single characters that have special meaning in Texinfo, such -as braces, and for inserting special graphic symbols that do not -correspond to characters, such as dots and bullets. - -* Menu: - -* Braces Atsigns Periods:: How to insert braces, `@' and periods. -* dmn:: How to format a dimension. -* Dots Bullets:: How to insert dots and bullets. -* TeX and copyright:: How to insert the TeX logo - and the copyright symbol. -* minus:: How to insert a minus sign. - - -File: texi.info, Node: Braces Atsigns Periods, Next: dmn, Up: Insertions - -Inserting `@', Braces, and Periods -================================== - - `@' 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. - - Periods are also special. Depending on whether the period 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 for -Texinfo 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.) - - Do not put braces after any of these commands; they are not -necessary. - -* Menu: - -* Inserting An Atsign:: -* Inserting Braces:: How to insert `{' and `}' -* Controlling Spacing:: How to insert the right amount of space - after punctuation within a sentence. - diff --git a/gnu/usr.bin/texinfo/info-files/texi.info-6 b/gnu/usr.bin/texinfo/info-files/texi.info-6 deleted file mode 100644 index cac7b3a..0000000 --- a/gnu/usr.bin/texinfo/info-files/texi.info-6 +++ /dev/null @@ -1,1461 +0,0 @@ -This is Info file texi.info, produced by Makeinfo-1.55 from the input -file texi.texi. - - This file documents Texinfo, a documentation system that uses a -single source file to produce both on-line information and a printed -manual. - - Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation, -Inc. - - This is the second edition of the Texinfo documentation, -and is consistent with version 2 of `texinfo.tex'. - - 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 Free Software Foundation. - - -File: texi.info, Node: Inserting An Atsign, Next: Inserting Braces, Up: Braces Atsigns Periods - -Inserting `@' with @@ ---------------------- - - `@@' stands for a single `@' in either printed or Info output. - - Do not put braces after an `@@' command. - - -File: texi.info, Node: Inserting Braces, Next: Controlling Spacing, Prev: Inserting An Atsign, Up: Braces Atsigns Periods - -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: texi.info, Node: Controlling Spacing, Prev: Inserting Braces, Up: Braces Atsigns Periods - -Spacing After Colons and Periods --------------------------------- - - 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. `@:' has no effect on the Info file output. - - For example, - - The s.o.p.@: has three parts ... - The s.o.p. has three parts ... - -produces - - The s.o.p. has three parts ... - The s.o.p. has three parts ... - -`@:' has no effect on the Info output. (`s.o.p' is an acronym for -"Standard Operating Procedure".) - - Use `@.' instead of a period at the end of a sentence that ends with -a single 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 `.'. - - The meanings of `@:' and `@.' in Texinfo are designed to work well -with the Emacs sentence motion commands. This made it necessary for -them to be incompatible with some other formatting systems that use -@-commands. - - Do not put braces after either an `@:' or an `@.' command. - - -File: texi.info, Node: dmn, Next: Dots Bullets, Prev: Braces Atsigns Periods, Up: Insertions - -`@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. Instead of writing `8.27@dmn{in}' in -the Texinfo file, you may write `8.27 in.' or `8.27 inches'. (In these -cases, the formatters may insert a line break between the number and the -dimension. 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. *Note Spacing After Colons and Periods: -Controlling Spacing.) - - -File: texi.info, Node: Dots Bullets, Next: TeX and copyright, Prev: dmn, Up: Insertions - -Inserting Ellipsis, Dots, 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: texi.info, Node: dots, Next: bullet, Up: Dots Bullets - -`@dots'{} ---------- - - Use the `@dots{}' command to generate an ellipsis, which is three -dots in a row, appropriately spaced, like this: `...'. 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. - - -File: texi.info, Node: bullet, Prev: dots, Up: Dots Bullets - -`@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::. - - -File: texi.info, Node: TeX and copyright, Next: minus, Prev: Dots Bullets, Up: Insertions - -Inserting TeX and the Copyright Symbol -====================================== - - The logo `TeX' is typeset in a special fashion and it needs an -@-command. The copyright symbol, `(C)', 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:: How to insert the TeX logo. -* copyright symbol:: How to use `@copyright'{}. - - -File: texi.info, Node: tex, Next: copyright symbol, Up: TeX and copyright - -`@TeX'{} --------- - - 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'. The `@TeX{}' command is unique -among Texinfo commands in that the T and the X are in upper case. - - -File: texi.info, Node: copyright symbol, Prev: tex, Up: TeX and copyright - -`@copyright'{} --------------- - - Use the `@copyright{}' command to generate `(C)'. In a printed -manual, this is a `c' inside a circle, and in Info, this is `(C)'. - - -File: texi.info, Node: minus, Prev: TeX and copyright, Up: Insertions - -`@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. - - You can compare the two forms: - - `-' is a minus sign generated with `@minus{}', - - `-' is a hyphen generated with the character `-'. - -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::.). - - -File: texi.info, Node: Glyphs, Next: Breaks, Prev: Insertions, Up: Top - -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: texi.info, Node: Glyphs Summary, Next: result, Up: Glyphs - -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. - - -File: texi.info, Node: result, Next: expansion, Prev: Glyphs Summary, Up: Glyphs - -=>: Indicating Evaluation -========================= - - Use the `@result{}' command to indicate the result of evaluating an -expression. - - The `@result{}' command is displayed as `=>' in Info and as a 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: texi.info, Node: expansion, Next: Print Glyph, Prev: result, Up: Glyphs - -==>: 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 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 five spaces. - - -File: texi.info, Node: Print Glyph, Next: Error Glyph, Prev: expansion, Up: Glyphs - --|: 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 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: texi.info, Node: Error Glyph, Next: Equivalence, Prev: Print Glyph, Up: Glyphs - -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 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 - - Note that `error-->' itself is not part of the error message. - - -File: texi.info, Node: Equivalence, Next: Point Glyph, Prev: Error Glyph, Up: Glyphs - -==: 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 as a 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: texi.info, Node: Point Glyph, Prev: Equivalence, Up: Glyphs - -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 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: texi.info, Node: Breaks, Next: Definition Commands, Prev: Glyphs, Up: Top - -Making 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:: Cause and prevent splits. -* Line Breaks:: How to force a single line to use two lines. -* w:: How to prevent unwanted line breaks. -* sp:: How to insert blank lines. -* page:: How to force the start of a new page. -* group:: How to prevent unwanted page breaks. -* need:: Another way to prevent unwanted page breaks. - - -File: texi.info, Node: Break Commands, Next: Line Breaks, Up: Breaks - -The Break Commands -================== - - The break commands create line and paragraph breaks: - -`@*' - Force a line break. - -`@sp N' - Skip N blank lines. - - The line-break-prevention command holds text together all on one -line: - -`@w{TEXT}' - Prevent TEXT from being split and hyphenated across two lines. - - 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: texi.info, Node: Line Breaks, Next: w, Prev: Break Commands, Up: Breaks - -`@*': Generate Line Breaks -========================== - - The `@*' command forces a line break in both the printed manual and -in Info. - - For example, - - This line @* is broken @*in two places. - -produces - - This line - is broken - in two places. - -(Note that the space after the first `@*' command is faithfully carried -down to the next line.) - - The `@*' command is often used in a file's copyright page: - - This is edition 2.0 of the Texinfo documentation,@* - and is for ... - -In this case, the `@*' command keeps TeX from stretching the line -across the whole page in an ugly manner. - - *Please note:* Do not write braces after an `@*' command; they are - not needed. - - Do not write an `@refill' command at the end of a paragraph - containing an `@*' command; it will cause the paragraph to be - refilled after the line break occurs, negating the effect of the - line break. - - -File: texi.info, Node: w, Next: sp, Prev: Line Breaks, Up: Breaks - -`@w'{TEXT}: Prevent Line Breaks -=============================== - - `@w{TEXT}' outputs TEXT and prohibits line breaks within TEXT. - - You can use the `@w' command to prevent TeX from automatically -hyphenating a long name or phrase that accidentally falls near the end -of a line. - - You can copy GNU software from @w{@file{prep.ai.mit.edu}}. - -produces - - You can copy GNU software from `prep.ai.mit.edu'. - - In the Texinfo file, you must write the `@w' command and its -argument (all the affected text) all on one line. - - *Caution:* Do not write an `@refill' command at the end of a - paragraph containing an `@w' command; it will cause the paragraph - to be refilled and may thereby negate the effect of the `@w' - command. - - -File: texi.info, Node: sp, Next: page, Prev: w, Up: Breaks - -`@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: texi.info, Node: page, Next: group, Prev: sp, Up: Breaks - -`@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: texi.info, Node: group, Next: need, Prev: page, Up: Breaks - -`@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: texi.info, Node: need, Prev: group, Up: Breaks - -`@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: texi.info, Node: Definition Commands, Next: Footnotes, Prev: Breaks, Up: Top - -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. - - 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:: How to structure a description using a - definition command. -* Optional Arguments:: How to handle optional and repeated arguments. -* deffnx:: How to group two or more `first' lines. -* Def Cmds in Detail:: All the definition commands. -* Def Cmd Conventions:: Conventions for writing definitions. -* Sample Function Definition:: - - -File: texi.info, Node: Def Cmd Template, Next: Optional Arguments, Up: Definition Commands - -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.) - - The template for a definition looks like this: - - @deffn CATEGORY NAME ARGUMENTS... - BODY-OF-DEFINITION - @end deffn - -For example, - - @deffn Command forward-word count - This command moves point forward @var{count} words - (or backward if @var{count} is negative). ... - @end deffn - -produces - - - Command: forward-word COUNT - This function moves point forward COUNT words (or backward if - COUNT is negative). ... - - Capitalize the category name like a title. If the name of the -category contains spaces, as in the phrase `Interactive Command', write -braces around it. For example: - - @deffn {Interactive Command} isearch-forward - ... - @end deffn - -Otherwise, the second word will be mistaken for the name of the entity. - - 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. -The `@deffn' command possesses three predefined, specialized -variations, `@defun', `@defmac', and `@defspec', that specify the -category for you: "Function", "Macro", and "Special Form" respectively. -The `@defvr' command also is accompanied by several predefined, -specialized variations for describing particular kinds of variables. - - The template for a specialized definition, such as `@defun', is -similar to the template for a generalized definition, except that you -do not need to specify the category: - - @defun NAME ARGUMENTS... - BODY-OF-DEFINITION - @end defun - -Thus, - - @defun buffer-end flag - This function returns @code{(point-min)} if @var{flag} - is less than 1, @code{(point-max)} otherwise. - ... - @end defun - -produces - - - Function: buffer-end FLAG - This function returns `(point-min)' if FLAG is less than 1, - `(point-max)' otherwise. ... - -*Note Sample Function Definition: Sample Function Definition, for a -more detailed example of a function definition, including the use of -`@example' inside the definition. - - The other specialized commands work like `@defun'. - - -File: texi.info, Node: Optional Arguments, Next: deffnx, Prev: Def Cmd Template, Up: Definition Commands - -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: texi.info, Node: deffnx, Next: Def Cmds in Detail, Prev: Optional Arguments, Up: Definition Commands - -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 of the other definition commands has an `x' form: `@defunx', -`@defvrx', `@deftypefunx', etc. - - The `x' forms work just like `@itemx'; see *Note `@itemx': itemx. - - -File: texi.info, Node: Def Cmds in Detail, Next: Def Cmd Conventions, Prev: deffnx, Up: Definition Commands - -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. -* Abstract Objects:: Commands for object-oriented programming. -* Data Types:: The definition command for data types. - - -File: texi.info, Node: Functions Commands, Next: Variables Commands, Up: Def Cmds in Detail - -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' prints argument names such as NCHARS in italics or upper - case, as if `@var' had been used, because we think of these names - as metasyntactic variables--they stand for the actual argument - values. Within the text of the description, 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. - - 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 ...'. - - For example, - - @defun set symbol new-value - Change the value of the symbol @var{symbol} - to @var{new-value}. - @end defun - - shows a rather terse definition for a function `set' whose - arguments are SYMBOL and NEW-VALUE. The argument names on the - `@defun' line automatically appear in italics or upper case as if - they were enclosed in `@var'. Terminate the definition with `@end - defun' on a line of its own. - - The template is: - - @defun FUNCTION-NAME ARGUMENTS... - BODY-OF-DEFINITION - @end defun - - `@defun' creates an entry in the index of functions. - -`@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.) `@defspec' is equivalent to `@deffn {Special Form} ...' - and works like `@defun'. - - -File: texi.info, Node: Variables Commands, Next: Typed Functions, Prev: Functions Commands, Up: Def Cmds in Detail - -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 followed - 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', write - braces around it. 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. - `@defopt' is equivalent to `@defvr {User Option} ...' and works - like `@defvar'. - - -File: texi.info, Node: Typed Functions, Next: Typed Variables, Prev: Variables Commands, Up: Def Cmds in Detail - -Functions in Typed Languages ----------------------------- - - The `@deftypefn' command and its variations are for describing -functions in C or any other language in which you must declare types of -variables and functions. - -`@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'). - - The argument names that you write in `@deftypefn' are not subject - to an implicit `@var'--since the actual names of the arguments in - `@deftypefn' are typically scattered among data type names and - keywords, Texinfo cannot find them without help. Instead, you - must write `@var' explicitly around the argument names. In the - example above, the argument names are `foo' and `bar'. - - 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 split into three lines, but - would be 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 ...'. - - Thus, - - @deftypefun int foobar (int @var{foo}, float @var{bar}) - ... - @end deftypefun - - produces the following in Info: - - -- Function: int foobar (int FOO, float BAR) - ... - - The template is: - - @deftypefun TYPE NAME ARGUMENTS... - BODY-OF-DESCRIPTION - @end deftypefun - - `@deftypefun' creates an entry in the index of functions for NAME. - - -File: texi.info, Node: Typed Variables, Next: Abstract Objects, Prev: Typed Functions, Up: Def Cmds in Detail - -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 - - `@deftypevr' creates an entry in the index of variables for NAME. - -`@deftypevar DATA-TYPE NAME' - The `@deftypevar' command is the specialized definition command - for variables in typed languages. `@deftypevar' is equivalent to - `@deftypevr Variable ...'. - - For example: - - @deftypevar int fubar - ... - @end deftypevar - - produces the following in Info: - - -- Variable: int fubar - ... - - The template is: - - @deftypevar DATA-TYPE NAME - BODY-OF-DESCRIPTION - @end deftypevar - - `@deftypevar' creates an entry in the index of variables for NAME. - - -File: texi.info, Node: Abstract Objects, Next: Data Types, Prev: Typed Variables, Up: Def Cmds in Detail - -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. - - In a definition, if the name of a class is truly a name defined in -the programming system for a class, then you should write an `@code' -around it. Otherwise, it is printed in the usual text font. - -`@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. Thus, - - @defcv {Class Option} Window border-pattern - ... - @end defcv - - illustrates how you would write the first line of a definition of - the `border-pattern' class option of the class `Window'. - - The template is - - @defcv CATEGORY CLASS NAME - ... - @end defcv - - `@defcv' 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} ...' - - The template is: - - @defivar CLASS INSTANCE-VARIABLE-NAME - BODY-OF-DEFINITION - @end defivar - - `@defivar' creates an entry in the index of variables. - -`@defop CATEGORY CLASS NAME ARGUMENTS...' - The `@defop' command is the general definition command for - entities that may resemble methods in object-oriented programming. - These entities take arguments, as functions do, but are associated - with particular classes of objects. - - 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. - -`@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. In the Lisp Machine, methods actually were functions, - but they were usually defined with `defmethod'. - - `@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. - - The template is: - - @defmethod CLASS METHOD-NAME ARGUMENTS... - BODY-OF-DEFINITION - @end defmethod - - `@defmethod' creates an entry in the index of functions, such as - ``bar-method' on `bar-class''. - - -File: texi.info, Node: Data Types, Prev: Abstract Objects, Up: Def Cmds in Detail - -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: texi.info, Node: Def Cmd Conventions, Next: Sample Function Definition, Prev: Def Cmds in Detail, Up: Definition Commands - -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: texi.info, Node: Sample Function Definition, Prev: Def Cmd Conventions, Up: Definition Commands - -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 `The GNU Emacs Lisp Reference Manual'. -(*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}.@refill - @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. - diff --git a/gnu/usr.bin/texinfo/info-files/texi.info-7 b/gnu/usr.bin/texinfo/info-files/texi.info-7 deleted file mode 100644 index 3ea85ee..0000000 --- a/gnu/usr.bin/texinfo/info-files/texi.info-7 +++ /dev/null @@ -1,1307 +0,0 @@ -This is Info file texi.info, produced by Makeinfo-1.55 from the input -file texi.texi. - - This file documents Texinfo, a documentation system that uses a -single source file to produce both on-line information and a printed -manual. - - Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation, -Inc. - - This is the second edition of the Texinfo documentation, -and is consistent with version 2 of `texinfo.tex'. - - 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 Free Software Foundation. - - -File: texi.info, Node: Footnotes, Next: Conditionals, Prev: Definition Commands, Up: Top - -Footnotes -********* - - A "footnote" is for a reference that documents or elucidates the -primary text.(1) - - 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. The template -is: - - @footnote{TEXT} - - Footnotes may be of any length, but are usually short. - - For example, this clause is followed by a sample footnote(2); in the -Texinfo source, it looks like this: - - ...a sample footnote @footnote{Here is the sample - footnote.}; in the Texinfo source... - - In a printed manual or book, the reference mark for a footnote is a -small, superscripted number; the text of the footnote is written 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)'. - - 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 containing 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) Note that the first syllable of "Texinfo" is - pronounced like "speck", not "hex". ... - - A Texinfo file may be formatted into an Info file with either -footnote style. - - 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, `makeinfo' uses the `end' style, while -`texinfo-format-buffer' and `texinfo-format-region' use the `separate' -style. - - This chapter contains two footnotes. - - ---------- 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. - - (2) Here is the sample footnote. - - -File: texi.info, Node: Conditionals, Next: Format/Print Hardcopy, Prev: Footnotes, Up: Top - -Conditionally Visible Text -************************** - - Sometimes it is good to use different text for a printed manual and -its corresponding Info file. In this case, you can use the -"conditional commands" to specify which text is for the printed manual -and which is for the Info file. - -* Menu: - -* Conditional Commands:: How to specify text for Info or TeX. -* Using Ordinary TeX Commands:: You can use any and all TeX commands. -* set clear value:: How to designate which text to format (for - both Info and TeX); and how to set a - flag to a string that you can insert. - - -File: texi.info, Node: Conditional Commands, Next: Using Ordinary TeX Commands, Up: Conditionals - -Using `@ifinfo' and `@iftex' -============================ - - `@ifinfo' begins segments of text that should be ignored by TeX when -it typesets the printed manual. The segment of text appears only in -the Info file. The `@ifinfo' command should appear on a line by -itself; end the Info-only text with a line containing `@end ifinfo' by -itself. At the beginning of a Texinfo file, the Info permissions are -contained within a region marked by `@ifinfo' and `@end ifinfo'. (*Note -Info Summary and Permissions::.) - - The `@iftex' and `@end iftex' commands are similar to the `@ifinfo' -and `@end ifinfo' commands, except that they specify text that will -appear in the printed manual but not in the Info file. - - For example, - - @iftex - This text will appear only in the printed manual. - @end iftex - - @ifinfo - However, this text will appear only in Info. - @end ifinfo - -The preceding example produces the following line: - - However, this text will appear only in Info. - -Note how you only see one of the two lines, depending on whether you -are reading the Info version or the printed version of this manual. - - The `@titlepage' command is a special variant of `@iftex' that is -used for making the title and copyright pages of the printed manual. -(*Note `@titlepage': titlepage.) - - -File: texi.info, Node: Using Ordinary TeX Commands, Next: set clear value, Prev: Conditional Commands, Up: Conditionals - -Using Ordinary TeX Commands -=========================== - - Inside a region delineated by `@iftex' and `@end iftex', you can -embed some PlainTeX commands. Info will ignore these commands since -they are only in that part of the file which is seen by TeX. 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, many features of PlainTeX will not work, as they are -overridden by features of Texinfo. - - You can enter PlainTeX completely, and use `\' in the TeX commands, -by delineating a region with the `@tex' and `@end tex' commands. (The -`@tex' command also causes Info to ignore the region, like the `@iftex' -command.) - - For example, here is a mathematical expression written in PlainTeX: - - @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 anything after this -paragraph. - - -File: texi.info, Node: set clear value, Prev: Using Ordinary TeX Commands, Up: Conditionals - -`@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. - - In addition, you can use the `@set FLAG' command to set the value of -FLAG to a string of characters; and use `@value{FLAG}' to insert that -string. You can use `@set', for example, to set a date and use -`@value' to insert the date in several places in the Texinfo file. - -* Menu: - -* ifset ifclear:: Format a region if a flag is set. -* value:: Replace a flag with a string. -* value Example:: An easy way to update edition information. - - -File: texi.info, Node: ifset ifclear, Next: value, Up: set clear value - -`@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. - - Use the `@set FLAG' command to turn on, or "set", a FLAG; a "flag" -can be any single word. The format for the command looks like this: - - @set FLAG - - 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. - - Use the `@clear FLAG' command to turn off, or "clear", a flag. -Clearing a flag is the opposite of setting a flag. The command looks -like this: - - @clear FLAG - -Write the command on a line of its own. - - 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 - - In brief, the commands are: - -`@set FLAG' - Tell the Texinfo formatting commands that FLAG is set. - -`@clear FLAG' - Tell the Texinfo formatting commands that FLAG is cleared. - -`@ifset FLAG' - If FLAG is set, tell the Texinfo formatting commands to format the - text up to the following `@end ifset' command. - - If FLAG is cleared, tell the Texinfo formatting commands to ignore - text up to the following `@end ifset' command. - -`@ifclear FLAG' - If FLAG is set, tell the Texinfo formatting commands to ignore the - text up to the following `@end ifclear' command. - - If FLAG is cleared, tell the Texinfo formatting commands to format - the text up to the following `@end ifclear' command. - - -File: texi.info, Node: value, Next: value Example, Prev: ifset ifclear, Up: set clear value - -`@value' --------- - - You can use the `@set' command to specify a value for a flag, which -is expanded by the `@value' command. The value is a string a -characters. - - Write the `@set' command like this: - - @set foo This is a string. - -This sets the value of `foo' to "This is a string." - - The Texinfo formatters 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 - - @value{foo} -to - 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 an empty string. - - If you clear a previously set flag with an `@clear FLAG' command, a -subsequent `@value{flag}' command is invalid and the string is replaced -with an error message that says `{No value for "FLAG"}'. - - For example, if you set `foo' as follows: - - @set how-much very, very, very - -then the formatters transform - - It is a @value{how-much} wet day. -into - It is a very, very, very wet day. - - If you write - - @clear how-much - -then the formatters transform - - It is a @value{how-much} wet day. -into - It is a {No value for "how-much"} wet day. - - -File: texi.info, Node: value Example, Prev: value, Up: set clear value - -`@value' Example ----------------- - - You can use the `@value' command to limit the number of places you -need to change when you record an update to a manual. Here is how it -is done in `The GNU Make Manual': - -Set the flags: - - @set EDITION 0.35 Beta - @set VERSION 3.63 Beta - @set UPDATED 14 August 1992 - @set UPDATE-MONTH August 1992 - -Write text for the first `@ifinfo' section, for people reading the -Texinfo file: - - This is Edition @value{EDITION}, - last updated @value{UPDATED}, - of @cite{The GNU Make Manual}, - for @code{make}, Version @value{VERSION}. - -Write text for the title page, for people reading the printed manual: - - @title GNU Make - @subtitle A Program for Directing Recompilation - @subtitle Edition @value{EDITION}, ... - @subtitle @value{UPDATE-MONTH} - -(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.) - -Write text for the Top node, for people reading the Info file: - - This is Edition @value{EDITION} - of the @cite{GNU Make Manual}, - last updated @value{UPDATED} - for @code{make} Version @value{VERSION}. - - After you format the manual, the text in the first `@ifinfo' section -looks 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, change only the values of the flags; you -do not need to rewrite the three sections. - - -File: texi.info, Node: Format/Print Hardcopy, Next: Create an Info File, Prev: Conditionals, Up: Top - -Format and Print 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. -* Shell Format & Print:: How to format and print a hardcopy manual - with shell commands. -* 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 you need to do to 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 European A4 paper. -* Cropmarks and Magnification:: How to print marks to indicate the size - of pages and how to print scaled up output. - - -File: texi.info, Node: Use TeX, Next: Shell Format & Print, Up: Format/Print Hardcopy - -Use TeX -======= - - The typesetting program called TeX is used for formatting a Texinfo -file. TeX is a very powerful typesetting program and, if used right, -does an exceptionally good job. *Note How to Obtain TeX: Obtaining -TeX, for information on how to obtain TeX. - - The `makeinfo', `texinfo-format-region', and `texinfo-format-buffer' -commands read the very same @-commands in the Texinfo file as does TeX, -but process them differently to make an Info file; see *Note Create an -Info File::. - - -File: texi.info, Node: Shell Format & Print, Next: Within Emacs, Prev: Use TeX, Up: Format/Print Hardcopy - -Format and Print Using Shell Commands -===================================== - - Format the Texinfo file with the shell command `tex' followed by the -name of the Texinfo file. This produces a formatted DVI file as well -as several auxiliary files containing indices, cross references, etc. -The DVI file (for "DeVice Independent" file) can be printed on a wide -variety of printers. - - The `tex' formatting command itself does not sort the indices; it -writes an output file of unsorted index data. This is a misfeature of -TeX. Hence, to generate a printed index, 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 GNU distribution and is -usually installed when Emacs is installed.) - - The `tex' formatting command outputs unsorted index files under -names that obey a standard convention. These names are the name of -your main input file to the `tex' formatting command, with everything -after the first period thrown away, and the two letter names of indices -added at the end. 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'. - - Or else, you can use `??' as "wild-cards" 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 knows to look for a file of that name. -`texindex' does not alter the raw index output file. - - After you have sorted the indices, you need to rerun the `tex' -formatting command on the Texinfo file. This regenerates a formatted -DVI file with up-to-date index entries.(1) - - To summarize, this is a three step process: - - 1. Run the `tex' formatting command on the Texinfo file. This - generates the formatted DVI file as well as the raw index files - with two letter extensions. - - 2. Run the shell command `texindex' on the raw index files to sort - them. This creates the corresponding sorted index files. - - 3. Rerun the `tex' formatting command on the Texinfo file. This - regenerates a formatted DVI file with the index entries in the - correct order. This second run also corrects the page numbers for - the cross references. (The tables of contents are always correct.) - - You need not run `texindex' each time after you run the `tex' -formatting. 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. - - Rather than type the `tex' and `texindex' commands yourself, you can -use `texi2dvi'. This shell script is designed to simplify the -`tex'--`texindex'--`tex' sequence by figuring out whether index files -and DVI files are up-to-date. It runs `texindex' and `tex' only when -necessary. - - The syntax for `texi2dvi' is like this (where `%' is the shell -prompt): - - % texi2dvi FILENAME... - - Finally, you can print the DVI file with the DVI print command. The -precise command to use depends on the system; `lpr -d' is common. The -DVI print command may require a file name without any extension or with -a `.dvi' extension. - - The following commands, for example, sort the indices, format, and -print the `Bison Manual' (where `%' is the shell prompt): - - % 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.) - - ---------- Footnotes ---------- - - (1) If you use more than one index and have cross references to an -index other than the first, you must run `tex' *three times* to get -correct output: once to generate raw index data; again (after -`texindex') to output the text of the indices and determine their true -page numbers; and a third time to output correct page numbers in cross -references to them. However, cross references to indices are rare. - - -File: texi.info, Node: Within Emacs, Next: Texinfo Mode Printing, Prev: Shell Format & Print, Up: Format/Print Hardcopy - -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 How to Format and -Print Using Shell Commands: Shell Format & Print, 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 (where `%' is the shell prompt): - - % texi2dvi gcc.texinfo - % lpr -d gcc.dvi - - *Note Texinfo Mode Printing::, for more information about formatting -and printing in Texinfo mode. - - -File: texi.info, Node: Texinfo Mode Printing, Next: Compile-Command, Prev: Within Emacs, Up: Format/Print Hardcopy - -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-r' -`M-x texinfo-tex-region' - Run TeX on the current region. - -`C-c C-t C-b' -`M-x texinfo-tex-buffer' - Run TeX on the current buffer. - -`C-c C-t C-i' -`M-x texinfo-texindex' - Sort the indices of a Texinfo file that have been formatted with - `texinfo-tex-region' or `texinfo-tex-buffer'. - -`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 texinfo-show-tex-print-queue' - Show the print queue. - -`C-c C-t C-d' -`M-x texinfo-delete-from-tex-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 texinfo-kill-tex-job' - Kill either the currently running TeX job that has been started by - `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-tex-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 texinfo-recenter-tex-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 TeX on the buffer. - C-c C-t C-i Sort the indices. - C-c C-t C-b Rerun TeX to regenerate indices. - 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 `*texinfo-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 `*texinfo-tex-shell*' -buffer, and you can switch to and from and use the -`*texinfo-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-tex-command "tex" - texinfo-texindex-command "texindex" - texinfo-tex-shell-cd-command "cd" - texinfo-tex-dvi-print-command "lpr -d" - texinfo-show-tex-queue-command "lpq" - texinfo-delete-from-print-queue-command "lprm" - texinfo-start-of-header "%**start" - texinfo-end-of-header "%**end" - texinfo-tex-trailer "@bye" - - The default values of both the `texinfo-tex-command' and the -`texinfo-texindex-command' variables are set in the `texnfo-tex.el' -file. - - You can change the values of these variables with the `M-x -edit-options' command (*note Editing Variable Values: (emacs)Edit -Options.), 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.). - - -File: texi.info, Node: Compile-Command, Next: Requirements Summary, Prev: Texinfo Mode Printing, Up: Format/Print Hardcopy - -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 formatting command as a -`compile-command' and have Emacs run the TeX formatting command 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 -would put the following: - - @c Local Variables: - @c compile-command: "tex gdb.texinfo" - @c End: - -This technique is most often used by programmers who also compile -programs this way; see *Note Compilation: (emacs)Compilation. - - -File: texi.info, Node: Requirements Summary, Next: Preparing for TeX, Prev: Compile-Command, Up: Format/Print Hardcopy - -TeX Formatting Requirements Summary -=================================== - - Every Texinfo file that is to be input to TeX must begin with a -`\input' command and contain an `@settitle' command: - - \input texinfo - @settitle NAME-OF-MANUAL - -The first command instructs TeX to load the macros it needs to process -a Texinfo file and the second command specifies the title of printed -manual. - - Every Texinfo file must end with a line that terminates TeX -processing and forces out unfinished pages: - - @bye - - Strictly speaking, these three lines are all a Texinfo file needs for -TeX, besides the body. (The `@setfilename' line is the only line that -a Texinfo file needs for Info formatting.) - - Usually, the file's first line contains an `@c -*-texinfo-*-' -comment that causes Emacs to switch to Texinfo mode when you edit the -file. In addition, the beginning usually includes an `@setfilename' -for Info formatting, 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. - -For more information, see -*Note `@setchapternewpage': setchapternewpage, -*Note Page Headings: Headings, -*Note Titlepage & Copyright Page::, -*Note Printing Indices & Menus::, and -*Note Contents::. - - -File: texi.info, Node: Preparing for TeX, Next: Overfull hboxes, Prev: Requirements Summary, Up: Format/Print Hardcopy - -Preparing to Use TeX -==================== - -TeX needs to know where to find the `texinfo.tex' file that you have -told it to input with the `\input texinfo' command at the beginning of -the first line. The `texinfo.tex' file tells TeX how to handle -@-commands. (`texinfo.tex' is included in the standard GNU -distributions.) - - Usually, the `texinfo.tex' file is put in the default directory that -contains TeX macros (the `/usr/lib/tex/macros' directory) when GNU -Emacs or other GNU software is installed. In this case, TeX will find -the file and you do not need to do anything special. Alternatively, -you can put `texinfo.tex' in the directory in which the Texinfo source -file is located, and TeX will find it there. - - However, you may want to specify the location of the `\input' file -yourself. One way to do this is to write the complete path for the file -after the `\input' command. Another way is to set the `TEXINPUTS' -environment variable in your `.cshrc' or `.profile' file. The -`TEXINPUTS' environment variable will tell TeX where to find the -`texinfo.tex' file and any other file that you might want TeX to use. - - Whether you use a `.cshrc' or `.profile' file depends on whether you -use `csh', `sh', or `bash' for your shell command interpreter. When -you use `csh', it looks to the `.cshrc' file for initialization -information, and when you use `sh' or `bash', it looks to the -`.profile' file. - - In a `.cshrc' file, you could use the following `csh' command -sequence: - - setenv TEXINPUTS .:/usr/me/mylib:/usr/lib/tex/macros - - In a `.profile' file, you could use the following `sh' command -sequence: - - TEXINPUTS=.:/usr/me/mylib:/usr/lib/tex/macros - export TEXINPUTS - -This would cause TeX to look for `\input' file first in the current -directory, indicated by the `.', then in a hypothetical user's -`me/mylib' directory, and finally in the system library. - - -File: texi.info, Node: Overfull hboxes, Next: smallbook, Prev: Preparing for TeX, Up: Format/Print Hardcopy - -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". The -backslash, `\', is the TeX equivalent of `@'.) - - 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 -knows how to hyphenate words. *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. - - However, unless told otherwise, TeX will print a large, ugly, black -rectangle beside the line that contains the overful hbox. 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: texi.info, Node: smallbook, Next: A4 Paper, Prev: Overfull hboxes, Up: Format/Print Hardcopy - -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 regular sized books are often 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::.). - - The Free Software Foundation distributes printed copies of `The GNU -Emacs Manual' and other manuals in the "small" book size. *Note -`@smallexample' and `@smalllisp': smallexample & smalllisp, for -information about commands that make it easier to produce examples for -a smaller manual. - - -File: texi.info, Node: A4 Paper, Next: Cropmarks and Magnification, Prev: smallbook, Up: Format/Print Hardcopy - -Printing on A4 Paper -==================== - - You can tell TeX to typeset a document for printing on European size -A4 paper with the `@afourpaper' command. Write the command on a line -by itself between `@iftex' and `@end iftex' lines 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 - @syncodeindex vr fn - @iftex - @afourpaper - @end iftex - @c %**end of header - - -File: texi.info, Node: Cropmarks and Magnification, Prev: A4 Paper, Up: Format/Print Hardcopy - -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 the -`texinfo.tex' definitions file. - - 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 PlainTeX -command that is prefixed with a backslash. You have to write this -command between `@tex' and `@end tex' (*note Using Ordinary TeX -Commands: Using Ordinary TeX 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 using a larger-than-normal master. - - Depending on your system, `\mag' may not work or may work only at -certain magnifications. Be prepared to experiment. - - -File: texi.info, Node: Create an Info File, Next: Install an Info File, Prev: Format/Print Hardcopy, Up: Top - -Creating an Info File -********************* - - `makeinfo' is a utility that converts a Texinfo file into an Info -file; `texinfo-format-region' and `texinfo-format-buffer' are GNU Emacs -functions that do the same. - - A Texinfo file must possess an `@setfilename' line near its -beginning, otherwise the Info formatting commands will fail. - - For information on installing the Info file in the Info system, see -*Note Install 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: texi.info, Node: makeinfo advantages, Next: Invoking makeinfo, Up: Create an Info File - -`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 a key 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: texi.info, Node: Invoking makeinfo, Next: makeinfo options, Prev: makeinfo advantages, Up: Create an Info File - -Invoking `makeinfo' from a Shell -================================ - - To create an Info file from a Texinfo file, type `makeinfo' followed -by the name of the Texinfo file. Thus, to create the Info file for -Bison, type the following at the shell prompt (where `%' is the prompt): - - % makeinfo bison.texinfo - - (You can run a shell inside Emacs by typing `M-x shell'.) - - Sometimes you will want to specify options. For example, if you wish -to discover which version of `makeinfo' you are using, type: - - % makeinfo --version - - *Note makeinfo options::, for more information. - - -File: texi.info, Node: makeinfo options, Next: Pointer Validation, Prev: Invoking makeinfo, Up: Create an Info File - -Options for `makeinfo' -====================== - - The `makeinfo' command takes a number of options. Most often, -options are used to set the value of the fill column and specify the -footnote style. Each command line option is a word preceded by `--'(1) -or a letter preceded by `-'. You can use abbreviations for the option -names as long as they are unique. - - For example, you could use the following command to create an Info -file for `bison.texinfo' in which each line is filled to only 68 -columns (where `%' is the prompt): - - % 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 VAR to be defined. This is equivalent to `@set VAR' in the - Texinfo file. - -`--error-limit LIMIT' - Set the maximum number of errors that `makeinfo' will report - before exiting (on the assumption that continuing would be - useless). The default number of errors that can be reported before - `makeinfo' gives up is 100. - -`--fill-column 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 for `fill-column' is 72. - -`--footnote-style STYLE' - Set the footnote style to STYLE, either `end' for the end node - style 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. 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. - -`-I DIR' - Add `dir' to the directory search list for finding files that are - included using the `@include' command. By default, `makeinfo' - searches only the current directory. - -`--no-headers' - Do not include menus or node lines in the output. This results in - an ASCII file that you cannot read in Info since it does not - contain the requisite nodes or menus; but you can print such a - file in a single, typewriter-like font and produce acceptable - output. - -`--no-split' - Suppress the splitting stage of `makeinfo'. Normally, large - output files (where the size is greater than 70k bytes) are split - into smaller subfiles, each one approximately 50k bytes. If you - specify `--no-split', `makeinfo' will not split up the output file. - -`--no-pointer-validate' -`--no-validate' - Suppress the pointer-validation phase of `makeinfo'. 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 the output of warning messages. This does *not* suppress - the output of error messages, only warnings. You might want this - if the file you are creating has examples of Texinfo cross - references within it, and the nodes that are referenced do not - actually exist. - -`--no-number-footnotes' - Supress automatic footnote numbering. By default, `makeinfo' - numbers each footnote sequentially in a single node, resetting the - current footnote number to 1 at the start of each node. - -`--output FILE' -`-o FILE' - Specify that the output should be directed to FILE and not to the - file name specified in the `@setfilename' command found in the - Texinfo source. FILE can be the special token `-', which specifies - standard output. - -`--paragraph-indent 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. The value of INDENT is interpreted as - follows: - - * If the value of INDENT is `asis', do not change the existing - indentation at the starts of paragraphs. - - * If the value of INDENT is zero, delete any existing - indentation. - - * If the value of INDENT is greater than zero, indent each - paragraph by that number of spaces. - -`--reference-limit LIMIT' - Set the value of the number of references to a node that - `makeinfo' will make without reporting a warning. If a node has - more than this number of references in it, `makeinfo' will make the - references but also report a warning. - -`-U VAR' - Cause VAR to be undefined. This is equivalent to `@clear VAR' in - the Texinfo file. - -`--verbose' - Cause `makeinfo' to display messages saying what it is doing. - Normally, `makeinfo' only outputs messages if there are errors or - warnings. - -`--version' - Report the version number of this copy of `makeinfo'. - - ---------- Footnotes ---------- - - (1) `--' has replaced `+', the old introductory character, to -maintain POSIX.2 compatibility without losing long-named options. - - -File: texi.info, Node: Pointer Validation, Next: makeinfo in Emacs, Prev: makeinfo options, Up: Create an Info File - -Pointer Validation -================== - - `makeinfo' will check the validity of the final Info file unless you -suppress pointer-validation by using the `--no-pointer-validation' -option. 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 `Previous' node must also be pointed to by a `Next' - node. - - 3. Every node except the `Top' node must have an `Up' pointer. - - 4. The node referenced by an `Up' pointer must contain a reference to - the current node in some manner other than through a `Next' - reference. This includes menu entries and cross references. - - 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. - - -File: texi.info, Node: makeinfo in Emacs, Next: texinfo-format commands, Prev: Pointer Validation, Up: Create an Info File - -Running `makeinfo' inside 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 either `makeinfo-region' or `makeinfo-buffer', Emacs -prompts for a file name, offering the name of the visited file as the -default. You can edit the default file name in the minibuffer if you -wish, before typing RET to start the `makeinfo' process. - - 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 currently running job created by `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 edit-options' 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 Editing Variable Values: (emacs)Edit Options, -*Note Examining and Setting Variables: (emacs)Examining, -*Note Init File: (emacs)Init File, and -*Note Options for `makeinfo': makeinfo options. - - -File: texi.info, Node: texinfo-format commands, Next: Batch Formatting, Prev: makeinfo in Emacs, Up: Create an Info File - -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::.). - diff --git a/gnu/usr.bin/texinfo/info-files/texi.info-8 b/gnu/usr.bin/texinfo/info-files/texi.info-8 deleted file mode 100644 index ba35e6e..0000000 --- a/gnu/usr.bin/texinfo/info-files/texi.info-8 +++ /dev/null @@ -1,1056 +0,0 @@ -This is Info file texi.info, produced by Makeinfo-1.55 from the input -file texi.texi. - - This file documents Texinfo, a documentation system that uses a -single source file to produce both on-line information and a printed -manual. - - Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation, -Inc. - - This is the second edition of the Texinfo documentation, -and is consistent with version 2 of `texinfo.tex'. - - 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 Free Software Foundation. - - -File: texi.info, Node: Batch Formatting, Next: Tag and Split Files, Prev: texinfo-format commands, Up: Create an Info File - -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 Line Switches and -Arguments: (emacs)Command Switches.) - - Here is the command to format all the files that end in `.texinfo' -in the current directory (where `%' is the shell prompt): - - % 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: texi.info, Node: Tag and Split Files, Prev: Batch Formatting, Up: Create an Info File - -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 70,000 -bytes, `texinfo-format-buffer' and `makeinfo' split the large Info file -into shorter "indirect" subfiles of about 50,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 `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. - - 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: texi.info, Node: Install an Info File, Next: Command List, Prev: Create an Info File, Up: Top - -Installing an Info File -*********************** - - Info files are usually kept in the `info' directory. (You can find -the location of this directory within Emacs by typing `C-h i' to enter -Info and then typing `C-x C-f' to see the full pathname to the `info' -directory.) - -* 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. - - -File: texi.info, Node: Directory file, Next: New Info File, Up: Install an Info File - -The `dir' File -============== - - 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'. 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 - -(Note that in this case, the `dir' file name is written in upper case -letters--it can be written in either upper or lower case. Info has a -feature that it will change the case of the file name to lower case if -it cannot find the name as written.) - - -File: texi.info, Node: New Info File, Next: Other Info Directories, Prev: Directory file, Up: Install an Info File - -Listing a New Info File -======================= - - To add a new Info file to your system, write a menu entry for it in -the menu in the `dir' file in the `info' directory. Also, move the new -Info file itself to 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. - - Conventionally, the name of an Info file has a `.info' extension. -Thus, you might list the name of the file like this: - - * GDB: (gdb.info). The source-level C debugger. - -However, Info will look for a file with a `.info' extension if it does -not find the file under the name given in the menu. This means that -you can refer to the file `gdb.info' as `gdb', as shown in the first -example. This looks better. - - -File: texi.info, Node: Other Info Directories, Prev: New Info File, Up: Install an Info File - -Info Files in Other Directories -=============================== - - If an Info file is not in the `info' directory, there are two ways -to specify its location: - - * Write the pathname as the menu's second part, or; - - * Specify the `info' directory name in an environment variable in - your `.profile' or `.cshrc' initialization file. (Only you and - others with the same environment variable will be able to find Info - files whose location is specified this way.) - - For example, to reach a test file in the `~bob/manuals' directory, -you could add an entry like this to the menu in the `dir' file: - - * Test: (~bob/manuals/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 can tell Info where to look by setting the -`INFOPATH' environment variable in your `.cshrc' or `.profile' file. - - If you use `sh' or `bash' for your shell command interpreter, you -must set the `INFOPATH' environment variable in the `.profile' -initialization file; but if you use `csh', you must set the variable in -the `.cshrc' initialization file. The two files require slightly -different command formats. - - * In a `.cshrc' file, you could set the `INFOPATH' variable as - follows: - - setenv INFOPATH .:~bob/manuals:/usr/local/emacs/info - - * In a `.profile' file, you would achieve the same effect by writing: - - INFOPATH=.:~bob/manuals:/usr/local/emacs/info - export INFOPATH - -Either form would cause Info to look first in the current directory, -indicated by the `.', then in the `~bob/manuals' directory, and finally -in the `/usr/local/emacs/info' directory (which is a common location -for the standard Info directory). - - -File: texi.info, Node: Command List, Next: Tips, Prev: Install an Info File, Up: Top - -@-Command List -************** - - Here is an alphabetical list of the @-commands in Texinfo. Square -brackets, [ ], indicate optional arguments; an ellipsis, `...', -indicates repeated text. - -`@*' - Force a line break. Do not end a paragraph that uses `@*' with an - `@refill' command. *Note Line Breaks::. - -`@.' - Stands for a period that really does end a sentence (usually after - an end-of-sentence capital letter). *Note Controlling Spacing::. - -`@:' - Indicate to TeX that an immediately preceding period, question - mark, exclamation mark, or colon does not end a sentence. Prevent - TeX from inserting extra whitespace as it does at the end of a - sentence. The command has no effect on the Info file output. - *Note Controlling Spacing::. - -`@@' - Stands for `@'. *Note Inserting `@': Braces Atsigns Periods. - -`@{' - Stands for a left-hand brace, `{'. *Note Inserting @ braces and - periods: Braces Atsigns Periods. - -`@}' - Stands for a right-hand brace, `}'. *Note Inserting @ braces and - periods: Braces Atsigns Periods. - -`@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 a subappendix. 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. - -`@asis' - Used following `@table', `@ftable', and `@vtable' to print the - table's first column without highlighting ("as is"). *Note Making - a Two-column Table: 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 General Syntactic Conventions: Conventions. - -`@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. - -`@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. - -`@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. - -`@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 General Syntactic Conventions: Conventions. - -`@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 a copyright symbol. *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' - Format a description for a variable associated with a class in - object-oriented programming. Takes three arguments: the category - of thing being defined, the class to which it belongs, and its - name. *Note Definition Commands::. - -`@deffn CATEGORY NAME ARGUMENTS...' - 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. - -`@defivar CLASS INSTANCE-VARIABLE-NAME' - Format a description for an instance variable in object-oriented - programming. The command is equivalent to `@defcv {Instance - Variable} ...'. *Note Definition Commands::. - -`@defmac MACRO-NAME ARGUMENTS...' - Format a description for a macro. The command is equivalent to - `@deffn Macro ...'. *Note Definition Commands::. - -`@defmethod 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::. - -`@defop 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::. - -`@defopt OPTION-NAME' - Format a description for a user option. The command is equivalent - to `@defvr {User Option} ...'. *Note Definition Commands::. - -`@defspec SPECIAL-FORM-NAME ARGUMENTS...' - Format a description for a special form. The command is - equivalent to `@deffn {Special Form} ...'. *Note Definition - Commands::. - -`@deftp 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::. - -`@deftypefn 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::. - -`@deftypefun 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::. - -`@deftypevr 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::. - -`@deftypevar DATA-TYPE VARIABLE-NAME' - Format a description for a variable in a typed language. The - command is equivalent to `@deftypevr Variable ...'. *Note - Definition Commands::. - -`@defun FUNCTION-NAME ARGUMENTS...' - Format a description for functions. The command is equivalent to - `@deffn Function ...'. *Note Definition Commands::. - -`@defvar VARIABLE-NAME' - Format a description for variables. The command is equivalent to - `@defvr Variable ...'. *Note Definition Commands::. - -`@defvr 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::. - -`@dfn{TERM}' - Highlight the introductory or defining use of a term. *Note - `@dfn': dfn. - -`@display' - Begin a kind of example. Indent text, do not fill, do not select a - new font. Pair with `@end display'. *Note `@display': display. - -`@dmn{DIMENSION}' - Format a dimension. Cause TeX to insert a narrow space before - DIMENSION. No effect in Info. Use for writing a number followed - by an abbreviation of a dimension name, such as `12pt', written as - `12@dmn{pt}', with no space between the number and the `@dmn' - command. *Note `@dmn': dmn. - -`@dots{}' - Insert an ellipsis: `...'. *Note `@dots': dots. - -`@emph{TEXT}' - Highlight TEXT; text is displayed in *italics* in printed output, - and surrounded by asterisks in Info. *Note Emphasizing Text: - Emphasis. - -`@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::. - -`@error{}' - Indicate to the reader with a glyph that the following text is an - error message: `error-->'. *Note Error Glyph::. - -`@evenfooting [LEFT] @| [CENTER] @| [RIGHT]' - Specify page footings for even-numbered (left-hand) pages. Not - relevant to Info. *Note How to Make Your Own Headings: Custom - Headings. - -`@evenheading [LEFT] @| [CENTER] @| [RIGHT]' - Specify page headings for even-numbered (left-hand) pages. Not - relevant to Info. *Note How to Make Your Own Headings: Custom - Headings. - -`@everyfooting [LEFT] @| [CENTER] @| [RIGHT]' - Specify page footings for every page. Not relevant to Info. - *Note How to Make Your Own Headings: Custom Headings. - -`@everyheading [LEFT] @| [CENTER] @| [RIGHT]' - Specify page 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. - -`@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. - -`@flushleft' - Left justify every line but leave the right end ragged. Leave - font as is. Pair with `@end flushleft'. *Note `@flushleft' and - `@flushright': flushleft & flushright. - -`@flushright' - Right justify every line but leave the left end ragged. Leave - font as is. Pair with `@end flushright'. *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 `@example' or `@display', but do - not narrow the margins and do not select the fixed-width font. - 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. - -`@group' - Hold text together that must appear on one printed page. Pair with - `@end group'. Not relevant to Info. *Note `@group': group. - -`@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, or specify single-sided or - double-sided page headings for printing. `@headings on' is - synonymous with `@headings double'. *Note The `@headings' - Command: headings on off. - -`@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. - -`@ifinfo' - Begin a stretch of text that will be ignored by TeX when it - typesets the printed manual. The text appears only in the Info - file. Pair with `@end ifinfo'. *Note Conditionally Visible Text: - 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 a stretch of text that will not appear in the Info file, but - will be processed only by TeX. Pair with `@end iftex'. *Note - Conditionally Visible Text: Conditionals. - -`@ignore' - Begin a stretch of text that will not appear in either the Info - file or the printed output. Pair with `@end ignore'. *Note - Comments and Ignored Text: Comments. - -`@include FILENAME' - Incorporate the contents of the file FILENAME into the Info file - or printed document. *Note Include Files::. - -`@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 properly recognize - `@' until after it has read the definitions file. *Note The - Texinfo File Header: 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 consists of characters of input to be typed by - users. *Note `@kbd': kbd. - -`@key{KEY-NAME}' - Highlight KEY-NAME, a conventional 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. - -`@lisp' - Begin an example of Lisp code. Indent text, do not fill, and - select fixed-width font. Pair with `@end lisp'. *Note `@lisp': - Lisp Example. - -`@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. In Info, the - chapter heading line is underlined with asterisks. *Note - `@majorheading' and `@chapheading': majorheading & chapheading. - -`@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. - -`@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. - -`@oddfooting [LEFT] @| [CENTER] @| [RIGHT]' - Specify page footings for odd-numbered (right-hand) pages. Not - relevant to Info. *Note How to Make Your Own Headings: Custom - Headings. - -`@oddheading [LEFT] @| [CENTER] @| [RIGHT]' - Specify page headings for odd-numbered (right-hand) pages. Not - relevant to Info. *Note How to Make Your Own Headings: Custom - Headings. - -`@page' - Start a new page in a printed manual. No effect in Info. *Note - `@page': page. - -`@paragraphindent INDENT' - Indent paragraphs by INDENT number of spaces; delete indentation - if the value of INDENT is 0; and do not change 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. - -`@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, which is why you do not - need to insert punctuation. Only the first argument is mandatory. - *Note `@pxref': pxref. - -`@quotation' - Narrow the margins to indicate text that is quoted from another - real or imaginary work. Write command on a line of its own. Pair - with `@end quotation'. *Note `@quotation': quotation. - -`@r{TEXT}' - Print TEXT in roman font. No effect in Info. *Note Fonts::. - -`@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' - In Info, refill and indent the paragraph after all the other - processing has been done. No effect on TeX, which always refills. - This command is no longer needed, since all formatters now - automatically refill. *Note Refilling Paragraphs::. - -`@result{}' - Indicate the result of an expression to the reader with a special - glyph: `=>'. *Note `@result': result. - -`@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. - -`@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. - -`@setfilename INFO-FILE-NAME' - Provide a name for the Info file. *Note General Syntactic - Conventions: Conventions. - -`@settitle TITLE' - Provide a title for page headers in a printed manual. *Note - General Syntactic Conventions: Conventions. - -`@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. - -`@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 `@smallexample' and - `@smalllisp': smallexample & smalllisp. - -`@smallexample' - Indent text to indicate an example. Do not fill, select - fixed-width font. In `@smallbook' format, print text in a smaller - font than with `@example'. Pair with `@end smallexample'. *Note - `@smallexample' and `@smalllisp': smallexample & smalllisp. - -`@smalllisp' - Begin an example of Lisp code. Indent text, do not fill, select - fixed-width font. In `@smallbook' format, print text in a smaller - font. Pair with `@end smalllisp'. *Note `@smallexample' and - `@smalllisp': smallexample & smalllisp. - -`@sp N' - Skip N blank lines. *Note `@sp': sp. - -`@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::. - -`@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 Inserting TeX and (C): TeX and - copyright. - -`@tex' - Enter TeX completely. Pair with `@end tex'. *Note Using Ordinary - TeX Commands: Using Ordinary TeX Commands. - -`@thischapter' - In a heading or footing, stands for the number and name of the - current chapter, in the format `Chapter 1: Title'. *Note How to - Make Your Own Headings: Custom Headings. - -`@thischaptername' - In a heading or footing, stands for the name of the current - chapter. *Note How to Make Your Own Headings: Custom Headings. - -`@thisfile' - In a heading or footing, stands for the name of the current - `@include' file. Does not insert anything if not within an - `@include' file. *Note How to Make Your Own Headings: Custom - Headings. - -`@thispage' - In a heading or footing, stands for the current page number. - *Note How to Make Your Own Headings: Custom Headings. - -`@thistitle' - In a heading or footing, stands for the name of the document, as - specified by the `@settitle' command. *Note How to Make Your Own - Headings: Custom Headings. - -`@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' line 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 `@ifinfo' and `@end ifinfo'. In TeX and - `texinfo-format-buffer', the `@top' command is merely a synonym - for `@unnumbered'. *Note Creating Pointers with `makeinfo': - makeinfo Pointer Creation. - -`@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. - -`@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. - -`@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 The Copyright Page and Printed - Permissions: Copyright & Permissions. - -`@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. Do not end a - paragraph that uses `@w' with an `@refill' command. In the - Texinfo file, keep TEXT on one line. *Note `@w': w. - -`@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. - diff --git a/gnu/usr.bin/texinfo/info-files/texi.info-9 b/gnu/usr.bin/texinfo/info-files/texi.info-9 deleted file mode 100644 index b128db5..0000000 --- a/gnu/usr.bin/texinfo/info-files/texi.info-9 +++ /dev/null @@ -1,1210 +0,0 @@ -This is Info file texi.info, produced by Makeinfo-1.55 from the input -file texi.texi. - - This file documents Texinfo, a documentation system that uses a -single source file to produce both on-line information and a printed -manual. - - Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation, -Inc. - - This is the second edition of the Texinfo documentation, -and is consistent with version 2 of `texinfo.tex'. - - 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 Free Software Foundation. - - -File: texi.info, Node: Tips, Next: Sample Texinfo File, Prev: Command List, Up: Top - -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. The index of an Info file lists - only one location for each entry. - - * 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 index entry, or - else use lower case. According to convention, you should - capitalize the first word of an index entry. However, this - practice may make an index look crowded. Some writers prefer - lower case. Regardless of which you prefer, choose one style and - stick to it. 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. - - * Write the indexing commands that refer to a whole section - immediately after the section command, and write the indexing - commands that refer to the paragraph before the 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 -............................ - - Write the edition and version numbers and date in three places in -every manual: - - 1. In the first `@ifinfo' section, for people reading the Texinfo - file. - - 2. In the `@titlepage' section, for people reading the printed manual. - - 3. In the `Top' node, for people reading the Info file. - -Also, it helps to write a note before the first `@ifinfo' section to -explain what you are doing. - -For example: - - @c ===> NOTE! <== - @c Specify the edition and version numbers and date - @c in *three* places: - @c 1. First ifinfo section 2. title page 3. top node - @c To find the locations, search for !!set - - @ifinfo - @c !!set edition, date, version - This is Edition 4.03, January 1992, - of the @cite{GDB Manual} for GDB Version 4.3. - ... - ---or use `@set' and `@value' (*note `@value' Example: value Example.). - -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 similar 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 convention, 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 user 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 user 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, readers find it hard to search for the -section. - - 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: texi.info, Node: Sample Texinfo File, Next: Sample Permissions, Prev: Tips, Up: Top - -A Sample Texinfo File -********************* - - Here is a complete, short sample Texinfo file, without any -commentary. You can see this file, with comments, in the first chapter. -*Note A Short Sample Texinfo File: Short Sample. - - \input texinfo @c -*-texinfo-*- - @c %**start of header - @setfilename sample.info - @settitle Sample Document - @c %**end of header - - @setchapternewpage odd - - @ifinfo - This is a short example of a complete Texinfo file. - - Copyright 1990 Free Software Foundation, Inc. - @end ifinfo - - @titlepage - @sp 10 - @comment The title is printed in a large font. - @center @titlefont{Sample Title} - - @c The following two commands start the copyright page. - @page - @vskip 0pt plus 1filll - Copyright @copyright{} 1990 Free Software Foundation, Inc. - @end titlepage - - @node Top, First Chapter, (dir), (dir) - @comment node-name, next, previous, up - - @menu - * First Chapter:: The first chapter is the - only chapter in this sample. - * Concept Index:: This index has two entries. - @end menu - - @node First Chapter, Concept Index, Top, Top - @comment node-name, next, previous, up - @chapter First Chapter - @cindex Sample index entry - - This is the contents of the first chapter. - @cindex Another sample index entry - - Here is a numbered list. - - @enumerate - @item - This is the first item. - - @item - This is the second item. - @end enumerate - - The @code{makeinfo} and @code{texinfo-format-buffer} - commands transform a Texinfo file such as this into - an Info file; and @TeX{} typesets it for a printed - manual. - - @node Concept Index, , First Chapter, Top - @comment node-name, next, previous, up - @unnumbered Concept Index - - @printindex cp - - @contents - @bye - - -File: texi.info, Node: Sample Permissions, Next: Include Files, Prev: Sample Texinfo File, Up: Top - -Sample Permissions -****************** - - Texinfo files should contain sections that tell the readers that they -have the right to copy and distribute the Texinfo file, the Info file, -and the printed manual. - - Also, if you are writing a manual about software, you should explain -that the software is free and either include the GNU General Public -License (GPL) or provide a reference to it. *Note Distribution: -(emacs)Distrib, for an example of the text that could be used in the -software "Distribution", "General Public License", and "NO WARRANTY" -sections of a document. *Note Texinfo Copying Conditions: Copying, for -an example of a brief explanation of how the copying conditions provide -you with rights. - -* Menu: - -* Inserting Permissions:: How to put permissions in your document. -* ifinfo Permissions:: Sample `ifinfo' copying permissions. -* Titlepage Permissions:: Sample Titlepage copying permissions. - - -File: texi.info, Node: Inserting Permissions, Next: ifinfo Permissions, Up: Sample Permissions - -Inserting Permissions -===================== - - In a Texinfo file, the first `@ifinfo' section usually begins with a -line that says what the file documents. This is what a person reading -the unprocessed Texinfo file or using the advanced Info command `g *' -sees first. *note Advanced Info commands: (info)Expert, for more -information. (A reader using the regular Info commands usually starts -reading at the first node and skips this first section, which is not in -a node.) - - In the `@ifinfo' section, the summary sentence is followed by a -copyright notice and then by the copying permission notice. One of the -copying permission paragraphs is enclosed in `@ignore' and `@end -ignore' commands. This paragraph states that the Texinfo file can be -processed through TeX and printed, provided the printed manual carries -the proper copying permission notice. This paragraph is not made part -of the Info file since it is not relevant to the Info file; but it is a -mandatory part of the Texinfo file since it permits people to process -the Texinfo file in TeX and print the results. - - In the printed manual, the Free Software Foundation copying -permission notice follows the copyright notice and publishing -information and is located within the region delineated by the -`@titlepage' and `@end titlepage' commands. The copying permission -notice is exactly the same as the notice in the `@ifinfo' section -except that the paragraph enclosed in `@ignore' and `@end ignore' -commands is not part of the notice. - - To make it simple to insert a permission notice into each section of -the Texinfo file, sample permission notices for each section are -reproduced in full below. - - Note that you may need to specify the correct name of a section -mentioned in the permission notice. For example, in `The GDB Manual', -the name of the section referring to the General Public License is -called the "GDB General Public License", but in the sample shown below, -that section is referred to generically as the "GNU General Public -License". If the Texinfo file does not carry a copy of the General -Public License, leave out the reference to it, but be sure to include -the rest of the sentence. - - -File: texi.info, Node: ifinfo Permissions, Next: Titlepage Permissions, Prev: Inserting Permissions, Up: Sample Permissions - -`ifinfo' Copying Permissions -============================ - - In the `@ifinfo' section of a Texinfo file, the standard Free -Software Foundation permission notice reads as follows: - - This file documents ... - - Copyright 1992 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. - - @ignore - Permission is granted to process this file through TeX - and print the results, provided the printed document - carries a copying permission notice identical to this - one except for the removal of this paragraph (this - paragraph not being relevant to the printed manual). - - @end ignore - Permission is granted to copy and distribute modified - versions of this manual under the conditions for - verbatim copying, provided also that the sections - entitled ``Copying'' and ``GNU General Public License'' - are included exactly as in the original, and 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 Free Software Foundation. - - -File: texi.info, Node: Titlepage Permissions, Prev: ifinfo Permissions, Up: Sample Permissions - -Titlepage Copying Permissions -============================= - - In the `@titlepage' section of a Texinfo file, the standard Free -Software Foundation copying permission notice follows the copyright -notice and publishing information. The standard phrasing is as follows: - - 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 also that the sections - entitled ``Copying'' and ``GNU General Public License'' - are included exactly as in the original, and 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 Free Software Foundation. - - -File: texi.info, Node: Include Files, Next: Headings, Prev: Sample Permissions, Up: Top - -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 File Requirements:: What `texinfo-multiple-files-update' expects. -* 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: texi.info, Node: Using Include Files, Next: texinfo-multiple-files-update, Up: Include Files - -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 - - 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. - - -File: texi.info, Node: texinfo-multiple-files-update, Next: Include File Requirements, Prev: Using Include Files, Up: Include Files - -`texinfo-multiple-files-update' -=============================== - - GNU Emacs Texinfo mode provides a command to handle included files -called `texinfo-multiple-files-update'. 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: texi.info, Node: Include File Requirements, Next: Sample Include File, Prev: texinfo-multiple-files-update, Up: Include Files - -Include File 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: texi.info, Node: Sample Include File, Next: Include Files Evolution, Prev: Include File Requirements, Up: Include Files - -Sample File with `@include' -=========================== - - Here is an example of a complete 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 - - @setchapternewpage odd - @titlepage - @sp 12 - @center @titlefont{Include Example} - @sp 2 - @center by Whom Ever - - @page - @vskip 0pt plus 1filll - Copyright @copyright{} 1990 Free Software Foundation, Inc. - @end titlepage - - @ifinfo - @node Top, First, (dir), (dir) - @top Master Menu - @end ifinfo - - @include foo.texinfo - @include bar.texinfo - @include concept-index.texinfo - - @summarycontents - @contents - - @bye - - An included file, such as `foo.texinfo', might look like this: - - @node First, Second, , Top - @chapter First Chapter - - Contents of first chapter ... - - The full contents of `concept-index.texinfo' might be as simple as -this: - - @node Concept Index, , Second, Top - @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: texi.info, Node: Include Files Evolution, Prev: Sample Include File, Up: Include Files - -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: texi.info, Node: Headings, Next: Catching Mistakes, Prev: Include Files, Up: Top - -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: texi.info, Node: Headings Introduced, Next: Heading Format, Up: Headings - -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. Usually, you will use one or other -of 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: texi.info, Node: Heading Format, Next: Heading Choice, Prev: Headings Introduced, Up: Headings - -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: texi.info, Node: Heading Choice, Next: Custom Headings, Prev: Heading Format, Up: Headings - -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: texi.info, Node: Custom Headings, Prev: Heading Choice, Up: Headings - -How to Make Your Own Headings -============================= - - You can use the standard headings provided with Texinfo or specify -your own. - - Texinfo provides six commands for specifying headings and footings. -The `@everyheading' command and `@everyfooting' command generate page -headers and footers that are the same for both even- and odd-numbered -pages. The `@evenheading' command and `@evenfooting' command generate -headers and footers for even-numbered (left-hand) pages; and the -`@oddheading' command and `@oddfooting' command generate headers and -footers for odd-numbered (right-hand) pages. - - Write custom heading specifications in the Texinfo file immediately -after the `@end titlepage' command. Enclose your specifications -between `@iftex' and `@end iftex' commands since the -`texinfo-format-buffer' command may not recognize them. Also, 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: - - @iftex - @headings off - @everyheading @thischapter @| @thispage @| @today{} - @end iftex - -You need to divide the left part from the central part and the central -part from the right had part by inserting `@|' between parts. -Otherwise, the specification command will not be able to tell where the -text for one part ends and the next part begins. - - Each part can contain text or @-commands. The text is printed as if -the part were within an ordinary paragraph in the body of the page. -The @-commands replace themselves with the page number, date, chapter -name, or whatever. - - Here are the six heading and footing commands: - -`@everyheading LEFT @| CENTER @| RIGHT' -`@everyfooting LEFT @| CENTER @| RIGHT' - The `every' commands specify the format for both even- and - odd-numbered pages. These commands are for documents that are - printed on one side of each sheet of paper, or for documents in - which you want symmetrical headers or footers. - -`@evenheading LEFT @| CENTER @| RIGHT' -`@oddheading LEFT @| CENTER @| RIGHT' -`@evenfooting LEFT @| CENTER @| RIGHT' -`@oddfooting LEFT @| CENTER @| RIGHT' - The `even' and `odd' commands specify the format for even-numbered - pages and odd-numbered pages. These commands are for books and - manuals that are printed on both sides of each sheet of paper. - - Use the `@this...' series of @-commands to provide the names of -chapters and sections and the page number. You can use the `@this...' -commands in the left, center, or right portions of headers and footers, -or anywhere else in a Texinfo file so long as they are between `@iftex' -and `@end iftex' commands. - - Here are the `@this...' commands: - -`@thispage' - Expands to the current page number. - -`@thischaptername' - Expands to the name of the current chapter. - -`@thischapter' - Expands to the number and name of the current chapter, in the - format `Chapter 1: Title'. - -`@thistitle' - Expands to the name of the document, as specified by the - `@settitle' command. - -`@thisfile' - For `@include' files only: expands to the name of the current - `@include' file. If the current Texinfo source file is not an - `@include' file, this command has no effect. This command does - *not* provide the name of the current Texinfo source file unless - it is an `@include' file. (*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: - - @iftex - @headings off - @everyheading @emph{Draft!} @| @thispage @| @thischapter - @everyfooting @| @| Version: 0.27: @today{} - @end iftex - - Beware of overlong titles: they may overlap another part of the -header or footer and blot it out. - - -File: texi.info, Node: Catching Mistakes, Next: Refilling Paragraphs, Prev: Headings, Up: Top - -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: texi.info, Node: makeinfo preferred, Next: Debugging with Info, Up: Catching Mistakes - -`makeinfo' Find Errors -====================== - - The `makeinfo' program does an excellent job of catching errors and -reporting them--far better than either the `texinfo-format-region' or -the `texinfo-format-buffer' command. 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: texi.info, Node: Debugging with Info, Next: Debugging with TeX, Prev: makeinfo preferred, Up: Catching Mistakes - -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 make 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').) - diff --git a/gnu/usr.bin/texinfo/info/info-stnd.info b/gnu/usr.bin/texinfo/info/info-stnd.info deleted file mode 100644 index 31f486a..0000000 --- a/gnu/usr.bin/texinfo/info/info-stnd.info +++ /dev/null @@ -1,1259 +0,0 @@ -This is Info file info-stnd.info, produced by Makeinfo-1.55 from the -input file info-stnd.texi. - -This file documents GNU Info, a program for viewing the on-line -formatted versions of Texinfo files. This documentation is different -from the documentation for the Info reader that is part of GNU Emacs. -If you do not know how to use Info, but have a working Info reader, you -should read that documentation first. - -Copyright (C) 1992, 1993 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 also that the -sections entitled "Copying" and "GNU General Public License" are -included exactly as in the original, and 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 Free Software Foundation. - - -File: info-stnd.info, Node: Top, Next: What is Info, Prev: (dir), Up: (dir) - -The GNU Info Program -******************** - -This file documents GNU Info, a program for viewing the on-line -formatted versions of Texinfo files, version 2.9. This documentation -is different from the documentation for the Info reader that is part of -GNU Emacs. - -* Menu: - -* What is Info:: -* Options:: Options you can pass on the command line. -* Cursor Commands:: Commands which move the cursor within a node. -* Scrolling Commands:: Commands for moving the node around - in a window. -* 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. -* GNU Info Global Index:: Global index containing keystrokes, - command names, variable names, - and general concepts. - - -File: info-stnd.info, Node: What is Info, Next: Options, Prev: Top, Up: Top - -What is Info? -************* - -"Info" is a program which is used to view Info files on an ASCII -terminal. "Info files" are the result of processing Texinfo files with -the program `makeinfo' or with one of the Emacs commands, such as `M-x -texinfo-format-buffer'. Texinfo itself is a documentation system that -uses a single source file to produce both on-line information and -printed output. You can typeset and print the files that you read in -Info. - - -File: info-stnd.info, Node: Options, Next: Cursor Commands, Prev: What is Info, Up: Top - -Command Line Options -******************** - -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-NAME OPTION-VALUE] MENU-ITEM... - -The following OPTION-NAMES are available when invoking Info from the -shell: - -`--directory DIRECTORY-PATH' -`-d DIRECTORY-PATH' - Add 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. - Alternatively, you may specify a value for the environment variable - `INFOPATH'; if `--directory' is not given, the value of `INFOPATH' - is used. The value of `INFOPATH' is a colon separated list of - directory names. If you do not supply `INFOPATH' or - `--directory-path', Info uses a default path. - -`--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. - -`--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'(1) - (*note Options-Footnotes::). 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. - -`--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. - -`--help' -`-h' - Produces a relatively brief description of the available Info - options. - -`--version' - Prints the version information of Info and exits. - -`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, - while the second argument is a menu item in the first argument's - node. 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'. - - -File: info-stnd.info, Node: Options-Footnotes, Up: Options - -(1) 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 from -the shell as in: `info --node '(emacs)Buffers'' - - -File: info-stnd.info, Node: Cursor Commands, Next: Scrolling Commands, Prev: Options, Up: Top - -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 Character Conventions: -(emacs)Characters, if you are unfamiliar with the notation. - -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'(1) (*note Cursor Commands-Footnotes::) -command name (displayed in parentheses), and a short description of -what the command does. All of the cursor motion commands can take an -"numeric" argument (*note `universal-argument': Miscellaneous -Commands.), to find out how to supply them. 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') - Move the cursor down to the next line. - -`C-p' (`prev-line') - Move the cursor up to the previous line. - -`C-a' (`beginning-of-line') - Move the cursor to the start of the current line. - -`C-e' (`end-of-line') - Move the cursor to the end of the current line. - -`C-f' (`forward-char') - Move the cursor forward a character. - -`C-b' (`backward-char') - Move the cursor backward a character. - -`M-f' (`forward-word') - Move the cursor forward a word. - -`M-b' (`backward-word') - Move the cursor backward a word. - -`M-<' (`beginning-of-node') -`b' - Move the cursor to the start of the current node. - -`M->' (`end-of-node') - 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. - - -File: info-stnd.info, Node: Cursor Commands-Footnotes, Up: Cursor Commands - -(1) `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 - -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. - -`SPC' (`scroll-forward') -`C-v' - 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. - -`DEL' (`scroll-backward') -`M-v' - Shift the text in this window down. The inverse of - `scroll-forward'. - -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': Variables, for more -information. - -`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. - - -File: info-stnd.info, Node: Node Commands, Next: Searching Commands, Prev: Scrolling Commands, Up: Top - -Selecting a New 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'. - -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') - Select the `Next' node. - -`p' (`prev-node') - Select the `Prev' node. - -`u' (`up-node') - 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 through the list of already visited nodes for this window. `l' -with a negative numeric argument moves forward through the history of -nodes for this window, so you can quickly step between two adjacent (in -viewing history) nodes. - -`l' (`history-node') - Select the most recently selected node in this window. - -Two additional commands make it easy to select the most commonly -selected nodes; they are `t' and `d'. - -`t' (`top-node') - Select the node `Top' in the current Info file. - -`d' (`dir-node') - 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') - Selects the first node which appears in this file. This node is - most often `Top', but it does not have to be. - -`>' (`last-node') - Select the last node which appears in this file. - -`]' (`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': Variables, for more information. - -`g' (`goto-node') - Read the name of a node and select it. No completion is done while - reading the node name, since the desired node may reside in a - separate file. The node must be typed exactly as it appears in - the Info file. A file name may be included as with any node - specification, for example - - `g(emacs)Buffers' - - finds the node `Buffers' in the Info file `emacs'. - -`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 - -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. - -`C-s' (`isearch-forward') - Interactively search forward through the Info file for a string as - you type it. - -`C-r' (`isearch-backward') - Interactively search backward through the Info file for a string as - you type it. - -`i' (`index-search') - Look up a string in the indices for this Info file, and select a - node where the found index entry points to. - -`,' (`next-index-match') - Move to the node containing the next matching index item from the - last `i' command. - -The most basic searching command is `s' (`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. - -"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. - - -File: info-stnd.info, Node: Xref Commands, Next: Window Commands, Prev: Searching Commands, Up: Top - -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 - -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 - -Selecting Xrefs -=============== - -The following table lists the Info commands which operate on menu items. - -`1' (`menu-digit') -`2' ... `9' - 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. - -`0' (`last-menu-item') - 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. - -`M-x find-menu' - Move the cursor to the start of this node's menu. - -This table lists the Info commands which operate on note cross -references. - -`f' (`xref-item') -`r' - 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. - -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') - Move the cursor the start of the nearest previous menu item or note - reference in this node. - -`RET' (`select-reference-this-line') - 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 - -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 - -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--------------- - -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 - -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, please *note automatic-tiling: - Variables. for more information. - -`C-x 0' (`delete-window') - Delete the current window from the screen. If you have made too - many windows and your screen appears cluttered, this is the way to - get rid of some of them. - -`C-x 1' (`keep-one-window') - Delete all of the windows excepting the current one. - -`ESC C-v' (`scroll-other-window') - Scroll the other window, in the same fashion that `C-v' might - scroll the current window. Given a negative argument, scroll the - "other" window backward. - -`C-x ^' (`grow-window') - Grow (or shrink) the current window. Given a numeric argument, - grow the current window that many lines; with a negative numeric - argument, shrink the window instead. - -`C-x t' (`tile-windows') - Divide the available screen space among all of the visible windows. - Each window is given an equal portion of the screen in which to - display its contents. The variable `automatic-tiling' can cause - `tile-windows' to be called when a window is created or deleted. - *Note `automatic-tiling': Variables. - - -File: info-stnd.info, Node: The Echo Area, Prev: Basic Windows, Up: Window Commands - -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') - Move forward a character. - -`C-b' (`echo-area-backward') - Move backward a character. - -`C-a' (`echo-area-beg-of-line') - Move to the start of the input line. - -`C-e' (`echo-area-end-of-line') - Move to the end of the input line. - -`M-f' (`echo-area-forward-word') - Move forward a word. - -`M-b' (`echo-area-backward-word') - Move backward a word. - -`C-d' (`echo-area-delete') - Delete the character under the cursor. - -`DEL' (`echo-area-rubout') - Delete the character behind the cursor. - -`C-g' (`echo-area-abort') - Cancel or quit the current operation. If completion is being read, - `C-g' discards the text of the input line which does not match any - completion. If the input line is empty, `C-g' aborts the calling - function. - -`RET' (`echo-area-newline') - Accept (or forces completion of) the current input line. - -`C-q' (`echo-area-quoted-insert') - Insert the next character verbatim. This is how you can insert - control characters into a search string, for example. - -PRINTING CHARACTER (`echo-area-insert') - Insert the character. - -`M-TAB' (`echo-area-tab-insert') - Insert a TAB character. - -`C-t' (`echo-area-transpose-chars') - Transpose the characters at the cursor. - -The next group of commands deal with "killing", and "yanking" text. -For an in depth discussion of killing and yanking, *note Killing and -Deleting: (emacs)Killing. - -`M-d' (`echo-area-kill-word') - Kill the word following the cursor. - -`M-DEL' (`echo-area-backward-kill-word') - Kill the word preceding the cursor. - -`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 `?', the possible - completions would contain: - - 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. - - -File: info-stnd.info, Node: Printing Nodes, Next: Miscellaneous Commands, Prev: Window Commands, Up: Top - -Printing Out Nodes -****************** - -You may wish to print out the contents of a node as a quick reference -document for later use. Info provides you with a command for doing -this. 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. - -`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'. - - -File: info-stnd.info, Node: Miscellaneous Commands, Next: Variables, Prev: Printing Nodes, Up: Top - -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') -`?' - 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') - 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. - -`M-1' (`add-digit-to-numeric-arg') -`M-2' ... `M-9' - 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' - -`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') - Cancel current operation. - -The `q' command of Info simply quits running Info. - -`q' (`quit') - 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. - -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: GNU Info Global Index, Prev: Miscellaneous Commands, Up: Top - -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. - -`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; 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. - This variable is `On' 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. - -`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'. - -`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. - -`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. - -`scroll-behavior' - Control what happens when forward scrolling is requested at the - end of a node, or when backward scrolling is requested at the - beginning of a node. The default value for this variable is - `Continuous'. There are three possible values for this variable: - - `Continuous' - Try to get the first item in this node's menu, or failing - that, the `Next' node, or failing that, the `Next' of the - `Up'. This behavior is identical to using the `]' - (`global-next-node') and `[' (`global-prev-node') commands. - - `Next Only' - Only try to get the `Next' node. - - `Page Only' - Simply give up, changing nothing. If `scroll-behavior' is - `Page Only', no scrolling command can change the node that is - being viewed. - -`scroll-step' - The number of lines to scroll when the cursor moves out of the - window. Scrolling happens automatically if the cursor has moved - out of the visible portion of the node text when it is time to - display. Usually the scrolling is done so as to put the cursor on - the center line of the current window. However, if the variable - `scroll-step' has a nonzero value, Info attempts to scroll the - node text by that many lines; if that is enough to bring the - cursor back into the window, that is what is done. The default - value of this variable is 0, thus placing the cursor (and the text - it is attached to) in the center of the window. Setting this - variable to 1 causes a kind of "smooth scrolling" which some - people prefer. - -`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. - - -File: info-stnd.info, Node: GNU Info Global Index, Prev: Variables, Up: Top - -Global Index -************ - -* Menu: - -* ,: Searching Commands. -* 0, in Info windows: Selecting Xrefs. -* 1 ... 9, in Info windows: Selecting Xrefs. -* 1 ... 9, in Info windows: Selecting Xrefs. -* <: Node Commands. -* >: Node Commands. -* ?, in Info windows: Miscellaneous Commands. -* ?, in the echo area: The Echo Area. -* -subnodes, command line option: Options. -* abort-key: Miscellaneous Commands. -* add-digit-to-numeric-arg: Miscellaneous Commands. -* arguments, command line: Options. -* automatic-footnotes: Variables. -* automatic-tiling: Variables. -* b, in Info windows: Cursor Commands. -* backward-char: Cursor Commands. -* backward-word: Cursor Commands. -* beginning-of-line: Cursor Commands. -* beginning-of-node: Cursor Commands. -* C-a, in Info windows: Cursor Commands. -* C-a, in the echo area: The Echo Area. -* C-b, in Info windows: Cursor Commands. -* C-b, in the echo area: The Echo Area. -* C-d, in the echo area: The Echo Area. -* C-e, in Info windows: Cursor Commands. -* C-e, in the echo area: The Echo Area. -* C-f, in Info windows: Cursor Commands. -* C-f, in the echo area: The Echo Area. -* C-g, in Info windows: Miscellaneous Commands. -* C-g, in the echo area: The Echo Area. -* C-h: Miscellaneous Commands. -* C-k, in the echo area: The Echo Area. -* C-l: Scrolling Commands. -* C-n: Cursor Commands. -* C-p: Cursor Commands. -* C-q, in the echo area: The Echo Area. -* C-r: Searching Commands. -* C-s: Searching Commands. -* C-t, in the echo area: The Echo Area. -* C-u: Miscellaneous Commands. -* C-v: Scrolling Commands. -* C-w: Scrolling Commands. -* C-x 0: Basic Windows. -* C-x 1: Basic Windows. -* C-x 2: Basic Windows. -* C-x b: Node Commands. -* C-x C-b: Node Commands. -* C-x C-f: Node Commands. -* C-x DEL, in the echo area: The Echo Area. -* C-x k: Node Commands. -* C-x o: Basic Windows. -* C-x t: Basic Windows. -* C-x ^: Basic Windows. -* C-y, in the echo area: The Echo Area. -* cancelling the current operation: Miscellaneous Commands. -* cancelling typeahead: Miscellaneous Commands. -* command line options: Options. -* commands, describing: Miscellaneous Commands. -* cursor, moving: Cursor Commands. -* d: Node Commands. -* DEL, in Info windows: Scrolling Commands. -* DEL, in the echo area: The Echo Area. -* delete-window: Basic Windows. -* describe-command: Miscellaneous Commands. -* describe-key: Miscellaneous Commands. -* describe-variable: Variables. -* dir-node: Node Commands. -* directory path: Options. -* echo area: The Echo Area. -* echo-area-abort: The Echo Area. -* echo-area-backward: The Echo Area. -* echo-area-backward-kill-line: The Echo Area. -* echo-area-backward-kill-word: The Echo Area. -* echo-area-backward-word: The Echo Area. -* echo-area-beg-of-line: The Echo Area. -* echo-area-complete: The Echo Area. -* echo-area-delete: The Echo Area. -* echo-area-end-of-line: The Echo Area. -* echo-area-forward: The Echo Area. -* echo-area-forward-word: The Echo Area. -* echo-area-insert: The Echo Area. -* echo-area-kill-line: The Echo Area. -* echo-area-kill-word: The Echo Area. -* echo-area-newline: The Echo Area. -* echo-area-possible-completions: The Echo Area. -* echo-area-quoted-insert: The Echo Area. -* echo-area-rubout: The Echo Area. -* echo-area-scroll-completions-window: The Echo Area. -* echo-area-tab-insert: The Echo Area. -* echo-area-transpose-chars: The Echo Area. -* echo-area-yank: The Echo Area. -* echo-area-yank-pop: The Echo Area. -* end-of-line: Cursor Commands. -* end-of-node: Cursor Commands. -* errors-ring-bell: Variables. -* ESC C-f: Miscellaneous Commands. -* ESC C-v, in Info windows: Basic Windows. -* ESC C-v, in the echo area: The Echo Area. -* f: Selecting Xrefs. -* file, outputting to: Options. -* find-menu: Selecting Xrefs. -* first-node: Node Commands. -* footnotes, displaying: Miscellaneous Commands. -* forward-char: Cursor Commands. -* forward-word: Cursor Commands. -* functions, describing: Miscellaneous Commands. -* g: Node Commands. -* gc-compressed-files: Variables. -* get-help-window: Miscellaneous Commands. -* get-info-help-node: Miscellaneous Commands. -* global-next-node: Node Commands. -* global-prev-node: Node Commands. -* goto-node: Node Commands. -* grow-window: Basic Windows. -* h: Miscellaneous Commands. -* history-node: Node Commands. -* i: Searching Commands. -* index-search: Searching Commands. -* Info file, selecting: Options. -* INFO_PRINT_COMMAND, environment variable: Printing Nodes. -* isearch-backward: Searching Commands. -* isearch-forward: Searching Commands. -* ISO Latin characters: Variables. -* ISO-Latin: Variables. -* keep-one-window: Basic Windows. -* keys, describing: Miscellaneous Commands. -* kill-node: Node Commands. -* l: Node Commands. -* last-menu-item: Selecting Xrefs. -* last-node: Node Commands. -* list-visited-nodes: Node Commands. -* m: Selecting Xrefs. -* M-1 ... M-9: Miscellaneous Commands. -* M-<: Cursor Commands. -* M->: Cursor Commands. -* M-b, in Info windows: Cursor Commands. -* M-b, in the echo area: The Echo Area. -* M-d, in the echo area: The Echo Area. -* M-DEL, in the echo area: The Echo Area. -* M-f, in Info windows: Cursor Commands. -* M-f, in the echo area: The Echo Area. -* M-r: Cursor Commands. -* M-TAB, in Info windows: Selecting Xrefs. -* M-TAB, in the echo area: The Echo Area. -* M-v: Scrolling Commands. -* M-y, in the echo area: The Echo Area. -* menu, following: Options. -* menu-digit: Selecting Xrefs. -* menu-item: Selecting Xrefs. -* move-to-next-xref: Selecting Xrefs. -* move-to-prev-xref: Selecting Xrefs. -* move-to-window-line: Cursor Commands. -* n: Node Commands. -* next-index-match: Searching Commands. -* next-line: Cursor Commands. -* next-node: Node Commands. -* next-window: Basic Windows. -* node, selecting: Options. -* nodes, selection of: Node Commands. -* numeric arguments: Miscellaneous Commands. -* outputting to a file: Options. -* p: Node Commands. -* prev-line: Cursor Commands. -* prev-node: Node Commands. -* prev-window: Basic Windows. -* print-node: Printing Nodes. -* printing: Printing Nodes. -* printing characters, in the echo area: The Echo Area. -* q: Miscellaneous Commands. -* quit: Miscellaneous Commands. -* quitting: Miscellaneous Commands. -* r: Selecting Xrefs. -* redraw-display: Scrolling Commands. -* RET, in Info windows: Selecting Xrefs. -* RET, in the echo area: The Echo Area. -* s: Searching Commands. -* screen, changing the height of: Miscellaneous Commands. -* scroll-backward: Scrolling Commands. -* scroll-behavior: Variables. -* scroll-forward: Scrolling Commands. -* scroll-other-window: Basic Windows. -* scroll-step: Variables. -* scrolling: Scrolling Commands. -* scrolling through node structure: Scrolling Commands. -* search: Searching Commands. -* searching: Searching Commands. -* select-reference-this-line: Selecting Xrefs. -* select-visited-node: Node Commands. -* set-screen-height: Miscellaneous Commands. -* set-variable: Variables. -* show-footnotes: Miscellaneous Commands. -* show-index-match: Variables. -* SPC, in Info windows: Scrolling Commands. -* SPC, in the echo area: The Echo Area. -* split-window: Basic Windows. -* t: Node Commands. -* TAB, in Info windows: Selecting Xrefs. -* TAB, in the echo area: The Echo Area. -* tile-windows: Basic Windows. -* tiling: Basic Windows. -* toggle-wrap: Scrolling Commands. -* top-node: Node Commands. -* u: Node Commands. -* universal-argument: Miscellaneous Commands. -* up-node: Node Commands. -* variables, describing: Variables. -* variables, setting: Variables. -* version information: Options. -* view-file: Node Commands. -* visible-bell: Variables. -* where-is: Miscellaneous Commands. -* windows, creating: Basic Windows. -* windows, deleting: Basic Windows. -* windows, manipulating: Window Commands. -* windows, selecting: Basic Windows. -* xref-item: Selecting Xrefs. -* [: Node Commands. -* ]: Node Commands. - - - -Tag Table: -Node: Top1263 -Node: What is Info2593 -Node: Options3127 -Node: Options-Footnotes6157 -Node: Cursor Commands6411 -Node: Cursor Commands-Footnotes8906 -Node: Scrolling Commands9136 -Node: Node Commands11600 -Node: Searching Commands15563 -Node: Xref Commands17151 -Node: Parts of an Xref17766 -Node: Selecting Xrefs19711 -Node: Window Commands21298 -Node: The Mode Line22233 -Node: Basic Windows23872 -Node: The Echo Area26374 -Node: Printing Nodes30531 -Node: Miscellaneous Commands31174 -Node: Variables34345 -Node: GNU Info Global Index40515 - -End Tag Table diff --git a/gnu/usr.bin/texinfo/info/info.info b/gnu/usr.bin/texinfo/info/info.info deleted file mode 100644 index b6fd850..0000000 --- a/gnu/usr.bin/texinfo/info/info.info +++ /dev/null @@ -1,777 +0,0 @@ -This is Info file info.info, produced by Makeinfo-1.55 from the input -file info.texi. - - This file describes how to use Info, the on-line, menu-driven GNU -documentation system. - - Copyright (C) 1989, 1992 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 Free Software Foundation. - - -File: info.info, Node: Top, Next: Getting Started, Prev: (dir), Up: (dir) - -Info: An Introduction -********************* - - Info is a program for reading documentation, which you are using now. - - To learn how to use Info, type the command `h'. It brings you to a -programmed instruction sequence. - - To learn advanced Info commands, type `n' twice. This brings you to -`Info for Experts', skipping over the . `Getting Started' chapter. - -* Menu: - -* Getting Started:: -* Advanced Info:: -* Create an Info File:: - - -File: info.info, Node: Getting Started, Next: Advanced Info, Prev: Top, Up: Top - -Getting Started -*************** - - This first part of the Info manual describes how to get around inside -of Info. The second part of the manual describes various advanced Info -commands, and how to write an Info as distinct from a Texinfo file. -The third part is about how to generate Info files from Texinfo files. - -* 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, Rubout, B and ^L commands. -* Help-M:: Menus -* Help-Adv:: Some advanced Info commands -* Help-Q:: Quitting Info - - -File: info.info, Node: Help-Small-Screen, Next: Help, Up: Getting Started - -Starting Info on a Small Screen -=============================== - - Since your terminal has an unusually small number of lines on its -screen, it is necessary to give you special advice at the beginning. - - If you see the text `--All----' at near the bottom right corner of -the screen, it means the entire text you are looking at fits on the -screen. If you see `--Top----' instead, it means that there is more -text below that does not fit. To move forward through the text and see -another screen full, press the Space bar, SPC. To move back up, press -the key labeled `Rubout' or `Delete' or DEL. - - 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 17 -This is line 18 -This is line 19 -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 -If you have managed to get here, go back to the beginning with DEL, and -come back here again, then you understand SPC and DEL. So now type an -`n'--just one character; do not type the quotes and do not type the -Return key, RET, 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 - -How to use Info -=============== - - You are talking to the program Info, for reading documentation. - - 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 top line of a node is its "header". This node's header (look at -it now) says that it is the node named `Help' in the file `info'. It -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. - - Besides a `Next', a node can have a `Previous' or an `Up'. This -node has a `Previous' but no `Up', as you can see. - - 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. - - -File: info.info, Node: Help-P, Next: Help-^L, Prev: Help, Up: Getting Started - -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 do that yet. First, try the `p' command, which takes - you to the `Previous' node. When you get there, you can do an `n' -again to return here. - - This all probably seems insultingly simple so far, but *do not* be -led into skimming. Things will get more complicated soon. Also, do -not try a new command until you are told it is time to. Otherwise, you -may make Info skip past an important warning that was coming up. - - >> Now do an `n' to get to the node `Help-^L' and learn more. - - -File: info.info, Node: Help-^L, Next: Help-M, Prev: Help-P, Up: Getting Started - -The Space, Rubout, B and ^L commands. -===================================== - - This node's header tells you that you are now at node `Help-^L', and -that `p' would get you back to `Help-P'. The node's title is -underlined; it says what the node is about (most nodes have titles). - - This is a big node and it does not all fit on your display screen. -You can tell that there is more that is not visible because you can see -the string `--Top-----' rather than `--All----' near the bottom right -corner of the screen. - - The SPC, DEL 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 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 DEL 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 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 type a SPC when there is no more to see, it rings the bell -and otherwise does nothing. The same goes for a DEL when the header of -the node is visible. - - If your screen is ever garbaged, you can tell Info to print it out -again by typing `C-l' (`Control-L', that is--hold down "Control" and -type an L or `l'). - - >> Type `C-l' now. - - To move back to the beginning of the node you are on, you can type a -lot of DELs. You can also type simply `b' for beginning. - - >> Try that now. (I have put in enough verbiage to make sure you are - not on the first screenful now). Then come back, typing SPC -several times. - - You have just learned a considerable number of commands. If you -want to use one but have trouble remembering which, you should type a ? -which prints out a brief list of commands. When you are finished -looking at the list, make it go away by typing a SPC. - - >> Type a ? now. After it finishes, type a SPC. - - (If you are using the standalone Info reader, type `l' to return -here.) - - From now on, you will encounter large nodes without warning, and -will be expected to know how to use SPC and DEL 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' to see the description of the `m' command. - - -File: info.info, Node: Help-M, Next: Help-Adv, Prev: Help-^L, Up: Getting Started - -Menus -===== - - Menus and the `m' command - - With only the `n' and `p' 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 `:'), the name of the node that talks about -that subtopic, 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: FOO's Node This tells about FOO - - The subtopic name is Foo, and the node describing it is `FOO's Node'. -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:'.]] - - 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'. - - >> Now use SPCs to find the menu in this node, then come back to -the front with a `b'. 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. - - The command to go to one of the subnodes is `m'--but *do not do it -yet!* Before you use `m', you must understand the difference between -commands and arguments. So far, you have learned several commands that -do not need arguments. When you type one, Info processes it and is -instantly ready for another command. The `m' command is different: it -is incomplete without the "name of the subtopic". Once you have typed -`m', Info tries to read the subtopic name. - - Now look for the line containing many dashes near the bottom of the -screen. There is one more line beneath that one, but usually it is -blank If it is empty, 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 mean -Info is trying to read the "argument" to a command. At such times, -commands do not work, because Info tries to use them as the argument. -You must either type the argument and finish the command you started, -or type `Control-g' to cancel the command. When you have done one of -those things, the line becomes blank 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. - - Here is a menu to give you a chance to practice. - - * Menu: The menu starts here. - - This menu givs you three ways of going to one place, Help-FOO. - - * Foo: Help-FOO. A node you can visit for fun. -* Bar: Help-FOO. Strange! two ways to get to the same place. -* Help-FOO:: And yet another! ->> 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' item name. Do not type RET yet. - - While you are typing the item name, you can use the DEL character to -cancel one character at a time if you make a mistake. - - >> Type one to cancel the `R'. You could type another `R' to -replace it. 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. - - >> Type `n' to see more commands. - - Here is another way to get to Help-FOO, a menu. You can ignore this -if you want, or else try it (but then please come back to here). - -* Menu: - -* Help-FOO:: - - -File: info.info, Node: Help-FOO, Up: Help-M - -The `u' command ---------------- - - Congratulations! This is the node `Help-FOO'. Unlike the other -nodes you have seen, this one has an `Up': `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". That puts you at the *front* of the node--to get back to where -you were reading you have to type some SPCs. - - >> Now type `u' to move back up to `Help-M'. - - -File: info.info, Node: Help-Adv, Next: Help-Q, Prev: Help-M, Up: Getting Started - -Some advanced Info commands -=========================== - - The course is almost over, so please stick with it to the end. - - 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 at a time. If you have been following directions, an `l' command -now will get you back to `Help-M'. Another `l' command would undo the -`u' and get you back to `Help-FOO'. Another `l' would undo the `m' and -get you back to `Help-M'. - - >> Try typing three `l''s, pausing in between to see what each -`l' does. - - Then follow directions again and you will end up 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, to `Help-M'). - - The `d' command 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. - - >> Try doing a `d', then do an `l' to return here (yes, *do* -return). - - Sometimes, in Info documentation, you will see a cross reference. -Cross references look like this: *Note Cross: Help-Cross. That is a -real, live cross reference which is named `Cross' and points at the -node named `Help-Cross'. - - If you wish to follow a cross reference, you must use the `f' -command. The `f' must be followed by the cross reference name (in this -case, `Cross'). You can use DEL to edit the name, and 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. - - >> Type `f', followed by `Cross', and a RET. - - 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 printing the list, so if you do not actually -want to follow a reference you should type a `Control-g' to cancel the -`f'. - - >> Type "f?" to get a list of the footnotes in this node. Then type -a `Control-g' and see how the `f' gives up. - - >> Now type `n' to see the last node of the course. - - -File: info.info, Node: Help-Cross, Up: Help-Adv - -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 Info. So you cannot expect the -footnote to have a `Next', `Previous' or `Up' 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: Help-Q, Prev: Help-Adv, Up: Getting Started - -Quitting Info -============= - - To get out of Info, back to what you were doing before, type `q' for -"Quit". - - This is the end of the course on using Info. There are some other -commands that are not essential or are meant for experienced users; -they are useful, and you can find them by looking in the directory 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 RET, to get to the node about Info and see what other help is -available. - - -File: info.info, Node: Advanced Info, Next: Create an Info File, Prev: Getting Started, Up: Top - -Info for Experts -**************** - - This chapter describes various advanced Info commands, and how to -write an Info as distinct from a Texinfo file. (However, in most -cases, writing a Texinfo file is better, since you can use it *both* to -generate an Info file and to make a printed manual. *Note Overview of -Texinfo: (texinfo)Top.) - -* Menu: - -* Expert:: Advanced Info commands: g, s, e, and 1 - 5. -* 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 tag tables for Info files. -* Checking:: Checking an Info File - - -File: info.info, Node: Expert, Next: Add, Up: Advanced Info - -Advanced Info Commands -====================== - - `g', `s', `1', - `5', and `e' - - If you know a node's name, you can go there by typing `g', the name, -and RET. Thus, `gTopRET' would go to the node called `Top' in this -file (its directory node). `gExpertRET' would come back here. - - Unlike `m', `g' does not allow the use of abbreviations. - - To go to a node in another file, you can include the filename in the -node name by putting it at the front, in parentheses. Thus, -`g(dir)TopRET' would go to the Info Directory node, which is node `Top' -in the file `dir'. - - 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'. - - The `s' command allows you to search a whole file for a string. It -switches to the next node if and when that is necessary. You type `s' -followed by the string to search for, terminated by RET. To search for -the same string again, just `s' followed by RET will do. The file's -nodes are scanned in the order they are in in the file, which has no -necessary relationship to the order that they may be in in the tree -structure of menus and `next' pointers. But normally the two orders -are not very different. In any case, you can always do a `b' to find -out what node you have reached, if the header is not visible (this can -happen, because `s' puts your cursor at the occurrence of the string, -not at the beginning of the node). - - If you grudge the system each character of type-in it requires, you -might like to use the commands `1', `2', `3', `4', and `5'. They are -short for the `m' command together with an argument. "1", "2", "3", -"4", and "5". `1' goes through the first item in the current node's -menu; `2' goes through the second item, etc. Note that numbers larger -than 5 are not allowed. If the item you want is that far down, you are -better off using an abbreviation for its name than counting. - - The Info command `e' changes from Info mode to an ordinary Emacs -editing mode, so that you can edit the text of the current node. Type -`C-c C-c' to switch back to Info. The `e' command is allowed only if -the variable `Info-enable-edit' is non-`nil'. - - -File: info.info, Node: Add, Next: Menus, Prev: Expert, Up: Advanced Info - -Adding a new node to Info -========================= - - To add a new topic to the list in the directory, you must: - - 1. Create a node, 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, or the end of file. Note: 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 ^_. - - 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 `Top', which points at all -the documentation for Info. The `Next' node is `Menus'. - - The keywords "Node", "Previous", "Up" and "Next", 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 is relative, it is taken starting from the standard Info file -directory 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)'. 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 filename, since Info when searching for a node does not -expect one 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. - - -File: info.info, Node: Menus, Next: Cross-refs, Prev: Add, Up: Advanced Info - -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-the argument -that the user must give to the `m' command 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, than 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 on that file directory, but they do not have to; and files on that -directory are not automatically listed in the Info Directory node. - - Also, although the Info node graph is claimed to be a "hierarchy", -in fact it can be *any* directed graph. Shared structures and pointer -cycles are perfectly possible, and can be used if they are appropriate -to the meaning to be expressed. There is no need for all the nodes in -a file to form a connected structure. In fact, this file has two -connected components. You are in one of them, which is under the node -`Top'; the other contains the node `Help' which the `h' command goes -to. In fact, since there is no garbage collector, nothing terrible -happens if a substructure is not pointed to, but such a substructure is -rather useless since nobody can ever find out that it exists. - - -File: info.info, Node: Cross-refs, Next: Tags, Prev: Menus, Up: Advanced Info - -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.) - - They are just examples. The places they "lead to" do not really -exist! - - -File: info.info, Node: Tags, Next: Checking, Prev: Cross-refs, Up: Advanced Info - -Tag Tables for Info Files -========================= - - You can speed up the access to nodes of a large Info file by giving -it a tag table. Unlike the tag table for a program, the tag table for -an Info file lives inside the file itself and is used automatically -whenever Info reads in the file. - - To make a tag 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. - - Once the Info file has a tag table, you must make certain it is up -to date. If, 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 tag table, Info will no longer be able to find that node. To -update the tag table, use the `Info-tagify' command again. - - An Info file tag table appears at the end of the file and looks like -this: - - ^_ - 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: Advanced Info - -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: Create an Info File, Prev: Advanced Info, Up: Top - -Creating an Info File from a Makeinfo file -****************************************** - - `makeinfo' is a utility that converts a Texinfo file into an Info -file; `texinfo-format-region' and `texinfo-format-buffer' are GNU Emacs -functions that do the same. - - *Note Creating an Info File: (texinfo)Create an Info File, to learn -how to create an Info file from a Texinfo file. - - *Note Overview of Texinfo: (texinfo)Top, to learn how to write a -Texinfo file. - - - -Tag Table: -Node: Top913 -Node: Getting Started1431 -Node: Help-Small-Screen2179 -Node: Help3921 -Node: Help-P4949 -Node: Help-^L5811 -Node: Help-M8462 -Node: Help-FOO14030 -Node: Help-Adv14766 -Node: Help-Cross17148 -Node: Help-Q17794 -Node: Advanced Info18434 -Node: Expert19330 -Node: Add21601 -Node: Menus24635 -Node: Cross-refs27509 -Node: Tags28211 -Node: Checking29510 -Node: Create an Info File30434 - -End Tag Table diff --git a/gnu/usr.bin/texinfo/misc/texindex.c b/gnu/usr.bin/texinfo/misc/texindex.c deleted file mode 100644 index a88d516..0000000 --- a/gnu/usr.bin/texinfo/misc/texindex.c +++ /dev/null @@ -1,1700 +0,0 @@ -/* Prepare TeX index dribble output into an actual index. - - Version 1.45 - - Copyright (C) 1987, 1991, 1992 Free Software Foundation, Inc. - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2, or (at your option) - any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ - - -#include <stdio.h> -#include <ctype.h> -#include <errno.h> -#include "getopt.h" - -#if defined (STDC_HEADERS) -# include <string.h> -# include <stdlib.h> -# if !defined (bzero) -# define bzero(p, n) memset((p), '\0', (n)) -# endif /* !bzero */ -#else /* !STDC_HEADERS */ -extern int errno; -char *getenv (), *malloc (), *realloc (); -void bzero (); -#endif /* !STDC_HEADERS */ - -#if defined (HAVE_UNISTD_H) -# include <unistd.h> -#else /* !HAVE_UNISTD_H */ -long lseek (); -#endif /* !HAVE_UNISTD_H */ - -char *mktemp (); - -#if defined (VMS) -# if !defined (VAX11C) -# define noshare -# endif /* !VAX11C */ -# include <perror.h> -extern noshare int sys_nerr; -extern noshare char *sys_errlist[]; - -# include <file.h> - -# define TI_NO_ERROR ((1 << 28) | 1) -# define TI_FATAL_ERROR ((1 << 28) | 4) -# define unlink delete - -#else /* !VMS */ - -extern int sys_nerr; -extern char *sys_errlist[]; - -# if defined (HAVE_SYS_FCNTL_H) -# include <sys/types.h> -# include <sys/fcntl.h> -# endif /* HAVE_SYS_FCNTL_H */ - -# if defined (_AIX) || !defined (_POSIX_VERSION) -# include <sys/file.h> -# else /* !AIX && _POSIX_VERSION */ -# if !defined (HAVE_SYS_FCNTL_H) -# include <fcntl.h> -# endif /* !HAVE_FCNTL_H */ -# endif /* !_AIX && _POSIX_VERSION */ -# define TI_NO_ERROR 0 -# define TI_FATAL_ERROR 1 -#endif /* !VMS */ - -#if !defined (SEEK_SET) -# define SEEK_SET 0 -# define SEEK_CUR 1 -# define SEEK_END 2 -#endif /* !SEEK_SET */ - -/* When sorting in core, this structure describes one line - and the position and length of its first keyfield. */ -struct lineinfo -{ - char *text; /* The actual text of the line. */ - union { - char *text; /* The start of the key (for textual comparison). */ - long number; /* The numeric value (for numeric comparison). */ - } key; - long keylen; /* Length of KEY field. */ -}; - -/* This structure describes a field to use as a sort key. */ -struct keyfield -{ - int startwords; /* Number of words to skip. */ - int startchars; /* Number of additional chars to skip. */ - int endwords; /* Number of words to ignore at end. */ - int endchars; /* Ditto for characters of last word. */ - char ignore_blanks; /* Non-zero means ignore spaces and tabs. */ - char fold_case; /* Non-zero means case doesn't matter. */ - char reverse; /* Non-zero means compare in reverse order. */ - char numeric; /* Non-zeros means field is ASCII numeric. */ - char positional; /* Sort according to file position. */ - char braced; /* Count balanced-braced groupings as fields. */ -}; - -/* Vector of keyfields to use. */ -struct keyfield keyfields[3]; - -/* Number of keyfields stored in that vector. */ -int num_keyfields = 3; - -/* Vector of input file names, terminated with a null pointer. */ -char **infiles; - -/* Vector of corresponding output file names, or NULL, meaning default it - (add an `s' to the end). */ -char **outfiles; - -/* Length of `infiles'. */ -int num_infiles; - -/* Pointer to the array of pointers to lines being sorted. */ -char **linearray; - -/* The allocated length of `linearray'. */ -long nlines; - -/* Directory to use for temporary files. On Unix, it ends with a slash. */ -char *tempdir; - -/* Start of filename to use for temporary files. */ -char *tempbase; - -/* Number of last temporary file. */ -int tempcount; - -/* Number of last temporary file already deleted. - Temporary files are deleted by `flush_tempfiles' in order of creation. */ -int last_deleted_tempcount; - -/* During in-core sort, this points to the base of the data block - which contains all the lines of data. */ -char *text_base; - -/* Additional command switches .*/ - -/* Nonzero means do not delete tempfiles -- for debugging. */ -int keep_tempfiles; - -/* The name this program was run with. */ -char *program_name; - -/* Forward declarations of functions in this file. */ - -void decode_command (); -void sort_in_core (); -void sort_offline (); -char **parsefile (); -char *find_field (); -char *find_pos (); -long find_value (); -char *find_braced_pos (); -char *find_braced_end (); -void writelines (); -int compare_field (); -int compare_full (); -long readline (); -int merge_files (); -int merge_direct (); -void pfatal_with_name (); -void fatal (); -void error (); -void *xmalloc (), *xrealloc (); -char *concat (); -char *maketempname (); -void flush_tempfiles (); -char *tempcopy (); - -#define MAX_IN_CORE_SORT 500000 - -void -main (argc, argv) - int argc; - char **argv; -{ - int i; - - tempcount = 0; - last_deleted_tempcount = 0; - program_name = argv[0]; - - /* Describe the kind of sorting to do. */ - /* The first keyfield uses the first braced field and folds case. */ - keyfields[0].braced = 1; - keyfields[0].fold_case = 1; - keyfields[0].endwords = -1; - keyfields[0].endchars = -1; - - /* The second keyfield uses the second braced field, numerically. */ - keyfields[1].braced = 1; - keyfields[1].numeric = 1; - keyfields[1].startwords = 1; - keyfields[1].endwords = -1; - keyfields[1].endchars = -1; - - /* The third keyfield (which is ignored while discarding duplicates) - compares the whole line. */ - keyfields[2].endwords = -1; - keyfields[2].endchars = -1; - - decode_command (argc, argv); - - tempbase = mktemp (concat ("txiXXXXXX", "", "")); - - /* Process input files completely, one by one. */ - - for (i = 0; i < num_infiles; i++) - { - int desc; - long ptr; - char *outfile; - - desc = open (infiles[i], O_RDONLY, 0); - if (desc < 0) - pfatal_with_name (infiles[i]); - lseek (desc, 0L, SEEK_END); - ptr = lseek (desc, 0L, SEEK_CUR); - - close (desc); - - outfile = outfiles[i]; - if (!outfile) - { - outfile = concat (infiles[i], "s", ""); - } - - if (ptr < MAX_IN_CORE_SORT) - /* Sort a small amount of data. */ - sort_in_core (infiles[i], ptr, outfile); - else - sort_offline (infiles[i], ptr, outfile); - } - - flush_tempfiles (tempcount); - exit (TI_NO_ERROR); -} - -void -usage () -{ - fprintf (stderr, "\ -Usage: %s [-k] infile [-o outfile] ...\n", program_name); - exit (1); -} - -/* Decode the command line arguments to set the parameter variables - and set up the vector of keyfields and the vector of input files. */ - -void -decode_command (argc, argv) - int argc; - char **argv; -{ - int optc; - char **ip; - char **op; - - /* Store default values into parameter variables. */ - - tempdir = getenv ("TMPDIR"); -#ifdef VMS - if (tempdir == NULL) - tempdir = "sys$scratch:"; -#else - if (tempdir == NULL) - tempdir = "/tmp/"; - else - tempdir = concat (tempdir, "/", ""); -#endif - - keep_tempfiles = 0; - - /* Allocate ARGC input files, which must be enough. */ - - infiles = (char **) xmalloc (argc * sizeof (char *)); - outfiles = (char **) xmalloc (argc * sizeof (char *)); - ip = infiles; - op = outfiles; - - while ((optc = getopt (argc, argv, "-ko:")) != EOF) - { - switch (optc) - { - case 1: /* Non-option filename. */ - *ip++ = optarg; - *op++ = NULL; - break; - - case 'k': - keep_tempfiles = 1; - break; - - case 'o': - if (op > outfiles) - *(op - 1) = optarg; - break; - - default: - usage (); - } - } - - /* Record number of keyfields and terminate list of filenames. */ - num_infiles = ip - infiles; - *ip = 0; - if (num_infiles == 0) - usage (); -} - -/* Return a name for a temporary file. */ - -char * -maketempname (count) - int count; -{ - char tempsuffix[10]; - sprintf (tempsuffix, "%d", count); - return concat (tempdir, tempbase, tempsuffix); -} - -/* Delete all temporary files up to TO_COUNT. */ - -void -flush_tempfiles (to_count) - int to_count; -{ - if (keep_tempfiles) - return; - while (last_deleted_tempcount < to_count) - unlink (maketempname (++last_deleted_tempcount)); -} - -/* Copy the input file open on IDESC into a temporary file - and return the temporary file name. */ - -#define BUFSIZE 1024 - -char * -tempcopy (idesc) - int idesc; -{ - char *outfile = maketempname (++tempcount); - int odesc; - char buffer[BUFSIZE]; - - odesc = open (outfile, O_WRONLY | O_CREAT, 0666); - - if (odesc < 0) - pfatal_with_name (outfile); - - while (1) - { - int nread = read (idesc, buffer, BUFSIZE); - write (odesc, buffer, nread); - if (!nread) - break; - } - - close (odesc); - - return outfile; -} - -/* Compare LINE1 and LINE2 according to the specified set of keyfields. */ - -int -compare_full (line1, line2) - char **line1, **line2; -{ - int i; - - /* Compare using the first keyfield; - if that does not distinguish the lines, try the second keyfield; - and so on. */ - - for (i = 0; i < num_keyfields; i++) - { - long length1, length2; - char *start1 = find_field (&keyfields[i], *line1, &length1); - char *start2 = find_field (&keyfields[i], *line2, &length2); - int tem = compare_field (&keyfields[i], start1, length1, *line1 - text_base, - start2, length2, *line2 - text_base); - if (tem) - { - if (keyfields[i].reverse) - return -tem; - return tem; - } - } - - return 0; /* Lines match exactly. */ -} - -/* Compare LINE1 and LINE2, described by structures - in which the first keyfield is identified in advance. - For positional sorting, assumes that the order of the lines in core - reflects their nominal order. */ - -int -compare_prepared (line1, line2) - struct lineinfo *line1, *line2; -{ - int i; - int tem; - char *text1, *text2; - - /* Compare using the first keyfield, which has been found for us already. */ - if (keyfields->positional) - { - if (line1->text - text_base > line2->text - text_base) - tem = 1; - else - tem = -1; - } - else if (keyfields->numeric) - tem = line1->key.number - line2->key.number; - else - tem = compare_field (keyfields, line1->key.text, line1->keylen, 0, - line2->key.text, line2->keylen, 0); - if (tem) - { - if (keyfields->reverse) - return -tem; - return tem; - } - - text1 = line1->text; - text2 = line2->text; - - /* Compare using the second keyfield; - if that does not distinguish the lines, try the third keyfield; - and so on. */ - - for (i = 1; i < num_keyfields; i++) - { - long length1, length2; - char *start1 = find_field (&keyfields[i], text1, &length1); - char *start2 = find_field (&keyfields[i], text2, &length2); - int tem = compare_field (&keyfields[i], start1, length1, text1 - text_base, - start2, length2, text2 - text_base); - if (tem) - { - if (keyfields[i].reverse) - return -tem; - return tem; - } - } - - return 0; /* Lines match exactly. */ -} - -/* Like compare_full but more general. - You can pass any strings, and you can say how many keyfields to use. - POS1 and POS2 should indicate the nominal positional ordering of - the two lines in the input. */ - -int -compare_general (str1, str2, pos1, pos2, use_keyfields) - char *str1, *str2; - long pos1, pos2; - int use_keyfields; -{ - int i; - - /* Compare using the first keyfield; - if that does not distinguish the lines, try the second keyfield; - and so on. */ - - for (i = 0; i < use_keyfields; i++) - { - long length1, length2; - char *start1 = find_field (&keyfields[i], str1, &length1); - char *start2 = find_field (&keyfields[i], str2, &length2); - int tem = compare_field (&keyfields[i], start1, length1, pos1, - start2, length2, pos2); - if (tem) - { - if (keyfields[i].reverse) - return -tem; - return tem; - } - } - - return 0; /* Lines match exactly. */ -} - -/* Find the start and length of a field in STR according to KEYFIELD. - A pointer to the starting character is returned, and the length - is stored into the int that LENGTHPTR points to. */ - -char * -find_field (keyfield, str, lengthptr) - struct keyfield *keyfield; - char *str; - long *lengthptr; -{ - char *start; - char *end; - char *(*fun) (); - - if (keyfield->braced) - fun = find_braced_pos; - else - fun = find_pos; - - start = (*fun) (str, keyfield->startwords, keyfield->startchars, - keyfield->ignore_blanks); - if (keyfield->endwords < 0) - { - if (keyfield->braced) - end = find_braced_end (start); - else - { - end = start; - while (*end && *end != '\n') - end++; - } - } - else - { - end = (*fun) (str, keyfield->endwords, keyfield->endchars, 0); - if (end - str < start - str) - end = start; - } - *lengthptr = end - start; - return start; -} - -/* Return a pointer to a specified place within STR, - skipping (from the beginning) WORDS words and then CHARS chars. - If IGNORE_BLANKS is nonzero, we skip all blanks - after finding the specified word. */ - -char * -find_pos (str, words, chars, ignore_blanks) - char *str; - int words, chars; - int ignore_blanks; -{ - int i; - char *p = str; - - for (i = 0; i < words; i++) - { - char c; - /* Find next bunch of nonblanks and skip them. */ - while ((c = *p) == ' ' || c == '\t') - p++; - while ((c = *p) && c != '\n' && !(c == ' ' || c == '\t')) - p++; - if (!*p || *p == '\n') - return p; - } - - while (*p == ' ' || *p == '\t') - p++; - - for (i = 0; i < chars; i++) - { - if (!*p || *p == '\n') - break; - p++; - } - return p; -} - -/* Like find_pos but assumes that each field is surrounded by braces - and that braces within fields are balanced. */ - -char * -find_braced_pos (str, words, chars, ignore_blanks) - char *str; - int words, chars; - int ignore_blanks; -{ - int i; - int bracelevel; - char *p = str; - char c; - - for (i = 0; i < words; i++) - { - bracelevel = 1; - while ((c = *p++) != '{' && c != '\n' && c) - /* Do nothing. */ ; - if (c != '{') - return p - 1; - while (bracelevel) - { - c = *p++; - if (c == '{') - bracelevel++; - if (c == '}') - bracelevel--; - if (c == 0 || c == '\n') - return p - 1; - } - } - - while ((c = *p++) != '{' && c != '\n' && c) - /* Do nothing. */ ; - - if (c != '{') - return p - 1; - - if (ignore_blanks) - while ((c = *p) == ' ' || c == '\t') - p++; - - for (i = 0; i < chars; i++) - { - if (!*p || *p == '\n') - break; - p++; - } - return p; -} - -/* Find the end of the balanced-brace field which starts at STR. - The position returned is just before the closing brace. */ - -char * -find_braced_end (str) - char *str; -{ - int bracelevel; - char *p = str; - char c; - - bracelevel = 1; - while (bracelevel) - { - c = *p++; - if (c == '{') - bracelevel++; - if (c == '}') - bracelevel--; - if (c == 0 || c == '\n') - return p - 1; - } - return p - 1; -} - -long -find_value (start, length) - char *start; - long length; -{ - while (length != 0L) - { - if (isdigit (*start)) - return atol (start); - length--; - start++; - } - return 0l; -} - -/* Vector used to translate characters for comparison. - This is how we make all alphanumerics follow all else, - and ignore case in the first sorting. */ -int char_order[256]; - -void -init_char_order () -{ - int i; - for (i = 1; i < 256; i++) - char_order[i] = i; - - for (i = '0'; i <= '9'; i++) - char_order[i] += 512; - - for (i = 'a'; i <= 'z'; i++) - { - char_order[i] = 512 + i; - char_order[i + 'A' - 'a'] = 512 + i; - } -} - -/* Compare two fields (each specified as a start pointer and a character count) - according to KEYFIELD. - The sign of the value reports the relation between the fields. */ - -int -compare_field (keyfield, start1, length1, pos1, start2, length2, pos2) - struct keyfield *keyfield; - char *start1; - long length1; - long pos1; - char *start2; - long length2; - long pos2; -{ - if (keyfields->positional) - { - if (pos1 > pos2) - return 1; - else - return -1; - } - if (keyfield->numeric) - { - long value = find_value (start1, length1) - find_value (start2, length2); - if (value > 0) - return 1; - if (value < 0) - return -1; - return 0; - } - else - { - char *p1 = start1; - char *p2 = start2; - char *e1 = start1 + length1; - char *e2 = start2 + length2; - - while (1) - { - int c1, c2; - - if (p1 == e1) - c1 = 0; - else - c1 = *p1++; - if (p2 == e2) - c2 = 0; - else - c2 = *p2++; - - if (char_order[c1] != char_order[c2]) - return char_order[c1] - char_order[c2]; - if (!c1) - break; - } - - /* Strings are equal except possibly for case. */ - p1 = start1; - p2 = start2; - while (1) - { - int c1, c2; - - if (p1 == e1) - c1 = 0; - else - c1 = *p1++; - if (p2 == e2) - c2 = 0; - else - c2 = *p2++; - - if (c1 != c2) - /* Reverse sign here so upper case comes out last. */ - return c2 - c1; - if (!c1) - break; - } - - return 0; - } -} - -/* A `struct linebuffer' is a structure which holds a line of text. - `readline' reads a line from a stream into a linebuffer - and works regardless of the length of the line. */ - -struct linebuffer -{ - long size; - char *buffer; -}; - -/* Initialize LINEBUFFER for use. */ - -void -initbuffer (linebuffer) - struct linebuffer *linebuffer; -{ - linebuffer->size = 200; - linebuffer->buffer = (char *) xmalloc (200); -} - -/* Read a line of text from STREAM into LINEBUFFER. - Return the length of the line. */ - -long -readline (linebuffer, stream) - struct linebuffer *linebuffer; - FILE *stream; -{ - char *buffer = linebuffer->buffer; - char *p = linebuffer->buffer; - char *end = p + linebuffer->size; - - while (1) - { - int c = getc (stream); - if (p == end) - { - buffer = (char *) xrealloc (buffer, linebuffer->size *= 2); - p += buffer - linebuffer->buffer; - end += buffer - linebuffer->buffer; - linebuffer->buffer = buffer; - } - if (c < 0 || c == '\n') - { - *p = 0; - break; - } - *p++ = c; - } - - return p - buffer; -} - -/* Sort an input file too big to sort in core. */ - -void -sort_offline (infile, nfiles, total, outfile) - char *infile; - int nfiles; - long total; - char *outfile; -{ - /* More than enough. */ - int ntemps = 2 * (total + MAX_IN_CORE_SORT - 1) / MAX_IN_CORE_SORT; - char **tempfiles = (char **) xmalloc (ntemps * sizeof (char *)); - FILE *istream = fopen (infile, "r"); - int i; - struct linebuffer lb; - long linelength; - int failure = 0; - - initbuffer (&lb); - - /* Read in one line of input data. */ - - linelength = readline (&lb, istream); - - if (lb.buffer[0] != '\\' && lb.buffer[0] != '@') - { - error ("%s: not a texinfo index file", infile); - return; - } - - /* Split up the input into `ntemps' temporary files, or maybe fewer, - and put the new files' names into `tempfiles' */ - - for (i = 0; i < ntemps; i++) - { - char *outname = maketempname (++tempcount); - FILE *ostream = fopen (outname, "w"); - long tempsize = 0; - - if (!ostream) - pfatal_with_name (outname); - tempfiles[i] = outname; - - /* Copy lines into this temp file as long as it does not make file - "too big" or until there are no more lines. */ - - while (tempsize + linelength + 1 <= MAX_IN_CORE_SORT) - { - tempsize += linelength + 1; - fputs (lb.buffer, ostream); - putc ('\n', ostream); - - /* Read another line of input data. */ - - linelength = readline (&lb, istream); - if (!linelength && feof (istream)) - break; - - if (lb.buffer[0] != '\\' && lb.buffer[0] != '@') - { - error ("%s: not a texinfo index file", infile); - failure = 1; - goto fail; - } - } - fclose (ostream); - if (feof (istream)) - break; - } - - free (lb.buffer); - -fail: - /* Record number of temp files we actually needed. */ - - ntemps = i; - - /* Sort each tempfile into another tempfile. - Delete the first set of tempfiles and put the names of the second - into `tempfiles'. */ - - for (i = 0; i < ntemps; i++) - { - char *newtemp = maketempname (++tempcount); - sort_in_core (&tempfiles[i], MAX_IN_CORE_SORT, newtemp); - if (!keep_tempfiles) - unlink (tempfiles[i]); - tempfiles[i] = newtemp; - } - - if (failure) - return; - - /* Merge the tempfiles together and indexify. */ - - merge_files (tempfiles, ntemps, outfile); -} - -/* Sort INFILE, whose size is TOTAL, - assuming that is small enough to be done in-core, - then indexify it and send the output to OUTFILE (or to stdout). */ - -void -sort_in_core (infile, total, outfile) - char *infile; - long total; - char *outfile; -{ - char **nextline; - char *data = (char *) xmalloc (total + 1); - char *file_data; - long file_size; - int i; - FILE *ostream = stdout; - struct lineinfo *lineinfo; - - /* Read the contents of the file into the moby array `data'. */ - - int desc = open (infile, O_RDONLY, 0); - - if (desc < 0) - fatal ("failure reopening %s", infile); - for (file_size = 0;;) - { - i = read (desc, data + file_size, total - file_size); - if (i <= 0) - break; - file_size += i; - } - file_data = data; - data[file_size] = 0; - - close (desc); - - if (file_size > 0 && data[0] != '\\' && data[0] != '@') - { - error ("%s: not a texinfo index file", infile); - return; - } - - init_char_order (); - - /* Sort routines want to know this address. */ - - text_base = data; - - /* Create the array of pointers to lines, with a default size - frequently enough. */ - - nlines = total / 50; - if (!nlines) - nlines = 2; - linearray = (char **) xmalloc (nlines * sizeof (char *)); - - /* `nextline' points to the next free slot in this array. - `nlines' is the allocated size. */ - - nextline = linearray; - - /* Parse the input file's data, and make entries for the lines. */ - - nextline = parsefile (infile, nextline, file_data, file_size); - if (nextline == 0) - { - error ("%s: not a texinfo index file", infile); - return; - } - - /* Sort the lines. */ - - /* If we have enough space, find the first keyfield of each line in advance. - Make a `struct lineinfo' for each line, which records the keyfield - as well as the line, and sort them. */ - - lineinfo = (struct lineinfo *) malloc ((nextline - linearray) * sizeof (struct lineinfo)); - - if (lineinfo) - { - struct lineinfo *lp; - char **p; - - for (lp = lineinfo, p = linearray; p != nextline; lp++, p++) - { - lp->text = *p; - lp->key.text = find_field (keyfields, *p, &lp->keylen); - if (keyfields->numeric) - lp->key.number = find_value (lp->key.text, lp->keylen); - } - - qsort (lineinfo, nextline - linearray, sizeof (struct lineinfo), compare_prepared); - - for (lp = lineinfo, p = linearray; p != nextline; lp++, p++) - *p = lp->text; - - free (lineinfo); - } - else - qsort (linearray, nextline - linearray, sizeof (char *), compare_full); - - /* Open the output file. */ - - if (outfile) - { - ostream = fopen (outfile, "w"); - if (!ostream) - pfatal_with_name (outfile); - } - - writelines (linearray, nextline - linearray, ostream); - if (outfile) - fclose (ostream); - - free (linearray); - free (data); -} - -/* Parse an input string in core into lines. - DATA is the input string, and SIZE is its length. - Data goes in LINEARRAY starting at NEXTLINE. - The value returned is the first entry in LINEARRAY still unused. - Value 0 means input file contents are invalid. */ - -char ** -parsefile (filename, nextline, data, size) - char *filename; - char **nextline; - char *data; - long size; -{ - char *p, *end; - char **line = nextline; - - p = data; - end = p + size; - *end = 0; - - while (p != end) - { - if (p[0] != '\\' && p[0] != '@') - return 0; - - *line = p; - while (*p && *p != '\n') - p++; - if (p != end) - p++; - - line++; - if (line == linearray + nlines) - { - char **old = linearray; - linearray = (char **) xrealloc (linearray, sizeof (char *) * (nlines *= 4)); - line += linearray - old; - } - } - - return line; -} - -/* Indexification is a filter applied to the sorted lines - as they are being written to the output file. - Multiple entries for the same name, with different page numbers, - get combined into a single entry with multiple page numbers. - The first braced field, which is used for sorting, is discarded. - However, its first character is examined, folded to lower case, - and if it is different from that in the previous line fed to us - a \initial line is written with one argument, the new initial. - - If an entry has four braced fields, then the second and third - constitute primary and secondary names. - In this case, each change of primary name - generates a \primary line which contains only the primary name, - and in between these are \secondary lines which contain - just a secondary name and page numbers. */ - -/* The last primary name we wrote a \primary entry for. - If only one level of indexing is being done, this is the last name seen. */ -char *lastprimary; -/* Length of storage allocated for lastprimary. */ -int lastprimarylength; - -/* Similar, for the secondary name. */ -char *lastsecondary; -int lastsecondarylength; - -/* Zero if we are not in the middle of writing an entry. - One if we have written the beginning of an entry but have not - yet written any page numbers into it. - Greater than one if we have written the beginning of an entry - plus at least one page number. */ -int pending; - -/* The initial (for sorting purposes) of the last primary entry written. - When this changes, a \initial {c} line is written */ - -char *lastinitial; - -int lastinitiallength; - -/* When we need a string of length 1 for the value of lastinitial, - store it here. */ - -char lastinitial1[2]; - -/* Initialize static storage for writing an index. */ - -void -init_index () -{ - pending = 0; - lastinitial = lastinitial1; - lastinitial1[0] = 0; - lastinitial1[1] = 0; - lastinitiallength = 0; - lastprimarylength = 100; - lastprimary = (char *) xmalloc (lastprimarylength + 1); - bzero (lastprimary, lastprimarylength + 1); - lastsecondarylength = 100; - lastsecondary = (char *) xmalloc (lastsecondarylength + 1); - bzero (lastsecondary, lastsecondarylength + 1); -} - -/* Indexify. Merge entries for the same name, - insert headers for each initial character, etc. */ - -void -indexify (line, ostream) - char *line; - FILE *ostream; -{ - char *primary, *secondary, *pagenumber; - int primarylength, secondarylength = 0, pagelength; - int nosecondary; - int initiallength; - char *initial; - char initial1[2]; - register char *p; - - /* First, analyze the parts of the entry fed to us this time. */ - - p = find_braced_pos (line, 0, 0, 0); - if (*p == '{') - { - initial = p; - /* Get length of inner pair of braces starting at `p', - including that inner pair of braces. */ - initiallength = find_braced_end (p + 1) + 1 - p; - } - else - { - initial = initial1; - initial1[0] = *p; - initial1[1] = 0; - initiallength = 1; - - if (initial1[0] >= 'a' && initial1[0] <= 'z') - initial1[0] -= 040; - } - - pagenumber = find_braced_pos (line, 1, 0, 0); - pagelength = find_braced_end (pagenumber) - pagenumber; - if (pagelength == 0) - abort (); - - primary = find_braced_pos (line, 2, 0, 0); - primarylength = find_braced_end (primary) - primary; - - secondary = find_braced_pos (line, 3, 0, 0); - nosecondary = !*secondary; - if (!nosecondary) - secondarylength = find_braced_end (secondary) - secondary; - - /* If the primary is different from before, make a new primary entry. */ - if (strncmp (primary, lastprimary, primarylength)) - { - /* Close off current secondary entry first, if one is open. */ - if (pending) - { - fputs ("}\n", ostream); - pending = 0; - } - - /* If this primary has a different initial, include an entry for - the initial. */ - if (initiallength != lastinitiallength || - strncmp (initial, lastinitial, initiallength)) - { - fprintf (ostream, "\\initial {"); - fwrite (initial, 1, initiallength, ostream); - fprintf (ostream, "}\n", initial); - if (initial == initial1) - { - lastinitial = lastinitial1; - *lastinitial1 = *initial1; - } - else - { - lastinitial = initial; - } - lastinitiallength = initiallength; - } - - /* Make the entry for the primary. */ - if (nosecondary) - fputs ("\\entry {", ostream); - else - fputs ("\\primary {", ostream); - fwrite (primary, primarylength, 1, ostream); - if (nosecondary) - { - fputs ("}{", ostream); - pending = 1; - } - else - fputs ("}\n", ostream); - - /* Record name of most recent primary. */ - if (lastprimarylength < primarylength) - { - lastprimarylength = primarylength + 100; - lastprimary = (char *) xrealloc (lastprimary, - 1 + lastprimarylength); - } - strncpy (lastprimary, primary, primarylength); - lastprimary[primarylength] = 0; - - /* There is no current secondary within this primary, now. */ - lastsecondary[0] = 0; - } - - /* Should not have an entry with no subtopic following one with a subtopic. */ - - if (nosecondary && *lastsecondary) - error ("entry %s follows an entry with a secondary name", line); - - /* Start a new secondary entry if necessary. */ - if (!nosecondary && strncmp (secondary, lastsecondary, secondarylength)) - { - if (pending) - { - fputs ("}\n", ostream); - pending = 0; - } - - /* Write the entry for the secondary. */ - fputs ("\\secondary {", ostream); - fwrite (secondary, secondarylength, 1, ostream); - fputs ("}{", ostream); - pending = 1; - - /* Record name of most recent secondary. */ - if (lastsecondarylength < secondarylength) - { - lastsecondarylength = secondarylength + 100; - lastsecondary = (char *) xrealloc (lastsecondary, - 1 + lastsecondarylength); - } - strncpy (lastsecondary, secondary, secondarylength); - lastsecondary[secondarylength] = 0; - } - - /* Here to add one more page number to the current entry. */ - if (pending++ != 1) - fputs (", ", ostream); /* Punctuate first, if this is not the first. */ - fwrite (pagenumber, pagelength, 1, ostream); -} - -/* Close out any unfinished output entry. */ - -void -finish_index (ostream) - FILE *ostream; -{ - if (pending) - fputs ("}\n", ostream); - free (lastprimary); - free (lastsecondary); -} - -/* Copy the lines in the sorted order. - Each line is copied out of the input file it was found in. */ - -void -writelines (linearray, nlines, ostream) - char **linearray; - int nlines; - FILE *ostream; -{ - char **stop_line = linearray + nlines; - char **next_line; - - init_index (); - - /* Output the text of the lines, and free the buffer space. */ - - for (next_line = linearray; next_line != stop_line; next_line++) - { - /* If -u was specified, output the line only if distinct from previous one. */ - if (next_line == linearray - /* Compare previous line with this one, using only the - explicitly specd keyfields. */ - || compare_general (*(next_line - 1), *next_line, 0L, 0L, num_keyfields - 1)) - { - char *p = *next_line; - char c; - - while ((c = *p++) && c != '\n') - /* Do nothing. */ ; - *(p - 1) = 0; - indexify (*next_line, ostream); - } - } - - finish_index (ostream); -} - -/* Assume (and optionally verify) that each input file is sorted; - merge them and output the result. - Returns nonzero if any input file fails to be sorted. - - This is the high-level interface that can handle an unlimited - number of files. */ - -#define MAX_DIRECT_MERGE 10 - -int -merge_files (infiles, nfiles, outfile) - char **infiles; - int nfiles; - char *outfile; -{ - char **tempfiles; - int ntemps; - int i; - int value = 0; - int start_tempcount = tempcount; - - if (nfiles <= MAX_DIRECT_MERGE) - return merge_direct (infiles, nfiles, outfile); - - /* Merge groups of MAX_DIRECT_MERGE input files at a time, - making a temporary file to hold each group's result. */ - - ntemps = (nfiles + MAX_DIRECT_MERGE - 1) / MAX_DIRECT_MERGE; - tempfiles = (char **) xmalloc (ntemps * sizeof (char *)); - for (i = 0; i < ntemps; i++) - { - int nf = MAX_DIRECT_MERGE; - if (i + 1 == ntemps) - nf = nfiles - i * MAX_DIRECT_MERGE; - tempfiles[i] = maketempname (++tempcount); - value |= merge_direct (&infiles[i * MAX_DIRECT_MERGE], nf, tempfiles[i]); - } - - /* All temporary files that existed before are no longer needed - since their contents have been merged into our new tempfiles. - So delete them. */ - flush_tempfiles (start_tempcount); - - /* Now merge the temporary files we created. */ - - merge_files (tempfiles, ntemps, outfile); - - free (tempfiles); - - return value; -} - -/* Assume (and optionally verify) that each input file is sorted; - merge them and output the result. - Returns nonzero if any input file fails to be sorted. - - This version of merging will not work if the number of - input files gets too high. Higher level functions - use it only with a bounded number of input files. */ - -int -merge_direct (infiles, nfiles, outfile) - char **infiles; - int nfiles; - char *outfile; -{ - struct linebuffer *lb1, *lb2; - struct linebuffer **thisline, **prevline; - FILE **streams; - int i; - int nleft; - int lossage = 0; - int *file_lossage; - struct linebuffer *prev_out = 0; - FILE *ostream = stdout; - - if (outfile) - { - ostream = fopen (outfile, "w"); - } - if (!ostream) - pfatal_with_name (outfile); - - init_index (); - - if (nfiles == 0) - { - if (outfile) - fclose (ostream); - return 0; - } - - /* For each file, make two line buffers. - Also, for each file, there is an element of `thisline' - which points at any time to one of the file's two buffers, - and an element of `prevline' which points to the other buffer. - `thisline' is supposed to point to the next available line from the file, - while `prevline' holds the last file line used, - which is remembered so that we can verify that the file is properly sorted. */ - - /* lb1 and lb2 contain one buffer each per file. */ - lb1 = (struct linebuffer *) xmalloc (nfiles * sizeof (struct linebuffer)); - lb2 = (struct linebuffer *) xmalloc (nfiles * sizeof (struct linebuffer)); - - /* thisline[i] points to the linebuffer holding the next available line in file i, - or is zero if there are no lines left in that file. */ - thisline = (struct linebuffer **) - xmalloc (nfiles * sizeof (struct linebuffer *)); - /* prevline[i] points to the linebuffer holding the last used line - from file i. This is just for verifying that file i is properly - sorted. */ - prevline = (struct linebuffer **) - xmalloc (nfiles * sizeof (struct linebuffer *)); - /* streams[i] holds the input stream for file i. */ - streams = (FILE **) xmalloc (nfiles * sizeof (FILE *)); - /* file_lossage[i] is nonzero if we already know file i is not - properly sorted. */ - file_lossage = (int *) xmalloc (nfiles * sizeof (int)); - - /* Allocate and initialize all that storage. */ - - for (i = 0; i < nfiles; i++) - { - initbuffer (&lb1[i]); - initbuffer (&lb2[i]); - thisline[i] = &lb1[i]; - prevline[i] = &lb2[i]; - file_lossage[i] = 0; - streams[i] = fopen (infiles[i], "r"); - if (!streams[i]) - pfatal_with_name (infiles[i]); - - readline (thisline[i], streams[i]); - } - - /* Keep count of number of files not at eof. */ - nleft = nfiles; - - while (nleft) - { - struct linebuffer *best = 0; - struct linebuffer *exch; - int bestfile = -1; - int i; - - /* Look at the next avail line of each file; choose the least one. */ - - for (i = 0; i < nfiles; i++) - { - if (thisline[i] && - (!best || - 0 < compare_general (best->buffer, thisline[i]->buffer, - (long) bestfile, (long) i, num_keyfields))) - { - best = thisline[i]; - bestfile = i; - } - } - - /* Output that line, unless it matches the previous one and we - don't want duplicates. */ - - if (!(prev_out && - !compare_general (prev_out->buffer, - best->buffer, 0L, 1L, num_keyfields - 1))) - indexify (best->buffer, ostream); - prev_out = best; - - /* Now make the line the previous of its file, and fetch a new - line from that file. */ - - exch = prevline[bestfile]; - prevline[bestfile] = thisline[bestfile]; - thisline[bestfile] = exch; - - while (1) - { - /* If the file has no more, mark it empty. */ - - if (feof (streams[bestfile])) - { - thisline[bestfile] = 0; - /* Update the number of files still not empty. */ - nleft--; - break; - } - readline (thisline[bestfile], streams[bestfile]); - if (thisline[bestfile]->buffer[0] || !feof (streams[bestfile])) - break; - } - } - - finish_index (ostream); - - /* Free all storage and close all input streams. */ - - for (i = 0; i < nfiles; i++) - { - fclose (streams[i]); - free (lb1[i].buffer); - free (lb2[i].buffer); - } - free (file_lossage); - free (lb1); - free (lb2); - free (thisline); - free (prevline); - free (streams); - - if (outfile) - fclose (ostream); - - return lossage; -} - -/* Print error message and exit. */ - -void -fatal (s1, s2) - char *s1, *s2; -{ - error (s1, s2); - exit (TI_FATAL_ERROR); -} - -/* Print error message. S1 is printf control string, S2 is arg for it. */ - -void -error (s1, s2) - char *s1, *s2; -{ - printf ("%s: ", program_name); - printf (s1, s2); - printf ("\n"); -} - -void -perror_with_name (name) - char *name; -{ - char *s; - - if (errno < sys_nerr) - s = concat ("", sys_errlist[errno], " for %s"); - else - s = "cannot open %s"; - error (s, name); -} - -void -pfatal_with_name (name) - char *name; -{ - char *s; - - if (errno < sys_nerr) - s = concat ("", sys_errlist[errno], " for %s"); - else - s = "cannot open %s"; - fatal (s, name); -} - -/* Return a newly-allocated string whose contents concatenate those of - S1, S2, S3. */ - -char * -concat (s1, s2, s3) - char *s1, *s2, *s3; -{ - int len1 = strlen (s1), len2 = strlen (s2), len3 = strlen (s3); - char *result = (char *) xmalloc (len1 + len2 + len3 + 1); - - strcpy (result, s1); - strcpy (result + len1, s2); - strcpy (result + len1 + len2, s3); - *(result + len1 + len2 + len3) = 0; - - return result; -} - -/* Just like malloc, but kills the program in case of fatal error. */ -void * -xmalloc (nbytes) - int nbytes; -{ - void *temp = (void *) malloc (nbytes); - - if (nbytes && temp == (void *)NULL) - memory_error ("xmalloc", nbytes); - - return (temp); -} - -/* Like realloc (), but barfs if there isn't enough memory. */ -void * -xrealloc (pointer, nbytes) - void *pointer; - int nbytes; -{ - void *temp; - - if (!pointer) - temp = (void *)xmalloc (nbytes); - else - temp = (void *)realloc (pointer, nbytes); - - if (nbytes && !temp) - memory_error ("xrealloc", nbytes); - - return (temp); -} - -memory_error (callers_name, bytes_wanted) - char *callers_name; - int bytes_wanted; -{ - char printable_string[80]; - - sprintf (printable_string, - "Virtual memory exhausted in %s ()! Needed %d bytes.", - callers_name, bytes_wanted); - - error (printable_string); - abort (); -} - -#ifndef STDC_HEADERS -void -bzero (b, length) - register char *b; - register int length; -{ -#ifdef VMS - short zero = 0; - long max_str = 65535; - - while (length > max_str) - { - (void) LIB$MOVC5 (&zero, &zero, &zero, &max_str, b); - length -= max_str; - b += max_str; - } - (void) LIB$MOVC5 (&zero, &zero, &zero, &length, b); -#else - while (length-- > 0) - *b++ = 0; -#endif /* not VMS */ -} -#endif /* not STDC_HEADERS */ |
