diff options
94 files changed, 68956 insertions, 0 deletions
diff --git a/gnu/usr.bin/texinfo/Makefile b/gnu/usr.bin/texinfo/Makefile new file mode 100644 index 0000000..453f0e0 --- /dev/null +++ b/gnu/usr.bin/texinfo/Makefile @@ -0,0 +1,8 @@ +# +# Bmake file for texinfo +# + +SUBDIR= info info-files makedoc makeinfo texindex + +.include <bsd.subdir.mk> + diff --git a/gnu/usr.bin/texinfo/Makefile.inc b/gnu/usr.bin/texinfo/Makefile.inc new file mode 100644 index 0000000..0b84ba6 --- /dev/null +++ b/gnu/usr.bin/texinfo/Makefile.inc @@ -0,0 +1,7 @@ +# +# +# + + +INFODIR= /usr/share/info + diff --git a/gnu/usr.bin/texinfo/info-files/Makefile b/gnu/usr.bin/texinfo/info-files/Makefile new file mode 100644 index 0000000..07cfc69 --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/Makefile @@ -0,0 +1,18 @@ +# +# Makefile for INFO files +# + +INFOFILES+= dir info.info makeinfo.info texi.info texi.info-1 texi.inf-2 +INFOFILES+= texi.info-3 texi.info-4 texi.info-5 texi.info-6 texi.info-7 +INFOFILES+= texi.info-8 texi.info-9 texi.info-10 texi.info-11 + +install: + mkdir -p ${INFODIR} + install -g ${BINGRP} -o ${BINOWN} -m 444 ${INFOFILES} ${INFODIR} + +clean: +cleandir: +obj: + +.include <bsd.prog.mk> + diff --git a/gnu/usr.bin/texinfo/info-files/dir b/gnu/usr.bin/texinfo/info-files/dir new file mode 100644 index 0000000..468d48c --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/dir @@ -0,0 +1,18 @@ +-*- Text -*- +This is the file .../info/dir, which contains the topmost node of the +Info hierarchy. The first time you invoke Info you start off +looking at that node, which is (dir)Top. + +File: dir Node: Top This is the top of the INFO tree + This (the Directory node) gives a menu of major topics. + Typing "d" returns here, "q" exits, "?" lists all INFO commands, "h" + gives a primer for first-timers, "mTexinfo<Return>" visits Texinfo topic, + etc. + --- PLEASE ADD DOCUMENTATION TO THIS TREE. (See INFO topic first.) --- + +* Menu: The list of major topics begins on the next line. + +* Info: (info). Documentation browsing system. +* Texi: (texi). TexInfo guide. +* Makeinfo: (makeinfo). Makeinfo guide. + diff --git a/gnu/usr.bin/texinfo/info-files/info-stnd.info b/gnu/usr.bin/texinfo/info-files/info-stnd.info new file mode 100644 index 0000000..31f486a --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/info-stnd.info @@ -0,0 +1,1259 @@ +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 new file mode 100644 index 0000000..b6fd850 --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/info.info @@ -0,0 +1,777 @@ +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 new file mode 100644 index 0000000..81dbe14 --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/makeinfo.info @@ -0,0 +1,224 @@ +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 new file mode 100644 index 0000000..286973b --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/texi-files/info-stnd.texi @@ -0,0 +1,1359 @@ +\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 new file mode 100644 index 0000000..5eec9f1 --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/texi-files/info.texi @@ -0,0 +1,861 @@ +\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 new file mode 100644 index 0000000..21ee2d3 --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/texi-files/makeinfo.texi @@ -0,0 +1,285 @@ +\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 new file mode 100644 index 0000000..f77f662 --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/texi-files/texi.texi @@ -0,0 +1,15626 @@ +\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 new file mode 100644 index 0000000..4ebeae8 --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/texi-files/userdoc.texi @@ -0,0 +1,1263 @@ +@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 new file mode 100644 index 0000000..cd677e8 --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/texi.info @@ -0,0 +1,297 @@ +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 new file mode 100644 index 0000000..28b4895 --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/texi.info-1 @@ -0,0 +1,1131 @@ +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 new file mode 100644 index 0000000..f28ff2e --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/texi.info-10 @@ -0,0 +1,1165 @@ +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 new file mode 100644 index 0000000..f960227 --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/texi.info-11 @@ -0,0 +1,451 @@ +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 new file mode 100644 index 0000000..6ad094d --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/texi.info-2 @@ -0,0 +1,1289 @@ +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 new file mode 100644 index 0000000..1058a1a --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/texi.info-3 @@ -0,0 +1,1262 @@ +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 new file mode 100644 index 0000000..8698ab6 --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/texi.info-4 @@ -0,0 +1,1412 @@ +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 new file mode 100644 index 0000000..84b7295 --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/texi.info-5 @@ -0,0 +1,1433 @@ +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 new file mode 100644 index 0000000..cac7b3a --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/texi.info-6 @@ -0,0 +1,1461 @@ +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 new file mode 100644 index 0000000..3ea85ee --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/texi.info-7 @@ -0,0 +1,1307 @@ +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 new file mode 100644 index 0000000..ba35e6e --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/texi.info-8 @@ -0,0 +1,1056 @@ +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 new file mode 100644 index 0000000..b128db5 --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/texi.info-9 @@ -0,0 +1,1210 @@ +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/Makefile b/gnu/usr.bin/texinfo/info/Makefile new file mode 100644 index 0000000..e21819f --- /dev/null +++ b/gnu/usr.bin/texinfo/info/Makefile @@ -0,0 +1,28 @@ +# +# Bmakefile for GNU info +# +# $id$ +# + +PROG= info + +SRCS+= dir.c display.c dribble.c echo_area.c filesys.c info-utils.c info.c +SRCS+= infodoc.c infomap.c m-x.c nodes.c search.c session.c signals.c +SRCS+= terminal.c tilde.c window.c indices.c doc.c nodemenu.c +SRCS+= footnotes.c variables.c gc.c xmalloc.c getopt1.c getopt.c + +CFLAGS= + +CFLAGS+= -I${.CURDIR} +CFLAGS+= -DNAMED_FUNCTIONS=1 -DSTDC_HEADERS=1 +CFLAGS+= -DHAVE_UNISTD_H=1 -DHAVE_STRING_H=1 -DHAVE_VARARGS_H=1 +CFLAGS+= -DHAVE_SYS_FCNTL_H=1 -DHAVE_SETVBUF=1 -DHAVE_GETCWD=1 -DHAVE_BZERO=1 +CFLAGS+= -DHAVE_RINDEX=1 -DHAVE_VFPRINTF=1 -DHAVE_VSPRINTF=1 +CFLAGS+= -DHAVE_SYS_TIME_H=1 -DDEFAULT_INFOPATH='"${INFODIR}"' + +LDADD+= -ltermcap +DPADD+= ${LIBTERMCAP} + +.include "../../Makefile.inc" +.include <bsd.prog.mk> + diff --git a/gnu/usr.bin/texinfo/info/dir.c b/gnu/usr.bin/texinfo/info/dir.c new file mode 100644 index 0000000..3820813 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/dir.c @@ -0,0 +1,224 @@ +/* dir.c -- How to build a special "dir" node from "localdir" files. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#include <stdio.h> +#include <sys/types.h> +#include <sys/stat.h> +#include <sys/file.h> +#include <sys/errno.h> +#include "info-utils.h" +#include "filesys.h" +#include "tilde.h" + +/* The "dir" node can be built from the contents of a file called "dir", + with the addition of the menus of every file called "localdir" found in + INFOPATH. */ + +static void add_menu_to_file_buffer (), insert_text_into_fb_at_binding (); + +void +maybe_build_dir_node (dirname, from_files_named) + char *dirname; + char *from_files_named; +{ + FILE_BUFFER *dir_buffer; + + /* See if the file has already been loaded and exists. */ + dir_buffer = info_find_file (dirname); + + /* If there is no "dir" in the current info path, we cannot build one + from nothing. */ + if (!dir_buffer) + return; + + /* If this directory has already been built, return now. */ + if (dir_buffer->flags & N_CannotGC) + return; + + dir_buffer->flags |= N_CannotGC; + + /* For every file named FROM_FILES_NAMED in the search path, add the + contents of that file's menu to our "dir" node. */ + { + struct stat finfo; + char *this_dir; + int namelen, path_index; + int update_tags = 0; + + namelen = strlen (from_files_named); + path_index = 0; + + /* Using each element of the path, check for "localdir". Do not check + for "localdir.info.Z" or anything else. Only files explictly named + "localdir" are eligible. This is a design decision. There can be + an info file name "localdir.info" which contains information on the + setting up of "localdir" files. */ + while (this_dir = extract_colon_unit (infopath, &path_index)) + { + char *fullpath; + int statable; + + /* Expand a leading tilde if one is present. */ + if (*this_dir == '~') + { + char *tilde_expanded_dirname; + + tilde_expanded_dirname = tilde_expand_word (this_dir); + free (this_dir); + this_dir = tilde_expanded_dirname; + } + + fullpath = (char *)xmalloc (3 + strlen (this_dir) + namelen); + strcpy (fullpath, this_dir); + if (fullpath[strlen (fullpath) - 1] != '/') + strcat (fullpath, "/"); + strcat (fullpath, from_files_named); + + statable = (stat (fullpath, &finfo) == 0); + + if (statable && S_ISREG (finfo.st_mode)) + { + long filesize; + char *contents; + + contents = filesys_read_info_file (fullpath, &filesize, &finfo); + + if (contents) + { + update_tags++; + add_menu_to_file_buffer (contents, filesize, dir_buffer); + free (contents); + } + } + + free (fullpath); + free (this_dir); + } + if (update_tags) + build_tags_and_nodes (dir_buffer); + } +} + +/* Given CONTENTS and FB (a file buffer), add the menu found in CONTENTS + to the menu found in FB->contents. Second argument SIZE is the total + size of CONTENTS. */ +static void +add_menu_to_file_buffer (contents, size, fb) + char *contents; + long size; + FILE_BUFFER *fb; +{ + SEARCH_BINDING contents_binding, fb_binding; + long contents_offset, fb_offset; + + contents_binding.buffer = contents; + contents_binding.start = 0; + contents_binding.end = size; + contents_binding.flags = S_FoldCase | S_SkipDest; + + fb_binding.buffer = fb->contents; + fb_binding.start = 0; + fb_binding.end = fb->filesize; + fb_binding.flags = S_FoldCase | S_SkipDest; + + /* Move to the start of the menus in CONTENTS and FB. */ + contents_offset = search_forward (INFO_MENU_LABEL, &contents_binding); + fb_offset = search_forward (INFO_MENU_LABEL, &fb_binding); + + /* If there is no menu in CONTENTS, quit now. */ + if (contents_offset == -1) + return; + + /* If there is no menu in FB, make one. */ + if (fb_offset == -1) + { + /* Find the start of the second node in this file buffer. If there + is only one node, we will be adding the contents to the end of + this node. */ + fb_offset = find_node_separator (&fb_binding); + + /* If not even a single node separator, give up. */ + if (fb_offset == -1) + return; + + fb_binding.start = fb_offset; + fb_binding.start += + skip_node_separator (fb_binding.buffer + fb_binding.start); + + /* Try to find the next node separator. */ + fb_offset = find_node_separator (&fb_binding); + + /* If found one, consider that the start of the menu. Otherwise, the + start of this menu is the end of the file buffer (i.e., fb->size). */ + if (fb_offset != -1) + fb_binding.start = fb_offset; + else + fb_binding.start = fb_binding.end; + + insert_text_into_fb_at_binding + (fb, &fb_binding, INFO_MENU_LABEL, strlen (INFO_MENU_LABEL)); + + fb_binding.buffer = fb->contents; + fb_binding.start = 0; + fb_binding.end = fb->filesize; + fb_offset = search_forward (INFO_MENU_LABEL, &fb_binding); + if (fb_offset == -1) + abort (); + } + + /* CONTENTS_OFFSET and FB_OFFSET point to the starts of the menus that + appear in their respective buffers. Add the remainder of CONTENTS + to the end of FB's menu. */ + fb_binding.start = fb_offset; + fb_offset = find_node_separator (&fb_binding); + if (fb_offset != -1) + fb_binding.start = fb_offset; + else + fb_binding.start = fb_binding.end; + + insert_text_into_fb_at_binding + (fb, &fb_binding, contents + contents_offset, size - contents_offset); +} + +static void +insert_text_into_fb_at_binding (fb, binding, text, textlen) + FILE_BUFFER *fb; + SEARCH_BINDING *binding; + char *text; + int textlen; +{ + char *contents; + long start, end; + + start = binding->start; + end = fb->filesize; + + contents = (char *)xmalloc (fb->filesize + textlen + 1); + memcpy (contents, fb->contents, start); + memcpy (contents + start, text, textlen); + memcpy (contents + start + textlen, fb->contents + start, end - start); + free (fb->contents); + fb->contents = contents; + fb->filesize += textlen; + fb->finfo.st_size = fb->filesize; +} diff --git a/gnu/usr.bin/texinfo/info/display.c b/gnu/usr.bin/texinfo/info/display.c new file mode 100644 index 0000000..441f1f2 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/display.c @@ -0,0 +1,561 @@ +/* display.c -- How to display Info windows. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#include <stdio.h> +#include <ctype.h> +#include <sys/types.h> +#include <sys/stat.h> +#include "display.h" + +extern int info_any_buffered_input_p (); /* Found in session.c. */ + +static void free_display (); +static DISPLAY_LINE **make_display (); + +/* An array of display lines which tell us what is currently visible on + the display. */ +DISPLAY_LINE **the_display = (DISPLAY_LINE **)NULL; + +/* Non-zero means do no output. */ +int display_inhibited = 0; + +/* Initialize THE_DISPLAY to WIDTH and HEIGHT, with nothing in it. */ +void +display_initialize_display (width, height) + int width, height; +{ + free_display (the_display); + the_display = make_display (width, height); + display_clear_display (the_display); +} + +/* Clear all of the lines in DISPLAY making the screen blank. */ +void +display_clear_display (display) + DISPLAY_LINE **display; +{ + register int i; + register DISPLAY_LINE *display_line; + + for (i = 0; display_line = display[i]; i++) + { + display[i]->text[0] = '\0'; + display[i]->textlen = 0; + display[i]->inverse = 0; + } +} + +/* Non-zero if we didn't completely redisplay a window. */ +int display_was_interrupted_p = 0; + +/* Update the windows pointed to by WINDOW in the_display. This actually + writes the text on the screen. */ +void +display_update_display (window) + WINDOW *window; +{ + register WINDOW *win; + + display_was_interrupted_p = 0; + + /* For every window in the list, check contents against the display. */ + for (win = window; win; win = win->next) + { + /* Only re-display visible windows which need updating. */ + if (((win->flags & W_WindowVisible) == 0) || + ((win->flags & W_UpdateWindow) == 0) || + (win->height == 0)) + continue; + + display_update_one_window (win); + if (display_was_interrupted_p) + break; + } + + /* Always update the echo area. */ + display_update_one_window (the_echo_area); +} + +/* Display WIN on the_display. Unlike display_update_display (), this + function only does one window. */ +void +display_update_one_window (win) + WINDOW *win; +{ + register char *nodetext; /* Current character to display. */ + register char *last_node_char; /* Position of the last character in node. */ + register int i; /* General use index. */ + char *printed_line; /* Buffer for a printed line. */ + int pl_index = 0; /* Index into PRINTED_LINE. */ + int line_index = 0; /* Number of lines done so far. */ + DISPLAY_LINE **display = the_display; + + /* If display is inhibited, that counts as an interrupted display. */ + if (display_inhibited) + display_was_interrupted_p = 1; + + /* If the window has no height, or display is inhibited, quit now. */ + if (!win->height || display_inhibited) + return; + + /* If the window's first row doesn't appear in the_screen, then it + cannot be displayed. This can happen when the_echo_area is the + window to be displayed, and the screen has shrunk to less than one + line. */ + if ((win->first_row < 0) || (win->first_row > the_screen->height)) + return; + + /* Print each line in the window into our local buffer, and then + check the contents of that buffer against the display. If they + differ, update the display. */ + printed_line = (char *)xmalloc (1 + win->width); + + if (!win->node || !win->line_starts) + goto done_with_node_display; + + nodetext = win->line_starts[win->pagetop]; + last_node_char = win->node->contents + win->node->nodelen; + + for (; nodetext < last_node_char; nodetext++) + { + char *rep, *rep_carried_over, rep_temp[2]; + int replen; + + if (isprint (*nodetext)) + { + rep_temp[0] = *nodetext; + replen = 1; + rep_temp[1] = '\0'; + rep = rep_temp; + } + else + { + if (*nodetext == '\r' || *nodetext == '\n') + { + replen = win->width - pl_index; + } + else + { + rep = printed_representation (*nodetext, pl_index); + replen = strlen (rep); + } + } + + /* If this character can be printed without passing the width of + the line, then stuff it into the line. */ + if (replen + pl_index < win->width) + { + /* Optimize if possible. */ + if (replen == 1) + { + printed_line[pl_index++] = *rep; + } + else + { + for (i = 0; i < replen; i++) + printed_line[pl_index++] = rep[i]; + } + } + else + { + DISPLAY_LINE *entry; + + /* If this character cannot be printed in this line, we have + found the end of this line as it would appear on the screen. + Carefully print the end of the line, and then compare. */ + if (*nodetext == '\n' || *nodetext == '\r' || *nodetext == '\t') + { + printed_line[pl_index] = '\0'; + rep_carried_over = (char *)NULL; + } + else + { + /* The printed representation of this character extends into + the next line. Remember the offset of the last character + printed out of REP so that we can carry the character over + to the next line. */ + for (i = 0; pl_index < (win->width - 1);) + printed_line[pl_index++] = rep[i++]; + + rep_carried_over = rep + i; + + /* If printing the last character in this window couldn't + possibly cause the screen to scroll, place a backslash + in the rightmost column. */ + if (1 + line_index + win->first_row < the_screen->height) + { + if (win->flags & W_NoWrap) + printed_line[pl_index++] = '$'; + else + printed_line[pl_index++] = '\\'; + } + printed_line[pl_index] = '\0'; + } + + /* We have the exact line as it should appear on the screen. + Check to see if this line matches the one already appearing + on the screen. */ + entry = display[line_index + win->first_row]; + + /* If the screen line is inversed, then we have to clear + the line from the screen first. Why, I don't know. */ + if (entry->inverse) + { + terminal_goto_xy (0, line_index + win->first_row); + terminal_clear_to_eol (); + entry->inverse = 0; + entry->text[0] = '\0'; + entry->textlen = 0; + } + + /* Find the offset where these lines differ. */ + for (i = 0; i < pl_index; i++) + if (printed_line[i] != entry->text[i]) + break; + + /* If the lines are not the same length, or if they differed + at all, we must do some redrawing. */ + if ((i != pl_index) || (pl_index != entry->textlen)) + { + /* Move to the proper point on the terminal. */ + terminal_goto_xy (i, line_index + win->first_row); + + /* If there is any text to print, print it. */ + if (i != pl_index) + terminal_put_text (printed_line + i); + + /* If the printed text didn't extend all the way to the edge + of the window, and text was appearing between here and the + edge of the window, clear from here to the end of the line. */ + if ((pl_index < win->width && pl_index < entry->textlen) || + (entry->inverse)) + terminal_clear_to_eol (); + + fflush (stdout); + + /* Update the display text buffer. */ + strcpy (entry->text + i, printed_line + i); + entry->textlen = pl_index; + + /* Lines showing node text are not in inverse. Only modelines + have that distinction. */ + entry->inverse = 0; + } + + /* We have done at least one line. Increment our screen line + index, and check against the bottom of the window. */ + if (++line_index == win->height) + break; + + /* A line has been displayed, and the screen reflects that state. + If there is typeahead pending, then let that typeahead be read + now, instead of continuing with the display. */ + if (info_any_buffered_input_p ()) + { + free (printed_line); + display_was_interrupted_p = 1; + return; + } + + /* Reset PL_INDEX to the start of the line. */ + pl_index = 0; + + /* If there are characters from REP left to print, stuff them + into the buffer now. */ + if (rep_carried_over) + for (; rep[pl_index]; pl_index++) + printed_line[pl_index] = rep[pl_index]; + + /* If this window has chosen not to wrap lines, skip to the end + of the physical line in the buffer, and start a new line here. */ + if (pl_index && (win->flags & W_NoWrap)) + { + char *begin; + + pl_index = 0; + printed_line[0] = '\0'; + + begin = nodetext; + + while ((nodetext < last_node_char) && (*nodetext != '\n')) + nodetext++; + } + } + } + + done_with_node_display: + /* We have reached the end of the node or the end of the window. If it + is the end of the node, then clear the lines of the window from here + to the end of the window. */ + for (; line_index < win->height; line_index++) + { + DISPLAY_LINE *entry = display[line_index + win->first_row]; + + /* If this line has text on it then make it go away. */ + if (entry && entry->textlen) + { + entry->textlen = 0; + entry->text[0] = '\0'; + + terminal_goto_xy (0, line_index + win->first_row); + terminal_clear_to_eol (); + } + } + + /* Finally, if this window has a modeline it might need to be redisplayed. + Check the window's modeline against the one in the display, and update + if necessary. */ + if ((win->flags & W_InhibitMode) == 0) + { + window_make_modeline (win); + line_index = win->first_row + win->height; + + /* This display line must both be in inverse, and have the same + contents. */ + if ((!display[line_index]->inverse) || + (strcmp (display[line_index]->text, win->modeline) != 0)) + { + terminal_goto_xy (0, line_index); + terminal_begin_inverse (); + terminal_put_text (win->modeline); + terminal_end_inverse (); + strcpy (display[line_index]->text, win->modeline); + display[line_index]->inverse = 1; + display[line_index]->textlen = strlen (win->modeline); + fflush (stdout); + } + } + + /* Okay, this window doesn't need updating anymore. */ + win->flags &= ~W_UpdateWindow; + free (printed_line); + fflush (stdout); +} + +/* Scroll the region of the_display starting at START, ending at END, and + moving the lines AMOUNT lines. If AMOUNT is less than zero, the lines + are moved up in the screen, otherwise down. Actually, it is possible + for no scrolling to take place in the case that the terminal doesn't + support it. This doesn't matter to us. */ +void +display_scroll_display (start, end, amount) + int start, end, amount; +{ + register int i, last; + DISPLAY_LINE *temp; + + /* If this terminal cannot do scrolling, give up now. */ + if (!terminal_can_scroll) + return; + + /* If there isn't anything displayed on the screen because it is too + small, quit now. */ + if (!the_display[0]) + return; + + /* If there is typeahead pending, then don't actually do any scrolling. */ + if (info_any_buffered_input_p ()) + return; + + /* Do it on the screen. */ + terminal_scroll_terminal (start, end, amount); + + /* Now do it in the display buffer so our contents match the screen. */ + if (amount > 0) + { + last = end + amount; + + /* Shift the lines to scroll right into place. */ + for (i = 0; i < (end - start); i++) + { + temp = the_display[last - i]; + the_display[last - i] = the_display[end - i]; + the_display[end - i] = temp; + } + + /* The lines have been shifted down in the buffer. Clear all of the + lines that were vacated. */ + for (i = start; i != (start + amount); i++) + { + the_display[i]->text[0] = '\0'; + the_display[i]->textlen = 0; + the_display[i]->inverse = 0; + } + } + + if (amount < 0) + { + last = start + amount; + for (i = 0; i < (end - start); i++) + { + temp = the_display[last + i]; + the_display[last + i] = the_display[start + i]; + the_display[start + i] = temp; + } + + /* The lines have been shifted up in the buffer. Clear all of the + lines that are left over. */ + for (i = end + amount; i != end; i++) + { + the_display[i]->text[0] = '\0'; + the_display[i]->textlen = 0; + the_display[i]->inverse = 0; + } + } +} + +/* Try to scroll lines in WINDOW. OLD_PAGETOP is the pagetop of WINDOW before + having had its line starts recalculated. OLD_STARTS is the list of line + starts that used to appear in this window. OLD_COUNT is the number of lines + that appear in the OLD_STARTS array. */ +void +display_scroll_line_starts (window, old_pagetop, old_starts, old_count) + WINDOW *window; + int old_pagetop, old_count; + char **old_starts; +{ + register int i, old, new; /* Indices into the line starts arrays. */ + int last_new, last_old; /* Index of the last visible line. */ + int old_first, new_first; /* Index of the first changed line. */ + int unchanged_at_top = 0; + int already_scrolled = 0; + + /* Locate the first line which was displayed on the old window. */ + old_first = old_pagetop; + new_first = window->pagetop; + + /* Find the last line currently visible in this window. */ + last_new = window->pagetop + (window->height - 1); + if (last_new > window->line_count) + last_new = window->line_count - 1; + + /* Find the last line which used to be currently visible in this window. */ + last_old = old_pagetop + (window->height - 1); + if (last_old > old_count) + last_old = old_count - 1; + + for (old = old_first, new = new_first; + old < last_old && new < last_new; + old++, new++) + if (old_starts[old] != window->line_starts[new]) + break; + else + unchanged_at_top++; + + /* Loop through the old lines looking for a match in the new lines. */ + for (old = old_first + unchanged_at_top; old < last_old; old++) + { + for (new = new_first; new < last_new; new++) + if (old_starts[old] == window->line_starts[new]) + { + /* Find the extent of the matching lines. */ + for (i = 0; (old + i) < last_old; i++) + if (old_starts[old + i] != window->line_starts[new + i]) + break; + + /* Scroll these lines if there are enough of them. */ + { + int start, end, amount; + + start = (window->first_row + + ((old + already_scrolled) - old_pagetop)); + amount = new - (old + already_scrolled); + end = window->first_row + window->height; + + /* If we are shifting the block of lines down, then the last + AMOUNT lines will become invisible. Thus, don't bother + scrolling them. */ + if (amount > 0) + end -= amount; + + if ((end - start) > 0) + { + display_scroll_display (start, end, amount); + + /* Some lines have been scrolled. Simulate the scrolling + by offsetting the value of the old index. */ + old += i; + already_scrolled += amount; + } + } + } + } +} + +/* Move the screen cursor to directly over the current character in WINDOW. */ +void +display_cursor_at_point (window) + WINDOW *window; +{ + int vpos, hpos; + + vpos = window_line_of_point (window) - window->pagetop + window->first_row; + hpos = window_get_cursor_column (window); + terminal_goto_xy (hpos, vpos); +} + +/* **************************************************************** */ +/* */ +/* Functions Static to this File */ +/* */ +/* **************************************************************** */ + +/* Make a DISPLAY_LINE ** with width and height. */ +static DISPLAY_LINE ** +make_display (width, height) + int width, height; +{ + register int i; + DISPLAY_LINE **display; + + display = (DISPLAY_LINE **)xmalloc ((1 + height) * sizeof (DISPLAY_LINE *)); + + for (i = 0; i < height; i++) + { + display[i] = (DISPLAY_LINE *)xmalloc (sizeof (DISPLAY_LINE)); + display[i]->text = (char *)xmalloc (1 + width); + display[i]->textlen = 0; + display[i]->inverse = 0; + } + display[i] = (DISPLAY_LINE *)NULL; + return (display); +} + +/* Free the storage allocated to DISPLAY. */ +static void +free_display (display) + DISPLAY_LINE **display; +{ + register int i; + register DISPLAY_LINE *display_line; + + if (!display) + return; + + for (i = 0; display_line = display[i]; i++) + { + free (display_line->text); + free (display_line); + } + free (display); +} diff --git a/gnu/usr.bin/texinfo/info/display.h b/gnu/usr.bin/texinfo/info/display.h new file mode 100644 index 0000000..f025403 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/display.h @@ -0,0 +1,76 @@ +/* display.h -- How the display in Info is done. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#ifndef _DISPLAY_H_ +#define _DISPLAY_H_ + +#include "info-utils.h" +#include "terminal.h" + +typedef struct { + char *text; /* Text of the line as it appears. */ + int textlen; /* Printable Length of TEXT. */ + int inverse; /* Non-zero means this line is inverse. */ +} DISPLAY_LINE; + +/* An array of display lines which tell us what is currently visible on + the display. */ +extern DISPLAY_LINE **the_display; + +/* Non-zero means do no output. */ +extern int display_inhibited; + +/* Non-zero if we didn't completely redisplay a window. */ +extern int display_was_interrupted_p; + +/* Initialize THE_DISPLAY to WIDTH and HEIGHT, with nothing in it. */ +extern void display_initialize_display (); + +/* Clear all of the lines in DISPLAY making the screen blank. */ +extern void display_clear_display (); + +/* Update the windows pointed to by WINDOWS in THE_DISPLAY. This actually + writes the text on the screen. */ +extern void display_update_display (); + +/* Display WIN on THE_DISPLAY. Unlike display_update_display (), this + function only does one window. */ +extern void display_update_one_window (); + +/* Move the screen cursor to directly over the current character in WINDOW. */ +extern void display_cursor_at_point (); + +/* Scroll the region of the_display starting at START, ending at END, and + moving the lines AMOUNT lines. If AMOUNT is less than zero, the lines + are moved up in the screen, otherwise down. Actually, it is possible + for no scrolling to take place in the case that the terminal doesn't + support it. This doesn't matter to us. */ +extern void display_scroll_display (); + +/* Try to scroll lines in WINDOW. OLD_PAGETOP is the pagetop of WINDOW before + having had its line starts recalculated. OLD_STARTS is the list of line + starts that used to appear in this window. OLD_COUNT is the number of lines + that appear in the OLD_STARTS array. */ +extern void display_scroll_line_starts (); + +#endif /* !_DISPLAY_H_ */ diff --git a/gnu/usr.bin/texinfo/info/doc.c b/gnu/usr.bin/texinfo/info/doc.c new file mode 100644 index 0000000..b4cd81f --- /dev/null +++ b/gnu/usr.bin/texinfo/info/doc.c @@ -0,0 +1,128 @@ +/* doc.c -- Generated structure containing function names and doc strings. + + This file was automatically made from various source files with the + command "./makedoc". DO NOT EDIT THIS FILE, only "./makedoc.c". + Source files groveled to make this file include: + + ./session.c + ./echo_area.c + ./infodoc.c + ./m-x.c + ./indices.c + ./nodemenu.c + ./footnotes.c + ./variables.c + + An entry in the array FUNCTION_DOC_ARRAY is made for each command + found in the above files; each entry consists of a function pointer, + a string which is the user-visible name of the function, + and a string which documents its purpose. */ + +#include "doc.h" +#include "funs.h" + +FUNCTION_DOC function_doc_array[] = { + +/* Commands found in "./session.c". */ + { info_next_line, "next-line", "Move down to the next line" }, + { info_prev_line, "prev-line", "Move up to the previous line" }, + { info_end_of_line, "end-of-line", "Move to the end of the line" }, + { info_beginning_of_line, "beginning-of-line", "Move to the start of the line" }, + { info_forward_char, "forward-char", "Move forward a character" }, + { info_backward_char, "backward-char", "Move backward a character" }, + { info_forward_word, "forward-word", "Move forward a word" }, + { info_backward_word, "backward-word", "Move backward a word" }, + { info_global_next_node, "global-next-node", "Move forwards or down through node structure" }, + { info_global_prev_node, "global-prev-node", "Move backwards or up through node structure" }, + { info_scroll_forward, "scroll-forward", "Scroll forward in this window" }, + { info_scroll_backward, "scroll-backward", "Scroll backward in this window" }, + { info_beginning_of_node, "beginning-of-node", "Move to the start of this node" }, + { info_end_of_node, "end-of-node", "Move to the end of this node" }, + { info_next_window, "next-window", "Select the next window" }, + { info_prev_window, "prev-window", "Select the previous window" }, + { info_split_window, "split-window", "Split the current window" }, + { info_delete_window, "delete-window", "Delete the current window" }, + { info_keep_one_window, "keep-one-window", "Delete all other windows" }, + { info_scroll_other_window, "scroll-other-window", "Scroll the other window" }, + { info_grow_window, "grow-window", "Grow (or shrink) this window" }, + { info_tile_windows, "tile-windows", "Divide the available screen space among the visible windows" }, + { info_toggle_wrap, "toggle-wrap", "Toggle the state of line wrapping in the current window" }, + { info_next_node, "next-node", "Select the `Next' node" }, + { info_prev_node, "prev-node", "Select the `Prev' node" }, + { info_up_node, "up-node", "Select the `Up' node" }, + { info_last_node, "last-node", "Select the last node in this file" }, + { info_first_node, "first-node", "Select the first node in this file" }, + { info_history_node, "history-node", "Select the most recently selected node" }, + { info_last_menu_item, "last-menu-item", "Select the last item in this node's menu" }, + { info_menu_digit, "menu-digit", "Select this menu item" }, + { info_menu_item, "menu-item", "Read a menu item and select its node" }, + { info_xref_item, "xref-item", "Read a footnote or cross reference and select its node" }, + { info_find_menu, "find-menu", "Move to the start of this node's menu" }, + { info_visit_menu, "visit-menu", "Visit as many menu items at once as possible" }, + { info_goto_node, "goto-node", "Read a node name and select it" }, + { info_top_node, "top-node", "Select the node `Top' in this file" }, + { info_dir_node, "dir-node", "Select the node `(dir)'" }, + { info_kill_node, "kill-node", "Kill this node" }, + { info_view_file, "view-file", "Read the name of a file and select it" }, + { info_print_node, "print-node", "Pipe the contents of this node through INFO_PRINT_COMMAND" }, + { info_search, "search", "Read a string and search for it" }, + { isearch_forward, "isearch-forward", "Search interactively for a string as you type it" }, + { isearch_backward, "isearch-backward", "Search interactively for a string as you type it" }, + { info_move_to_prev_xref, "move-to-prev-xref", "Move to the previous cross reference" }, + { info_move_to_next_xref, "move-to-next-xref", "Move to the next cross reference" }, + { info_select_reference_this_line, "select-reference-this-line", "Select reference or menu item appearing on this line" }, + { info_abort_key, "abort-key", "Cancel current operation" }, + { info_move_to_window_line, "move-to-window-line", "Move to the cursor to a specific line of the window" }, + { info_redraw_display, "redraw-display", "Redraw the display" }, + { info_quit, "quit", "Quit using Info" }, + { info_do_lowercase_version, "do-lowercase-version", "" }, + { info_add_digit_to_numeric_arg, "add-digit-to-numeric-arg", "Add this digit to the current numeric argument" }, + { info_universal_argument, "universal-argument", "Start (or multiply by 4) the current numeric argument" }, + { info_numeric_arg_digit_loop, "numeric-arg-digit-loop", "" }, +/* Commands found in "./echo_area.c". */ + { ea_forward, "echo-area-forward", "Move forward a character" }, + { ea_backward, "echo-area-backward", "Move backward a character" }, + { ea_beg_of_line, "echo-area-beg-of-line", "Move to the start of this line" }, + { ea_end_of_line, "echo-area-end-of-line", "Move to the end of this line" }, + { ea_forward_word, "echo-area-forward-word", "Move forward a word" }, + { ea_backward_word, "echo-area-backward-word", "Move backward a word" }, + { ea_delete, "echo-area-delete", "Delete the character under the cursor" }, + { ea_rubout, "echo-area-rubout", "Delete the character behind the cursor" }, + { ea_abort, "echo-area-abort", "Cancel or quit operation" }, + { ea_newline, "echo-area-newline", "Accept (or force completion of) this line" }, + { ea_quoted_insert, "echo-area-quoted-insert", "Insert next character verbatim" }, + { ea_insert, "echo-area-insert", "Insert this character" }, + { ea_tab_insert, "echo-area-tab-insert", "Insert a TAB character" }, + { ea_transpose_chars, "echo-area-transpose-chars", "Transpose characters at point" }, + { ea_yank, "echo-area-yank", "Yank back the contents of the last kill" }, + { ea_yank_pop, "echo-area-yank-pop", "Yank back a previous kill" }, + { ea_kill_line, "echo-area-kill-line", "Kill to the end of the line" }, + { ea_backward_kill_line, "echo-area-backward-kill-line", "Kill to the beginning of the line" }, + { ea_kill_word, "echo-area-kill-word", "Kill the word following the cursor" }, + { ea_backward_kill_word, "echo-area-backward-kill-word", "Kill the word preceding the cursor" }, + { ea_possible_completions, "echo-area-possible-completions", "List possible completions" }, + { ea_complete, "echo-area-complete", "Insert completion" }, + { ea_scroll_completions_window, "echo-area-scroll-completions-window", "Scroll the completions window" }, +/* Commands found in "./infodoc.c". */ + { info_get_help_window, "get-help-window", "Display help message" }, + { info_get_info_help_node, "get-info-help-node", "Visit Info node `(info)Help'" }, + { describe_key, "describe-key", "Print documentation for KEY" }, + { info_where_is, "where-is", "Show what to type to execute a given command" }, +/* Commands found in "./m-x.c". */ + { describe_command, "describe-command", "Read the name of an Info command and describe it" }, + { info_execute_command, "execute-command", "Read a command name in the echo area and execute it" }, + { set_screen_height, "set-screen-height", "Set the height of the displayed window" }, +/* Commands found in "./indices.c". */ + { info_index_search, "index-search", "Look up a string in the index for this file" }, + { info_next_index_match, "next-index-match", "Go to the next matching index item from the last `\\[index-search]' command" }, + { info_index_apropos, "index-apropos", "Grovel all known info file's indices for a string and build a menu" }, +/* Commands found in "./nodemenu.c". */ + { list_visited_nodes, "list-visited-nodes", "Make a window containing a menu of all of the currently visited nodes" }, + { select_visited_node, "select-visited-node", "Select a node which has been previously visited in a visible window" }, +/* Commands found in "./footnotes.c". */ + { info_show_footnotes, "show-footnotes", "Show the footnotes associated with this node in another window" }, +/* Commands found in "./variables.c". */ + { describe_variable, "describe-variable", "Explain the use of a variable" }, + { set_variable, "set-variable", "Set the value of an Info variable" }, + { (VFunction *)NULL, (char *)NULL, (char *)NULL } +}; diff --git a/gnu/usr.bin/texinfo/info/doc.h b/gnu/usr.bin/texinfo/info/doc.h new file mode 100644 index 0000000..03d82e0 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/doc.h @@ -0,0 +1,58 @@ +/* doc.h -- Structure associating function pointers with documentation. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#ifndef _DOC_H_ +#define _DOC_H_ + +#if !defined (NULL) +# define NULL 0x0 +#endif /* !NULL */ + +#if !defined (__FUNCTION_DEF) +# define __FUNCTION_DEF +typedef int Function (); +typedef void VFunction (); +#endif /* _FUNCTION_DEF */ + +typedef struct { + VFunction *func; +#if defined (NAMED_FUNCTIONS) + char *func_name; +#endif /* NAMED_FUNCTIONS */ + char *doc; +} FUNCTION_DOC; + +extern FUNCTION_DOC function_doc_array[]; + +extern char *function_documentation (); +extern char *key_documentation (); +extern char *pretty_keyname (); +extern char *replace_in_documentation (); +extern void info_document_key (); +extern void dump_map_to_message_buffer (); + +#if defined (NAMED_FUNCTIONS) +extern char *function_name (); +extern VFunction *named_function (); +#endif /* NAMED_FUNCTIONS */ +#endif /* !_DOC_H_ */ diff --git a/gnu/usr.bin/texinfo/info/dribble.c b/gnu/usr.bin/texinfo/info/dribble.c new file mode 100644 index 0000000..3a63a15 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/dribble.c @@ -0,0 +1,71 @@ +/* dribble.c -- Dribble files for Info. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#include <stdio.h> +#include "dribble.h" + +/* When non-zero, it is a stream to write all input characters to for the + duration of this info session. */ +FILE *info_dribble_file = (FILE *)NULL; + +/* Open a dribble file named NAME, perhaps closing an already open one. + This sets the global variable INFO_DRIBBLE_FILE to the open stream. */ +void +open_dribble_file (name) + char *name; +{ + /* Perhaps close existing dribble file. */ + close_dribble_file (); + + info_dribble_file = fopen (name, "w"); + +#if defined (HAVE_SETVBUF) + if (info_dribble_file) +# if defined (SETVBUF_REVERSED) + setvbuf (info_dribble_file, _IONBF, (char *)NULL, 1); +# else + setvbuf (info_dribble_file, (char *)NULL, _IONBF, 1); +# endif /* !SETVBUF_REVERSED */ +#endif /* HAVE_SETVBUF */ +} + +/* If there is a dribble file already open, close it. */ +void +close_dribble_file () +{ + if (info_dribble_file) + { + fflush (info_dribble_file); + fclose (info_dribble_file); + info_dribble_file = (FILE *)NULL; + } +} + +/* Write some output to our existing dribble file. */ +void +dribble (byte) + unsigned char byte; +{ + if (info_dribble_file) + fwrite (&byte, sizeof (unsigned char), 1, info_dribble_file); +} diff --git a/gnu/usr.bin/texinfo/info/dribble.h b/gnu/usr.bin/texinfo/info/dribble.h new file mode 100644 index 0000000..85bd732 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/dribble.h @@ -0,0 +1,41 @@ +/* dribble.h -- Functions and vars declared in dribble.c. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#ifndef _DRIBBLE_H_ +#define _DRIBBLE_H_ + +/* When non-zero, it is a stream to write all input characters to for the + duration of this info session. */ +extern FILE *info_dribble_file; + +/* Open a dribble file named NAME, perhaps closing an already open one. + This sets the global variable INFO_DRIBBLE_FILE to the open stream. */ +extern void open_dribble_file (); + +/* If there is a dribble file already open, close it. */ +extern void close_dribble_file (); + +/* Write some output to our existing dribble file. */ +extern void dribble (); + +#endif /* !_DRIBBLE_H_ */ diff --git a/gnu/usr.bin/texinfo/info/echo_area.c b/gnu/usr.bin/texinfo/info/echo_area.c new file mode 100644 index 0000000..d751e90 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/echo_area.c @@ -0,0 +1,1500 @@ +/* echo_area.c -- How to read a line in the echo area. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#include "info.h" + +/* Non-zero means that C-g was used to quit reading input. */ +int info_aborted_echo_area = 0; + +/* Non-zero means that the echo area is being used to read input. */ +int echo_area_is_active = 0; + +/* The address of the last command executed in the echo area. */ +VFunction *ea_last_executed_command = (VFunction *)NULL; + +/* Non-zero means that the last command executed while reading input + killed some text. */ +int echo_area_last_command_was_kill = 0; + +/* Variables which hold on to the current state of the input line. */ +static char input_line[1 + EA_MAX_INPUT]; +static char *input_line_prompt; +static int input_line_point; +static int input_line_beg; +static int input_line_end; +static NODE input_line_node = { + (char *)NULL, (char *)NULL, (char *)NULL, input_line, EA_MAX_INPUT, 0 +}; + +static void echo_area_initialize_node (); +static void push_echo_area (), pop_echo_area (); +static int echo_area_stack_depth (), echo_area_stack_contains_completions_p (); + +static void ea_kill_text (); + +/* Non-zero means we force the user to complete. */ +static int echo_area_must_complete_p = 0; +static int completions_window_p (); + +/* If non-null, this is a window which was specifically created to display + possible completions output. We remember it so we can delete it when + appropriate. */ +static WINDOW *echo_area_completions_window = (WINDOW *)NULL; + +/* Variables which keep track of the window which was active prior to + entering the echo area. */ +static WINDOW *calling_window = (WINDOW *)NULL; +static NODE *calling_window_node = (NODE *)NULL; +static long calling_window_point = 0; +static long calling_window_pagetop = 0; + +/* Remember the node and pertinent variables of the calling window. */ +static void +remember_calling_window (window) + WINDOW *window; +{ + /* Only do this if the calling window is not the completions window, or, + if it is the completions window and there is no other window. */ + if (!completions_window_p (window) || + ((window == windows) && !(window->next))) + { + calling_window = window; + calling_window_node = window->node; + calling_window_point = window->point; + calling_window_pagetop = window->pagetop; + } +} + +/* Restore the caller's window so that it shows the node that it was showing + on entry to info_read_xxx_echo_area (). */ +static void +restore_calling_window () +{ + register WINDOW *win, *compwin = (WINDOW *)NULL; + + /* If the calling window is still visible, and it is the window that + we used for completions output, then restore the calling window. */ + for (win = windows; win; win = win->next) + { + if (completions_window_p (win)) + compwin = win; + + if (win == calling_window && win == compwin) + { + window_set_node_of_window (calling_window, calling_window_node); + calling_window->point = calling_window_point; + calling_window->pagetop = calling_window_pagetop; + compwin = (WINDOW *)NULL; + break; + } + } + + /* Delete the completions window if it is still present, it isn't the + last window on the screen, and there aren't any prior echo area reads + pending which created a completions window. */ + if (compwin) + { + if ((compwin != windows || windows->next) && + !echo_area_stack_contains_completions_p ()) + { + WINDOW *next; + int pagetop, start, end, amount; + + next = compwin->next; + if (next) + { + start = next->first_row; + end = start + next->height; + amount = - (compwin->height + 1); + pagetop = next->pagetop; + } + + info_delete_window_internal (compwin); + + /* This is not necessary because info_delete_window_internal () + calls echo_area_inform_of_deleted_window (), which does the + right thing. */ +#if defined (UNNECESSARY) + echo_area_completions_window = (WINDOW *)NULL; +#endif /* UNNECESSARY */ + + if (next) + { + display_scroll_display (start, end, amount); + next->pagetop = pagetop; + display_update_display (windows); + } + } + } +} + +/* Set up a new input line with PROMPT. */ +static void +initialize_input_line (prompt) + char *prompt; +{ + input_line_prompt = prompt; + if (prompt) + strcpy (input_line, prompt); + else + input_line[0] = '\0'; + + input_line_beg = input_line_end = input_line_point = strlen (prompt); +} + +static char * +echo_area_after_read () +{ + char *return_value; + + if (info_aborted_echo_area) + { + info_aborted_echo_area = 0; + return_value = (char *)NULL; + } + else + { + if (input_line_beg == input_line_end) + return_value = savestring (""); + else + { + int line_len = input_line_end - input_line_beg; + return_value = (char *) xmalloc (1 + line_len); + strncpy (return_value, &input_line[input_line_beg], line_len); + return_value[line_len] = '\0'; + } + } + return (return_value); +} + +/* Read a line of text in the echo area. Return a malloc ()'ed string, + or NULL if the user aborted out of this read. WINDOW is the currently + active window, so that we can restore it when we need to. PROMPT, if + non-null, is a prompt to print before reading the line. */ +char * +info_read_in_echo_area (window, prompt) + WINDOW *window; + char *prompt; +{ + char *line; + + /* If the echo area is already active, remember the current state. */ + if (echo_area_is_active) + push_echo_area (); + + /* Initialize our local variables. */ + initialize_input_line (prompt); + + /* Initialize the echo area for the first (but maybe not the last) time. */ + echo_area_initialize_node (); + + /* Save away the original node of this window, and the window itself, + so echo area commands can temporarily use this window. */ + remember_calling_window (window); + + /* Let the rest of Info know that the echo area is active. */ + echo_area_is_active++; + active_window = the_echo_area; + + /* Read characters in the echo area. */ + info_read_and_dispatch (); + + echo_area_is_active--; + + /* Restore the original active window and show point in it. */ + active_window = calling_window; + restore_calling_window (); + display_cursor_at_point (active_window); + fflush (stdout); + + /* Get the value of the line. */ + line = echo_area_after_read (); + + /* If there is a previous loop waiting for us, restore it now. */ + if (echo_area_is_active) + pop_echo_area (); + + /* Return the results to the caller. */ + return (line); +} + +/* (re) Initialize the echo area node. */ +static void +echo_area_initialize_node () +{ + register int i; + + for (i = input_line_end; i < sizeof (input_line); i++) + input_line[i] = ' '; + + input_line[i - 1] = '\n'; + window_set_node_of_window (the_echo_area, &input_line_node); + input_line[input_line_end] = '\n'; +} + +/* Prepare to read characters in the echo area. This can initialize the + echo area node, but its primary purpose is to side effect the input + line buffer contents. */ +void +echo_area_prep_read () +{ + if (the_echo_area->node != &input_line_node) + echo_area_initialize_node (); + + the_echo_area->point = input_line_point; + input_line[input_line_end] = '\n'; + display_update_one_window (the_echo_area); + display_cursor_at_point (active_window); +} + + +/* **************************************************************** */ +/* */ +/* Echo Area Movement Commands */ +/* */ +/* **************************************************************** */ + +DECLARE_INFO_COMMAND (ea_forward, "Move forward a character") +{ + if (count < 0) + ea_backward (window, -count, key); + else + { + input_line_point += count; + if (input_line_point > input_line_end) + input_line_point = input_line_end; + } +} + +DECLARE_INFO_COMMAND (ea_backward, "Move backward a character") +{ + if (count < 0) + ea_forward (window, -count, key); + else + { + input_line_point -= count; + if (input_line_point < input_line_beg) + input_line_point = input_line_beg; + } +} + +DECLARE_INFO_COMMAND (ea_beg_of_line, "Move to the start of this line") +{ + input_line_point = input_line_beg; +} + +DECLARE_INFO_COMMAND (ea_end_of_line, "Move to the end of this line") +{ + input_line_point = input_line_end; +} + +#define alphabetic(c) (islower (c) || isupper (c) || isdigit (c)) + +/* Move forward a word in the input line. */ +DECLARE_INFO_COMMAND (ea_forward_word, "Move forward a word") +{ + int c; + + if (count < 0) + ea_backward_word (window, -count, key); + else + { + while (count--) + { + if (input_line_point == input_line_end) + return; + + /* If we are not in a word, move forward until we are in one. + Then, move forward until we hit a non-alphabetic character. */ + c = input_line[input_line_point]; + + if (!alphabetic (c)) + { + while (++input_line_point < input_line_end) + { + c = input_line[input_line_point]; + if (alphabetic (c)) + break; + } + } + + if (input_line_point == input_line_end) + return; + + while (++input_line_point < input_line_end) + { + c = input_line[input_line_point]; + if (!alphabetic (c)) + break; + } + } + } +} + +DECLARE_INFO_COMMAND (ea_backward_word, "Move backward a word") +{ + int c; + + if (count < 0) + ea_forward_word (window, -count, key); + else + { + while (count--) + { + if (input_line_point == input_line_beg) + return; + + /* Like ea_forward_word (), except that we look at the + characters just before point. */ + + c = input_line[input_line_point - 1]; + + if (!alphabetic (c)) + { + while (--input_line_point) + { + c = input_line[input_line_point - 1]; + if (alphabetic (c)) + break; + } + } + + while (input_line_point != input_line_beg) + { + c = input_line[input_line_point - 1]; + if (!alphabetic (c)) + break; + else + --input_line_point; + } + } + } +} + +DECLARE_INFO_COMMAND (ea_delete, "Delete the character under the cursor") +{ + register int i; + + if (count < 0) + ea_rubout (window, -count, key); + else + { + if (input_line_point == input_line_end) + return; + + if (info_explicit_arg || count > 1) + { + int orig_point; + + orig_point = input_line_point; + ea_forward (window, count, key); + ea_kill_text (orig_point, input_line_point); + input_line_point = orig_point; + } + else + { + for (i = input_line_point; i < input_line_end; i++) + input_line[i] = input_line[i + 1]; + + input_line_end--; + } + } +} + +DECLARE_INFO_COMMAND (ea_rubout, "Delete the character behind the cursor") +{ + if (count < 0) + ea_delete (window, -count, key); + else + { + int start; + + if (input_line_point == input_line_beg) + return; + + start = input_line_point; + ea_backward (window, count, key); + + if (info_explicit_arg || count > 1) + ea_kill_text (start, input_line_point); + else + ea_delete (window, count, key); + } +} + +DECLARE_INFO_COMMAND (ea_abort, "Cancel or quit operation") +{ + /* If any text, just discard it, and restore the calling window's node. + If no text, quit. */ + if (input_line_end != input_line_beg) + { + terminal_ring_bell (); + input_line_end = input_line_point = input_line_beg; + if (calling_window->node != calling_window_node) + restore_calling_window (); + } + else + info_aborted_echo_area = 1; +} + +DECLARE_INFO_COMMAND (ea_newline, "Accept (or force completion of) this line") +{ + /* Stub does nothing. Simply here to see if it has been executed. */ +} + +DECLARE_INFO_COMMAND (ea_quoted_insert, "Insert next character verbatim") +{ + unsigned char character; + + character = info_get_another_input_char (); + ea_insert (window, count, character); +} + +DECLARE_INFO_COMMAND (ea_insert, "Insert this character") +{ + register int i; + + if ((input_line_end + 1) == EA_MAX_INPUT) + { + terminal_ring_bell (); + return; + } + + for (i = input_line_end + 1; i != input_line_point; i--) + input_line[i] = input_line[i - 1]; + + input_line[input_line_point] = key; + input_line_point++; + input_line_end++; +} + +DECLARE_INFO_COMMAND (ea_tab_insert, "Insert a TAB character") +{ + ea_insert (window, count, '\t'); +} + +/* Transpose the characters at point. If point is at the end of the line, + then transpose the characters before point. */ +DECLARE_INFO_COMMAND (ea_transpose_chars, "Transpose characters at point") +{ + /* Handle conditions that would make it impossible to transpose + characters. */ + if (!count || !input_line_point || (input_line_end - input_line_beg) < 2) + return; + + while (count) + { + int t; + if (input_line_point == input_line_end) + { + t = input_line[input_line_point - 1]; + + input_line[input_line_point - 1] = input_line[input_line_point - 2]; + input_line[input_line_point - 2] = t; + } + else + { + t = input_line[input_line_point]; + + input_line[input_line_point] = input_line[input_line_point - 1]; + input_line[input_line_point - 1] = t; + + if (count < 0 && input_line_point != input_line_beg) + input_line_point--; + else + input_line_point++; + } + + if (count < 0) + count++; + else + count--; + } +} + +/* **************************************************************** */ +/* */ +/* Echo Area Killing and Yanking */ +/* */ +/* **************************************************************** */ + +static char **kill_ring = (char **)NULL; +static int kill_ring_index = 0; /* Number of kills appearing in KILL_RING. */ +static int kill_ring_slots = 0; /* Number of slots allocated to KILL_RING. */ +static int kill_ring_loc = 0; /* Location of current yank pointer. */ + +/* The largest number of kills that we remember at one time. */ +static int max_retained_kills = 15; + +DECLARE_INFO_COMMAND (ea_yank, "Yank back the contents of the last kill") +{ + register int i; + register char *text; + + if (!kill_ring_index) + { + inform_in_echo_area ("Kill ring is empty"); + return; + } + + text = kill_ring[kill_ring_loc]; + + for (i = 0; text[i]; i++) + ea_insert (window, 1, text[i]); +} + +/* If the last command was yank, or yank_pop, and the text just before + point is identical to the current kill item, then delete that text + from the line, rotate the index down, and yank back some other text. */ +DECLARE_INFO_COMMAND (ea_yank_pop, "Yank back a previous kill") +{ + register int len; + + if (((ea_last_executed_command != ea_yank) && + (ea_last_executed_command != ea_yank_pop)) || + (kill_ring_index == 0)) + return; + + len = strlen (kill_ring[kill_ring_loc]); + + /* Delete the last yanked item from the line. */ + { + register int i, counter; + + counter = input_line_end - input_line_point; + + for (i = input_line_point - len; counter; i++, counter--) + input_line[i] = input_line[i + len]; + + input_line_end -= len; + input_line_point -= len; + } + + /* Get a previous kill, and yank that. */ + kill_ring_loc--; + if (kill_ring_loc < 0) + kill_ring_loc = kill_ring_index - 1; + + ea_yank (window, count, key); +} + +/* Delete the text from point to end of line. */ +DECLARE_INFO_COMMAND (ea_kill_line, "Kill to the end of the line") +{ + if (count < 0) + { + ea_kill_text (input_line_point, input_line_beg); + input_line_point = input_line_beg; + } + else + ea_kill_text (input_line_point, input_line_end); +} + +/* Delete the text from point to beg of line. */ +DECLARE_INFO_COMMAND (ea_backward_kill_line, + "Kill to the beginning of the line") +{ + if (count < 0) + ea_kill_text (input_line_point, input_line_end); + else + { + ea_kill_text (input_line_point, input_line_beg); + input_line_point = input_line_beg; + } +} + +/* Delete from point to the end of the current word. */ +DECLARE_INFO_COMMAND (ea_kill_word, "Kill the word following the cursor") +{ + int orig_point = input_line_point; + + if (count < 0) + ea_backward_kill_word (window, -count, key); + else + { + ea_forward_word (window, count, key); + + if (input_line_point != orig_point) + ea_kill_text (orig_point, input_line_point); + + input_line_point = orig_point; + } +} + +/* Delete from point to the start of the current word. */ +DECLARE_INFO_COMMAND (ea_backward_kill_word, + "Kill the word preceding the cursor") +{ + int orig_point = input_line_point; + + if (count < 0) + ea_kill_word (window, -count, key); + else + { + ea_backward_word (window, count, key); + + if (input_line_point != orig_point) + ea_kill_text (orig_point, input_line_point); + } +} + +/* The way to kill something. This appends or prepends to the last + kill, if the last command was a kill command. If FROM is less + than TO, then the killed text is appended to the most recent kill, + otherwise it is prepended. If the last command was not a kill command, + then a new slot is made for this kill. */ +static void +ea_kill_text (from, to) + int from, to; +{ + register int i, counter, distance; + int killing_backwards, slot; + char *killed_text; + + killing_backwards = (from > to); + + /* If killing backwards, reverse the values of FROM and TO. */ + if (killing_backwards) + { + int temp = from; + from = to; + to = temp; + } + + /* Remember the text that we are about to delete. */ + distance = to - from; + killed_text = (char *)xmalloc (1 + distance); + strncpy (killed_text, &input_line[from], distance); + killed_text[distance] = '\0'; + + /* Actually delete the text from the line. */ + counter = input_line_end - to; + + for (i = from; counter; i++, counter--) + input_line[i] = input_line[i + distance]; + + input_line_end -= distance; + + /* If the last command was a kill, append or prepend the killed text to + the last command's killed text. */ + if (echo_area_last_command_was_kill) + { + char *old, *new; + + slot = kill_ring_loc; + old = kill_ring[slot]; + new = (char *)xmalloc (1 + strlen (old) + strlen (killed_text)); + + if (killing_backwards) + { + /* Prepend TEXT to current kill. */ + strcpy (new, killed_text); + strcat (new, old); + } + else + { + /* Append TEXT to current kill. */ + strcpy (new, old); + strcat (new, killed_text); + } + + free (old); + free (killed_text); + kill_ring[slot] = new; + } + else + { + /* Try to store the kill in a new slot, unless that would cause there + to be too many remembered kills. */ + slot = kill_ring_index; + + if (slot == max_retained_kills) + slot = 0; + + if (slot + 1 > kill_ring_slots) + kill_ring = (char **) xrealloc + (kill_ring, + (kill_ring_slots += max_retained_kills) * sizeof (char *)); + + if (slot != kill_ring_index) + free (kill_ring[slot]); + else + kill_ring_index++; + + kill_ring[slot] = killed_text; + + kill_ring_loc = slot; + } + + /* Notice that the last command was a kill. */ + echo_area_last_command_was_kill++; +} + +/* **************************************************************** */ +/* */ +/* Echo Area Completion */ +/* */ +/* **************************************************************** */ + +/* Pointer to an array of REFERENCE to complete over. */ +static REFERENCE **echo_area_completion_items = (REFERENCE **)NULL; + +/* Sorted array of REFERENCE * which is the possible completions found in + the variable echo_area_completion_items. If there is only one element, + it is the only possible completion. */ +static REFERENCE **completions_found = (REFERENCE **)NULL; +static int completions_found_index = 0; +static int completions_found_slots = 0; + +/* The lowest common denominator found while completing. */ +static REFERENCE *LCD_completion; + +/* Internal functions used by the user calls. */ +static void build_completions (), completions_must_be_rebuilt (); + +/* Variable which holds the output of completions. */ +static NODE *possible_completions_output_node = (NODE *)NULL; + +static char *compwin_name = "*Completions*"; + +/* Return non-zero if WINDOW is a window used for completions output. */ +static int +completions_window_p (window) + WINDOW *window; +{ + int result = 0; + + if (internal_info_node_p (window->node) && + (strcmp (window->node->nodename, compwin_name) == 0)) + result = 1; + + return (result); +} + +/* Workhorse for completion readers. If FORCE is non-zero, the user cannot + exit unless the line read completes, or is empty. */ +char * +info_read_completing_internal (window, prompt, completions, force) + WINDOW *window; + char *prompt; + REFERENCE **completions; + int force; +{ + char *line; + + /* If the echo area is already active, remember the current state. */ + if (echo_area_is_active) + push_echo_area (); + + echo_area_must_complete_p = force; + + /* Initialize our local variables. */ + initialize_input_line (prompt); + + /* Initialize the echo area for the first (but maybe not the last) time. */ + echo_area_initialize_node (); + + /* Save away the original node of this window, and the window itself, + so echo area commands can temporarily use this window. */ + remember_calling_window (window); + + /* Save away the list of items to complete over. */ + echo_area_completion_items = completions; + completions_must_be_rebuilt (); + + active_window = the_echo_area; + echo_area_is_active++; + + /* Read characters in the echo area. */ + while (1) + { + info_read_and_dispatch (); + + line = echo_area_after_read (); + + /* Force the completion to take place if the user hasn't accepted + a default or aborted, and if FORCE is active. */ + if (force && line && *line && completions) + { + register int i; + + build_completions (); + + /* If there is only one completion, then make the line be that + completion. */ + if (completions_found_index == 1) + { + free (line); + line = savestring (completions_found[0]->label); + break; + } + + /* If one of the completions matches exactly, then that is okay, so + return the current line. */ + for (i = 0; i < completions_found_index; i++) + if (stricmp (completions_found[i]->label, line) == 0) + { + free (line); + line = savestring (completions_found[i]->label); + break; + } + + /* If no match, go back and try again. */ + if (i == completions_found_index) + { + inform_in_echo_area ("Not complete"); + continue; + } + } + break; + } + echo_area_is_active--; + + /* Restore the original active window and show point in it. */ + active_window = calling_window; + restore_calling_window (); + display_cursor_at_point (active_window); + fflush (stdout); + + echo_area_completion_items = (REFERENCE **)NULL; + completions_must_be_rebuilt (); + + /* If there is a previous loop waiting for us, restore it now. */ + if (echo_area_is_active) + pop_echo_area (); + + return (line); +} + +/* Read a line in the echo area with completion over COMPLETIONS. */ +char * +info_read_completing_in_echo_area (window, prompt, completions) + WINDOW *window; + char *prompt; + REFERENCE **completions; +{ + return (info_read_completing_internal (window, prompt, completions, 1)); +} + +/* Read a line in the echo area allowing completion over COMPLETIONS, but + not requiring it. */ +char * +info_read_maybe_completing (window, prompt, completions) + WINDOW *window; + char *prompt; + REFERENCE **completions; +{ + return (info_read_completing_internal (window, prompt, completions, 0)); +} + +DECLARE_INFO_COMMAND (ea_possible_completions, "List possible completions") +{ + if (!echo_area_completion_items) + { + ea_insert (window, count, key); + return; + } + + build_completions (); + + if (!completions_found_index) + { + terminal_ring_bell (); + inform_in_echo_area ("No completions"); + } + else if ((completions_found_index == 1) && (key != '?')) + { + inform_in_echo_area ("Sole completion"); + } + else + { + register int i, l; + int limit, count, max_label = 0; + + initialize_message_buffer (); + printf_to_message_buffer + ("There %s %d ", completions_found_index == 1 ? "is" : "are", + completions_found_index); + printf_to_message_buffer + ("completion%s:\n", completions_found_index == 1 ? "" : "s"); + + /* Find the maximum length of a label. */ + for (i = 0; i < completions_found_index; i++) + { + int len = strlen (completions_found[i]->label); + if (len > max_label) + max_label = len; + } + + max_label += 4; + + /* Find out how many columns we should print in. */ + limit = calling_window->width / max_label; + if (limit != 1 && (limit * max_label == calling_window->width)) + limit--; + + /* Avoid a possible floating exception. If max_label > width then + the limit will be 0 and a divide-by-zero fault will result. */ + if (limit == 0) + limit = 1; + + /* How many iterations of the printing loop? */ + count = (completions_found_index + (limit - 1)) / limit; + + /* Watch out for special case. If the number of completions is less + than LIMIT, then just do the inner printing loop. */ + if (completions_found_index < limit) + count = 1; + + /* Print the sorted items, up-and-down alphabetically. */ + for (i = 0; i < count; i++) + { + register int j; + + for (j = 0, l = i; j < limit; j++) + { + if (l >= completions_found_index) + break; + else + { + char *label; + int printed_length, k; + + label = completions_found[l]->label; + printed_length = strlen (label); + printf_to_message_buffer ("%s", label); + + if (j + 1 < limit) + { + for (k = 0; k < max_label - printed_length; k++) + printf_to_message_buffer (" "); + } + } + l += count; + } + printf_to_message_buffer ("\n"); + } + + /* Make a new node to hold onto possible completions. Don't destroy + dangling pointers. */ + { + NODE *temp; + + temp = message_buffer_to_node (); + add_gcable_pointer (temp->contents); + name_internal_node (temp, compwin_name); + possible_completions_output_node = temp; + } + + /* Find a suitable window for displaying the completions output. + First choice is an existing window showing completions output. + If there is only one window, and it is large, make another + (smaller) window, and use that one. Otherwise, use the caller's + window. */ + { + WINDOW *compwin; + + compwin = get_internal_info_window (compwin_name); + + if (!compwin) + { + /* If we can split the window to display most of the completion + items, then do so. */ + if (calling_window->height > (count * 2)) + { + int start, end, pagetop; + + active_window = calling_window; + + /* Perhaps we can scroll this window on redisplay. */ + start = calling_window->first_row; + pagetop = calling_window->pagetop; + + compwin = + window_make_window (possible_completions_output_node); + active_window = the_echo_area; + window_change_window_height + (compwin, -(compwin->height - (count + 2))); + + window_adjust_pagetop (calling_window); + remember_calling_window (calling_window); + +#if defined (SPLIT_BEFORE_ACTIVE) + /* If the pagetop hasn't changed, scrolling the calling + window is a reasonable thing to do. */ + if (pagetop == calling_window->pagetop) + { + end = start + calling_window->height; + display_scroll_display + (start, end, calling_window->prev->height + 1); + } +#else /* !SPLIT_BEFORE_ACTIVE */ + /* If the pagetop has changed, set the new pagetop here. */ + if (pagetop != calling_window->pagetop) + { + int newtop = calling_window->pagetop; + calling_window->pagetop = pagetop; + set_window_pagetop (calling_window, newtop); + } +#endif /* !SPLIT_BEFORE_ACTIVE */ + + echo_area_completions_window = compwin; + remember_window_and_node (compwin, compwin->node); + } + else + compwin = calling_window; + } + + if (compwin->node != possible_completions_output_node) + { + window_set_node_of_window + (compwin, possible_completions_output_node); + remember_window_and_node (compwin, compwin->node); + } + + display_update_display (windows); + } + } +} + +DECLARE_INFO_COMMAND (ea_complete, "Insert completion") +{ + if (!echo_area_completion_items) + { + ea_insert (window, count, key); + return; + } + + /* If KEY is SPC, and we are not forcing completion to take place, simply + insert the key. */ + if (!echo_area_must_complete_p && key == SPC) + { + ea_insert (window, count, key); + return; + } + + if (ea_last_executed_command == ea_complete) + { + /* If the keypress is a SPC character, and we have already tried + completing once, and there are several completions, then check + the batch of completions to see if any continue with a space. + If there are some, insert the space character and continue. */ + if (key == SPC && completions_found_index > 1) + { + register int i, offset; + + offset = input_line_end - input_line_beg; + + for (i = 0; i < completions_found_index; i++) + if (completions_found[i]->label[offset] == ' ') + break; + + if (completions_found[i]) + ea_insert (window, 1, ' '); + else + { + ea_possible_completions (window, count, key); + return; + } + } + else + { + ea_possible_completions (window, count, key); + return; + } + } + + input_line_point = input_line_end; + build_completions (); + + if (!completions_found_index) + terminal_ring_bell (); + else if (LCD_completion->label[0] == '\0') + ea_possible_completions (window, count, key); + else + { + register int i; + input_line_point = input_line_end = input_line_beg; + for (i = 0; LCD_completion->label[i]; i++) + ea_insert (window, 1, LCD_completion->label[i]); + } +} + +/* Utility REFERENCE used to store possible LCD. */ +static REFERENCE LCD_reference = { (char *)NULL, (char *)NULL, (char *)NULL }; + +static void remove_completion_duplicates (); + +/* Variables which remember the state of the most recent call + to build_completions (). */ +static char *last_completion_request = (char *)NULL; +static REFERENCE **last_completion_items = (REFERENCE **)NULL; + +/* How to tell the completion builder to reset internal state. */ +static void +completions_must_be_rebuilt () +{ + maybe_free (last_completion_request); + last_completion_request = (char *)NULL; + last_completion_items = (REFERENCE **)NULL; +} + +/* Build a list of possible completions from echo_area_completion_items, + and the contents of input_line. */ +static void +build_completions () +{ + register int i, len; + register REFERENCE *entry; + char *request; + int informed_of_lengthy_job = 0; + + /* If there are no items to complete over, exit immediately. */ + if (!echo_area_completion_items) + { + completions_found_index = 0; + LCD_completion = (REFERENCE *)NULL; + return; + } + + /* Check to see if this call to build completions is the same as the last + call to build completions. */ + len = input_line_end - input_line_beg; + request = (char *)xmalloc (1 + len); + strncpy (request, &input_line[input_line_beg], len); + request[len] = '\0'; + + if (last_completion_request && last_completion_items && + last_completion_items == echo_area_completion_items && + (strcmp (last_completion_request, request) == 0)) + { + free (request); + return; + } + + maybe_free (last_completion_request); + last_completion_request = request; + last_completion_items = echo_area_completion_items; + + /* Always start at the beginning of the list. */ + completions_found_index = 0; + LCD_completion = (REFERENCE *)NULL; + + for (i = 0; entry = echo_area_completion_items[i]; i++) + { + if (strnicmp (request, entry->label, len) == 0) + add_pointer_to_array (entry, completions_found_index, + completions_found, completions_found_slots, + 20, REFERENCE *); + + if (!informed_of_lengthy_job && completions_found_index > 100) + { + informed_of_lengthy_job = 1; + window_message_in_echo_area ("Building completions..."); + } + } + + if (!completions_found_index) + return; + + /* Sort and prune duplicate entries from the completions array. */ + remove_completion_duplicates (); + + /* If there is only one completion, just return that. */ + if (completions_found_index == 1) + { + LCD_completion = completions_found[0]; + return; + } + + /* Find the least common denominator. */ + { + long shortest = 100000; + + for (i = 1; i < completions_found_index; i++) + { + register int j; + int c1, c2; + + for (j = 0; + (c1 = info_tolower (completions_found[i - 1]->label[j])) && + (c2 = info_tolower (completions_found[i]->label[j])); + j++) + if (c1 != c2) + break; + + if (shortest > j) + shortest = j; + } + + maybe_free (LCD_reference.label); + LCD_reference.label = (char *)xmalloc (1 + shortest); + strncpy (LCD_reference.label, completions_found[0]->label, shortest); + LCD_reference.label[shortest] = '\0'; + LCD_completion = &LCD_reference; + } + + if (informed_of_lengthy_job) + echo_area_initialize_node (); +} + +/* Function called by qsort. */ +static int +compare_references (entry1, entry2) + REFERENCE **entry1, **entry2; +{ + return (stricmp ((*entry1)->label, (*entry2)->label)); +} + +/* Prune duplicate entries from COMPLETIONS_FOUND. */ +static void +remove_completion_duplicates () +{ + register int i, j; + REFERENCE **temp; + int newlen; + + if (!completions_found_index) + return; + + /* Sort the items. */ + qsort (completions_found, completions_found_index, sizeof (REFERENCE *), + compare_references); + + for (i = 0, newlen = 1; i < completions_found_index - 1; i++) + { + if (strcmp (completions_found[i]->label, + completions_found[i + 1]->label) == 0) + completions_found[i] = (REFERENCE *)NULL; + else + newlen++; + } + + /* We have marked all the dead slots. It is faster to copy the live slots + twice than to prune the dead slots one by one. */ + temp = (REFERENCE **)xmalloc ((1 + newlen) * sizeof (REFERENCE *)); + for (i = 0, j = 0; i < completions_found_index; i++) + if (completions_found[i]) + temp[j++] = completions_found[i]; + + for (i = 0; i < newlen; i++) + completions_found[i] = temp[i]; + + completions_found[i] = (REFERENCE *)NULL; + completions_found_index = newlen; + free (temp); +} + +/* Scroll the "other" window. If there is a window showing completions, scroll + that one, otherwise scroll the window which was active on entering the read + function. */ +DECLARE_INFO_COMMAND (ea_scroll_completions_window, "Scroll the completions window") +{ + WINDOW *compwin; + int old_pagetop; + + compwin = get_internal_info_window (compwin_name); + + if (!compwin) + compwin = calling_window; + + old_pagetop = compwin->pagetop; + + /* Let info_scroll_forward () do the work, and print any messages that + need to be displayed. */ + info_scroll_forward (compwin, count, key); +} + +/* Function which gets called when an Info window is deleted while the + echo area is active. WINDOW is the window which has just been deleted. */ +void +echo_area_inform_of_deleted_window (window) + WINDOW *window; +{ + /* If this is the calling_window, forget what we remembered about it. */ + if (window == calling_window) + { + if (active_window != the_echo_area) + remember_calling_window (active_window); + else + remember_calling_window (windows); + } + + /* If this window was the echo_area_completions_window, then notice that + the window has been deleted. */ + if (window == echo_area_completions_window) + echo_area_completions_window = (WINDOW *)NULL; +} + +/* **************************************************************** */ +/* */ +/* Pushing and Popping the Echo Area */ +/* */ +/* **************************************************************** */ + +/* Push and Pop the echo area. */ +typedef struct { + char *line; + char *prompt; + REFERENCE **comp_items; + int point, beg, end; + int must_complete; + NODE node; + WINDOW *compwin; +} PUSHED_EA; + +static PUSHED_EA **pushed_echo_areas = (PUSHED_EA **)NULL; +static int pushed_echo_areas_index = 0; +static int pushed_echo_areas_slots = 0; + +/* Pushing the echo_area has a side effect of zeroing the completion_items. */ +static void +push_echo_area () +{ + PUSHED_EA *pushed; + + pushed = (PUSHED_EA *)xmalloc (sizeof (PUSHED_EA)); + pushed->line = savestring (input_line); + pushed->prompt = input_line_prompt; + pushed->point = input_line_point; + pushed->beg = input_line_beg; + pushed->end = input_line_end; + pushed->node = input_line_node; + pushed->comp_items = echo_area_completion_items; + pushed->must_complete = echo_area_must_complete_p; + pushed->compwin = echo_area_completions_window; + + add_pointer_to_array (pushed, pushed_echo_areas_index, pushed_echo_areas, + pushed_echo_areas_slots, 4, PUSHED_EA *); + + echo_area_completion_items = (REFERENCE **)NULL; +} + +static void +pop_echo_area () +{ + PUSHED_EA *popped; + + popped = pushed_echo_areas[--pushed_echo_areas_index]; + + strcpy (input_line, popped->line); + free (popped->line); + input_line_prompt = popped->prompt; + input_line_point = popped->point; + input_line_beg = popped->beg; + input_line_end = popped->end; + input_line_node = popped->node; + echo_area_completion_items = popped->comp_items; + echo_area_must_complete_p = popped->must_complete; + echo_area_completions_window = popped->compwin; + completions_must_be_rebuilt (); + + /* If the completion window no longer exists, forget about it. */ + if (echo_area_completions_window) + { + register WINDOW *win; + + for (win = windows; win; win = win->next) + if (echo_area_completions_window == win) + break; + + /* If the window wasn't found, then it has already been deleted. */ + if (!win) + echo_area_completions_window = (WINDOW *)NULL; + } + + free (popped); +} + +static int +echo_area_stack_depth () +{ + return (pushed_echo_areas_index); +} + +/* Returns non-zero if any of the prior stacked calls to read in the echo + area produced a completions window. */ +static int +echo_area_stack_contains_completions_p () +{ + register int i; + + for (i = 0; i < pushed_echo_areas_index; i++) + if (pushed_echo_areas[i]->compwin) + return (1); + + return (0); +} + +/* **************************************************************** */ +/* */ +/* Error Messages While Reading in Echo Area */ +/* */ +/* **************************************************************** */ + +#if defined (HAVE_SYS_TIME_H) +# include <sys/time.h> +# define HAVE_STRUCT_TIMEVAL +#endif /* HAVE_SYS_TIME_H */ + +static void +pause_or_input () +{ +#if defined (FD_SET) + struct timeval timer; + fd_set readfds; + int ready; + + FD_ZERO (&readfds); + FD_SET (fileno (stdin), &readfds); + timer.tv_sec = 2; + timer.tv_usec = 750; + ready = select (1, &readfds, (fd_set *)NULL, (fd_set *)NULL, &timer); +#endif /* FD_SET */ +} + +/* Print MESSAGE right after the end of the current line, and wait + for input or 2.75 seconds, whichever comes first. Then flush the + informational message that was printed. */ +void +inform_in_echo_area (message) + char *message; +{ + register int i; + char *text; + + text = savestring (message); + for (i = 0; text[i] && text[i] != '\n'; i++); + text[i] = '\0'; + + echo_area_initialize_node (); + sprintf (&input_line[input_line_end], "%s[%s]\n", + echo_area_is_active ? " ": "", text); + free (text); + the_echo_area->point = input_line_point; + display_update_one_window (the_echo_area); + display_cursor_at_point (active_window); + fflush (stdout); + pause_or_input (); + echo_area_initialize_node (); +} diff --git a/gnu/usr.bin/texinfo/info/echo_area.h b/gnu/usr.bin/texinfo/info/echo_area.h new file mode 100644 index 0000000..3b06078 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/echo_area.h @@ -0,0 +1,63 @@ +/* echo_area.h -- Functions used in reading information from the echo area. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#ifndef _ECHO_AREA_H_ +#define _ECHO_AREA_H_ + +#define EA_MAX_INPUT 256 + +extern int echo_area_is_active, info_aborted_echo_area; + +/* Non-zero means that the last command executed while reading input + killed some text. */ +extern int echo_area_last_command_was_kill; + +extern void inform_in_echo_area (), echo_area_inform_of_deleted_window (); +extern void echo_area_prep_read (); +extern VFunction *ea_last_executed_command; + +/* Read a line of text in the echo area. Return a malloc ()'ed string, + or NULL if the user aborted out of this read. WINDOW is the currently + active window, so that we can restore it when we need to. PROMPT, if + non-null, is a prompt to print before reading the line. */ +extern char *info_read_in_echo_area (); + +/* Read a line in the echo area with completion over COMPLETIONS. + Takes arguments of WINDOW, PROMPT, and COMPLETIONS, a REFERENCE **. */ +char *info_read_completing_in_echo_area (); + +/* Read a line in the echo area allowing completion over COMPLETIONS, but + not requiring it. Takes arguments of WINDOW, PROMPT, and COMPLETIONS, + a REFERENCE **. */ +extern char *info_read_maybe_completing (); + +extern void ea_insert (), ea_quoted_insert (); +extern void ea_beg_of_line (), ea_backward (), ea_delete (), ea_end_of_line (); +extern void ea_forward (), ea_abort (), ea_rubout (), ea_complete (); +extern void ea_newline (), ea_kill_line (), ea_transpose_chars (); +extern void ea_yank (), ea_tab_insert (), ea_possible_completions (); +extern void ea_backward_word (), ea_kill_word (), ea_forward_word (); +extern void ea_yank_pop (), ea_backward_kill_word (); +extern void ea_scroll_completions_window (); + +#endif /* _ECHO_AREA_H_ */ diff --git a/gnu/usr.bin/texinfo/info/filesys.c b/gnu/usr.bin/texinfo/info/filesys.c new file mode 100644 index 0000000..8c2cf646 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/filesys.c @@ -0,0 +1,624 @@ +/* filesys.c -- File system specific functions for hacking this system. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#include <stdio.h> +#include <sys/types.h> +#include <sys/stat.h> +#include <sys/file.h> +#include <sys/errno.h> +#include "general.h" +#include "tilde.h" +#include "filesys.h" + +#if !defined (O_RDONLY) +#if defined (HAVE_SYS_FCNTL_H) +#include <sys/fcntl.h> +#else /* !HAVE_SYS_FCNTL_H */ +#include <fcntl.h> +#endif /* !HAVE_SYS_FCNTL_H */ +#endif /* !O_RDONLY */ + +#if !defined (errno) +extern int errno; +#endif /* !errno */ + +/* Found in info-utils.c. */ +extern char *filename_non_directory (); + +#if !defined (BUILDING_LIBRARY) +/* Found in session.c */ +extern int info_windows_initialized_p; + +/* Found in window.c. */ +extern void message_in_echo_area (), unmessage_in_echo_area (); +#endif /* !BUILDING_LIBRARY */ + +/* Local to this file. */ +static char *info_file_in_path (), *lookup_info_filename (); +static void remember_info_filename (), maybe_initialize_infopath (); + +#if !defined (NULL) +# define NULL 0x0 +#endif /* !NULL */ + +typedef struct { + char *suffix; + char *decompressor; +} COMPRESSION_ALIST; + +static char *info_suffixes[] = { + "", + ".info", + "-info", + (char *)NULL +}; + +static COMPRESSION_ALIST compress_suffixes[] = { + { ".Z", "uncompress" }, + { ".Y", "unyabba" }, + { ".z", "gunzip" }, + { (char *)NULL, (char *)NULL } +}; + +/* The path on which we look for info files. You can initialize this + from the environment variable INFOPATH if there is one, or you can + call info_add_path () to add paths to the beginning or end of it. + You can call zap_infopath () to make the path go away. */ +char *infopath = (char *)NULL; +static int infopath_size = 0; + +/* Expand the filename in PARTIAL to make a real name for this operating + system. This looks in INFO_PATHS in order to find the correct file. + If it can't find the file, it returns NULL. */ +static char *local_temp_filename = (char *)NULL; +static int local_temp_filename_size = 0; + +char * +info_find_fullpath (partial) + char *partial; +{ + int initial_character; + char *temp; + + filesys_error_number = 0; + + maybe_initialize_infopath (); + + if (partial && (initial_character = *partial)) + { + char *expansion; + + expansion = lookup_info_filename (partial); + + if (expansion) + return (expansion); + + /* If we have the full path to this file, we still may have to add + various extensions to it. I guess we have to stat this file + after all. */ + if (initial_character == '/') + temp = info_file_in_path (partial + 1, "/"); + else if (initial_character == '~') + { + expansion = tilde_expand_word (partial); + if (*expansion == '/') + { + temp = info_file_in_path (expansion + 1, "/"); + free (expansion); + } + else + temp = expansion; + } + else if (initial_character == '.' && + (partial[1] == '/' || (partial[1] == '.' && partial[2] == '/'))) + { + if (local_temp_filename_size < 1024) + local_temp_filename = (char *)xrealloc + (local_temp_filename, (local_temp_filename_size = 1024)); +#if defined (HAVE_GETCWD) + if (!getcwd (local_temp_filename, local_temp_filename_size)) +#else /* !HAVE_GETCWD */ + if (!getwd (local_temp_filename)) +#endif /* !HAVE_GETCWD */ + { + filesys_error_number = errno; + return (partial); + } + + strcat (local_temp_filename, "/"); + strcat (local_temp_filename, partial); + return (local_temp_filename); + } + else + temp = info_file_in_path (partial, infopath); + + if (temp) + { + remember_info_filename (partial, temp); + if (strlen (temp) > local_temp_filename_size) + local_temp_filename = (char *) xrealloc + (local_temp_filename, + (local_temp_filename_size = (50 + strlen (temp)))); + strcpy (local_temp_filename, temp); + free (temp); + return (local_temp_filename); + } + } + return (partial); +} + +/* Scan the list of directories in PATH looking for FILENAME. If we find + one that is a regular file, return it as a new string. Otherwise, return + a NULL pointer. */ +static char * +info_file_in_path (filename, path) + char *filename, *path; +{ + struct stat finfo; + char *temp_dirname; + int statable, dirname_index; + + dirname_index = 0; + + while (temp_dirname = extract_colon_unit (path, &dirname_index)) + { + register int i, pre_suffix_length; + char *temp; + + /* Expand a leading tilde if one is present. */ + if (*temp_dirname == '~') + { + char *expanded_dirname; + + expanded_dirname = tilde_expand_word (temp_dirname); + free (temp_dirname); + temp_dirname = expanded_dirname; + } + + temp = (char *)xmalloc (30 + strlen (temp_dirname) + strlen (filename)); + strcpy (temp, temp_dirname); + if (temp[(strlen (temp)) - 1] != '/') + strcat (temp, "/"); + strcat (temp, filename); + + pre_suffix_length = strlen (temp); + + free (temp_dirname); + + for (i = 0; info_suffixes[i]; i++) + { + strcpy (temp + pre_suffix_length, info_suffixes[i]); + + statable = (stat (temp, &finfo) == 0); + + /* If we have found a regular file, then use that. Else, if we + have found a directory, look in that directory for this file. */ + if (statable) + { + if (S_ISREG (finfo.st_mode)) + { + return (temp); + } + else if (S_ISDIR (finfo.st_mode)) + { + char *newpath, *filename_only, *newtemp; + + newpath = savestring (temp); + filename_only = filename_non_directory (filename); + newtemp = info_file_in_path (filename_only, newpath); + + free (newpath); + if (newtemp) + { + free (temp); + return (newtemp); + } + } + } + else + { + /* Add various compression suffixes to the name to see if + the file is present in compressed format. */ + register int j, pre_compress_suffix_length; + + pre_compress_suffix_length = strlen (temp); + + for (j = 0; compress_suffixes[j].suffix; j++) + { + strcpy (temp + pre_compress_suffix_length, + compress_suffixes[j].suffix); + + statable = (stat (temp, &finfo) == 0); + if (statable && (S_ISREG (finfo.st_mode))) + return (temp); + } + } + } + free (temp); + } + return ((char *)NULL); +} + +/* Given a string containing units of information separated by colons, + return the next one pointed to by IDX, or NULL if there are no more. + Advance IDX to the character after the colon. */ +char * +extract_colon_unit (string, idx) + char *string; + int *idx; +{ + register int i, start; + + i = start = *idx; + if ((i >= strlen (string)) || !string) + return ((char *) NULL); + + while (string[i] && string[i] != ':') + i++; + if (i == start) + { + return ((char *) NULL); + } + else + { + char *value = (char *) xmalloc (1 + (i - start)); + strncpy (value, &string[start], (i - start)); + value[i - start] = '\0'; + if (string[i]) + ++i; + *idx = i; + return (value); + } +} + +/* A structure which associates a filename with its expansion. */ +typedef struct { + char *filename; + char *expansion; +} FILENAME_LIST; + +/* An array of remembered arguments and results. */ +static FILENAME_LIST **names_and_files = (FILENAME_LIST **)NULL; +static int names_and_files_index = 0; +static int names_and_files_slots = 0; + +/* Find the result for having already called info_find_fullpath () with + FILENAME. */ +static char * +lookup_info_filename (filename) + char *filename; +{ + if (filename && names_and_files) + { + register int i; + for (i = 0; names_and_files[i]; i++) + { + if (strcmp (names_and_files[i]->filename, filename) == 0) + return (names_and_files[i]->expansion); + } + } + return (char *)NULL;; +} + +/* Add a filename and its expansion to our list. */ +static void +remember_info_filename (filename, expansion) + char *filename, *expansion; +{ + FILENAME_LIST *new; + + if (names_and_files_index + 2 > names_and_files_slots) + { + int alloc_size; + names_and_files_slots += 10; + + alloc_size = names_and_files_slots * sizeof (FILENAME_LIST *); + + names_and_files = + (FILENAME_LIST **) xrealloc (names_and_files, alloc_size); + } + + new = (FILENAME_LIST *)xmalloc (sizeof (FILENAME_LIST)); + new->filename = savestring (filename); + new->expansion = expansion ? savestring (expansion) : (char *)NULL; + + names_and_files[names_and_files_index++] = new; + names_and_files[names_and_files_index] = (FILENAME_LIST *)NULL; +} + +static void +maybe_initialize_infopath () +{ + if (!infopath_size) + { + infopath = (char *) + xmalloc (infopath_size = (1 + strlen (DEFAULT_INFOPATH))); + + strcpy (infopath, DEFAULT_INFOPATH); + } +} + +/* Add PATH to the list of paths found in INFOPATH. 2nd argument says + whether to put PATH at the front or end of INFOPATH. */ +void +info_add_path (path, where) + char *path; + int where; +{ + int len; + + if (!infopath) + { + infopath = (char *)xmalloc (infopath_size = 200 + strlen (path)); + infopath[0] = '\0'; + } + + len = strlen (path) + strlen (infopath); + + if (len + 2 >= infopath_size) + infopath = (char *)xrealloc (infopath, (infopath_size += (2 * len) + 2)); + + if (!*infopath) + strcpy (infopath, path); + else if (where == INFOPATH_APPEND) + { + strcat (infopath, ":"); + strcat (infopath, path); + } + else if (where == INFOPATH_PREPEND) + { + char *temp = savestring (infopath); + strcpy (infopath, path); + strcat (infopath, ":"); + strcat (infopath, temp); + free (temp); + } +} + +/* Make INFOPATH have absolutely nothing in it. */ +void +zap_infopath () +{ + if (infopath) + free (infopath); + + infopath = (char *)NULL; + infopath_size = 0; +} + +/* Read the contents of PATHNAME, returning a buffer with the contents of + that file in it, and returning the size of that buffer in FILESIZE. + FINFO is a stat struct which has already been filled in by the caller. + If the file cannot be read, return a NULL pointer. */ +char * +filesys_read_info_file (pathname, filesize, finfo) + char *pathname; + long *filesize; + struct stat *finfo; +{ + *filesize = filesys_error_number = 0; + + if (compressed_filename_p (pathname)) + return (filesys_read_compressed (pathname, filesize, finfo)); + else + { + int descriptor; + char *contents; + + descriptor = open (pathname, O_RDONLY, 0666); + + /* If the file couldn't be opened, give up. */ + if (descriptor < 0) + { + filesys_error_number = errno; + return ((char *)NULL); + } + + /* Try to read the contents of this file. */ + contents = (char *)xmalloc (1 + finfo->st_size); + if ((read (descriptor, contents, finfo->st_size)) != finfo->st_size) + { + filesys_error_number = errno; + close (descriptor); + free (contents); + return ((char *)NULL); + } + + close (descriptor); + + *filesize = finfo->st_size; + return (contents); + } +} + +/* Typically, pipe buffers are 4k. */ +#define BASIC_PIPE_BUFFER (4 * 1024) + +/* We use some large multiple of that. */ +#define FILESYS_PIPE_BUFFER_SIZE (16 * BASIC_PIPE_BUFFER) + +char * +filesys_read_compressed (pathname, filesize, finfo) + char *pathname; + long *filesize; + struct stat *finfo; +{ + FILE *stream; + char *command, *decompressor; + char *contents = (char *)NULL; + + *filesize = filesys_error_number = 0; + + decompressor = filesys_decompressor_for_file (pathname); + + if (!decompressor) + return ((char *)NULL); + + command = (char *)xmalloc (10 + strlen (pathname) + strlen (decompressor)); + sprintf (command, "%s < %s", decompressor, pathname); + +#if !defined (BUILDING_LIBRARY) + if (info_windows_initialized_p) + { + char *temp; + + temp = (char *)xmalloc (5 + strlen (command)); + sprintf (temp, "%s...", command); + message_in_echo_area ("%s", temp); + free (temp); + } +#endif /* !BUILDING_LIBRARY */ + + stream = popen (command, "r"); + free (command); + + /* Read chunks from this file until there are none left to read. */ + if (stream) + { + int offset, size; + char *chunk; + + offset = size = 0; + chunk = (char *)xmalloc (FILESYS_PIPE_BUFFER_SIZE); + + while (1) + { + int bytes_read; + + bytes_read = fread (chunk, 1, FILESYS_PIPE_BUFFER_SIZE, stream); + + if (bytes_read + offset >= size) + contents = (char *)xrealloc + (contents, size += (2 * FILESYS_PIPE_BUFFER_SIZE)); + + memcpy (contents + offset, chunk, bytes_read); + offset += bytes_read; + if (bytes_read != FILESYS_PIPE_BUFFER_SIZE) + break; + } + + free (chunk); + pclose (stream); + contents = (char *)xrealloc (contents, offset + 1); + *filesize = offset; + } + else + { + filesys_error_number = errno; + } + +#if !defined (BUILDING_LIBARARY) + if (info_windows_initialized_p) + unmessage_in_echo_area (); +#endif /* !BUILDING_LIBRARY */ + return (contents); +} + +/* Return non-zero if FILENAME belongs to a compressed file. */ +int +compressed_filename_p (filename) + char *filename; +{ + char *decompressor; + + /* Find the final extension of this filename, and see if it matches one + of our known ones. */ + decompressor = filesys_decompressor_for_file (filename); + + if (decompressor) + return (1); + else + return (0); +} + +/* Return the command string that would be used to decompress FILENAME. */ +char * +filesys_decompressor_for_file (filename) + char *filename; +{ + register int i; + char *extension = (char *)NULL; + + /* Find the final extension of FILENAME, and see if it appears in our + list of known compression extensions. */ + for (i = strlen (filename) - 1; i > 0; i--) + if (filename[i] == '.') + { + extension = filename + i; + break; + } + + if (!extension) + return ((char *)NULL); + + for (i = 0; compress_suffixes[i].suffix; i++) + if (strcmp (extension, compress_suffixes[i].suffix) == 0) + return (compress_suffixes[i].decompressor); + + return ((char *)NULL); +} + +/* The number of the most recent file system error. */ +int filesys_error_number = 0; + +#if !defined (HAVE_STRERROR) +extern const char * const sys_errlist[]; +extern int sys_nerr; + +char * +strerror (num) + int num; +{ + if (num >= sys_nerr) + return (""); + else + return (sys_errlist[num]); +} +#endif /* !HAVE_STRERROR */ + +/* A function which returns a pointer to a static buffer containing + an error message for FILENAME and ERROR_NUM. */ +static char *errmsg_buf = (char *)NULL; +static int errmsg_buf_size = 0; + +char * +filesys_error_string (filename, error_num) + char *filename; + int error_num; +{ + int len; + char *result; + + if (error_num == 0) + return ((char *)NULL); + + result = strerror (error_num); + + len = 4 + strlen (filename) + strlen (result); + if (len >= errmsg_buf_size) + errmsg_buf = (char *)xrealloc (errmsg_buf, (errmsg_buf_size = 2 + len)); + + sprintf (errmsg_buf, "%s: %s", filename, result); + return (errmsg_buf); +} + diff --git a/gnu/usr.bin/texinfo/info/filesys.h b/gnu/usr.bin/texinfo/info/filesys.h new file mode 100644 index 0000000..9ee4a71 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/filesys.h @@ -0,0 +1,84 @@ +/* filesys.h -- External declarations of functions and vars in filesys.c. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#ifndef _FILESYS_H_ +#define _FILESYS_H_ + +/* The path on which we look for info files. You can initialize this + from the environment variable INFOPATH if there is one, or you can + call info_add_path () to add paths to the beginning or end of it. */ +extern char *infopath; + +/* Make INFOPATH have absolutely nothing in it. */ +extern void zap_infopath (); + +/* Add PATH to the list of paths found in INFOPATH. 2nd argument says + whether to put PATH at the front or end of INFOPATH. */ +extern void info_add_path (); + +/* Defines that are passed along with the pathname to info_add_path (). */ +#define INFOPATH_PREPEND 0 +#define INFOPATH_APPEND 1 + +/* Expand the filename in PARTIAL to make a real name for this operating + system. This looks in INFO_PATHS in order to find the correct file. + If it can't find the file, it returns NULL. */ +extern char *info_find_fullpath (); + +/* Read the contents of PATHNAME, returning a buffer with the contents of + that file in it, and returning the size of that buffer in FILESIZE. + FINFO is a stat struct which has already been filled in by the caller. + If the file cannot be read, return a NULL pointer. */ +extern char *filesys_read_info_file (); +extern char *filesys_read_compressed (); + +/* Return the command string that would be used to decompress FILENAME. */ +extern char *filesys_decompressor_for_file (); +extern int compressed_filename_p (); + +/* A function which returns a pointer to a static buffer containing + an error message for FILENAME and ERROR_NUM. */ +extern char *filesys_error_string (); + +/* The number of the most recent file system error. */ +extern int filesys_error_number; + +/* Given a string containing units of information separated by colons, + return the next one pointed to by IDX, or NULL if there are no more. + Advance IDX to the character after the colon. */ +extern char *extract_colon_unit (); + +/* The default value of INFOPATH. */ +#if !defined (DEFAULT_INFOPATH) +# define DEFAULT_INFOPATH "/usr/gnu/info:/local/gnu/info:/usr/gnu/lib/info:/usr/gnu/lib/emacs/info:/usr/local/gnu/info:/usr/local/gnu/lib/info:/usr/local/gnu/lib/emacs/info:/usr/local/lib/info:/usr/local/lib/emacs/info:/usr/local/emacs/info:." +#endif /* !DEFAULT_INFOPATH */ + +#if !defined (S_ISREG) && defined (S_IFREG) +# define S_ISREG(m) (((m) & S_IFMT) == S_IFREG) +#endif /* !S_ISREG && S_IFREG */ + +#if !defined (S_ISDIR) && defined (S_IFDIR) +# define S_ISDIR(m) (((m) & S_IFMT) == S_IFDIR) +#endif /* !S_ISDIR && S_IFDIR */ + +#endif /* !_FILESYS_H_ */ diff --git a/gnu/usr.bin/texinfo/info/footnotes.c b/gnu/usr.bin/texinfo/info/footnotes.c new file mode 100644 index 0000000..f6e8b6b --- /dev/null +++ b/gnu/usr.bin/texinfo/info/footnotes.c @@ -0,0 +1,264 @@ +/* footnotes.c -- Some functions for manipulating footnotes. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#include "info.h" + +/* Non-zero means attempt to show footnotes when displaying a new window. */ +int auto_footnotes_p = 1; + +static char *footnote_nodename = "*Footnotes*"; + +#define FOOTNOTE_HEADER_FORMAT \ + "*** Footnotes appearing in the node \"%s\" ***\n" + +/* Find the window currently showing footnotes. */ +static WINDOW * +find_footnotes_window () +{ + WINDOW *win; + + /* Try to find an existing window first. */ + for (win = windows; win; win = win->next) + if (internal_info_node_p (win->node) && + (strcmp (win->node->nodename, footnote_nodename) == 0)) + break; + + return (win); +} + +/* Manufacture a node containing the footnotes of this node, and + return the manufactured node. If NODE has no footnotes, return a + NULL pointer. */ +NODE * +make_footnotes_node (node) + NODE *node; +{ + NODE *fn_node, *result = (NODE *)NULL; + long fn_start; + + /* Make the initial assumption that the footnotes appear as simple + text within this windows node. */ + fn_node = node; + + /* See if this node contains the magic footnote label. */ + fn_start = + info_search_in_node (FOOTNOTE_LABEL, node, 0, (WINDOW *)NULL, 1); + + /* If it doesn't, check to see if it has an associated footnotes node. */ + if (fn_start == -1) + { + REFERENCE **refs; + + refs = info_xrefs_of_node (node); + + if (refs) + { + register int i; + char *refname; + + refname = (char *)xmalloc + (1 + strlen ("-Footnotes") + strlen (node->nodename)); + + strcpy (refname, node->nodename); + strcat (refname, "-Footnotes"); + + for (i = 0; refs[i]; i++) + if (strcmp (refs[i]->nodename, refname) == 0) + { + char *filename; + + filename = node->parent; + if (!filename) + filename = node->filename; + + fn_node = info_get_node (filename, refname); + + if (fn_node) + fn_start = 0; + + break; + } + + free (refname); + info_free_references (refs); + } + } + + /* If we never found the start of a footnotes area, quit now. */ + if (fn_start == -1) + return ((NODE *)NULL); + + /* Make the new node. */ + result = (NODE *)xmalloc (sizeof (NODE)); + result->flags = 0; + + /* Get the size of the footnotes appearing within this node. */ + { + char *header; + long text_start = fn_start; + + header = (char *)xmalloc + (1 + strlen (node->nodename) + strlen (FOOTNOTE_HEADER_FORMAT)); + sprintf (header, FOOTNOTE_HEADER_FORMAT, node->nodename); + + /* Move the start of the displayed text to right after the first line. + This effectively skips either "---- footno...", or "File: foo...". */ + while (text_start < fn_node->nodelen) + if (fn_node->contents[text_start++] == '\n') + break; + + result->nodelen = strlen (header) + fn_node->nodelen - text_start; + + /* Set the contents of this node. */ + result->contents = (char *)xmalloc (1 + result->nodelen); + sprintf (result->contents, "%s", header); + memcpy (result->contents + strlen (header), + fn_node->contents + text_start, fn_node->nodelen - text_start); + + name_internal_node (result, footnote_nodename); + free (header); + } + +#if defined (NOTDEF) + /* If the footnotes were gleaned from the node that we were called with, + shorten the calling node's display length. */ + if (fn_node == node) + narrow_node (node, 0, fn_start); +#endif /* NOTDEF */ + + return (result); +} + +/* Create or delete the footnotes window depending on whether footnotes + exist in WINDOW's node or not. Returns FN_FOUND if footnotes were found + and displayed. Returns FN_UNFOUND if there were no footnotes found + in WINDOW's node. Returns FN_UNABLE if there were footnotes, but the + window to show them couldn't be made. */ +int +info_get_or_remove_footnotes (window) + WINDOW *window; +{ + WINDOW *fn_win; + NODE *new_footnotes; + + fn_win = find_footnotes_window (); + + /* If we are in the footnotes window, change nothing. */ + if (fn_win == window) + return (FN_FOUND); + + /* Try to find footnotes for this window's node. */ + new_footnotes = make_footnotes_node (window->node); + + /* If there was a window showing footnotes, and there are no footnotes + for the current window, delete the old footnote window. */ + if (fn_win && !new_footnotes) + { + if (windows->next) + info_delete_window_internal (fn_win); + } + + /* If there are footnotes for this window's node, but no window around + showing footnotes, try to make a new window. */ + if (new_footnotes && !fn_win) + { + WINDOW *old_active; + WINDOW *last, *win; + + /* Always make this window be the last one appearing in the list. Find + the last window in the chain. */ + for (win = windows, last = windows; win; last = win, win = win->next); + + /* Try to split this window, and make the split window the one to + contain the footnotes. */ + old_active = active_window; + active_window = last; + fn_win = window_make_window (new_footnotes); + active_window = old_active; + + if (!fn_win) + { + free (new_footnotes->contents); + free (new_footnotes); + + /* If we are hacking automatic footnotes, and there are footnotes + but we couldn't display them, print a message to that effect. */ + if (auto_footnotes_p) + inform_in_echo_area ("Footnotes could not be displayed"); + return (FN_UNABLE); + } + } + + /* If there are footnotes, and there is a window to display them, + make that window be the number of lines appearing in the footnotes. */ + if (new_footnotes && fn_win) + { + window_set_node_of_window (fn_win, new_footnotes); + + window_change_window_height + (fn_win, fn_win->line_count - fn_win->height); + + remember_window_and_node (fn_win, new_footnotes); + add_gcable_pointer (new_footnotes->contents); + } + + if (!new_footnotes) + return (FN_UNFOUND); + else + return (FN_FOUND); +} + +/* Show the footnotes associated with this node in another window. */ +DECLARE_INFO_COMMAND (info_show_footnotes, + "Show the footnotes associated with this node in another window") +{ + int result; + + /* A negative argument means just make the window go away. */ + if (count < 0) + { + WINDOW *fn_win = find_footnotes_window (); + + /* If there is an old footnotes window, and it isn't the only window + on the screen, delete it. */ + if (fn_win && windows->next) + info_delete_window_internal (fn_win); + } + else + { + int result; + + result = info_get_or_remove_footnotes (window); + + switch (result) + { + case FN_UNFOUND: + info_error (NO_FOOT_NODE); + break; + + case FN_UNABLE: + info_error (WIN_TOO_SMALL); + break; + } + } +} diff --git a/gnu/usr.bin/texinfo/info/footnotes.h b/gnu/usr.bin/texinfo/info/footnotes.h new file mode 100644 index 0000000..71c9d93 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/footnotes.h @@ -0,0 +1,46 @@ +/* footnotes.h -- Some functions for manipulating footnotes. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#ifndef _FOOTNOTES_H_ +#define _FOOTNOTES_H_ + +/* Magic string which indicates following text is footnotes. */ +#define FOOTNOTE_LABEL "---------- Footnotes ----------" + +#define FN_FOUND 0 +#define FN_UNFOUND 1 +#define FN_UNABLE 2 + + +/* Create or delete the footnotes window depending on whether footnotes + exist in WINDOW's node or not. Returns FN_FOUND if footnotes were found + and displayed. Returns FN_UNFOUND if there were no footnotes found + in WINDOW's node. Returns FN_UNABLE if there were footnotes, but the + window to show them couldn't be made. */ +extern int info_get_or_remove_footnotes (); + +/* Non-zero means attempt to show footnotes when displaying a new window. */ +extern int auto_footnotes_p; + +#endif /* !_FOOTNOTES_H_ */ + diff --git a/gnu/usr.bin/texinfo/info/funs.h b/gnu/usr.bin/texinfo/info/funs.h new file mode 100644 index 0000000..1474f0d --- /dev/null +++ b/gnu/usr.bin/texinfo/info/funs.h @@ -0,0 +1,110 @@ +/* funs.h -- Generated declarations for Info commands. */ + +/* Functions declared in "./session.c". */ +extern void info_next_line (); +extern void info_prev_line (); +extern void info_end_of_line (); +extern void info_beginning_of_line (); +extern void info_forward_char (); +extern void info_backward_char (); +extern void info_forward_word (); +extern void info_backward_word (); +extern void info_global_next_node (); +extern void info_global_prev_node (); +extern void info_scroll_forward (); +extern void info_scroll_backward (); +extern void info_beginning_of_node (); +extern void info_end_of_node (); +extern void info_next_window (); +extern void info_prev_window (); +extern void info_split_window (); +extern void info_delete_window (); +extern void info_keep_one_window (); +extern void info_scroll_other_window (); +extern void info_grow_window (); +extern void info_tile_windows (); +extern void info_toggle_wrap (); +extern void info_next_node (); +extern void info_prev_node (); +extern void info_up_node (); +extern void info_last_node (); +extern void info_first_node (); +extern void info_history_node (); +extern void info_last_menu_item (); +extern void info_menu_digit (); +extern void info_menu_item (); +extern void info_xref_item (); +extern void info_find_menu (); +extern void info_visit_menu (); +extern void info_goto_node (); +extern void info_top_node (); +extern void info_dir_node (); +extern void info_kill_node (); +extern void info_view_file (); +extern void info_print_node (); +extern void info_search (); +extern void isearch_forward (); +extern void isearch_backward (); +extern void info_move_to_prev_xref (); +extern void info_move_to_next_xref (); +extern void info_select_reference_this_line (); +extern void info_abort_key (); +extern void info_move_to_window_line (); +extern void info_redraw_display (); +extern void info_quit (); +extern void info_do_lowercase_version (); +extern void info_add_digit_to_numeric_arg (); +extern void info_universal_argument (); +extern void info_numeric_arg_digit_loop (); + +/* Functions declared in "./echo_area.c". */ +extern void ea_forward (); +extern void ea_backward (); +extern void ea_beg_of_line (); +extern void ea_end_of_line (); +extern void ea_forward_word (); +extern void ea_backward_word (); +extern void ea_delete (); +extern void ea_rubout (); +extern void ea_abort (); +extern void ea_newline (); +extern void ea_quoted_insert (); +extern void ea_insert (); +extern void ea_tab_insert (); +extern void ea_transpose_chars (); +extern void ea_yank (); +extern void ea_yank_pop (); +extern void ea_kill_line (); +extern void ea_backward_kill_line (); +extern void ea_kill_word (); +extern void ea_backward_kill_word (); +extern void ea_possible_completions (); +extern void ea_complete (); +extern void ea_scroll_completions_window (); + +/* Functions declared in "./infodoc.c". */ +extern void info_get_help_window (); +extern void info_get_info_help_node (); +extern void describe_key (); +extern void info_where_is (); + +/* Functions declared in "./m-x.c". */ +extern void describe_command (); +extern void info_execute_command (); +extern void set_screen_height (); + +/* Functions declared in "./indices.c". */ +extern void info_index_search (); +extern void info_next_index_match (); +extern void info_index_apropos (); + +/* Functions declared in "./nodemenu.c". */ +extern void list_visited_nodes (); +extern void select_visited_node (); + +/* Functions declared in "./footnotes.c". */ +extern void info_show_footnotes (); + +/* Functions declared in "./variables.c". */ +extern void describe_variable (); +extern void set_variable (); diff --git a/gnu/usr.bin/texinfo/info/gc.c b/gnu/usr.bin/texinfo/info/gc.c new file mode 100644 index 0000000..6a50e81 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/gc.c @@ -0,0 +1,95 @@ +/* gc.c -- Functions to remember and garbage collect unused node contents. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#include "info.h" + +/* Array of pointers to the contents of gc-able nodes. A pointer on this + list can be garbage collected when no info window contains a node whose + contents member match the pointer. */ +static char **gcable_pointers = (char **)NULL; +static int gcable_pointers_index = 0; +static int gcable_pointers_slots = 0; + +/* Add POINTER to the list of garbage collectible pointers. A pointer + is not actually garbage collected until no info window contains a node + whose contents member is equal to the pointer. */ +void +add_gcable_pointer (pointer) + char *pointer; +{ + gc_pointers (); + add_pointer_to_array (pointer, gcable_pointers_index, gcable_pointers, + gcable_pointers_slots, 10, char *); +} + +/* Grovel the list of info windows and gc-able pointers finding those + node->contents which are collectible, and free them. */ +void +gc_pointers () +{ + register int i, j, k; + INFO_WINDOW *iw; + char **new = (char **)NULL; + int new_index = 0; + int new_slots = 0; + + if (!info_windows || !gcable_pointers_index) + return; + + for (i = 0; iw = info_windows[i]; i++) + { + for (j = 0; j < iw->nodes_index; j++) + { + NODE *node = iw->nodes[j]; + + /* If this node->contents appears in our list of gcable_pointers, + it is not gc-able, so save it. */ + for (k = 0; k < gcable_pointers_index; k++) + if (gcable_pointers[k] == node->contents) + { + add_pointer_to_array + (node->contents, new_index, new, new_slots, 10, char *); + break; + } + } + } + + /* We have gathered all of the pointers which need to be saved. Free any + of the original pointers which do not appear in the new list. */ + for (i = 0; i < gcable_pointers_index; i++) + { + for (j = 0; j < new_index; j++) + if (gcable_pointers[i] == new[j]) + break; + + /* If we got all the way through the new list, then the old pointer + can be garbage collected. */ + if (new && !new[j]) + free (gcable_pointers[i]); + } + + free (gcable_pointers); + gcable_pointers = new; + gcable_pointers_slots = new_slots; + gcable_pointers_index = new_index; +} diff --git a/gnu/usr.bin/texinfo/info/gc.h b/gnu/usr.bin/texinfo/info/gc.h new file mode 100644 index 0000000..a521ae6 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/gc.h @@ -0,0 +1,36 @@ +/* gc.h -- Functions for garbage collecting unused node contents. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#ifndef _GC_H_ +#define _GC_H_ + +/* Add POINTER to the list of garbage collectible pointers. A pointer + is not actually garbage collected until no info window contains a node + whose contents member is equal to the pointer. */ +extern void add_gcable_pointer (); + +/* Grovel the list of info windows and gc-able pointers finding those + node->contents which are collectible, and free them. */ +extern void gc_pointers (); + +#endif /* !_GC_H_ */ diff --git a/gnu/usr.bin/texinfo/info/general.h b/gnu/usr.bin/texinfo/info/general.h new file mode 100644 index 0000000..605a75a --- /dev/null +++ b/gnu/usr.bin/texinfo/info/general.h @@ -0,0 +1,81 @@ +/* general.h -- Some generally useful defines. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#if !defined (_GENERAL_H_) +#define _GENERAL_H_ + +extern void *xmalloc (), *xrealloc (); + +#if defined (HAVE_UNISTD_H) +# include <unistd.h> +#endif /* HAVE_UNISTD_H */ + +#if defined (HAVE_STRING_H) +# include <string.h> +#else +# include <strings.h> +#endif /* !HAVE_STRING_H */ + +#if !defined (savestring) +# define savestring(x) (char *)strcpy ((char *)xmalloc (1 + strlen (x)), x) +#endif /* !savestring */ + +#define info_toupper(x) (islower (x) ? toupper (x) : x) +#define info_tolower(x) (isupper (x) ? tolower (x) : x) + +#if !defined (whitespace) +# define whitespace(c) ((c == ' ') || (c == '\t')) +#endif /* !whitespace */ + +#if !defined (whitespace_or_newline) +# define whitespace_or_newline(c) (whitespace (c) || (c == '\n')) +#endif /* !whitespace_or_newline */ + +#if !defined (__FUNCTION_DEF) +# define __FUNCTION_DEF +typedef int Function (); +typedef void VFunction (); +#endif /* _FUNCTION_DEF */ + +/* Add POINTER to the list of pointers found in ARRAY. SLOTS is the number + of slots that have already been allocated. INDEX is the index into the + array where POINTER should be added. GROW is the number of slots to grow + ARRAY by, in the case that it needs growing. TYPE is a cast of the type + of object stored in ARRAY (e.g., NODE_ENTRY *. */ +#define add_pointer_to_array(pointer, idx, array, slots, grow, type) \ + do { \ + if (idx + 2 >= slots) \ + array = (type *)(xrealloc (array, (slots += grow) * sizeof (type))); \ + array[idx++] = (type)pointer; \ + array[idx] = (type)NULL; \ + } while (0) + +#define maybe_free(x) do { if (x) free (x); } while (0) + +#if !defined (HAVE_BZERO) +# define zero_mem(mem, length) memset (mem, 0, length) +#else +# define zero_mem(mem, length) bzero (mem, length) +#endif /* !BZERO_MISSING */ + +#endif /* !_GENERAL_H_ */ diff --git a/gnu/usr.bin/texinfo/info/getopt.c b/gnu/usr.bin/texinfo/info/getopt.c new file mode 100644 index 0000000..a59a013 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/getopt.c @@ -0,0 +1,731 @@ +/* Getopt for GNU. + NOTE: getopt is now part of the C library, so if you don't know what + "Keep this file name-space clean" means, talk to roland@gnu.ai.mit.edu + before changing it! + + Copyright (C) 1987, 88, 89, 90, 91, 92, 1993 + 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, 675 Mass Ave, Cambridge, MA 02139, USA. */ + +/* NOTE!!! AIX requires this to be the first thing in the file. + Do not put ANYTHING before it! */ +#if !defined (__GNUC__) && defined (_AIX) + #pragma alloca +#endif + +#ifdef HAVE_CONFIG_H +#include "config.h" +#endif + +#ifdef __GNUC__ +#define alloca __builtin_alloca +#else /* not __GNUC__ */ +#if defined (HAVE_ALLOCA_H) || (defined(sparc) && (defined(sun) || (!defined(USG) && !defined(SVR4) && !defined(__svr4__)))) +#include <alloca.h> +#else +#ifndef _AIX +char *alloca (); +#endif +#endif /* alloca.h */ +#endif /* not __GNUC__ */ + +#if !__STDC__ && !defined(const) && IN_GCC +#define const +#endif + +/* This tells Alpha OSF/1 not to define a getopt prototype in <stdio.h>. */ +#ifndef _NO_PROTO +#define _NO_PROTO +#endif + +#include <stdio.h> + +/* Comment out all this code if we are using the GNU C Library, and are not + actually compiling the library itself. This code is part of the GNU C + Library, but also included in many other GNU distributions. Compiling + and linking in this code is a waste when using the GNU C library + (especially if it is a shared library). Rather than having every GNU + program understand `configure --with-gnu-libc' and omit the object files, + it is simpler to just do this in the source for each such file. */ + +#if defined (_LIBC) || !defined (__GNU_LIBRARY__) + + +/* This needs to come after some library #include + to get __GNU_LIBRARY__ defined. */ +#ifdef __GNU_LIBRARY__ +#undef alloca +/* Don't include stdlib.h for non-GNU C libraries because some of them + contain conflicting prototypes for getopt. */ +#include <stdlib.h> +#else /* Not GNU C library. */ +#define __alloca alloca +#endif /* GNU C library. */ + +/* If GETOPT_COMPAT is defined, `+' as well as `--' can introduce a + long-named option. Because this is not POSIX.2 compliant, it is + being phased out. */ +/* #define GETOPT_COMPAT */ + +/* This version of `getopt' appears to the caller like standard Unix `getopt' + but it behaves differently for the user, since it allows the user + to intersperse the options with the other arguments. + + As `getopt' works, it permutes the elements of ARGV so that, + when it is done, all the options precede everything else. Thus + all application programs are extended to handle flexible argument order. + + Setting the environment variable POSIXLY_CORRECT disables permutation. + Then the behavior is completely standard. + + GNU application programs can use a third alternative mode in which + they can distinguish the relative order of options and other arguments. */ + +#include "getopt.h" + +/* For communication from `getopt' to the caller. + When `getopt' finds an option that takes an argument, + the argument value is returned here. + Also, when `ordering' is RETURN_IN_ORDER, + each non-option ARGV-element is returned here. */ + +char *optarg = 0; + +/* Index in ARGV of the next element to be scanned. + This is used for communication to and from the caller + and for communication between successive calls to `getopt'. + + On entry to `getopt', zero means this is the first call; initialize. + + When `getopt' returns EOF, this is the index of the first of the + non-option elements that the caller should itself scan. + + Otherwise, `optind' communicates from one call to the next + how much of ARGV has been scanned so far. */ + +/* XXX 1003.2 says this must be 1 before any call. */ +int optind = 0; + +/* The next char to be scanned in the option-element + in which the last option character we returned was found. + This allows us to pick up the scan where we left off. + + If this is zero, or a null string, it means resume the scan + by advancing to the next ARGV-element. */ + +static char *nextchar; + +/* Callers store zero here to inhibit the error message + for unrecognized options. */ + +int opterr = 1; + +/* Set to an option character which was unrecognized. + This must be initialized on some systems to avoid linking in the + system's own getopt implementation. */ + +int optopt = '?'; + +/* Describe how to deal with options that follow non-option ARGV-elements. + + If the caller did not specify anything, + the default is REQUIRE_ORDER if the environment variable + POSIXLY_CORRECT is defined, PERMUTE otherwise. + + REQUIRE_ORDER means don't recognize them as options; + stop option processing when the first non-option is seen. + This is what Unix does. + This mode of operation is selected by either setting the environment + variable POSIXLY_CORRECT, or using `+' as the first character + of the list of option characters. + + PERMUTE is the default. We permute the contents of ARGV as we scan, + so that eventually all the non-options are at the end. This allows options + to be given in any order, even with programs that were not written to + expect this. + + RETURN_IN_ORDER is an option available to programs that were written + to expect options and other ARGV-elements in any order and that care about + the ordering of the two. We describe each non-option ARGV-element + as if it were the argument of an option with character code 1. + Using `-' as the first character of the list of option characters + selects this mode of operation. + + The special argument `--' forces an end of option-scanning regardless + of the value of `ordering'. In the case of RETURN_IN_ORDER, only + `--' can cause `getopt' to return EOF with `optind' != ARGC. */ + +static enum +{ + REQUIRE_ORDER, PERMUTE, RETURN_IN_ORDER +} ordering; + +#ifdef __GNU_LIBRARY__ +/* We want to avoid inclusion of string.h with non-GNU libraries + because there are many ways it can cause trouble. + On some systems, it contains special magic macros that don't work + in GCC. */ +#include <string.h> +#define my_index strchr +#define my_bcopy(src, dst, n) memcpy ((dst), (src), (n)) +#else + +/* Avoid depending on library functions or files + whose names are inconsistent. */ + +char *getenv (); + +static char * +my_index (str, chr) + const char *str; + int chr; +{ + while (*str) + { + if (*str == chr) + return (char *) str; + str++; + } + return 0; +} + +static void +my_bcopy (from, to, size) + const char *from; + char *to; + int size; +{ + int i; + for (i = 0; i < size; i++) + to[i] = from[i]; +} +#endif /* GNU C library. */ + +/* Handle permutation of arguments. */ + +/* Describe the part of ARGV that contains non-options that have + been skipped. `first_nonopt' is the index in ARGV of the first of them; + `last_nonopt' is the index after the last of them. */ + +static int first_nonopt; +static int last_nonopt; + +/* Exchange two adjacent subsequences of ARGV. + One subsequence is elements [first_nonopt,last_nonopt) + which contains all the non-options that have been skipped so far. + The other is elements [last_nonopt,optind), which contains all + the options processed since those non-options were skipped. + + `first_nonopt' and `last_nonopt' are relocated so that they describe + the new indices of the non-options in ARGV after they are moved. */ + +static void +exchange (argv) + char **argv; +{ + int nonopts_size = (last_nonopt - first_nonopt) * sizeof (char *); + char **temp = (char **) __alloca (nonopts_size); + + /* Interchange the two blocks of data in ARGV. */ + + my_bcopy ((char *) &argv[first_nonopt], (char *) temp, nonopts_size); + my_bcopy ((char *) &argv[last_nonopt], (char *) &argv[first_nonopt], + (optind - last_nonopt) * sizeof (char *)); + my_bcopy ((char *) temp, + (char *) &argv[first_nonopt + optind - last_nonopt], + nonopts_size); + + /* Update records for the slots the non-options now occupy. */ + + first_nonopt += (optind - last_nonopt); + last_nonopt = optind; +} + +/* Scan elements of ARGV (whose length is ARGC) for option characters + given in OPTSTRING. + + If an element of ARGV starts with '-', and is not exactly "-" or "--", + then it is an option element. The characters of this element + (aside from the initial '-') are option characters. If `getopt' + is called repeatedly, it returns successively each of the option characters + from each of the option elements. + + If `getopt' finds another option character, it returns that character, + updating `optind' and `nextchar' so that the next call to `getopt' can + resume the scan with the following option character or ARGV-element. + + If there are no more option characters, `getopt' returns `EOF'. + Then `optind' is the index in ARGV of the first ARGV-element + that is not an option. (The ARGV-elements have been permuted + so that those that are not options now come last.) + + OPTSTRING is a string containing the legitimate option characters. + If an option character is seen that is not listed in OPTSTRING, + return '?' after printing an error message. If you set `opterr' to + zero, the error message is suppressed but we still return '?'. + + If a char in OPTSTRING is followed by a colon, that means it wants an arg, + so the following text in the same ARGV-element, or the text of the following + ARGV-element, is returned in `optarg'. Two colons mean an option that + wants an optional arg; if there is text in the current ARGV-element, + it is returned in `optarg', otherwise `optarg' is set to zero. + + If OPTSTRING starts with `-' or `+', it requests different methods of + handling the non-option ARGV-elements. + See the comments about RETURN_IN_ORDER and REQUIRE_ORDER, above. + + Long-named options begin with `--' instead of `-'. + Their names may be abbreviated as long as the abbreviation is unique + or is an exact match for some defined option. If they have an + argument, it follows the option name in the same ARGV-element, separated + from the option name by a `=', or else the in next ARGV-element. + When `getopt' finds a long-named option, it returns 0 if that option's + `flag' field is nonzero, the value of the option's `val' field + if the `flag' field is zero. + + The elements of ARGV aren't really const, because we permute them. + But we pretend they're const in the prototype to be compatible + with other systems. + + LONGOPTS is a vector of `struct option' terminated by an + element containing a name which is zero. + + LONGIND returns the index in LONGOPT of the long-named option found. + It is only valid when a long-named option has been found by the most + recent call. + + If LONG_ONLY is nonzero, '-' as well as '--' can introduce + long-named options. */ + +int +_getopt_internal (argc, argv, optstring, longopts, longind, long_only) + int argc; + char *const *argv; + const char *optstring; + const struct option *longopts; + int *longind; + int long_only; +{ + int option_index; + + optarg = 0; + + /* Initialize the internal data when the first call is made. + Start processing options with ARGV-element 1 (since ARGV-element 0 + is the program name); the sequence of previously skipped + non-option ARGV-elements is empty. */ + + if (optind == 0) + { + first_nonopt = last_nonopt = optind = 1; + + nextchar = NULL; + + /* Determine how to handle the ordering of options and nonoptions. */ + + if (optstring[0] == '-') + { + ordering = RETURN_IN_ORDER; + ++optstring; + } + else if (optstring[0] == '+') + { + ordering = REQUIRE_ORDER; + ++optstring; + } + else if (getenv ("POSIXLY_CORRECT") != NULL) + ordering = REQUIRE_ORDER; + else + ordering = PERMUTE; + } + + if (nextchar == NULL || *nextchar == '\0') + { + if (ordering == PERMUTE) + { + /* If we have just processed some options following some non-options, + exchange them so that the options come first. */ + + if (first_nonopt != last_nonopt && last_nonopt != optind) + exchange ((char **) argv); + else if (last_nonopt != optind) + first_nonopt = optind; + + /* Now skip any additional non-options + and extend the range of non-options previously skipped. */ + + while (optind < argc + && (argv[optind][0] != '-' || argv[optind][1] == '\0') +#ifdef GETOPT_COMPAT + && (longopts == NULL + || argv[optind][0] != '+' || argv[optind][1] == '\0') +#endif /* GETOPT_COMPAT */ + ) + optind++; + last_nonopt = optind; + } + + /* Special ARGV-element `--' means premature end of options. + Skip it like a null option, + then exchange with previous non-options as if it were an option, + then skip everything else like a non-option. */ + + if (optind != argc && !strcmp (argv[optind], "--")) + { + optind++; + + if (first_nonopt != last_nonopt && last_nonopt != optind) + exchange ((char **) argv); + else if (first_nonopt == last_nonopt) + first_nonopt = optind; + last_nonopt = argc; + + optind = argc; + } + + /* If we have done all the ARGV-elements, stop the scan + and back over any non-options that we skipped and permuted. */ + + if (optind == argc) + { + /* Set the next-arg-index to point at the non-options + that we previously skipped, so the caller will digest them. */ + if (first_nonopt != last_nonopt) + optind = first_nonopt; + return EOF; + } + + /* If we have come to a non-option and did not permute it, + either stop the scan or describe it to the caller and pass it by. */ + + if ((argv[optind][0] != '-' || argv[optind][1] == '\0') +#ifdef GETOPT_COMPAT + && (longopts == NULL + || argv[optind][0] != '+' || argv[optind][1] == '\0') +#endif /* GETOPT_COMPAT */ + ) + { + if (ordering == REQUIRE_ORDER) + return EOF; + optarg = argv[optind++]; + return 1; + } + + /* We have found another option-ARGV-element. + Start decoding its characters. */ + + nextchar = (argv[optind] + 1 + + (longopts != NULL && argv[optind][1] == '-')); + } + + if (longopts != NULL + && ((argv[optind][0] == '-' + && (argv[optind][1] == '-' || long_only)) +#ifdef GETOPT_COMPAT + || argv[optind][0] == '+' +#endif /* GETOPT_COMPAT */ + )) + { + const struct option *p; + char *s = nextchar; + int exact = 0; + int ambig = 0; + const struct option *pfound = NULL; + int indfound; + + while (*s && *s != '=') + s++; + + /* Test all options for either exact match or abbreviated matches. */ + for (p = longopts, option_index = 0; p->name; + p++, option_index++) + if (!strncmp (p->name, nextchar, s - nextchar)) + { + if (s - nextchar == strlen (p->name)) + { + /* Exact match found. */ + pfound = p; + indfound = option_index; + exact = 1; + break; + } + else if (pfound == NULL) + { + /* First nonexact match found. */ + pfound = p; + indfound = option_index; + } + else + /* Second nonexact match found. */ + ambig = 1; + } + + if (ambig && !exact) + { + if (opterr) + fprintf (stderr, "%s: option `%s' is ambiguous\n", + argv[0], argv[optind]); + nextchar += strlen (nextchar); + optind++; + return '?'; + } + + if (pfound != NULL) + { + option_index = indfound; + optind++; + if (*s) + { + /* Don't test has_arg with >, because some C compilers don't + allow it to be used on enums. */ + if (pfound->has_arg) + optarg = s + 1; + else + { + if (opterr) + { + if (argv[optind - 1][1] == '-') + /* --option */ + fprintf (stderr, + "%s: option `--%s' doesn't allow an argument\n", + argv[0], pfound->name); + else + /* +option or -option */ + fprintf (stderr, + "%s: option `%c%s' doesn't allow an argument\n", + argv[0], argv[optind - 1][0], pfound->name); + } + nextchar += strlen (nextchar); + return '?'; + } + } + else if (pfound->has_arg == 1) + { + if (optind < argc) + optarg = argv[optind++]; + else + { + if (opterr) + fprintf (stderr, "%s: option `%s' requires an argument\n", + argv[0], argv[optind - 1]); + nextchar += strlen (nextchar); + return optstring[0] == ':' ? ':' : '?'; + } + } + nextchar += strlen (nextchar); + if (longind != NULL) + *longind = option_index; + if (pfound->flag) + { + *(pfound->flag) = pfound->val; + return 0; + } + return pfound->val; + } + /* Can't find it as a long option. If this is not getopt_long_only, + or the option starts with '--' or is not a valid short + option, then it's an error. + Otherwise interpret it as a short option. */ + if (!long_only || argv[optind][1] == '-' +#ifdef GETOPT_COMPAT + || argv[optind][0] == '+' +#endif /* GETOPT_COMPAT */ + || my_index (optstring, *nextchar) == NULL) + { + if (opterr) + { + if (argv[optind][1] == '-') + /* --option */ + fprintf (stderr, "%s: unrecognized option `--%s'\n", + argv[0], nextchar); + else + /* +option or -option */ + fprintf (stderr, "%s: unrecognized option `%c%s'\n", + argv[0], argv[optind][0], nextchar); + } + nextchar = (char *) ""; + optind++; + return '?'; + } + } + + /* Look at and handle the next option-character. */ + + { + char c = *nextchar++; + char *temp = my_index (optstring, c); + + /* Increment `optind' when we start to process its last character. */ + if (*nextchar == '\0') + ++optind; + + if (temp == NULL || c == ':') + { + if (opterr) + { +#if 0 + if (c < 040 || c >= 0177) + fprintf (stderr, "%s: unrecognized option, character code 0%o\n", + argv[0], c); + else + fprintf (stderr, "%s: unrecognized option `-%c'\n", argv[0], c); +#else + /* 1003.2 specifies the format of this message. */ + fprintf (stderr, "%s: illegal option -- %c\n", argv[0], c); +#endif + } + optopt = c; + return '?'; + } + if (temp[1] == ':') + { + if (temp[2] == ':') + { + /* This is an option that accepts an argument optionally. */ + if (*nextchar != '\0') + { + optarg = nextchar; + optind++; + } + else + optarg = 0; + nextchar = NULL; + } + else + { + /* This is an option that requires an argument. */ + if (*nextchar != '\0') + { + optarg = nextchar; + /* If we end this ARGV-element by taking the rest as an arg, + we must advance to the next element now. */ + optind++; + } + else if (optind == argc) + { + if (opterr) + { +#if 0 + fprintf (stderr, "%s: option `-%c' requires an argument\n", + argv[0], c); +#else + /* 1003.2 specifies the format of this message. */ + fprintf (stderr, "%s: option requires an argument -- %c\n", + argv[0], c); +#endif + } + optopt = c; + if (optstring[0] == ':') + c = ':'; + else + c = '?'; + } + else + /* We already incremented `optind' once; + increment it again when taking next ARGV-elt as argument. */ + optarg = argv[optind++]; + nextchar = NULL; + } + } + return c; + } +} + +int +getopt (argc, argv, optstring) + int argc; + char *const *argv; + const char *optstring; +{ + return _getopt_internal (argc, argv, optstring, + (const struct option *) 0, + (int *) 0, + 0); +} + +#endif /* _LIBC or not __GNU_LIBRARY__. */ + +#ifdef TEST + +/* Compile with -DTEST to make an executable for use in testing + the above definition of `getopt'. */ + +int +main (argc, argv) + int argc; + char **argv; +{ + int c; + int digit_optind = 0; + + while (1) + { + int this_option_optind = optind ? optind : 1; + + c = getopt (argc, argv, "abc:d:0123456789"); + if (c == EOF) + break; + + switch (c) + { + case '0': + case '1': + case '2': + case '3': + case '4': + case '5': + case '6': + case '7': + case '8': + case '9': + if (digit_optind != 0 && digit_optind != this_option_optind) + printf ("digits occur in two different argv-elements.\n"); + digit_optind = this_option_optind; + printf ("option %c\n", c); + break; + + case 'a': + printf ("option a\n"); + break; + + case 'b': + printf ("option b\n"); + break; + + case 'c': + printf ("option c with value `%s'\n", optarg); + break; + + case '?': + break; + + default: + printf ("?? getopt returned character code 0%o ??\n", c); + } + } + + if (optind < argc) + { + printf ("non-option ARGV-elements: "); + while (optind < argc) + printf ("%s ", argv[optind++]); + printf ("\n"); + } + + exit (0); +} + +#endif /* TEST */ diff --git a/gnu/usr.bin/texinfo/info/getopt.h b/gnu/usr.bin/texinfo/info/getopt.h new file mode 100644 index 0000000..45541f5 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/getopt.h @@ -0,0 +1,129 @@ +/* Declarations for getopt. + Copyright (C) 1989, 1990, 1991, 1992, 1993 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, 675 Mass Ave, Cambridge, MA 02139, USA. */ + +#ifndef _GETOPT_H +#define _GETOPT_H 1 + +#ifdef __cplusplus +extern "C" { +#endif + +/* For communication from `getopt' to the caller. + When `getopt' finds an option that takes an argument, + the argument value is returned here. + Also, when `ordering' is RETURN_IN_ORDER, + each non-option ARGV-element is returned here. */ + +extern char *optarg; + +/* Index in ARGV of the next element to be scanned. + This is used for communication to and from the caller + and for communication between successive calls to `getopt'. + + On entry to `getopt', zero means this is the first call; initialize. + + When `getopt' returns EOF, this is the index of the first of the + non-option elements that the caller should itself scan. + + Otherwise, `optind' communicates from one call to the next + how much of ARGV has been scanned so far. */ + +extern int optind; + +/* Callers store zero here to inhibit the error message `getopt' prints + for unrecognized options. */ + +extern int opterr; + +/* Set to an option character which was unrecognized. */ + +extern int optopt; + +/* Describe the long-named options requested by the application. + The LONG_OPTIONS argument to getopt_long or getopt_long_only is a vector + of `struct option' terminated by an element containing a name which is + zero. + + The field `has_arg' is: + no_argument (or 0) if the option does not take an argument, + required_argument (or 1) if the option requires an argument, + optional_argument (or 2) if the option takes an optional argument. + + If the field `flag' is not NULL, it points to a variable that is set + to the value given in the field `val' when the option is found, but + left unchanged if the option is not found. + + To have a long-named option do something other than set an `int' to + a compiled-in constant, such as set a value from `optarg', set the + option's `flag' field to zero and its `val' field to a nonzero + value (the equivalent single-letter option character, if there is + one). For long options that have a zero `flag' field, `getopt' + returns the contents of the `val' field. */ + +struct option +{ +#if __STDC__ + const char *name; +#else + char *name; +#endif + /* has_arg can't be an enum because some compilers complain about + type mismatches in all the code that assumes it is an int. */ + int has_arg; + int *flag; + int val; +}; + +/* Names for the values of the `has_arg' field of `struct option'. */ + +#define no_argument 0 +#define required_argument 1 +#define optional_argument 2 + +#if __STDC__ +#if defined(__GNU_LIBRARY__) +/* Many other libraries have conflicting prototypes for getopt, with + differences in the consts, in stdlib.h. To avoid compilation + errors, only prototype getopt for the GNU C library. */ +extern int getopt (int argc, char *const *argv, const char *shortopts); +#else /* not __GNU_LIBRARY__ */ +extern int getopt (); +#endif /* not __GNU_LIBRARY__ */ +extern int getopt_long (int argc, char *const *argv, const char *shortopts, + const struct option *longopts, int *longind); +extern int getopt_long_only (int argc, char *const *argv, + const char *shortopts, + const struct option *longopts, int *longind); + +/* Internal only. Users should not call this directly. */ +extern int _getopt_internal (int argc, char *const *argv, + const char *shortopts, + const struct option *longopts, int *longind, + int long_only); +#else /* not __STDC__ */ +extern int getopt (); +extern int getopt_long (); +extern int getopt_long_only (); + +extern int _getopt_internal (); +#endif /* not __STDC__ */ + +#ifdef __cplusplus +} +#endif + +#endif /* _GETOPT_H */ diff --git a/gnu/usr.bin/texinfo/info/getopt1.c b/gnu/usr.bin/texinfo/info/getopt1.c new file mode 100644 index 0000000..a32615c --- /dev/null +++ b/gnu/usr.bin/texinfo/info/getopt1.c @@ -0,0 +1,176 @@ +/* getopt_long and getopt_long_only entry points for GNU getopt. + Copyright (C) 1987, 88, 89, 90, 91, 92, 1993 + 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, 675 Mass Ave, Cambridge, MA 02139, USA. */ + +#ifdef HAVE_CONFIG_H +#include "config.h" +#endif + +#include "getopt.h" + +#if !__STDC__ && !defined(const) && IN_GCC +#define const +#endif + +#include <stdio.h> + +/* Comment out all this code if we are using the GNU C Library, and are not + actually compiling the library itself. This code is part of the GNU C + Library, but also included in many other GNU distributions. Compiling + and linking in this code is a waste when using the GNU C library + (especially if it is a shared library). Rather than having every GNU + program understand `configure --with-gnu-libc' and omit the object files, + it is simpler to just do this in the source for each such file. */ + +#if defined (_LIBC) || !defined (__GNU_LIBRARY__) + + +/* This needs to come after some library #include + to get __GNU_LIBRARY__ defined. */ +#ifdef __GNU_LIBRARY__ +#include <stdlib.h> +#else +char *getenv (); +#endif + +#ifndef NULL +#define NULL 0 +#endif + +int +getopt_long (argc, argv, options, long_options, opt_index) + int argc; + char *const *argv; + const char *options; + const struct option *long_options; + int *opt_index; +{ + return _getopt_internal (argc, argv, options, long_options, opt_index, 0); +} + +/* Like getopt_long, but '-' as well as '--' can indicate a long option. + If an option that starts with '-' (not '--') doesn't match a long option, + but does match a short option, it is parsed as a short option + instead. */ + +int +getopt_long_only (argc, argv, options, long_options, opt_index) + int argc; + char *const *argv; + const char *options; + const struct option *long_options; + int *opt_index; +{ + return _getopt_internal (argc, argv, options, long_options, opt_index, 1); +} + + +#endif /* _LIBC or not __GNU_LIBRARY__. */ + +#ifdef TEST + +#include <stdio.h> + +int +main (argc, argv) + int argc; + char **argv; +{ + int c; + int digit_optind = 0; + + while (1) + { + int this_option_optind = optind ? optind : 1; + int option_index = 0; + static struct option long_options[] = + { + {"add", 1, 0, 0}, + {"append", 0, 0, 0}, + {"delete", 1, 0, 0}, + {"verbose", 0, 0, 0}, + {"create", 0, 0, 0}, + {"file", 1, 0, 0}, + {0, 0, 0, 0} + }; + + c = getopt_long (argc, argv, "abc:d:0123456789", + long_options, &option_index); + if (c == EOF) + break; + + switch (c) + { + case 0: + printf ("option %s", long_options[option_index].name); + if (optarg) + printf (" with arg %s", optarg); + printf ("\n"); + break; + + case '0': + case '1': + case '2': + case '3': + case '4': + case '5': + case '6': + case '7': + case '8': + case '9': + if (digit_optind != 0 && digit_optind != this_option_optind) + printf ("digits occur in two different argv-elements.\n"); + digit_optind = this_option_optind; + printf ("option %c\n", c); + break; + + case 'a': + printf ("option a\n"); + break; + + case 'b': + printf ("option b\n"); + break; + + case 'c': + printf ("option c with value `%s'\n", optarg); + break; + + case 'd': + printf ("option d with value `%s'\n", optarg); + break; + + case '?': + break; + + default: + printf ("?? getopt returned character code 0%o ??\n", c); + } + } + + if (optind < argc) + { + printf ("non-option ARGV-elements: "); + while (optind < argc) + printf ("%s ", argv[optind++]); + printf ("\n"); + } + + exit (0); +} + +#endif /* TEST */ diff --git a/gnu/usr.bin/texinfo/info/indices.c b/gnu/usr.bin/texinfo/info/indices.c new file mode 100644 index 0000000..12029f6 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/indices.c @@ -0,0 +1,667 @@ +/* indices.c -- Commands for dealing with an Info file Index. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#include "info.h" +#include "indices.h" + +/* User-visible variable controls the output of info-index-next. */ +int show_index_match = 1; + +/* In the Info sense, an index is a menu. This variable holds the last + parsed index. */ +static REFERENCE **index_index = (REFERENCE **)NULL; + +/* The offset of the most recently selected index element. */ +static int index_offset = 0; + +/* Variable which holds the last string searched for. */ +static char *index_search = (char *)NULL; + +/* A couple of "globals" describing where the initial index was found. */ +static char *initial_index_filename = (char *)NULL; +static char *initial_index_nodename = (char *)NULL; + +/* A structure associating index names with index offset ranges. */ +typedef struct { + char *name; /* The nodename of this index. */ + int first; /* The index in our list of the first entry. */ + int last; /* The index in our list of the last entry. */ +} INDEX_NAME_ASSOC; + +/* An array associating index nodenames with index offset ranges. */ +static INDEX_NAME_ASSOC **index_nodenames = (INDEX_NAME_ASSOC **)NULL; +static int index_nodenames_index = 0; +static int index_nodenames_slots = 0; + +/* Add the name of NODE, and the range of the associated index elements + (passed in ARRAY) to index_nodenames. */ +static void +add_index_to_index_nodenames (array, node) + REFERENCE **array; + NODE *node; +{ + register int i, last; + INDEX_NAME_ASSOC *assoc; + + for (last = 0; array[last]; last++); + assoc = (INDEX_NAME_ASSOC *)xmalloc (sizeof (INDEX_NAME_ASSOC)); + assoc->name = savestring (node->nodename); + + if (!index_nodenames_index) + { + assoc->first = 0; + assoc->last = last; + } + else + { + for (i = 0; index_nodenames[i + 1]; i++); + assoc->first = 1 + index_nodenames[i]->last; + assoc->last = assoc->first + last; + } + add_pointer_to_array + (assoc, index_nodenames_index, index_nodenames, index_nodenames_slots, + 10, INDEX_NAME_ASSOC *); +} + +/* Find and return the indices of WINDOW's file. The indices are defined + as the first node in the file containing the word "Index" and any + immediately following nodes whose names also contain "Index". All such + indices are concatenated and the result returned. If WINDOW's info file + doesn't have any indices, a NULL pointer is returned. */ +REFERENCE ** +info_indices_of_window (window) + WINDOW *window; +{ + FILE_BUFFER *fb; + + fb = file_buffer_of_window (window); + + return (info_indices_of_file_buffer (fb)); +} + +REFERENCE ** +info_indices_of_file_buffer (file_buffer) + FILE_BUFFER *file_buffer; +{ + register int i; + REFERENCE **result = (REFERENCE **)NULL; + + /* No file buffer, no indices. */ + if (!file_buffer) + return ((REFERENCE **)NULL); + + /* Reset globals describing where the index was found. */ + maybe_free (initial_index_filename); + maybe_free (initial_index_nodename); + initial_index_filename = (char *)NULL; + initial_index_nodename = (char *)NULL; + + if (index_nodenames) + { + for (i = 0; index_nodenames[i]; i++) + { + free (index_nodenames[i]->name); + free (index_nodenames[i]); + } + + index_nodenames_index = 0; + index_nodenames[0] = (INDEX_NAME_ASSOC *)NULL; + } + + /* Grovel the names of the nodes found in this file. */ + if (file_buffer->tags) + { + TAG *tag; + + for (i = 0; tag = file_buffer->tags[i]; i++) + { + if (string_in_line ("Index", tag->nodename) != -1) + { + NODE *node; + REFERENCE **menu; + + /* Found one. Get its menu. */ + node = info_get_node (tag->filename, tag->nodename); + if (!node) + continue; + + /* Remember the filename and nodename of this index. */ + initial_index_filename = savestring (file_buffer->filename); + initial_index_nodename = savestring (tag->nodename); + + menu = info_menu_of_node (node); + + /* If we have a menu, add this index's nodename and range + to our list of index_nodenames. */ + if (menu) + { + add_index_to_index_nodenames (menu, node); + + /* Concatenate the references found so far. */ + result = info_concatenate_references (result, menu); + } + free (node); + } + } + } + + /* If there is a result, clean it up so that every entry has a filename. */ + for (i = 0; result && result[i]; i++) + if (!result[i]->filename) + result[i]->filename = savestring (file_buffer->filename); + + return (result); +} + +DECLARE_INFO_COMMAND (info_index_search, + "Look up a string in the index for this file") +{ + FILE_BUFFER *fb; + char *line; + + /* Reset the index offset, since this is not the info-index-next command. */ + index_offset = 0; + + /* The user is selecting a new search string, so flush the old one. */ + maybe_free (index_search); + index_search = (char *)NULL; + + /* If this window's file is not the same as the one that we last built an + index for, build and remember an index now. */ + fb = file_buffer_of_window (window); + if (!initial_index_filename || + (strcmp (initial_index_filename, fb->filename) != 0)) + { + info_free_references (index_index); + window_message_in_echo_area ("Finding index entries..."); + index_index = info_indices_of_file_buffer (fb); + } + + /* If there is no index, quit now. */ + if (!index_index) + { + info_error ("No indices found."); + return; + } + + /* Okay, there is an index. Let the user select one of the members of it. */ + line = + info_read_maybe_completing (window, "Index entry: ", index_index); + + window = active_window; + + /* User aborted? */ + if (!line) + { + info_abort_key (active_window, 1, 0); + return; + } + + /* Empty line means move to the Index node. */ + if (!*line) + { + free (line); + + if (initial_index_filename && initial_index_nodename) + { + NODE *node; + + node = + info_get_node (initial_index_filename, initial_index_nodename); + set_remembered_pagetop_and_point (window); + window_set_node_of_window (window, node); + remember_window_and_node (window, node); + window_clear_echo_area (); + return; + } + } + + /* The user typed either a completed index label, or a partial string. + Find an exact match, or, failing that, the first index entry containing + the partial string. So, we just call info_next_index_match () with minor + manipulation of INDEX_OFFSET. */ + { + int old_offset; + + /* Start the search right after/before this index. */ + if (count < 0) + { + register int i; + for (i = 0; index_index[i]; i++); + index_offset = i; + } + else + index_offset = -1; + + old_offset == index_offset; + + /* The "last" string searched for is this one. */ + index_search = line; + + /* Find it, or error. */ + info_next_index_match (window, count, 0); + + /* If the search failed, return the index offset to where it belongs. */ + if (index_offset == old_offset) + index_offset = 0; + } +} + +DECLARE_INFO_COMMAND (info_next_index_match, + "Go to the next matching index item from the last `\\[index-search]' command") +{ + register int i; + int partial, dir; + NODE *node; + + /* If there is no previous search string, the user hasn't built an index + yet. */ + if (!index_search) + { + info_error ("No previous index search string."); + return; + } + + /* If there is no index, that is an error. */ + if (!index_index) + { + info_error ("No index entries."); + return; + } + + /* The direction of this search is controlled by the value of the + numeric argument. */ + if (count < 0) + dir = -1; + else + dir = 1; + + /* Search for the next occurence of index_search. First try to find + an exact match. */ + partial = 0; + + for (i = index_offset + dir; (i > -1) && (index_index[i]); i += dir) + if (strcmp (index_search, index_index[i]->label) == 0) + break; + + /* If that failed, look for the next substring match. */ + if ((i < 0) || (!index_index[i])) + { + for (i = index_offset + dir; (i > -1) && (index_index[i]); i += dir) + if (string_in_line (index_search, index_index[i]->label) != -1) + break; + + if ((i > -1) && (index_index[i])) + partial = string_in_line (index_search, index_index[i]->label); + } + + /* If that failed, print an error. */ + if ((i < 0) || (!index_index[i])) + { + info_error ("No %sindex entries containing \"%s\".", + index_offset > 0 ? "more " : "", index_search); + return; + } + + /* Okay, we found the next one. Move the offset to the current entry. */ + index_offset = i; + + /* Report to the user on what we have found. */ + { + register int j; + char *name = "CAN'T SEE THIS"; + char *match; + + for (j = 0; index_nodenames[j]; j++) + { + if ((i >= index_nodenames[j]->first) && + (i <= index_nodenames[j]->last)) + { + name = index_nodenames[j]->name; + break; + } + } + + /* If we had a partial match, indicate to the user which part of the + string matched. */ + match = savestring (index_index[i]->label); + + if (partial && show_index_match) + { + int j, ls, start, upper; + + ls = strlen (index_search); + start = partial - ls; + upper = isupper (match[start]) ? 1 : 0; + + for (j = 0; j < ls; j++) + if (upper) + match[j + start] = info_tolower (match[j + start]); + else + match[j + start] = info_toupper (match[j + start]); + } + + { + char *format; + + format = replace_in_documentation + ("Found \"%s\" in %s. (`\\[next-index-match]' tries to find next.)"); + + window_message_in_echo_area (format, match, name); + } + + free (match); + } + + /* Select the node corresponding to this index entry. */ + node = info_get_node (index_index[i]->filename, index_index[i]->nodename); + + if (!node) + { + info_error (CANT_FILE_NODE, + index_index[i]->filename, index_index[i]->nodename); + return; + } + + set_remembered_pagetop_and_point (window); + window_set_node_of_window (window, node); + remember_window_and_node (window, node); + + + /* Try to find an occurence of LABEL in this node. */ + { + long start, loc; + + start = window->line_starts[1] - window->node->contents; + loc = info_target_search_node (node, index_index[i]->label, start); + + if (loc != -1) + { + window->point = loc; + window_adjust_pagetop (window); + } + } +} + +/* **************************************************************** */ +/* */ +/* Info APROPOS: Search every known index. */ +/* */ +/* **************************************************************** */ + +/* For every menu item in DIR, search the indices of that file for + SEARCH_STRING. */ +REFERENCE ** +apropos_in_all_indices (search_string, inform) + char *search_string; + int inform; +{ + register int i, dir_index; + REFERENCE **all_indices = (REFERENCE **)NULL; + REFERENCE **dir_menu = (REFERENCE **)NULL; + NODE *dir_node; + int printed = 0; + + dir_node = info_get_node ("dir", "Top"); + if (dir_node) + dir_menu = info_menu_of_node (dir_node); + + if (!dir_menu) + return; + + /* For every menu item in DIR, get the associated node's file buffer and + read the indices of that file buffer. Gather all of the indices into + one large one. */ + for (dir_index = 0; dir_menu[dir_index]; dir_index++) + { + REFERENCE **this_index, *this_item; + NODE *this_node; + FILE_BUFFER *this_fb; + + this_item = dir_menu[dir_index]; + + if (!this_item->filename) + { + if (dir_node->parent) + this_item->filename = savestring (dir_node->parent); + else + this_item->filename = savestring (dir_node->filename); + } + + /* Find this node. If we cannot find it, try using the label of the + entry as a file (i.e., "(LABEL)Top"). */ + this_node = info_get_node (this_item->filename, this_item->nodename); + + if (!this_node && this_item->nodename && + (strcmp (this_item->label, this_item->nodename) == 0)) + this_node = info_get_node (this_item->label, "Top"); + + if (!this_node) + continue; + + /* Get the file buffer associated with this node. */ + { + char *files_name; + + files_name = this_node->parent; + if (!files_name) + files_name = this_node->filename; + + this_fb = info_find_file (files_name); + + if (this_fb && inform) + message_in_echo_area ("Scanning indices of \"%s\"...", files_name); + + this_index = info_indices_of_file_buffer (this_fb); + free (this_node); + + if (this_fb && inform) + unmessage_in_echo_area (); + } + + if (this_index) + { + /* Remember the filename which contains this set of references. */ + for (i = 0; this_index && this_index[i]; i++) + if (!this_index[i]->filename) + this_index[i]->filename = savestring (this_fb->filename); + + /* Concatenate with the other indices. */ + all_indices = info_concatenate_references (all_indices, this_index); + } + } + + info_free_references (dir_menu); + + /* Build a list of the references which contain SEARCH_STRING. */ + if (all_indices) + { + REFERENCE *entry, **apropos_list = (REFERENCE **)NULL; + int apropos_list_index = 0; + int apropos_list_slots = 0; + + for (i = 0; (entry = all_indices[i]); i++) + { + if (string_in_line (search_string, entry->label) != -1) + { + add_pointer_to_array + (entry, apropos_list_index, apropos_list, apropos_list_slots, + 100, REFERENCE *); + } + else + { + maybe_free (entry->label); + maybe_free (entry->filename); + maybe_free (entry->nodename); + free (entry); + } + } + + free (all_indices); + all_indices = apropos_list; + } + return (all_indices); +} + +#define APROPOS_NONE \ + "No available info files reference \"%s\" in their indices." + +void +info_apropos (string) + char *string; +{ + REFERENCE **apropos_list; + + apropos_list = apropos_in_all_indices (string, 0); + + if (!apropos_list) + { + info_error (APROPOS_NONE, string); + } + else + { + register int i; + REFERENCE *entry; + + for (i = 0; (entry = apropos_list[i]); i++) + fprintf (stderr, "\"(%s)%s\" -- %s\n", + entry->filename, entry->nodename, entry->label); + } + info_free_references (apropos_list); +} + +static char *apropos_list_nodename = "*Apropos*"; + +DECLARE_INFO_COMMAND (info_index_apropos, + "Grovel all known info file's indices for a string and build a menu") +{ + char *line; + + line = info_read_in_echo_area (window, "Index apropos: "); + + window = active_window; + + /* User aborted? */ + if (!line) + { + info_abort_key (window, 1, 1); + return; + } + + /* User typed something? */ + if (*line) + { + REFERENCE **apropos_list; + NODE *apropos_node; + + apropos_list = apropos_in_all_indices (line, 1); + + if (!apropos_list) + { + info_error (APROPOS_NONE, line); + } + else + { + register int i; + char *line_buffer; + + initialize_message_buffer (); + printf_to_message_buffer + ("\n* Menu: Nodes whoses indices contain \"%s\":\n", line); + line_buffer = (char *)xmalloc (500); + + for (i = 0; apropos_list[i]; i++) + { + int len; + sprintf (line_buffer, "* (%s)%s::", + apropos_list[i]->filename, apropos_list[i]->nodename); + len = pad_to (36, line_buffer); + sprintf (line_buffer + len, "%s", apropos_list[i]->label); + printf_to_message_buffer ("%s\n", line_buffer); + } + free (line_buffer); + } + + apropos_node = message_buffer_to_node (); + add_gcable_pointer (apropos_node); + name_internal_node (apropos_node, apropos_list_nodename); + + /* Even though this is an internal node, we don't want the window + system to treat it specially. So we turn off the internalness + of it here. */ + apropos_node->flags &= ~N_IsInternal; + + /* Find/Create a window to contain this node. */ + { + WINDOW *new; + NODE *node; + + set_remembered_pagetop_and_point (window); + + /* If a window is visible and showing an apropos list already, + re-use it. */ + for (new = windows; new; new = new->next) + { + node = new->node; + + if (internal_info_node_p (node) && + (strcmp (node->nodename, apropos_list_nodename) == 0)) + break; + } + + /* If we couldn't find an existing window, try to use the next window + in the chain. */ + if (!new && window->next) + new = window->next; + + /* If we still don't have a window, make a new one to contain + the list. */ + if (!new) + { + WINDOW *old_active; + + old_active = active_window; + active_window = window; + new = window_make_window ((NODE *)NULL); + active_window = old_active; + } + + /* If we couldn't make a new window, use this one. */ + if (!new) + new = window; + + /* Lines do not wrap in this window. */ + new->flags |= W_NoWrap; + + window_set_node_of_window (new, apropos_node); + remember_window_and_node (new, apropos_node); + active_window = new; + } + info_free_references (apropos_list); + } + free (line); + + if (!info_error_was_printed) + window_clear_echo_area (); +} + diff --git a/gnu/usr.bin/texinfo/info/indices.h b/gnu/usr.bin/texinfo/info/indices.h new file mode 100644 index 0000000..b63a458 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/indices.h @@ -0,0 +1,39 @@ +/* indices.h -- Functions defined in indices.c. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#ifndef _INDICES_H_ +#define _INDICES_H_ + +/* User-visible variable controls the output of info-index-next. */ +extern int show_index_match; + +extern REFERENCE **info_indices_of_window (), **info_indices_of_file_buffer (); +extern void info_apropos (); + +/* For every menu item in DIR, search the indices of that file for STRING. */ +REFERENCE **apropos_in_all_indices (); + +/* User visible functions declared in indices.c. */ +extern void info_index_search (), info_next_index_match (); + +#endif /* !_INDICES_H_ */ diff --git a/gnu/usr.bin/texinfo/info/info-stnd.info b/gnu/usr.bin/texinfo/info/info-stnd.info new file mode 100644 index 0000000..31f486a --- /dev/null +++ b/gnu/usr.bin/texinfo/info/info-stnd.info @@ -0,0 +1,1259 @@ +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-utils.c b/gnu/usr.bin/texinfo/info/info-utils.c new file mode 100644 index 0000000..56edcd6 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/info-utils.c @@ -0,0 +1,653 @@ +/* info-utils.c -- Useful functions for manipulating Info file quirks. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#include <stdio.h> /* For "NULL". Yechhh! */ +#include <ctype.h> +#include <sys/types.h> +#include <sys/stat.h> +#include "info-utils.h" + +/* When non-zero, various display and input functions handle ISO Latin + character sets correctly. */ +int ISO_Latin_p = 0; + +/* Variable which holds the most recent filename parsed as a result of + calling info_parse_xxx (). */ +char *info_parsed_filename = (char *)NULL; + +/* Variable which holds the most recent nodename parsed as a result of + calling info_parse_xxx (). */ +char *info_parsed_nodename = (char *)NULL; + +/* Functions to remember a filename or nodename for later return. */ +static void save_filename (), saven_filename (); +static void save_nodename (), saven_nodename (); + +/* How to get a reference (either menu or cross). */ +static REFERENCE **info_references_internal (); + +/* Parse the filename and nodename out of STRING. If STRING doesn't + contain a filename (i.e., it is NOT (FILENAME)NODENAME) then set + INFO_PARSED_FILENAME to NULL. If second argument NEWLINES_OKAY is + non-zero, it says to allow the nodename specification to cross a + newline boundary (i.e., only `,', `.', or `TAB' can end the spec). */ +void +info_parse_node (string, newlines_okay) + char *string; + int newlines_okay; +{ + register int i = 0; + + /* Default the answer. */ + save_filename ((char *)NULL); + save_nodename ((char *)NULL); + + /* Special case of nothing passed. Return nothing. */ + if (!string || !*string) + return; + + string += skip_whitespace (string); + + /* Check for (FILENAME)NODENAME. */ + if (*string == '(') + { + i = 0; + /* Advance past the opening paren. */ + string++; + + /* Find the closing paren. */ + while (string[i] && string[i] != ')') + i++; + + /* Remember parsed filename. */ + saven_filename (string, i); + + /* Point directly at the nodename. */ + string += i; + + if (*string) + string++; + } + + /* Parse out nodename. */ + i = skip_node_characters (string, newlines_okay); + saven_nodename (string, i); + canonicalize_whitespace (info_parsed_nodename); + if (info_parsed_nodename && !*info_parsed_nodename) + { + free (info_parsed_nodename); + info_parsed_nodename = (char *)NULL; + } +} + +/* Return the node addressed by LABEL in NODE (usually one of "Prev:", + "Next:", "Up:", "File:", or "Node:". After a call to this function, + the global INFO_PARSED_NODENAME and INFO_PARSED_FILENAME contain + the information. */ +void +info_parse_label (label, node) + char *label; + NODE *node; +{ + register int i; + char *nodeline; + + /* Default answer to failure. */ + save_nodename ((char *)NULL); + save_filename ((char *)NULL); + + /* Find the label in the first line of this node. */ + nodeline = node->contents; + i = string_in_line (label, nodeline); + + if (i == -1) + return; + + nodeline += i; + nodeline += skip_whitespace (nodeline); + info_parse_node (nodeline, DONT_SKIP_NEWLINES); +} + +/* **************************************************************** */ +/* */ +/* Finding and Building Menus */ +/* */ +/* **************************************************************** */ + +/* Return a NULL terminated array of REFERENCE * which represents the menu + found in NODE. If there is no menu in NODE, just return a NULL pointer. */ +REFERENCE ** +info_menu_of_node (node) + NODE *node; +{ + long position; + SEARCH_BINDING search; + REFERENCE **menu = (REFERENCE **)NULL; + + search.buffer = node->contents; + search.start = 0; + search.end = node->nodelen; + search.flags = S_FoldCase; + + /* Find the start of the menu. */ + position = search_forward (INFO_MENU_LABEL, &search); + + if (position == -1) + return ((REFERENCE **) NULL); + + /* We have the start of the menu now. Glean menu items from the rest + of the node. */ + search.start = position + strlen (INFO_MENU_LABEL); + search.start += skip_line (search.buffer + search.start); + search.start--; + menu = info_menu_items (&search); + return (menu); +} + +/* Return a NULL terminated array of REFERENCE * which represents the cross + refrences found in NODE. If there are no cross references in NODE, just + return a NULL pointer. */ +REFERENCE ** +info_xrefs_of_node (node) + NODE *node; +{ + SEARCH_BINDING search; + + search.buffer = node->contents; + search.start = 0; + search.end = node->nodelen; + search.flags = S_FoldCase; + + return (info_xrefs (&search)); +} + +/* Glean menu entries from BINDING->buffer + BINDING->start until we + have looked at the entire contents of BINDING. Return an array + of REFERENCE * that represents each menu item in this range. */ +REFERENCE ** +info_menu_items (binding) + SEARCH_BINDING *binding; +{ + return (info_references_internal (INFO_MENU_ENTRY_LABEL, binding)); +} + +/* Glean cross references from BINDING->buffer + BINDING->start until + BINDING->end. Return an array of REFERENCE * that represents each + cross reference in this range. */ +REFERENCE ** +info_xrefs (binding) + SEARCH_BINDING *binding; +{ + return (info_references_internal (INFO_XREF_LABEL, binding)); +} + +/* Glean cross references or menu items from BINDING. Return an array + of REFERENCE * that represents the items found. */ +static REFERENCE ** +info_references_internal (label, binding) + char *label; + SEARCH_BINDING *binding; +{ + SEARCH_BINDING search; + REFERENCE **refs = (REFERENCE **)NULL; + int refs_index = 0, refs_slots = 0; + int searching_for_menu_items = 0; + long position; + + search.buffer = binding->buffer; + search.start = binding->start; + search.end = binding->end; + search.flags = S_FoldCase | S_SkipDest; + + searching_for_menu_items = (stricmp (label, INFO_MENU_ENTRY_LABEL) == 0); + + while ((position = search_forward (label, &search)) != -1) + { + int offset, start; + char *refdef; + REFERENCE *entry; + + search.start = position; + search.start += skip_whitespace (search.buffer + search.start); + start = search.start - binding->start; + refdef = search.buffer + search.start; + offset = string_in_line (":", refdef); + + /* When searching for menu items, if no colon, there is no + menu item on this line. */ + if (offset == -1) + { + if (searching_for_menu_items) + continue; + else + { + int temp; + + temp = skip_line (refdef); + offset = string_in_line (":", refdef + temp); + if (offset == -1) + continue; /* Give up? */ + else + offset += temp; + } + } + + entry = (REFERENCE *)xmalloc (sizeof (REFERENCE)); + entry->filename = (char *)NULL; + entry->nodename = (char *)NULL; + entry->label = (char *)xmalloc (offset); + strncpy (entry->label, refdef, offset - 1); + entry->label[offset - 1] = '\0'; + canonicalize_whitespace (entry->label); + + refdef += offset; + entry->start = start; + entry->end = refdef - binding->buffer; + + /* If this reference entry continues with another ':' then the + nodename is the same as the label. */ + if (*refdef == ':') + { + entry->nodename = savestring (entry->label); + } + else + { + /* This entry continues with a specific nodename. Parse the + nodename from the specification. */ + + refdef += skip_whitespace_and_newlines (refdef); + + if (searching_for_menu_items) + info_parse_node (refdef, DONT_SKIP_NEWLINES); + else + info_parse_node (refdef, SKIP_NEWLINES); + + if (info_parsed_filename) + entry->filename = savestring (info_parsed_filename); + + if (info_parsed_nodename) + entry->nodename = savestring (info_parsed_nodename); + } + + add_pointer_to_array + (entry, refs_index, refs, refs_slots, 50, REFERENCE *); + } + return (refs); +} + +/* Get the entry associated with LABEL in MENU. Return a pointer to the + REFERENCE if found, or NULL. */ +REFERENCE * +info_get_labeled_reference (label, references) + char *label; + REFERENCE **references; +{ + register int i; + REFERENCE *entry; + + for (i = 0; references && (entry = references[i]); i++) + { + if (strcmp (label, entry->label) == 0) + return (entry); + } + return ((REFERENCE *)NULL); +} + +/* A utility function for concatenating REFERENCE **. Returns a new + REFERENCE ** which is the concatenation of REF1 and REF2. The REF1 + and REF2 arrays are freed, but their contents are not. */ +REFERENCE ** +info_concatenate_references (ref1, ref2) + REFERENCE **ref1, **ref2; +{ + register int i, j; + REFERENCE **result; + int size; + + /* With one argument passed as NULL, simply return the other arg. */ + if (!ref1) + return (ref2); + else if (!ref2) + return (ref1); + + /* Get the total size of the slots that we will need. */ + for (i = 0; ref1[i]; i++); + size = i; + for (i = 0; ref2[i]; i++); + size += i; + + result = (REFERENCE **)xmalloc ((1 + size) * sizeof (REFERENCE *)); + + /* Copy the contents over. */ + for (i = 0; ref1[i]; i++) + result[i] = ref1[i]; + + j = i; + for (i = 0; ref2[i]; i++) + result[j++] = ref2[i]; + + result[j] = (REFERENCE *)NULL; + free (ref1); + free (ref2); + return (result); +} + +/* Free the data associated with REFERENCES. */ +void +info_free_references (references) + REFERENCE **references; +{ + register int i; + REFERENCE *entry; + + if (references) + { + for (i = 0; references && (entry = references[i]); i++) + { + maybe_free (entry->label); + maybe_free (entry->filename); + maybe_free (entry->nodename); + + free (entry); + } + + free (references); + } +} + +/* Search for sequences of whitespace or newlines in STRING, replacing + all such sequences with just a single space. Remove whitespace from + start and end of string. */ +void +canonicalize_whitespace (string) + char *string; +{ + register int i, j; + int len, whitespace_found, whitespace_loc; + char *temp; + + if (!string) + return; + + len = strlen (string); + temp = (char *)xmalloc (1 + len); + + /* Search for sequences of whitespace or newlines. Replace all such + sequences in the string with just a single space. */ + + whitespace_found = 0; + for (i = 0, j = 0; string[i]; i++) + { + if (whitespace_or_newline (string[i])) + { + whitespace_found++; + whitespace_loc = i; + continue; + } + else + { + if (whitespace_found && whitespace_loc) + { + whitespace_found = 0; + temp[j++] = ' '; + } + + temp[j++] = string[i]; + } + } + + /* Kill trailing whitespace. */ + if (j && whitespace (temp[j - 1])) + j--; + + temp[j] = '\0'; + strcpy (string, temp); + free (temp); +} + +/* String representation of a char returned by printed_representation (). */ +static char the_rep[10]; + +/* Return a pointer to a string which is the printed representation + of CHARACTER if it were printed at HPOS. */ +char * +printed_representation (character, hpos) + unsigned char character; + int hpos; +{ + register int i = 0; + int printable_limit; + + if (ISO_Latin_p) + printable_limit = 160; + else + printable_limit = 127; + + if (character == '\177') + { + the_rep[i++] = '^'; + the_rep[i++] = '?'; + } + else if (iscntrl (character)) + { + switch (character) + { + case '\r': + case '\n': + the_rep[i++] = character; + break; + + case '\t': + { + int tw; + + tw = ((hpos + 8) & 0xf8) - hpos; + while (i < tw) + the_rep[i++] = ' '; + } + break; + + default: + the_rep[i++] = '^'; + the_rep[i++] = (character | 0x40); + } + } + else if (character > printable_limit) + { + sprintf (the_rep + i, "\\%0o", character); + i = strlen (the_rep); + } + else + the_rep[i++] = character; + + the_rep[i] = '\0'; + + return (the_rep); +} + + +/* **************************************************************** */ +/* */ +/* Functions Static To This File */ +/* */ +/* **************************************************************** */ + +/* Amount of space allocated to INFO_PARSED_FILENAME via xmalloc (). */ +static int parsed_filename_size = 0; + +/* Amount of space allocated to INFO_PARSED_NODENAME via xmalloc (). */ +static int parsed_nodename_size = 0; + +static void save_string (), saven_string (); + +/* Remember FILENAME in PARSED_FILENAME. An empty FILENAME is translated + to a NULL pointer in PARSED_FILENAME. */ +static void +save_filename (filename) + char *filename; +{ + save_string (filename, &info_parsed_filename, &parsed_filename_size); +} + +/* Just like save_filename (), but you pass the length of the string. */ +static void +saven_filename (filename, len) + char *filename; + int len; +{ + saven_string (filename, len, + &info_parsed_filename, &parsed_filename_size); +} + +/* Remember NODENAME in PARSED_NODENAME. An empty NODENAME is translated + to a NULL pointer in PARSED_NODENAME. */ +static void +save_nodename (nodename) + char *nodename; +{ + save_string (nodename, &info_parsed_nodename, &parsed_nodename_size); +} + +/* Just like save_nodename (), but you pass the length of the string. */ +static void +saven_nodename (nodename, len) + char *nodename; + int len; +{ + saven_string (nodename, len, + &info_parsed_nodename, &parsed_nodename_size); +} + +/* Remember STRING in STRING_P. STRING_P should currently have STRING_SIZE_P + bytes allocated to it. An empty STRING is translated to a NULL pointer + in STRING_P. */ +static void +save_string (string, string_p, string_size_p) + char *string; + char **string_p; + int *string_size_p; +{ + if (!string || !*string) + { + if (*string_p) + free (*string_p); + + *string_p = (char *)NULL; + *string_size_p = 0; + } + else + { + if (strlen (string) >= *string_size_p) + *string_p = (char *)xrealloc + (*string_p, (*string_size_p = 1 + strlen (string))); + + strcpy (*string_p, string); + } +} + +/* Just like save_string (), but you also pass the length of STRING. */ +static void +saven_string (string, len, string_p, string_size_p) + char *string; + int len; + char **string_p; + int *string_size_p; +{ + if (!string) + { + if (*string_p) + free (*string_p); + + *string_p = (char *)NULL; + *string_size_p = 0; + } + else + { + if (len >= *string_size_p) + *string_p = (char *)xrealloc (*string_p, (*string_size_p = 1 + len)); + + strncpy (*string_p, string, len); + (*string_p)[len] = '\0'; + } +} + +/* Return a pointer to the part of PATHNAME that simply defines the file. */ +char * +filename_non_directory (pathname) + char *pathname; +{ + char *filename; + + filename = (char *)rindex (pathname, '/'); + + if (filename) + filename++; + else + filename = pathname; + + return (filename); +} + +/* Return non-zero if NODE is one especially created by Info. */ +int +internal_info_node_p (node) + NODE *node; +{ + if (node && + (node->filename && !*node->filename) && + !node->parent && node->nodename) + return (1); + else + return (0); +} + +/* Make NODE appear to be one especially created by Info. */ +void +name_internal_node (node, name) + NODE *node; + char *name; +{ + if (!node) + return; + + node->filename = ""; + node->parent = (char *)NULL; + node->nodename = name; + node->flags |= N_IsInternal; +} + +/* Return the window displaying NAME, the name of an internally created + Info window. */ +WINDOW * +get_internal_info_window (name) + char *name; +{ + WINDOW *win = (WINDOW *)NULL; + + for (win = windows; win; win = win->next) + if (internal_info_node_p (win->node) && + (strcmp (win->node->nodename, name) == 0)) + break; + + return (win); +} diff --git a/gnu/usr.bin/texinfo/info/info-utils.h b/gnu/usr.bin/texinfo/info/info-utils.h new file mode 100644 index 0000000..6c4ec30 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/info-utils.h @@ -0,0 +1,144 @@ +/* info-utils.h -- Exported functions and variables from info-util.c. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#ifndef _INFO_UTILS_H_ +#define _INFO_UTILS_H_ + +#if !defined (HAVE_RINDEX) +#undef index +#undef rindex +#define index strchr +#define rindex strrchr +#endif + +#if !defined (HAVE_BCOPY) +#undef bcopy +#define bcopy(source, dest, count) memcpy(dest, source, count) +#endif + +#include "nodes.h" +#include "window.h" +#include "search.h" + +/* Structure which describes a node reference, such as a menu entry or + cross reference. Arrays of such references can be built by calling + info_menus_of_node () or info_xrefs_of_node (). */ +typedef struct { + char *label; /* User Label. */ + char *filename; /* File where this node can be found. */ + char *nodename; /* Name of the node. */ + int start, end; /* Offsets within the containing node of LABEL. */ +} REFERENCE; + +/* When non-zero, various display and input functions handle ISO Latin + character sets correctly. */ +extern int ISO_Latin_p; + +/* Variable which holds the most recent filename parsed as a result of + calling info_parse_xxx (). */ +extern char *info_parsed_filename; + +/* Variable which holds the most recent nodename parsed as a result of + calling info_parse_xxx (). */ +extern char *info_parsed_nodename; + +/* Parse the filename and nodename out of STRING. If STRING doesn't + contain a filename (i.e., it is NOT (FILENAME)NODENAME) then set + INFO_PARSED_FILENAME to NULL. If second argument NEWLINES_OKAY is + non-zero, it says to allow the nodename specification to cross a + newline boundary (i.e., only `,', `.', or `TAB' can end the spec). */ +void info_parse_node (); + +/* Return a NULL terminated array of REFERENCE * which represents the menu + found in NODE. If there is no menu in NODE, just return a NULL pointer. */ +extern REFERENCE **info_menu_of_node (); + +/* Return a NULL terminated array of REFERENCE * which represents the cross + refrences found in NODE. If there are no cross references in NODE, just + return a NULL pointer. */ +extern REFERENCE **info_xrefs_of_node (); + +/* Glean cross references from BINDING->buffer + BINDING->start until + BINDING->end. Return an array of REFERENCE * that represents each + cross reference in this range. */ +extern REFERENCE **info_xrefs (); + +/* Get the entry associated with LABEL in REFERENCES. Return a pointer to + the reference if found, or NULL. */ +extern REFERENCE *info_get_labeled_reference (); + +/* Glean menu entries from BINDING->buffer + BINDING->start until we + have looked at the entire contents of BINDING. Return an array + of REFERENCE * that represents each menu item in this range. */ +extern REFERENCE **info_menu_items (); + +/* A utility function for concatenating REFERENCE **. Returns a new + REFERENCE ** which is the concatenation of REF1 and REF2. The REF1 + and REF2 arrays are freed, but their contents are not. */ +REFERENCE **info_concatenate_references (); + +/* Free the data associated with REFERENCES. */ +extern void info_free_references (); + +/* Search for sequences of whitespace or newlines in STRING, replacing + all such sequences with just a single space. Remove whitespace from + start and end of string. */ +void canonicalize_whitespace (); + +/* Return a pointer to a string which is the printed representation + of CHARACTER if it were printed at HPOS. */ +extern char *printed_representation (); + +/* Return a pointer to the part of PATHNAME that simply defines the file. */ +extern char *filename_non_directory (); + +/* Return non-zero if NODE is one especially created by Info. */ +extern int internal_info_node_p (); + +/* Make NODE appear to be one especially created by Info, and give it NAME. */ +extern void name_internal_node (); + +/* Return the window displaying NAME, the name of an internally created + Info window. */ +extern WINDOW *get_internal_info_window (); + +/* Return the node addressed by LABEL in NODE (usually one of "Prev:", + "Next:", "Up:", "File:", or "Node:". After a call to this function, + the global INFO_PARSED_NODENAME and INFO_PARSED_FILENAME contain + the information. */ +extern void info_parse_label (/* label, node */); + +#define info_label_was_found \ + (info_parsed_nodename != NULL || info_parsed_filename != NULL) + +#define info_file_label_of_node(n) info_parse_label (INFO_FILE_LABEL, n) +#define info_next_label_of_node(n) info_parse_label (INFO_NEXT_LABEL, n) +#define info_up_label_of_node(n) info_parse_label (INFO_UP_LABEL, n) +#define info_prev_label_of_node(n) \ + do { \ + info_parse_label (INFO_PREV_LABEL, n); \ + if (!info_label_was_found) \ + info_parse_label (INFO_ALTPREV_LABEL, n); \ + } while (0) + +#endif /* !_INFO_UTILS_H_ */ diff --git a/gnu/usr.bin/texinfo/info/info.1 b/gnu/usr.bin/texinfo/info/info.1 new file mode 100644 index 0000000..674bcef --- /dev/null +++ b/gnu/usr.bin/texinfo/info/info.1 @@ -0,0 +1,229 @@ +.TH info 1 "7th December 1990" +.SH NAME +info \- GNU's hypertext system +.SH SYNOPSIS +.B info +[ +.B \-\-option-name option-value +] +.B \menu-item... +.SH COPYRIGHT +.if n Copyright (C) 1989, 1993 Free Software Foundation, Inc. +.if t Copyright \(co 1989, 1993 Free Software Foundation, Inc. +.SH DESCRIPTION +.LP +The GNU project has a hypertext system called +.I Info +which allows the same source file to be either printed as a +paper manual, or viewed using +.B info. +It is possible to use the +.B info +program from inside Emacs, or to use the stand-alone version described here. +This manual page gives a brief summary of its capabilities. + +.SH OPTIONS +.TP +.B \-\-directory directory-path +Add +.B directory-path +to the list of directory paths searched when +.B info +needs to find a file. You may issue +.B \-\-directory +multiple times. +Alternatively, you may specify a value for the environment variable +.B INFOPATH; +if +.B \-\-directory +is not given, the value of +.B INFOPATH +is used. The value of +.B INFOPATH +is a colon separated list of directory names. If you do not supply either +.B INFOPATH +or +.B \-\-directory-path, +.B info +uses a default path. +.TP +.B \-f filename +Specify a particular +.B info +file to visit. By default, +.B info +visits +the file +.B dir; +if you use this option, +.B info +will start with +.B (FILENAME)Top +as the first file and node. +.TP +.B \-n nodename +Specify a particular node to visit in the initial file that +.B info +loads. This is especially useful in conjunction with +.B \-\-file. +You may specify +.B \-\-node +multiple times. +.TP +.B -o file +Direct output to +.B file +instead of starting an interactive +.B info +session. +.TP +.B \-h +Produce a relatively brief description of the available +.B info +options. +.TP +.B \-\-version +Print the version information of +.B info +and exit. +.TP +.B menu-item +.B 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, + +.B info emacs buffers + +first selects the menu item +.B emacs +in the node +.B (dir)Top, +and then selects the menu item +.B buffers +in the node +.B (emacs)Top. +.SH COMMANDS +When in +.B info +the following commands are available: +.TP +.B h +Invoke the Info tutorial. +.TP +.B ? +Get a short summary of +.B info +commands. +.TP +.B h +Select the +.B info +node from the main directory; this is much more complete than just +using +.B ?. +.TP +.B Ctrl-g +Abort whatever you are doing. +.TP +.B Ctrl-l +Redraw the screen. +.PP +Selecting other nodes: +.TP +.B n +Move to the "next" node of this node. +.TP +.B p +Move to the "previous" node of this node. +.TP +.B u +Move to this node's "up" node. +.TP +.B m +Pick a menu item specified by name. Picking a menu item causes another +node to be selected. You do not need to type a complete nodename; if +you type a few letters and then a space or tab +.B info +will will try to fill in the rest of the nodename. If you ask for further +completion without typing any more characters you'll be given a list +of possibilities; you can also get the list with +.B ?. +If you type a few characters and then hit return +.B info +will try to do a completion, and if it is ambigous use the first possibility. +.TP +.B f +Follow a cross reference. You are asked for the name of the reference, +using command completion as for +.B m. +.TP +.B l +Move to the last node you were at. +.PP +Moving within a node: +.TP +.B Space +Scroll forward a page. +.TP +.B DEL +Scroll backward a page. +.TP +.B b +Go to the beginning of this node. +.PP +Advanced commands: +.TP +.B q +Quit +.B info. +.TP +.B 1 +Pick first item in node's menu. +.TP +.B 2 \-\- 5 +Pick second ... fifth item in node's menu. +.TP +.B g +Move to node specified by name. You may include a filename as well, +as +.B (FILENAME)NODENAME. +.TP +.B s +Search through this +.B info +file for a specified string, and select the node in which +the next occurrence is found. +.TP +.B M-x print-node +Pipe the contents of the current node through the command in the +environment variable +.B INFO_PRINT_COMMAND. +If the variable does not exist, the node is simply piped to +.B lpr. +.SH ENVIRONMENT +.TP +.B INFOPATHS +A colon-separated list of directories to search for +.B info +files. Used if +.B \-\-directory +is not given. +.TP +.B INFO_PRINT_COMMAND +The command used for printing. +.SH SEE ALSO +.BR emacs (1) +.SH AUTHOR +.RS +Brian Fox, Free Software Foundation +.br +bfox@ai.mit.edu +.SH MANUAL AUTHOR +.RS +Robert Lupton; updated by Robert J. Chassell. +.br +rhl@astro.princeton.edu; bob@gnu.ai.mit.edu diff --git a/gnu/usr.bin/texinfo/info/info.c b/gnu/usr.bin/texinfo/info/info.c new file mode 100644 index 0000000..0647d98 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/info.c @@ -0,0 +1,511 @@ +/* info.c -- Display nodes of Info files in multiple windows. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#include "info.h" +#include "dribble.h" +#include "getopt.h" + +/* The version numbers of this version of Info. */ +int info_major_version = 2; +int info_minor_version = 10; +int info_patch_level = 1; + +/* Non-zero means search all indices for APROPOS_SEARCH_STRING. */ +static int apropos_p = 0; + +/* Variable containing the string to search for when apropos_p is non-zero. */ +static char *apropos_search_string = (char *)NULL; + +/* Non-zero means print version info only. */ +static int print_version_p = 0; + +/* Non-zero means print a short description of the options. */ +static int print_help_p = 0; + +/* Array of the names of nodes that the user specified with "--node" on the + command line. */ +static char **user_nodenames = (char **)NULL; +static int user_nodenames_index = 0; +static int user_nodenames_slots = 0; + +/* String specifying the first file to load. This string can only be set + by the user specifying "--file" on the command line. */ +static char *user_filename = (char *)NULL; + +/* String specifying the name of the file to dump nodes to. This value is + filled if the user speficies "--output" on the command line. */ +static char *user_output_filename = (char *)NULL; + +/* Non-zero indicates that when "--output" is specified, all of the menu + items of the specified nodes (and their subnodes as well) should be + dumped in the order encountered. This basically can print a book. */ +int dump_subnodes = 0; + +/* Structure describing the options that Info accepts. We pass this structure + to getopt_long (). If you add or otherwise change this structure, you must + also change the string which follows it. */ +#define APROPOS_OPTION 1 +#define DRIBBLE_OPTION 2 +#define RESTORE_OPTION 3 +static struct option long_options[] = { + { "apropos", 1, 0, APROPOS_OPTION }, + { "directory", 1, 0, 'd' }, + { "node", 1, 0, 'n' }, + { "file", 1, 0, 'f' }, + { "subnodes", 0, &dump_subnodes, 1 }, + { "output", 1, 0, 'o' }, + { "help", 0, &print_help_p, 1 }, + { "version", 0, &print_version_p, 1 }, + { "dribble", 1, 0, DRIBBLE_OPTION }, + { "restore", 1, 0, RESTORE_OPTION }, + {NULL, 0, NULL, 0} +}; + +/* String describing the shorthand versions of the long options found above. */ +static char *short_options = "d:n:f:o:s"; + +/* When non-zero, the Info window system has been initialized. */ +int info_windows_initialized_p = 0; + +/* Some "forward" declarations. */ +static void usage (), info_short_help (), remember_info_program_name (); + + +/* **************************************************************** */ +/* */ +/* Main Entry Point to the Info Program */ +/* */ +/* **************************************************************** */ + +int +main (argc, argv) + int argc; + char **argv; +{ + int getopt_long_index; /* Index returned by getopt_long (). */ + NODE *initial_node; /* First node loaded by Info. */ + +#if defined (NeXT) && defined (NOTDEF) + malloc_debug (0x0ffffffff); +#endif /* NeXT && NOTDEF */ + + remember_info_program_name (argv[0]); + + while (1) + { + int option_character; + + option_character = getopt_long + (argc, argv, short_options, long_options, &getopt_long_index); + + /* getopt_long () returns EOF when there are no more long options. */ + if (option_character == EOF) + break; + + /* If this is a long option, then get the short version of it. */ + if (option_character == 0 && long_options[getopt_long_index].flag == 0) + option_character = long_options[getopt_long_index].val; + + /* Case on the option that we have received. */ + switch (option_character) + { + case 0: + break; + + /* User wants to add a directory. */ + case 'd': + info_add_path (optarg, INFOPATH_PREPEND); + break; + + /* User is specifying a particular node. */ + case 'n': + add_pointer_to_array (optarg, user_nodenames_index, user_nodenames, + user_nodenames_slots, 10, char *); + break; + + /* User is specifying a particular Info file. */ + case 'f': + if (user_filename) + free (user_filename); + + user_filename = savestring (optarg); + break; + + /* User is specifying the name of a file to output to. */ + case 'o': + if (user_output_filename) + free (user_output_filename); + user_output_filename = savestring (optarg); + break; + + /* User is specifying that she wishes to dump the subnodes of + the node that she is dumping. */ + case 's': + dump_subnodes = 1; + break; + + /* User has specified a string to search all indices for. */ + case APROPOS_OPTION: + apropos_p = 1; + maybe_free (apropos_search_string); + apropos_search_string = savestring (optarg); + break; + + /* User has specified a dribble file to receive keystrokes. */ + case DRIBBLE_OPTION: + close_dribble_file (); + open_dribble_file (optarg); + break; + + /* User has specified an alternate input stream. */ + case RESTORE_OPTION: + info_set_input_from_file (optarg); + break; + + default: + usage (); + } + } + + /* If the user specified --version, then show the version and exit. */ + if (print_version_p) + { + printf ("GNU Info, Version %s.\n", version_string ()); + exit (0); + } + + /* If the `--help' option was present, show the help and exit. */ + if (print_help_p) + { + info_short_help (); + exit (0); + } + + /* If the user hasn't specified a path for Info files, default that path + now. */ + if (!infopath) + { + char *path_from_env, *getenv (); + + path_from_env = getenv ("INFOPATH"); + + if (path_from_env) + info_add_path (path_from_env); + else + info_add_path (DEFAULT_INFOPATH); + } + + /* If the user specified a particular filename, add the path of that + file to the contents of INFOPATH. */ + if (user_filename) + { + char *directory_name, *temp; + + directory_name = savestring (user_filename); + temp = filename_non_directory (directory_name); + + if (temp != directory_name) + { + *temp = 0; + info_add_path (directory_name, INFOPATH_PREPEND); + } + + free (directory_name); + } + + /* If the user wants to search every known index for a given string, + do that now, and report the results. */ + if (apropos_p) + { + info_apropos (apropos_search_string); + exit (0); + } + + /* Get the initial Info node. It is either "(dir)Top", or what the user + specifed with values in user_filename and user_nodenames. */ + if (user_nodenames) + initial_node = info_get_node (user_filename, user_nodenames[0]); + else + initial_node = info_get_node (user_filename, (char *)NULL); + + /* If we couldn't get the initial node, this user is in trouble. */ + if (!initial_node) + { + if (info_recent_file_error) + info_error (info_recent_file_error); + else + info_error + (CANT_FIND_NODE, user_nodenames ? user_nodenames[0] : "Top"); + exit (1); + } + + /* Special cases for when the user specifies multiple nodes. If we are + dumping to an output file, dump all of the nodes specified. Otherwise, + attempt to create enough windows to handle the nodes that this user wants + displayed. */ + if (user_nodenames_index > 1) + { + free (initial_node); + + if (user_output_filename) + dump_nodes_to_file + (user_filename, user_nodenames, user_output_filename, dump_subnodes); + else + begin_multiple_window_info_session (user_filename, user_nodenames); + + exit (0); + } + + /* If there are arguments remaining, they are the names of menu items + in sequential info files starting from the first one loaded. That + file name is either "dir", or the contents of user_filename if one + was specified. */ + while (optind != argc) + { + REFERENCE **menu; + REFERENCE *entry; + NODE *node; + char *arg; + + /* Remember the name of the menu entry we want. */ + arg = argv[optind++]; + + /* Build and return a list of the menu items in this node. */ + menu = info_menu_of_node (initial_node); + + /* If there wasn't a menu item in this node, stop here, but let + the user continue to use Info. Perhaps they wanted this node + and didn't realize it. */ + if (!menu) + { + begin_info_session_with_error + (initial_node, "There is no menu in this node."); + exit (0); + } + + /* Find the specified menu item. */ + entry = info_get_labeled_reference (arg, menu); + + /* If the item wasn't found, search the list sloppily. Perhaps this + user typed "buffer" when they really meant "Buffers". */ + if (!entry) + { + register int i; + + for (i = 0; entry = menu[i]; i++) + if (strnicmp (entry->label, arg, strlen (arg)) == 0) + break; + } + + /* If we failed to find the reference, start Info with the current + node anyway. It is probably a misspelling. */ + if (!entry) + { + char *error_message = "There is no menu item \"%s\" in this node."; + + info_free_references (menu); + + /* If we were supposed to dump this node, complain. */ + if (user_output_filename) + info_error (error_message, arg); + else + begin_info_session_with_error (initial_node, error_message, arg); + + exit (0); + } + + /* We have found the reference that the user specified. Clean it + up a little bit. */ + if (!entry->filename) + { + if (initial_node->parent) + entry->filename = savestring (initial_node->parent); + else + entry->filename = savestring (initial_node->filename); + } + + /* Find this node. If we can find it, then turn the initial_node + into this one. If we cannot find it, try using the label of the + entry as a file (i.e., "(LABEL)Top"). Otherwise the Info file is + malformed in some way, and we will just use the current value of + initial node. */ + node = info_get_node (entry->filename, entry->nodename); + + if (!node && entry->nodename && + (strcmp (entry->label, entry->nodename) == 0)) + node = info_get_node (entry->label, "Top"); + + if (node) + { + free (initial_node); + initial_node = node; + info_free_references (menu); + } + else + { + char *temp = savestring (entry->label); + char *error_message; + + error_message = "Unable to find the node referenced by \"%s\"."; + + info_free_references (menu); + + /* If we were trying to dump the node, then give up. Otherwise, + start the session with an error message. */ + if (user_output_filename) + info_error (error_message, temp); + else + begin_info_session_with_error (initial_node, error_message, temp); + + exit (0); + } + } + + /* If the user specified that this node should be output, then do that + now. Otherwise, start the Info session with this node. */ + if (user_output_filename) + dump_node_to_file (initial_node, user_output_filename, dump_subnodes); + else + begin_info_session (initial_node); + + exit (0); +} + +/* Return a string describing the current version of Info. */ +char * +version_string () +{ + static char *vstring = (char *)NULL; + + if (!vstring) + { + vstring = (char *)xmalloc (50); + sprintf (vstring, "%d.%d", info_major_version, info_minor_version); + if (info_patch_level) + sprintf (vstring + strlen (vstring), "-p%d", info_patch_level); + } + return (vstring); +} + +/* **************************************************************** */ +/* */ +/* Error Handling for Info */ +/* */ +/* **************************************************************** */ + +static char *program_name = (char *)NULL; + +static void +remember_info_program_name (fullpath) + char *fullpath; +{ + char *filename; + + filename = filename_non_directory (fullpath); + program_name = savestring (filename); +} + +/* Non-zero if an error has been signalled. */ +int info_error_was_printed = 0; + +/* Non-zero means ring terminal bell on errors. */ +int info_error_rings_bell_p = 1; + +/* Print FORMAT with ARG1 and ARG2. If the window system was initialized, + then the message is printed in the echo area. Otherwise, a message is + output to stderr. */ +void +info_error (format, arg1, arg2) + char *format; + void *arg1, *arg2; +{ + info_error_was_printed = 1; + + if (!info_windows_initialized_p || display_inhibited) + { + fprintf (stderr, "%s: ", program_name); + fprintf (stderr, format, arg1, arg2); + fprintf (stderr, "\n"); + fflush (stderr); + } + else + { + if (!echo_area_is_active) + { + if (info_error_rings_bell_p) + terminal_ring_bell (); + window_message_in_echo_area (format, arg1, arg2); + } + else + { + NODE *temp; + + temp = build_message_node (format, arg1, arg2); + if (info_error_rings_bell_p) + terminal_ring_bell (); + inform_in_echo_area (temp->contents); + free (temp->contents); + free (temp); + } + } +} + +/* Produce a very brief descripton of the available options and exit with + an error. */ +static void +usage () +{ + fprintf (stderr,"%s\n%s\n%s\n%s\n%s\n", +"Usage: info [-d dir-path] [-f info-file] [-o output-file] [-n node-name]...", +" [--directory dir-path] [--file info-file] [--node node-name]...", +" [--help] [--output output-file] [--subnodes] [--version]", +" [--dribble dribble-file] [--restore from-file]", +" [menu-selection ...]"); + exit (1); +} + +/* Produce a scaled down description of the available options to Info. */ +static void +info_short_help () +{ + printf ("%s", "\ +Here is a quick description of Info's options. For a more complete\n\ +description of how to use Info, type `info info options'.\n\ +\n\ + --directory DIR Add DIR to INFOPATH.\n\ + --file FILENAME Specify Info file to visit.\n\ + --node NODENAME Specify nodes in first visited Info file.\n\ + --output FILENAME Output selected nodes to FILENAME.\n\ + --dribble FILENAME Remember user keystrokes in FILENAME.\n\ + --restore FILENAME Read initial keystrokes from FILENAME.\n\ + --subnodes Recursively output menu items.\n\ + --help Get this help message.\n\ + --version Display Info's version information.\n\ +\n\ +Remaining arguments to Info are treated as the names of menu\n\ +items in the initial node visited. You can easily move to the\n\ +node of your choice by specifying the menu names which describe\n\ +the path to that node. For example, `info emacs buffers'.\n"); + + exit (0); +} diff --git a/gnu/usr.bin/texinfo/info/info.h b/gnu/usr.bin/texinfo/info/info.h new file mode 100644 index 0000000..09e40c2 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/info.h @@ -0,0 +1,96 @@ +/* info.h -- Header file which includes all of the other headers. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#ifndef _INFO_H_ +#define _INFO_H_ + +#include <stdio.h> +#include <ctype.h> +#include <sys/types.h> +#include <sys/stat.h> +#include "filesys.h" +#include "display.h" +#include "session.h" +#include "echo_area.h" +#include "doc.h" +#include "footnotes.h" +#include "gc.h" + +/* A structure associating the nodes visited in a particular window. */ +typedef struct { + WINDOW *window; /* The window that this list is attached to. */ + NODE **nodes; /* Array of nodes visited in this window. */ + int *pagetops; /* For each node in NODES, the pagetop. */ + long *points; /* For each node in NODES, the point. */ + int current; /* Index in NODES of the current node. */ + int nodes_index; /* Index where to add the next node. */ + int nodes_slots; /* Number of slots allocated to NODES. */ +} INFO_WINDOW; + +/* Array of structures describing for each window which nodes have been + visited in that window. */ +extern INFO_WINDOW **info_windows; + +/* For handling errors. If you initialize the window system, you should + also set info_windows_initialized_p to non-zero. It is used by the + info_error () function to determine how to format and output errors. */ +extern int info_windows_initialized_p; + +/* Non-zero if an error message has been printed. */ +extern int info_error_was_printed; + +/* Non-zero means ring terminal bell on errors. */ +extern int info_error_rings_bell_p; + +/* Print FORMAT with ARG1 and ARG2. If the window system was initialized, + then the message is printed in the echo area. Otherwise, a message is + output to stderr. */ +extern void info_error (); + +/* The version numbers of Info. */ +extern int info_major_version, info_minor_version, info_patch_level; + +/* How to get the version string for this version of Info. Returns + something similar to "2.9". */ +extern char *version_string (); + +/* Error message defines. */ +#define CANT_FIND_NODE "Cannot find the node \"%s\"." +#define CANT_FILE_NODE "Cannot find the node \"(%s)%s\"." +#define CANT_FIND_WIND "Cannot find a window!" +#define CANT_FIND_POINT "Point doesn't appear within this window's node!" +#define CANT_KILL_LAST "Cannot delete the last window." +#define NO_MENU_NODE "No menu in this node." +#define NO_FOOT_NODE "No footnotes in this node." +#define NO_XREF_NODE "No cross references in this node." +#define NO_POINTER "No \"%s\" pointer for this node." +#define UNKNOWN_COMMAND "Unknown Info command `%c'. `?' for help." +#define TERM_TOO_DUMB "Terminal type \"%s\" is not smart enough to run Info." +#define AT_NODE_BOTTOM "You are already at the last page of this node." +#define AT_NODE_TOP "You are already at the first page of this node." +#define ONE_WINDOW "Only one window." +#define WIN_TOO_SMALL "Resulting window would be too small." +#define CANT_MAKE_HELP \ +"There isn't enough room to make a help window. Please delete a window." + +#endif /* !_INFO_H_ */ diff --git a/gnu/usr.bin/texinfo/info/info.info b/gnu/usr.bin/texinfo/info/info.info new file mode 100644 index 0000000..b6fd850 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/info.info @@ -0,0 +1,777 @@ +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/infodoc.c b/gnu/usr.bin/texinfo/info/infodoc.c new file mode 100644 index 0000000..2fcbf0f --- /dev/null +++ b/gnu/usr.bin/texinfo/info/infodoc.c @@ -0,0 +1,689 @@ +/* infohelp.c -- Functions which build documentation nodes. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#include "info.h" + +/* **************************************************************** */ +/* */ +/* Info Help Windows */ +/* */ +/* **************************************************************** */ + +/* The name of the node used in the help window. */ +static char *info_help_nodename = "*Info Help*"; + +/* A node containing printed key bindings and their documentation. */ +static NODE *internal_info_help_node = (NODE *)NULL; + +/* The static text which appears in the internal info help node. */ +static char *info_internal_help_text[] = { + "Basic Commands in Info Windows", + "******************************", + "", + " h Invoke the Info tutorial.", + "", + "Selecting other nodes:", + "----------------------", + " n Move to the \"next\" node of this node.", + " p Move to the \"previous\" node of this node.", + " u Move \"up\" from this node.", + " m Pick menu item specified by name.", + " Picking a menu item causes another node to be selected.", + " f Follow a cross reference. Reads name of reference.", + " l Move to the last node seen in this window.", + " d Move to the `directory' node. Equivalent to `g(DIR)'.", + "", + "Moving within a node:", + "---------------------", + " SPC Scroll forward a page.", + " DEL Scroll backward a page.", + " b Go to the beginning of this node.", + " e Go to the end of this node.", + "", + "\"Advanced\" commands:", + "--------------------", + " q Quit Info.", + " 1 Pick first item in node's menu.", + " 2-9 Pick second ... ninth item in node's menu.", + " 0 Pick last item in node's menu.", + " g Move to node specified by name.", + " You may include a filename as well, as in (FILENAME)NODENAME.", + " s Search through this Info file for a specified string,", + " and select the node in which the next occurrence is found.", + (char *)NULL +}; + +void +dump_map_to_message_buffer (prefix, map) + char *prefix; + Keymap map; +{ + register int i; + + for (i = 0; i < 256; i++) + { + if (map[i].type == ISKMAP) + { + char *new_prefix, *keyname; + + keyname = pretty_keyname (i); + new_prefix = (char *) + xmalloc (3 + strlen (prefix) + strlen (keyname)); + sprintf (new_prefix, "%s%s%s ", prefix, *prefix ? " " : "", keyname); + + dump_map_to_message_buffer (new_prefix, (Keymap)map[i].function); + free (new_prefix); + } + else if (map[i].function) + { + register int last; + char *doc, *name; + + doc = function_documentation (map[i].function); + name = function_name (map[i].function); + + if (!*doc) + continue; + + /* Find out if there is a series of identical functions, as in + ea_insert (). */ + for (last = i + 1; last < 256; last++) + if ((map[last].type != ISFUNC) || + (map[last].function != map[i].function)) + break; + + if (last - 1 != i) + { + printf_to_message_buffer + ("%s%s .. ", prefix, pretty_keyname (i)); + printf_to_message_buffer + ("%s%s\t", prefix, pretty_keyname (last - 1)); + i = last - 1; + } + else + printf_to_message_buffer ("%s%s\t", prefix, pretty_keyname (i)); + +#if defined (NAMED_FUNCTIONS) + /* Print the name of the function, and some padding before the + documentation string is printed. */ + { + int length_so_far; + int desired_doc_start = 40; /* Must be multiple of 8. */ + + printf_to_message_buffer ("(%s)", name); + length_so_far = message_buffer_length_this_line (); + + if ((desired_doc_start + strlen (doc)) >= the_screen->width) + printf_to_message_buffer ("\n "); + else + { + while (length_so_far < desired_doc_start) + { + printf_to_message_buffer ("\t"); + length_so_far += character_width ('\t', length_so_far); + } + } + } +#endif /* NAMED_FUNCTIONS */ + printf_to_message_buffer ("%s\n", doc); + } + } +} + +/* How to create internal_info_help_node. */ +static void +create_internal_info_help_node () +{ + register int i; + + initialize_message_buffer (); + + for (i = 0; info_internal_help_text[i]; i++) + printf_to_message_buffer ("%s\n", info_internal_help_text[i]); + + printf_to_message_buffer ("---------------------\n\n"); + printf_to_message_buffer ("The current search path is:\n"); + printf_to_message_buffer (" \"%s\"\n", infopath); + printf_to_message_buffer ("---------------------\n\n"); + printf_to_message_buffer ("Commands available in Info windows:\n\n"); + dump_map_to_message_buffer ("", info_keymap); + printf_to_message_buffer ("---------------------\n\n"); + printf_to_message_buffer ("Commands available in the echo area:\n\n"); + dump_map_to_message_buffer ("", echo_area_keymap); + + { + char *message; + + message = replace_in_documentation + ("--- Use `\\[history-node]' or `\\[kill-node]' to exit ---\n"); + printf_to_message_buffer ("%s", message); + } + + internal_info_help_node = message_buffer_to_node (); + add_gcable_pointer (internal_info_help_node->contents); + name_internal_node (internal_info_help_node, info_help_nodename); + + /* Even though this is an internal node, we don't want the window + system to treat it specially. So we turn off the internalness + of it here. */ + internal_info_help_node->flags &= ~N_IsInternal; +} + +/* Return a window which is the window showing help in this Info. */ +static WINDOW * +info_find_or_create_help_window () +{ + WINDOW *help_window; + + help_window = get_internal_info_window (info_help_nodename); + + /* If we couldn't find the help window, then make it. */ + if (!help_window) + { + WINDOW *window, *eligible = (WINDOW *)NULL; + int max = 0; + + for (window = windows; window; window = window->next) + { + if (window->height > max) + { + max = window->height; + eligible = window; + } + } + + if (!eligible) + return ((WINDOW *)NULL); + else + { + /* Make a new node containing the help text. Split the largest + window into 2 windows, and show the help text in that window. */ + if (!internal_info_help_node) + create_internal_info_help_node (); + + if (eligible->height > 30) + { + active_window = eligible; + help_window = window_make_window (internal_info_help_node); + } + else + { + set_remembered_pagetop_and_point (active_window); + window_set_node_of_window + (active_window, internal_info_help_node); + help_window = active_window; + } + + remember_window_and_node (help_window, help_window->node); + } + } + return (help_window); +} + +/* Create or move to the help window. */ +DECLARE_INFO_COMMAND (info_get_help_window, "Display help message") +{ + WINDOW *help_window; + + help_window = info_find_or_create_help_window (); + if (help_window) + { + active_window = help_window; + active_window->flags |= W_UpdateWindow; + } + else + { + info_error (CANT_MAKE_HELP); + } +} + +/* Show the Info help node. This means that the "info" file is installed + where it can easily be found on your system. */ +DECLARE_INFO_COMMAND (info_get_info_help_node, "Visit Info node `(info)Help'") +{ + NODE *node; + char *nodename; + + /* If there is a window on the screen showing the node "(info)Help" or + the node "(info)Help-Small-Screen", simply select that window. */ + { + WINDOW *win; + + for (win = windows; win; win = win->next) + { + if (win->node && win->node->filename && + (stricmp + (filename_non_directory (win->node->filename), "info") == 0) && + ((strcmp (win->node->nodename, "Help") == 0) || + (strcmp (win->node->nodename, "Help-Small-Screen") == 0))) + { + active_window = win; + return; + } + } + } + + /* If the current window is small, show the small screen help. */ + if (active_window->height < 24) + nodename = "Help-Small-Screen"; + else + nodename = "Help"; + + /* Try to get the info file for Info. */ + node = info_get_node ("Info", nodename); + + if (!node) + { + if (info_recent_file_error) + info_error (info_recent_file_error); + else + info_error (CANT_FILE_NODE, "Info", nodename); + } + else + { + /* If the current window is very large (greater than 45 lines), + then split it and show the help node in another window. + Otherwise, use the current window. */ + + if (active_window->height > 45) + active_window = window_make_window (node); + else + { + set_remembered_pagetop_and_point (active_window); + window_set_node_of_window (active_window, node); + } + + remember_window_and_node (active_window, node); + } +} + +/* **************************************************************** */ +/* */ +/* Groveling Info Keymaps and Docs */ +/* */ +/* **************************************************************** */ + +/* Return the documentation associated with the Info command FUNCTION. */ +char * +function_documentation (function) + VFunction *function; +{ + register int i; + + for (i = 0; function_doc_array[i].func; i++) + if (function == function_doc_array[i].func) + break; + + return (replace_in_documentation (function_doc_array[i].doc)); +} + +#if defined (NAMED_FUNCTIONS) +/* Return the user-visible name of the function associated with the + Info command FUNCTION. */ +char * +function_name (function) + + VFunction *function; +{ + register int i; + + for (i = 0; function_doc_array[i].func; i++) + if (function == function_doc_array[i].func) + break; + + return (function_doc_array[i].func_name); +} + +/* Return a pointer to the function named NAME. */ +VFunction * +named_function (name) + char *name; +{ + register int i; + + for (i = 0; function_doc_array[i].func; i++) + if (strcmp (function_doc_array[i].func_name, name) == 0) + break; + + return (function_doc_array[i].func); +} +#endif /* NAMED_FUNCTIONS */ + +/* Return the documentation associated with KEY in MAP. */ +char * +key_documentation (key, map) + char key; + Keymap map; +{ + VFunction *function = map[key].function; + + if (function) + return (function_documentation (function)); + else + return ((char *)NULL); +} + +DECLARE_INFO_COMMAND (describe_key, "Print documentation for KEY") +{ + char keyname[50]; + int keyname_index = 0; + unsigned char keystroke; + char *rep; + Keymap map; + + keyname[0] = '\0'; + map = window->keymap; + + while (1) + { + message_in_echo_area ("Describe key: %s", keyname); + keystroke = info_get_input_char (); + unmessage_in_echo_area (); + + if (Meta_p (keystroke) && (!ISO_Latin_p || key < 160)) + { + if (map[ESC].type != ISKMAP) + { + window_message_in_echo_area + ("ESC %s is undefined.", pretty_keyname (UnMeta (keystroke))); + return; + } + + strcpy (keyname + keyname_index, "ESC "); + keyname_index = strlen (keyname); + keystroke = UnMeta (keystroke); + map = (Keymap)map[ESC].function; + } + + /* Add the printed representation of KEYSTROKE to our keyname. */ + rep = pretty_keyname (keystroke); + strcpy (keyname + keyname_index, rep); + keyname_index = strlen (keyname); + + if (map[keystroke].function == (VFunction *)NULL) + { + message_in_echo_area ("%s is undefined.", keyname); + return; + } + else if (map[keystroke].type == ISKMAP) + { + map = (Keymap)map[keystroke].function; + strcat (keyname, " "); + keyname_index = strlen (keyname); + continue; + } + else + { + char *message, *fundoc, *funname = ""; + +#if defined (NAMED_FUNCTIONS) + funname = function_name (map[keystroke].function); +#endif /* NAMED_FUNCTIONS */ + + fundoc = function_documentation (map[keystroke].function); + + message = (char *)xmalloc + (10 + strlen (keyname) + strlen (fundoc) + strlen (funname)); + +#if defined (NAMED_FUNCTIONS) + sprintf (message, "%s (%s): %s.", keyname, funname, fundoc); +#else + sprintf (message, "%s is defined to %s.", keyname, fundoc); +#endif /* !NAMED_FUNCTIONS */ + + window_message_in_echo_area ("%s", message); + free (message); + break; + } + } +} + +/* How to get the pretty printable name of a character. */ +static char rep_buffer[30]; + +char * +pretty_keyname (key) + unsigned char key; +{ + char *rep; + + if (Meta_p (key)) + { + char temp[20]; + + rep = pretty_keyname (UnMeta (key)); + + sprintf (temp, "ESC %s", rep); + strcpy (rep_buffer, temp); + rep = rep_buffer; + } + else if (Control_p (key)) + { + switch (key) + { + case '\n': rep = "LFD"; break; + case '\t': rep = "TAB"; break; + case '\r': rep = "RET"; break; + case ESC: rep = "ESC"; break; + + default: + sprintf (rep_buffer, "C-%c", UnControl (key)); + rep = rep_buffer; + } + } + else + { + switch (key) + { + case ' ': rep = "SPC"; break; + case DEL: rep = "DEL"; break; + default: + rep_buffer[0] = key; + rep_buffer[1] = '\0'; + rep = rep_buffer; + } + } + return (rep); +} + +/* Replace the names of functions with the key that invokes them. */ +static char *where_is (), *where_is_internal (); + +char * +replace_in_documentation (string) + char *string; +{ + register int i, start, next; + static char *result = (char *)NULL; + + maybe_free (result); + result = (char *)xmalloc (1 + strlen (string)); + + i = next = start = 0; + + /* Skip to the beginning of a replaceable function. */ + for (i = start; string[i]; i++) + { + /* Is this the start of a replaceable function name? */ + if (string[i] == '\\' && string[i + 1] == '[') + { + char *fun_name, *rep; + VFunction *function; + + /* Copy in the old text. */ + strncpy (result + next, string + start, i - start); + next += (i - start); + start = i + 2; + + /* Move to the end of the function name. */ + for (i = start; string[i] && (string[i] != ']'); i++); + + fun_name = (char *)xmalloc (1 + i - start); + strncpy (fun_name, string + start, i - start); + fun_name[i - start] = '\0'; + + /* Find a key which invokes this function in the info_keymap. */ + function = named_function (fun_name); + + /* If the internal documentation string fails, there is a + serious problem with the associated command's documentation. + We croak so that it can be fixed immediately. */ + if (!function) + abort (); + + rep = where_is (info_keymap, function); + strcpy (result + next, rep); + next = strlen (result); + + start = i; + if (string[i]) + start++; + } + } + strcpy (result + next, string + start); + return (result); +} + +/* Return a string of characters which could be typed from the keymap + MAP to invoke FUNCTION. */ +static char *where_is_rep = (char *)NULL; +static int where_is_rep_index = 0; +static int where_is_rep_size = 0; + +static char * +where_is (map, function) + Keymap map; + VFunction *function; +{ + char *rep; + + if (!where_is_rep_size) + where_is_rep = (char *)xmalloc (where_is_rep_size = 100); + where_is_rep_index = 0; + + rep = where_is_internal (map, function); + + /* If it couldn't be found, return "M-x Foo". */ + if (!rep) + { + char *name; + + name = function_name (function); + + if (name) + sprintf (where_is_rep, "M-x %s", name); + + rep = where_is_rep; + } + return (rep); +} + +/* Return the printed rep of FUNCTION as found in MAP, or NULL. */ +static char * +where_is_internal (map, function) + Keymap map; + VFunction *function; +{ + register int i; + + /* If the function is directly invokable in MAP, return the representation + of that keystroke. */ + for (i = 0; i < 256; i++) + if ((map[i].type == ISFUNC) && map[i].function == function) + { + sprintf (where_is_rep + where_is_rep_index, "%s", pretty_keyname (i)); + return (where_is_rep); + } + + /* Okay, search subsequent maps for this function. */ + for (i = 0; i < 256; i++) + { + if (map[i].type == ISKMAP) + { + int saved_index = where_is_rep_index; + char *rep; + + sprintf (where_is_rep + where_is_rep_index, "%s ", + pretty_keyname (i)); + + where_is_rep_index = strlen (where_is_rep); + rep = where_is_internal ((Keymap)map[i].function, function); + + if (rep) + return (where_is_rep); + + where_is_rep_index = saved_index; + } + } + + return ((char *)NULL); +} + +extern char *read_function_name (); + +DECLARE_INFO_COMMAND (info_where_is, + "Show what to type to execute a given command") +{ + char *command_name; + + command_name = read_function_name ("Where is command: ", window); + + if (!command_name) + { + info_abort_key (active_window, count, key); + return; + } + + if (*command_name) + { + VFunction *function; + + function = named_function (command_name); + + if (function) + { + char *location; + + location = where_is (active_window->keymap, function); + + if (!location) + { + info_error ("`%s' is not on any keys", command_name); + } + else + { + if (strncmp (location, "M-x ", 4) == 0) + window_message_in_echo_area + ("%s can only be invoked via %s.", command_name, location); + else + window_message_in_echo_area + ("%s can be invoked via %s.", command_name, location); + } + } + else + info_error ("There is no function named `%s'", command_name); + } + + free (command_name); +} + diff --git a/gnu/usr.bin/texinfo/info/infomap.c b/gnu/usr.bin/texinfo/info/infomap.c new file mode 100644 index 0000000..47eafa9 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/infomap.c @@ -0,0 +1,269 @@ +/* infomap.c -- Keymaps for Info. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#include "stdio.h" +#include "ctype.h" +#include "infomap.h" +#include "funs.h" + +/* Return a new keymap which has all the uppercase letters mapped to run + the function info_do_lowercase_version (). */ +Keymap +keymap_make_keymap () +{ + register int i; + Keymap keymap; + + keymap = (Keymap)xmalloc (256 * sizeof (KEYMAP_ENTRY)); + + for (i = 0; i < 256; i++) + { + keymap[i].type = ISFUNC; + keymap[i].function = (VFunction *)NULL; + } + + for (i = 'A'; i < ('Z' + 1); i++) + { + keymap[i].type = ISFUNC; + keymap[i].function = info_do_lowercase_version; + } + + return (keymap); +} + +/* Return a new keymap which is a copy of MAP. */ +Keymap +keymap_copy_keymap (map) + Keymap map; +{ + register int i; + Keymap keymap; + + keymap = keymap_make_keymap (); + + for (i = 0; i < 256; i++) + { + keymap[i].type = map[i].type; + keymap[i].function = map[i].function; + } + return (keymap); +} + +/* Free the keymap and it's descendents. */ +void +keymap_discard_keymap (map) + Keymap (map); +{ + register int i; + + if (!map) + return; + + for (i = 0; i < 256; i++) + { + switch (map[i].type) + { + case ISFUNC: + break; + + case ISKMAP: + keymap_discard_keymap ((Keymap)map[i].function); + break; + + } + } +} + +/* Initialize the standard info keymaps. */ + +Keymap info_keymap = (Keymap)NULL; +Keymap echo_area_keymap = (Keymap)NULL; + +void +initialize_info_keymaps () +{ + register int i; + Keymap map; + + if (!info_keymap) + { + info_keymap = keymap_make_keymap (); + info_keymap[ESC].type = ISKMAP; + info_keymap[ESC].function = (VFunction *)keymap_make_keymap (); + info_keymap[Control ('x')].type = ISKMAP; + info_keymap[Control ('x')].function = (VFunction *)keymap_make_keymap (); + echo_area_keymap = keymap_make_keymap (); + echo_area_keymap[ESC].type = ISKMAP; + echo_area_keymap[ESC].function = (VFunction *)keymap_make_keymap (); + echo_area_keymap[Control ('x')].type = ISKMAP; + echo_area_keymap[Control ('x')].function = + (VFunction *)keymap_make_keymap (); + } + + /* Bind numeric arg functions for both echo area and info window maps. */ + for (i = '0'; i < '9' + 1; i++) + { + ((Keymap) info_keymap[ESC].function)[i].function = + ((Keymap) echo_area_keymap[ESC].function)[i].function = + info_add_digit_to_numeric_arg; + } + ((Keymap) info_keymap[ESC].function)['-'].function = + ((Keymap) echo_area_keymap[ESC].function)['-'].function = + info_add_digit_to_numeric_arg; + + /* Bind the echo area routines. */ + map = echo_area_keymap; + + /* Bind the echo area insert routines. */ + for (i = 0; i < 160; i++) + if (isprint (i)) + map[i].function = ea_insert; + + map[Control ('a')].function = ea_beg_of_line; + map[Control ('b')].function = ea_backward; + map[Control ('d')].function = ea_delete; + map[Control ('e')].function = ea_end_of_line; + map[Control ('f')].function = ea_forward; + map[Control ('g')].function = ea_abort; + map[Control ('h')].function = ea_rubout; + map[Control ('k')].function = ea_kill_line; + map[Control ('l')].function = info_redraw_display; + map[Control ('q')].function = ea_quoted_insert; + map[Control ('t')].function = ea_transpose_chars; + map[Control ('u')].function = info_universal_argument; + map[Control ('y')].function = ea_yank; + + map[LFD].function = ea_newline; + map[RET].function = ea_newline; + map[SPC].function = ea_complete; + map[TAB].function = ea_complete; + map['?'].function = ea_possible_completions; + map[DEL].function = ea_rubout; + + /* Bind the echo area ESC keymap. */ + map = (Keymap)echo_area_keymap[ESC].function; + + map[Control ('g')].function = ea_abort; + map[Control ('v')].function = ea_scroll_completions_window; + map['b'].function = ea_backward_word; + map['d'].function = ea_kill_word; + map['f'].function = ea_forward_word; +#if defined (NAMED_FUNCTIONS) + /* map['x'].function = info_execute_command; */ +#endif /* NAMED_FUNCTIONS */ + map['y'].function = ea_yank_pop; + map['?'].function = ea_possible_completions; + map[TAB].function = ea_tab_insert; + map[DEL].function = ea_backward_kill_word; + + /* Bind the echo area Control-x keymap. */ + map = (Keymap)echo_area_keymap[Control ('x')].function; + + map['o'].function = info_next_window; + map[DEL].function = ea_backward_kill_line; + + /* Bind commands for Info window keymaps. */ + map = info_keymap; + map[TAB].function = info_move_to_next_xref; + map[LFD].function = info_select_reference_this_line; + map[RET].function = info_select_reference_this_line; + map[SPC].function = info_scroll_forward; + map[Control ('a')].function = info_beginning_of_line; + map[Control ('b')].function = info_backward_char; + map[Control ('e')].function = info_end_of_line; + map[Control ('f')].function = info_forward_char; + map[Control ('g')].function = info_abort_key; + map[Control ('h')].function = info_get_help_window; + map[Control ('l')].function = info_redraw_display; + map[Control ('n')].function = info_next_line; + map[Control ('p')].function = info_prev_line; + map[Control ('r')].function = isearch_backward; + map[Control ('s')].function = isearch_forward; + map[Control ('u')].function = info_universal_argument; + map[Control ('v')].function = info_scroll_forward; + map[','].function = info_next_index_match; + + for (i = '1'; i < '9' + 1; i++) + map[i].function = info_menu_digit; + map['0'].function = info_last_menu_item; + + map['<'].function = info_first_node; + map['>'].function = info_last_node; + map['?'].function = info_get_help_window; + map['['].function = info_global_prev_node; + map[']'].function = info_global_next_node; + + map['b'].function = info_beginning_of_node; + map['d'].function = info_dir_node; + map['e'].function = info_end_of_node; + map['f'].function = info_xref_item; + map['g'].function = info_goto_node; + map['h'].function = info_get_info_help_node; + map['i'].function = info_index_search; + map['l'].function = info_history_node; + map['m'].function = info_menu_item; + map['n'].function = info_next_node; + map['p'].function = info_prev_node; + map['q'].function = info_quit; + map['r'].function = info_xref_item; + map['s'].function = info_search; + map['t'].function = info_top_node; + map['u'].function = info_up_node; + map[DEL].function = info_scroll_backward; + + /* Bind members in the ESC map for Info windows. */ + map = (Keymap)info_keymap[ESC].function; + map[Control ('f')].function = info_show_footnotes; + map[Control ('g')].function = info_abort_key; + map[TAB].function = info_move_to_prev_xref; + map[Control ('v')].function = info_scroll_other_window; + map['<'].function = info_beginning_of_node; + map['>'].function = info_end_of_node; + map['b'].function = info_backward_word; + map['f'].function = info_forward_word; + map['r'].function = info_move_to_window_line; + map['v'].function = info_scroll_backward; +#if defined (NAMED_FUNCTIONS) + map['x'].function = info_execute_command; +#endif /* NAMED_FUNCTIONS */ + + /* Bind members in the Control-X map for Info windows. */ + map = (Keymap)info_keymap[Control ('x')].function; + + map[Control ('b')].function = list_visited_nodes; + map[Control ('c')].function = info_quit; + map[Control ('f')].function = info_view_file; + map[Control ('g')].function = info_abort_key; + map[Control ('v')].function = info_view_file; + map['0'].function = info_delete_window; + map['1'].function = info_keep_one_window; + map['2'].function = info_split_window; + map['^'].function = info_grow_window; + map['b'].function = select_visited_node; + map['k'].function = info_kill_node; + map['o'].function = info_next_window; + map['t'].function = info_tile_windows; + map['w'].function = info_toggle_wrap; +} + + diff --git a/gnu/usr.bin/texinfo/info/infomap.h b/gnu/usr.bin/texinfo/info/infomap.h new file mode 100644 index 0000000..43d160d --- /dev/null +++ b/gnu/usr.bin/texinfo/info/infomap.h @@ -0,0 +1,82 @@ +/* infomap.h -- Description of a keymap in Info and related functions. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#ifndef _INFOMAP_H_ +#define _INFOMAP_H_ + +#include "general.h" + +#define ESC '\033' +#define DEL '\177' +#define TAB '\011' +#define RET '\r' +#define LFD '\n' +#define SPC ' ' + +#define meta_character_threshold (DEL + 1) +#define control_character_threshold (SPC) + +#define meta_character_bit 0x80 +#define control_character_bit 0x40 + +#define Meta_p(c) (((c) > meta_character_threshold)) +#define Control_p(c) ((c) < control_character_threshold) + +#define Meta(c) ((c) | (meta_character_bit)) +#define UnMeta(c) ((c) & (~meta_character_bit)) +#define Control(c) ((toupper (c)) & (~control_character_bit)) +#define UnControl(c) (tolower ((c) | control_character_bit)) + +/* A keymap contains one entry for each key in the ASCII set. + Each entry consists of a type and a pointer. + FUNCTION is the address of a function to run, or the + address of a keymap to indirect through. + TYPE says which kind of thing FUNCTION is. */ +typedef struct { + char type; + VFunction *function; +} KEYMAP_ENTRY; + +typedef KEYMAP_ENTRY *Keymap; + +/* The values that TYPE can have in a keymap entry. */ +#define ISFUNC 0 +#define ISKMAP 1 + +extern Keymap info_keymap; +extern Keymap echo_area_keymap; + +/* Return a new keymap which has all the uppercase letters mapped to run + the function info_do_lowercase_version (). */ +extern Keymap keymap_make_keymap (); + +/* Return a new keymap which is a copy of MAP. */ +extern Keymap keymap_copy_keymap (); + +/* Free MAP and it's descendents. */ +extern void keymap_discard_keymap (); + +/* Initialize the info keymaps. */ +extern void initialize_info_keymaps (); + +#endif /* _INFOMAP_H_ */ diff --git a/gnu/usr.bin/texinfo/info/m-x.c b/gnu/usr.bin/texinfo/info/m-x.c new file mode 100644 index 0000000..13a861f --- /dev/null +++ b/gnu/usr.bin/texinfo/info/m-x.c @@ -0,0 +1,195 @@ +/* m-x.c -- Meta-X minibuffer reader. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#include "info.h" + +/* **************************************************************** */ +/* */ +/* Reading Named Commands */ +/* */ +/* **************************************************************** */ + +/* Read the name of an Info function in the echo area and return the + name. A return value of NULL indicates that no function name could + be read. */ +char * +read_function_name (prompt, window) + char *prompt; + WINDOW *window; +{ + register int i; + char *line; + REFERENCE **array = (REFERENCE **)NULL; + int array_index = 0, array_slots = 0; + + /* Make an array of REFERENCE which actually contains the names of + the functions available in Info. */ + for (i = 0; function_doc_array[i].func; i++) + { + REFERENCE *entry; + + entry = (REFERENCE *)xmalloc (sizeof (REFERENCE)); + entry->label = savestring (function_doc_array[i].func_name); + entry->nodename = (char *)NULL; + entry->filename = (char *)NULL; + + add_pointer_to_array + (entry, array_index, array, array_slots, 200, REFERENCE *); + } + + line = info_read_completing_in_echo_area (window, prompt, array); + + info_free_references (array); + + if (!echo_area_is_active) + window_clear_echo_area (); + + return (line); +} + +DECLARE_INFO_COMMAND (describe_command, + "Read the name of an Info command and describe it") +{ + char *line; + + line = read_function_name ("Describe command: ", window); + + if (!line) + { + info_abort_key (active_window, count, key); + return; + } + + /* Describe the function named in "LINE". */ + if (*line) + { + char *fundoc; + VFunction *fun; + + fun = named_function (line); + + if (!fun) + return; + + window_message_in_echo_area ("%s: %s.", + line, function_documentation (fun)); + } + free (line); +} + +DECLARE_INFO_COMMAND (info_execute_command, + "Read a command name in the echo area and execute it") +{ + char *line; + + /* Ask the completer to read a reference for us. */ + if (info_explicit_arg || count != 1) + { + char *prompt; + + prompt = (char *)xmalloc (20); + sprintf (prompt, "%d M-x ", count); + line = read_function_name (prompt, window); + } + else + line = read_function_name ("M-x ", window); + + /* User aborted? */ + if (!line) + { + info_abort_key (active_window, count, key); + return; + } + + /* User accepted "default"? (There is none.) */ + if (!*line) + { + free (line); + return; + } + + /* User wants to execute a named command. Do it. */ + { + VFunction *function; + + if ((active_window != the_echo_area) && + (strncmp (line, "echo-area-", 10) == 0)) + { + free (line); + info_error ("Cannot execute an `echo-area' command here."); + return; + } + + function = named_function (line); + free (line); + + if (!function) + return; + + (*function) (active_window, count, 0); + } +} + +/* Okay, now that we have M-x, let the user set the screen height. */ +DECLARE_INFO_COMMAND (set_screen_height, + "Set the height of the displayed window") +{ + int new_height; + + if (info_explicit_arg || count != 1) + new_height = count; + else + { + char prompt[80]; + char *line; + + new_height = screenheight; + + sprintf (prompt, "Set screen height to (%d): ", new_height); + + line = info_read_in_echo_area (window, prompt); + + /* If the user aborted, do that now. */ + if (!line) + { + info_abort_key (active_window, count, 0); + return; + } + + /* Find out what the new height is supposed to be. */ + if (*line) + new_height = atoi (line); + + /* Clear the echo area if it isn't active. */ + if (!echo_area_is_active) + window_clear_echo_area (); + + free (line); + } + + terminal_clear_screen (); + display_clear_display (the_display); + screenheight = new_height; + display_initialize_display (screenwidth, screenheight); + window_new_screen_size (screenwidth, screenheight); +} diff --git a/gnu/usr.bin/texinfo/info/nodemenu.c b/gnu/usr.bin/texinfo/info/nodemenu.c new file mode 100644 index 0000000..674ea7c --- /dev/null +++ b/gnu/usr.bin/texinfo/info/nodemenu.c @@ -0,0 +1,321 @@ +/* nodemenu.c -- Produce a menu of all visited nodes. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#include "info.h" + +/* Return a line describing the format of a node information line. */ +static char * +nodemenu_format_info () +{ + return ("\n\ +* Menu:\n\ + (File)Node Lines Size Containing File\n\ + ---------- ----- ---- ---------------"); +} + +/* Produce a formatted line of information about NODE. Here is what we want + the output listing to look like: + +* Menu: + (File)Node Lines Size Containing File + ---------- ----- ---- --------------- +* (emacs)Buffers:: 48 2230 /usr/gnu/info/emacs/emacs-1 +* (autoconf)Writing configure.in:: 123 58789 /usr/gnu/info/autoconf/autoconf-1 +* (dir)Top:: 40 589 /usr/gnu/info/dir +*/ +static char * +format_node_info (node) + NODE *node; +{ + register int i, len; + char *parent, *containing_file; + static char *line_buffer = (char *)NULL; + + if (!line_buffer) + line_buffer = (char *)xmalloc (1000); + + if (node->parent) + { + parent = filename_non_directory (node->parent); + if (!parent) + parent = node->parent; + } + else + parent = (char *)NULL; + + containing_file = node->filename; + + if (!parent && !*containing_file) + sprintf (line_buffer, "* %s::", node->nodename); + else + { + char *file = (char *)NULL; + + if (parent) + file = parent; + else + file = filename_non_directory (containing_file); + + if (!file) + file = containing_file; + + if (!*file) + file = "dir"; + + sprintf (line_buffer, "* (%s)%s::", file, node->nodename); + } + + len = pad_to (36, line_buffer); + + { + int lines = 1; + + for (i = 0; i < node->nodelen; i++) + if (node->contents[i] == '\n') + lines++; + + sprintf (line_buffer + len, "%d", lines); + } + + len = pad_to (44, line_buffer); + sprintf (line_buffer + len, "%d", node->nodelen); + + if (node->filename && *(node->filename)) + { + len = pad_to (51, line_buffer); + sprintf (line_buffer + len, node->filename); + } + + return (savestring (line_buffer)); +} + +/* Little string comparison routine for qsort (). */ +static int +compare_strings (string1, string2) + char **string1, **string2; +{ + return (stricmp (*string1, *string2)); +} + +/* The name of the nodemenu node. */ +static char *nodemenu_nodename = "*Node Menu*"; + +/* Produce an informative listing of all the visited nodes, and return it + in a node. If FILTER_FUNC is non-null, it is a function which filters + which nodes will appear in the listing. FILTER_FUNC takes an argument + of NODE, and returns non-zero if the node should appear in the listing. */ +NODE * +get_visited_nodes (filter_func) + Function *filter_func; +{ + register int i, iw_index; + INFO_WINDOW *info_win; + NODE *node; + char **lines = (char **)NULL; + int lines_index = 0, lines_slots = 0; + + if (!info_windows) + return ((NODE *)NULL); + + for (iw_index = 0; info_win = info_windows[iw_index]; iw_index++) + { + for (i = 0; i < info_win->nodes_index; i++) + { + node = info_win->nodes[i]; + + /* We skip mentioning "*Node Menu*" nodes. */ + if (internal_info_node_p (node) && + (strcmp (node->nodename, nodemenu_nodename) == 0)) + continue; + + if (node && (!filter_func || (*filter_func) (node))) + { + char *line; + + line = format_node_info (node); + add_pointer_to_array + (line, lines_index, lines, lines_slots, 20, char *); + } + } + } + + /* Sort the array of information lines. */ + qsort (lines, lines_index, sizeof (char *), compare_strings); + + /* Delete duplicates. */ + { + register int j, newlen; + char **temp; + + for (i = 0, newlen = 1; i < lines_index - 1; i++) + { + if (strcmp (lines[i], lines[i + 1]) == 0) + { + free (lines[i]); + lines[i] = (char *)NULL; + } + else + newlen++; + } + + /* We have free ()'d and marked all of the duplicate slots. Copy the + live slots rather than pruning the dead slots. */ + temp = (char **)xmalloc ((1 + newlen) * sizeof (char *)); + for (i = 0, j = 0; i < lines_index; i++) + if (lines[i]) + temp[j++] = lines[i]; + + temp[j] = (char *)NULL; + free (lines); + lines = temp; + lines_index = newlen; + } + + initialize_message_buffer (); + printf_to_message_buffer + ("Here is a menu of nodes you could select with info-history-node:\n"); + printf_to_message_buffer ("%s\n", nodemenu_format_info ()); + for (i = 0; i < lines_index; i++) + { + printf_to_message_buffer ("%s\n", lines[i]); + free (lines[i]); + } + free (lines); + + node = message_buffer_to_node (); + add_gcable_pointer (node->contents); + return (node); +} + +DECLARE_INFO_COMMAND (list_visited_nodes, + "Make a window containing a menu of all of the currently visited nodes") +{ + WINDOW *new; + NODE *node; + + set_remembered_pagetop_and_point (window); + + /* If a window is visible and showing the buffer list already, re-use it. */ + for (new = windows; new; new = new->next) + { + node = new->node; + + if (internal_info_node_p (node) && + (strcmp (node->nodename, nodemenu_nodename) == 0)) + break; + } + + /* If we couldn't find an existing window, try to use the next window + in the chain. */ + if (!new && window->next) + new = window->next; + + /* If we still don't have a window, make a new one to contain the list. */ + if (!new) + { + WINDOW *old_active; + + old_active = active_window; + active_window = window; + new = window_make_window ((NODE *)NULL); + active_window = old_active; + } + + /* If we couldn't make a new window, use this one. */ + if (!new) + new = window; + + /* Lines do not wrap in this window. */ + new->flags |= W_NoWrap; + node = get_visited_nodes ((Function *)NULL); + name_internal_node (node, nodemenu_nodename); + + /* Even if this is an internal node, we don't want the window + system to treat it specially. So we turn off the internalness + of it here. */ + node->flags &= ~N_IsInternal; + + /* If this window is already showing a node menu, reuse the existing node + slot. */ + { + int remember_me = 1; + +#if defined (NOTDEF) + if (internal_info_node_p (new->node) && + (strcmp (new->node->nodename, nodemenu_nodename) == 0)) + remember_me = 0; +#endif /* NOTDEF */ + + window_set_node_of_window (new, node); + + if (remember_me) + remember_window_and_node (new, node); + } + + active_window = new; +} + +DECLARE_INFO_COMMAND (select_visited_node, + "Select a node which has been previously visited in a visible window") +{ + char *line; + NODE *node; + REFERENCE **menu; + + node = get_visited_nodes ((Function *)NULL); + + menu = info_menu_of_node (node); + free (node); + + line = + info_read_completing_in_echo_area (window, "Select visited node: ", menu); + + window = active_window; + + /* User aborts, just quit. */ + if (!line) + { + info_abort_key (window, 0, 0); + info_free_references (menu); + return; + } + + if (*line) + { + REFERENCE *entry; + + /* Find the selected label in the references. */ + entry = info_get_labeled_reference (line, menu); + + if (!entry) + info_error ("The reference disappeared! (%s).", line); + else + info_select_reference (window, entry); + } + + free (line); + info_free_references (menu); + + if (!info_error_was_printed) + window_clear_echo_area (); +} diff --git a/gnu/usr.bin/texinfo/info/nodes.c b/gnu/usr.bin/texinfo/info/nodes.c new file mode 100644 index 0000000..c66a8c1 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/nodes.c @@ -0,0 +1,1167 @@ +/* nodes.c -- How to get an Info file and node. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#include <stdio.h> +#include <ctype.h> +#include <sys/types.h> +#include <sys/file.h> +#include <sys/errno.h> +#include <sys/stat.h> +#include "nodes.h" +#include "search.h" +#include "filesys.h" +#include "info-utils.h" + +#if !defined (O_RDONLY) +#if defined (HAVE_SYS_FCNTL_H) +#include <sys/fcntl.h> +#else /* !HAVE_SYS_FCNTL_H */ +#include <fcntl.h> +#endif /* !HAVE_SYS_FCNTL_H */ +#endif /* !O_RDONLY */ + +#if !defined (errno) +extern int errno; +#endif /* !errno */ + +/* **************************************************************** */ +/* */ +/* Functions Static to this File */ +/* */ +/* **************************************************************** */ + +static void forget_info_file (), remember_info_file (); +static void free_file_buffer_tags (), free_info_tag (); +static void get_nodes_of_tags_table (), get_nodes_of_info_file (); +static void get_tags_of_indirect_tags_table (); +static void info_reload_file_buffer_contents (); +static char *adjust_nodestart (); +static FILE_BUFFER *make_file_buffer (); +static FILE_BUFFER *info_load_file_internal (), *info_find_file_internal (); +static NODE *info_node_of_file_buffer_tags (); + +static long get_node_length (); + +/* Magic number that RMS used to decide how much a tags table pointer could + be off by. I feel that it should be much smaller, like on the order of + 4. */ +#define DEFAULT_INFO_FUDGE 1000 + +/* Passed to *_internal functions. INFO_GET_TAGS says to do what is + neccessary to fill in the nodes or tags arrays in FILE_BUFFER. */ +#define INFO_NO_TAGS 0 +#define INFO_GET_TAGS 1 + +/* **************************************************************** */ +/* */ +/* Global Variables */ +/* */ +/* **************************************************************** */ + +/* When non-zero, this is a string describing the recent file error. */ +char *info_recent_file_error = (char *)NULL; + +/* The list of already loaded nodes. */ +FILE_BUFFER **info_loaded_files = (FILE_BUFFER **)NULL; + +/* The number of slots currently allocated to LOADED_FILES. */ +int info_loaded_files_slots = 0; + +/* **************************************************************** */ +/* */ +/* Public Functions for Node Manipulation */ +/* */ +/* **************************************************************** */ + +/* Used to build "dir" menu from "localdir" files found in INFOPATH. */ +extern void maybe_build_dir_node (); + +/* Return a pointer to a NODE structure for the Info node (FILENAME)NODENAME. + FILENAME can be passed as NULL, in which case the filename of "dir" is used. + NODENAME can be passed as NULL, in which case the nodename of "Top" is used. + If the node cannot be found, return a NULL pointer. */ +NODE * +info_get_node (filename, nodename) + char *filename, *nodename; +{ + FILE_BUFFER *file_buffer; + NODE *node; + + file_buffer = (FILE_BUFFER *)NULL; + info_recent_file_error = (char *)NULL; + + info_parse_node (nodename, DONT_SKIP_NEWLINES); + nodename = (char *)NULL; + + if (info_parsed_filename) + filename = info_parsed_filename; + + if (info_parsed_nodename) + nodename = info_parsed_nodename; + + /* If FILENAME is not specified, it defaults to "dir". */ + if (!filename) + filename = "dir"; + + /* If the file to be looked up is "dir", build the contents from all of + the "localdir"'s found in INFOPATH. */ + if (stricmp (filename, "dir") == 0) + maybe_build_dir_node (filename, "localdir"); + + /* Find the correct info file. */ + file_buffer = info_find_file (filename); + + if (!file_buffer) + { + if (filesys_error_number) + info_recent_file_error = + filesys_error_string (filename, filesys_error_number); + return ((NODE *)NULL); + } + + node = info_get_node_of_file_buffer (nodename, file_buffer); + /* If the node looked for was "Top", try again looking for the node under + a slightly different name. */ + if (!node && (nodename == NULL || stricmp (nodename, "Top") == 0)) + { + node = info_get_node_of_file_buffer ("Top", file_buffer); + if (!node) + node = info_get_node_of_file_buffer ("top", file_buffer); + if (!node) + node = info_get_node_of_file_buffer ("TOP", file_buffer); + } + return (node); +} + +/* Return a pointer to a NODE structure for the Info node NODENAME in + FILE_BUFFER. NODENAME can be passed as NULL, in which case the + nodename of "Top" is used. If the node cannot be found, return a + NULL pointer. */ +NODE * +info_get_node_of_file_buffer (nodename, file_buffer) + char *nodename; + FILE_BUFFER *file_buffer; +{ + NODE *node = (NODE *)NULL; + + /* If we are unable to find the file, we have to give up. There isn't + anything else we can do. */ + if (!file_buffer) + return ((NODE *)NULL); + + /* If the file buffer was gc'ed, reload the contents now. */ + if (!file_buffer->contents) + info_reload_file_buffer_contents (file_buffer); + + /* If NODENAME is not specified, it defaults to "Top". */ + if (!nodename) + nodename = "Top"; + + /* If the name of the node that we wish to find is exactly "*", then the + node body is the contents of the entire file. Create and return such + a node. */ + if (strcmp (nodename, "*") == 0) + { + node = (NODE *)xmalloc (sizeof (NODE)); + node->filename = file_buffer->fullpath; + node->parent = (char *)NULL; + node->nodename = savestring ("*"); + node->contents = file_buffer->contents; + node->nodelen = file_buffer->filesize; + node->flags = 0; + } + + /* If this is the "main" info file, it might contain a tags table. Search + the tags table for an entry which matches the node that we want. If + there is a tags table, get the file which contains this node, but don't + bother building a node list for it. */ + else if (file_buffer->tags) + node = info_node_of_file_buffer_tags (file_buffer, nodename); + + /* Return the results of our node search. */ + return (node); +} + +/* Locate the file named by FILENAME, and return the information structure + describing this file. The file may appear in our list of loaded files + already, or it may not. If it does not already appear, find the file, + and add it to the list of loaded files. If the file cannot be found, + return a NULL FILE_BUFFER *. */ +FILE_BUFFER * +info_find_file (filename) + char *filename; +{ + return (info_find_file_internal (filename, INFO_GET_TAGS)); +} + +/* Load the info file FILENAME, remembering information about it in a + file buffer. */ +FILE_BUFFER * +info_load_file (filename) + char *filename; +{ + return (info_load_file_internal (filename, INFO_GET_TAGS)); +} + + +/* **************************************************************** */ +/* */ +/* Private Functions Implementation */ +/* */ +/* **************************************************************** */ + +/* The workhorse for info_find_file (). Non-zero 2nd argument says to + try to build a tags table (or otherwise glean the nodes) for this + file once found. By default, we build the tags table, but when this + function is called by info_get_node () when we already have a valid + tags table describing the nodes, it is unnecessary. */ +static FILE_BUFFER * +info_find_file_internal (filename, get_tags) + char *filename; + int get_tags; +{ + register int i; + register FILE_BUFFER *file_buffer; + + /* First try to find the file in our list of already loaded files. */ + if (info_loaded_files) + { + for (i = 0; file_buffer = info_loaded_files[i]; i++) + if ((strcmp (filename, file_buffer->filename) == 0) || + (strcmp (filename, file_buffer->fullpath) == 0) || + ((*filename != '/') && + strcmp (filename, + filename_non_directory (file_buffer->fullpath)) == 0)) + { + struct stat new_info, *old_info; + + /* This file is loaded. If the filename that we want is + specifically "dir", then simply return the file buffer. */ + if (stricmp (filename_non_directory (filename), "dir") == 0) + return (file_buffer); + + /* The file appears to be already loaded, and it is not "dir". + Check to see if it has changed since the last time it was + loaded. */ + if (stat (file_buffer->fullpath, &new_info) == -1) + { + filesys_error_number = errno; + return ((FILE_BUFFER *)NULL); + } + + old_info = &file_buffer->finfo; + + if ((new_info.st_size != old_info->st_size) || + (new_info.st_mtime != old_info->st_mtime)) + { + /* The file has changed. Forget that we ever had loaded it + in the first place. */ + forget_info_file (filename); + break; + } + else + { + /* The info file exists, and has not changed since the last + time it was loaded. If the caller requested a nodes list + for this file, and there isn't one here, build the nodes + for this file_buffer. In any case, return the file_buffer + object. */ + if (get_tags && !file_buffer->tags) + build_tags_and_nodes (file_buffer); + + return (file_buffer); + } + } + } + + /* The file wasn't loaded. Try to load it now. */ + file_buffer = info_load_file_internal (filename, get_tags); + + /* If the file was loaded, remember the name under which it was found. */ + if (file_buffer) + remember_info_file (file_buffer); + + return (file_buffer); +} + +/* The workhorse function for info_load_file (). Non-zero second argument + says to build a list of tags (or nodes) for this file. This is the + default behaviour when info_load_file () is called, but it is not + necessary when loading a subfile for which we already have tags. */ +static FILE_BUFFER * +info_load_file_internal (filename, get_tags) + char *filename; + int get_tags; +{ + char *fullpath, *contents; + long filesize; + struct stat finfo; + int retcode; + FILE_BUFFER *file_buffer = (FILE_BUFFER *)NULL; + + /* Get the full pathname of this file, as known by the info system. + That is to say, search along INFOPATH and expand tildes, etc. */ + fullpath = info_find_fullpath (filename); + + /* Did we actually find the file? */ + retcode = stat (fullpath, &finfo); + + /* If the file referenced by the name returned from info_find_fullpath () + doesn't exist, then try again with the last part of the filename + appearing in lowercase. */ + if (retcode < 0) + { + char *lowered_name; + char *basename; + + lowered_name = savestring (filename); + basename = (char *)rindex (lowered_name, '/'); + + if (basename) + basename++; + else + basename = lowered_name; + + while (*basename) + { + if (isupper (*basename)) + *basename = tolower (*basename); + + basename++; + } + + fullpath = info_find_fullpath (lowered_name); + free (lowered_name); + + retcode = stat (fullpath, &finfo); + } + + /* If the file wasn't found, give up, returning a NULL pointer. */ + if (retcode < 0) + { + filesys_error_number = errno; + return ((FILE_BUFFER *)NULL); + } + + /* Otherwise, try to load the file. */ + contents = filesys_read_info_file (fullpath, &filesize, &finfo); + + if (!contents) + return ((FILE_BUFFER *)NULL); + + /* The file was found, and can be read. Allocate FILE_BUFFER and fill + in the various members. */ + file_buffer = make_file_buffer (); + file_buffer->filename = savestring (filename); + file_buffer->fullpath = savestring (fullpath); + file_buffer->finfo = finfo; + file_buffer->filesize = filesize; + file_buffer->contents = contents; + if (file_buffer->filesize != file_buffer->finfo.st_size) + file_buffer->flags |= N_IsCompressed; + + /* If requested, build the tags and nodes for this file buffer. */ + if (get_tags) + build_tags_and_nodes (file_buffer); + + return (file_buffer); +} + +/* Grovel FILE_BUFFER->contents finding tags and nodes, and filling in the + various slots. This can also be used to rebuild a tag or node table. */ +void +build_tags_and_nodes (file_buffer) + FILE_BUFFER *file_buffer; +{ + SEARCH_BINDING binding; + long position; + + free_file_buffer_tags (file_buffer); + file_buffer->flags &= ~N_HasTagsTable; + + /* See if there is a tags table in this info file. */ + binding.buffer = file_buffer->contents; + binding.start = file_buffer->filesize; + binding.end = binding.start - 1000; + if (binding.end < 0) + binding.end = 0; + binding.flags = S_FoldCase; + + position = search_backward (TAGS_TABLE_END_LABEL, &binding); + + /* If there is a tag table, find the start of it, and grovel over it + extracting tag information. */ + if (position != -1) + while (1) + { + long tags_table_begin, tags_table_end; + + binding.end = position; + binding.start = binding.end - 5 - strlen (TAGS_TABLE_END_LABEL); + if (binding.start < 0) + binding.start = 0; + + position = find_node_separator (&binding); + + /* For this test, (and all others here) failure indicates a bogus + tags table. Grovel the file. */ + if (position == -1) + break; + + /* Remember the end of the tags table. */ + binding.start = position; + tags_table_end = binding.start; + binding.end = 0; + + /* Locate the start of the tags table. */ + position = search_backward (TAGS_TABLE_BEG_LABEL, &binding); + + if (position == -1) + break; + + binding.end = position; + binding.start = binding.end - 5 - strlen (TAGS_TABLE_BEG_LABEL); + position = find_node_separator (&binding); + + if (position == -1) + break; + + /* The file contains a valid tags table. Fill the FILE_BUFFER's + tags member. */ + file_buffer->flags |= N_HasTagsTable; + tags_table_begin = position; + + /* If this isn't an indirect tags table, just remember the nodes + described locally in this tags table. Note that binding.end + is pointing to just after the beginning label. */ + binding.start = binding.end; + binding.end = file_buffer->filesize; + + if (!looking_at (TAGS_TABLE_IS_INDIRECT_LABEL, &binding)) + { + binding.start = tags_table_begin; + binding.end = tags_table_end; + get_nodes_of_tags_table (file_buffer, &binding); + return; + } + else + { + /* This is an indirect tags table. Build TAGS member. */ + SEARCH_BINDING indirect; + + indirect.start = tags_table_begin; + indirect.end = 0; + indirect.buffer = binding.buffer; + indirect.flags = S_FoldCase; + + position = search_backward (INDIRECT_TAGS_TABLE_LABEL, &indirect); + + if (position == -1) + { + /* This file is malformed. Give up. */ + return; + } + + indirect.start = position; + indirect.end = tags_table_begin; + binding.start = tags_table_begin; + binding.end = tags_table_end; + get_tags_of_indirect_tags_table (file_buffer, &indirect, &binding); + return; + } + } + + /* This file doesn't contain any kind of tags table. Grovel the + file and build node entries for it. */ + get_nodes_of_info_file (file_buffer); +} + +/* Search through FILE_BUFFER->contents building an array of TAG *, + one entry per each node present in the file. Store the tags in + FILE_BUFFER->tags, and the number of allocated slots in + FILE_BUFFER->tags_slots. */ +static void +get_nodes_of_info_file (file_buffer) + FILE_BUFFER *file_buffer; +{ + long nodestart; + int tags_index = 0; + SEARCH_BINDING binding; + + binding.buffer = file_buffer->contents; + binding.start = 0; + binding.end = file_buffer->filesize; + binding.flags = S_FoldCase; + + while ((nodestart = find_node_separator (&binding)) != -1) + { + int start, end; + char *nodeline; + TAG *entry; + + /* Skip past the characters just found. */ + binding.start = nodestart; + binding.start += skip_node_separator (binding.buffer + binding.start); + + /* Move to the start of the line defining the node. */ + nodeline = binding.buffer + binding.start; + + /* Find "Node:" */ + start = string_in_line (INFO_NODE_LABEL, nodeline); + + /* If not there, this is not the start of a node. */ + if (start == -1) + continue; + + /* Find the start of the nodename. */ + start += skip_whitespace (nodeline + start); + + /* Find the end of the nodename. */ + end = start + + skip_node_characters (nodeline + start, DONT_SKIP_NEWLINES); + + /* Okay, we have isolated the node name, and we know where the + node starts. Remember this information in a NODE structure. */ + entry = (TAG *)xmalloc (sizeof (TAG)); + entry->nodename = (char *)xmalloc (1 + (end - start)); + strncpy (entry->nodename, nodeline + start, end - start); + entry->nodename[end - start] = '\0'; + entry->nodestart = nodestart; + { + SEARCH_BINDING node_body; + + node_body.buffer = binding.buffer + binding.start; + node_body.start = 0; + node_body.end = binding.end - binding.start; + node_body.flags = S_FoldCase; + entry->nodelen = get_node_length (&node_body); + } + + entry->filename = file_buffer->fullpath; + + /* Add this tag to the array of tag structures in this FILE_BUFFER. */ + add_pointer_to_array (entry, tags_index, file_buffer->tags, + file_buffer->tags_slots, 100, TAG *); + } +} + +/* Return the length of the node which starts at BINDING. */ +static long +get_node_length (binding) + SEARCH_BINDING *binding; +{ + register int i; + char *body; + + /* From the Info-RFC file: + [A node] ends with either a ^_, a ^L, or the end of file. */ + for (i = binding->start, body = binding->buffer; i < binding->end; i++) + { + if (body[i] == INFO_FF || body[i] == INFO_COOKIE) + break; + } + return ((long) i - binding->start); +} + +/* Build and save the array of nodes in FILE_BUFFER by searching through the + contents of BUFFER_BINDING for a tags table, and groveling the contents. */ +static void +get_nodes_of_tags_table (file_buffer, buffer_binding) + FILE_BUFFER *file_buffer; + SEARCH_BINDING *buffer_binding; +{ + int offset, tags_index = 0; + SEARCH_BINDING *search; + long position; + + search = copy_binding (buffer_binding); + + /* Find the start of the tags table. */ + position = find_tags_table (search); + + /* If none, we're all done. */ + if (position == -1) + return; + + /* Move to one character before the start of the actual table. */ + search->start = position; + search->start += skip_node_separator (search->buffer + search->start); + search->start += strlen (TAGS_TABLE_BEG_LABEL); + search->start--; + + /* The tag table consists of lines containing node names and positions. + Do each line until we find one that doesn't contain a node name. */ + while ((position = search_forward ("\n", search)) != -1) + { + TAG *entry; + char *nodedef; + + /* Prepare to skip this line. */ + search->start = position; + search->start++; + + /* Skip past informative "(Indirect)" tags table line. */ + if (!tags_index && looking_at (TAGS_TABLE_IS_INDIRECT_LABEL, search)) + continue; + + /* Find the label preceding the node name. */ + offset = + string_in_line (INFO_NODE_LABEL, search->buffer + search->start); + + /* If not there, not a defining line, so we must be out of the + tags table. */ + if (offset == -1) + break; + + /* Point to the beginning of the node definition. */ + search->start += offset; + nodedef = search->buffer + search->start; + nodedef += skip_whitespace (nodedef); + + /* Move past the node's name. */ + for (offset = 0; + (nodedef[offset]) && (nodedef[offset] != INFO_TAGSEP); + offset++); + + if (nodedef[offset] != INFO_TAGSEP) + continue; + + entry = (TAG *)xmalloc (sizeof (TAG)); + entry->nodename = (char *)xmalloc (1 + offset); + strncpy (entry->nodename, nodedef, offset); + entry->nodename[offset] = '\0'; + offset++; + entry->nodestart = (long) atol (nodedef + offset); + + /* We don't know the length of this node yet. */ + entry->nodelen = -1; + + /* The filename of this node is currently known as the same as the + name of this file. */ + entry->filename = file_buffer->fullpath; + + /* Add this node structure to the array of node structures in this + FILE_BUFFER. */ + add_pointer_to_array (entry, tags_index, file_buffer->tags, + file_buffer->tags_slots, 100, TAG *); + } + free (search); +} + +/* A structure used only in get_tags_of_indirect_tags_table () to hold onto + an intermediate value. */ +typedef struct { + char *filename; + long first_byte; +} SUBFILE; + +/* Remember in FILE_BUFFER the nodenames, subfilenames, and offsets within the + subfiles of every node which appears in TAGS_BINDING. The 2nd argument is + a binding surrounding the indirect files list. */ +static void +get_tags_of_indirect_tags_table (file_buffer, indirect_binding, tags_binding) + FILE_BUFFER *file_buffer; + SEARCH_BINDING *indirect_binding, *tags_binding; +{ + register int i; + SUBFILE **subfiles = (SUBFILE **)NULL; + int subfiles_index = 0, subfiles_slots = 0; + TAG *entry; + + /* First get the list of tags from the tags table. Then lookup the + associated file in the indirect list for each tag, and update it. */ + get_nodes_of_tags_table (file_buffer, tags_binding); + + /* We have the list of tags in file_buffer->tags. Get the list of + subfiles from the indirect table. */ + { + char *start, *end, *line; + SUBFILE *subfile; + + start = indirect_binding->buffer + indirect_binding->start; + end = indirect_binding->buffer + indirect_binding->end; + line = start; + + while (line < end) + { + int colon; + + colon = string_in_line (":", line); + + if (colon == -1) + break; + + subfile = (SUBFILE *)xmalloc (sizeof (SUBFILE)); + subfile->filename = (char *)xmalloc (colon); + strncpy (subfile->filename, line, colon - 1); + subfile->filename[colon - 1] = '\0'; + subfile->first_byte = (long) atol (line + colon); + + add_pointer_to_array + (subfile, subfiles_index, subfiles, subfiles_slots, 10, SUBFILE *); + + while (*line++ != '\n'); + } + } + + /* If we have successfully built the indirect files table, then + merge the information in the two tables. */ + if (!subfiles) + { + free_file_buffer_tags (file_buffer); + return; + } + else + { + register int tags_index; + long header_length; + SEARCH_BINDING binding; + + /* Find the length of the header of the file containing the indirect + tags table. This header appears at the start of every file. We + want the absolute position of each node within each subfile, so + we subtract the start of the containing subfile from the logical + position of the node, and then add the length of the header in. */ + binding.buffer = file_buffer->contents; + binding.start = 0; + binding.end = file_buffer->filesize; + binding.flags = S_FoldCase; + + header_length = find_node_separator (&binding); + if (header_length == -1) + header_length = 0; + + /* Build the file buffer's list of subfiles. */ + { + char *containing_dir, *temp; + int len_containing_dir; + + containing_dir = savestring (file_buffer->fullpath); + temp = (char *)rindex (containing_dir, '/'); + + if (temp) + *temp = '\0'; + + len_containing_dir = strlen (containing_dir); + + for (i = 0; subfiles[i]; i++); + + file_buffer->subfiles = (char **) xmalloc ((1 + i) * sizeof (char *)); + + for (i = 0; subfiles[i]; i++) + { + char *fullpath; + + fullpath = (char *) xmalloc + (2 + strlen (subfiles[i]->filename) + len_containing_dir); + + sprintf (fullpath, "%s/%s", + containing_dir, subfiles[i]->filename); + + file_buffer->subfiles[i] = fullpath; + } + file_buffer->subfiles[i] = (char *)NULL; + free (containing_dir); + } + + /* For each node in the file's tags table, remember the starting + position. */ + for (tags_index = 0; + entry = file_buffer->tags[tags_index]; + tags_index++) + { + for (i = 0; + subfiles[i] && entry->nodestart >= subfiles[i]->first_byte; + i++); + + /* If the Info file containing the indirect tags table is + malformed, then give up. */ + if (!i) + { + /* The Info file containing the indirect tags table is + malformed. Give up. */ + for (i = 0; subfiles[i]; i++) + { + free (subfiles[i]->filename); + free (subfiles[i]); + free (file_buffer->subfiles[i]); + } + file_buffer->subfiles = (char **)NULL; + free_file_buffer_tags (file_buffer); + return; + } + + /* SUBFILES[i] is the index of the first subfile whose logical + first byte is greater than the logical offset of this node's + starting position. This means that the subfile directly + preceding this one is the one containing the node. */ + + entry->filename = file_buffer->subfiles[i - 1]; + entry->nodestart -= subfiles[i -1]->first_byte; + entry->nodestart += header_length; + entry->nodelen = -1; + } + + /* We have successfully built the tags table. Remember that it + was indirect. */ + file_buffer->flags |= N_TagsIndirect; + } + + /* Free the structures assigned to SUBFILES. Free the names as well + as the structures themselves, then finally, the array. */ + for (i = 0; subfiles[i]; i++) + { + free (subfiles[i]->filename); + free (subfiles[i]); + } + free (subfiles); +} + +/* Return the node from FILE_BUFFER which matches NODENAME by searching + the tags table in FILE_BUFFER. If the node could not be found, return + a NULL pointer. */ +static NODE * +info_node_of_file_buffer_tags (file_buffer, nodename) + FILE_BUFFER *file_buffer; + char *nodename; +{ + register int i; + TAG *tag; + + for (i = 0; tag = file_buffer->tags[i]; i++) + if (strcmp (nodename, tag->nodename) == 0) + { + FILE_BUFFER *subfile; + + subfile = info_find_file_internal (tag->filename, INFO_NO_TAGS); + + if (!subfile) + return ((NODE *)NULL); + + if (!subfile->contents) + info_reload_file_buffer_contents (subfile); + + if (!subfile->contents) + return ((NODE *)NULL); + + /* If we were able to find this file and load it, then return + the node within it. */ + { + NODE *node; + + node = (NODE *)xmalloc (sizeof (NODE)); + node->filename = (subfile->fullpath); + node->nodename = tag->nodename; + node->contents = subfile->contents + tag->nodestart; + node->flags = 0; + node->parent = (char *)NULL; + + if (file_buffer->flags & N_HasTagsTable) + { + node->flags |= N_HasTagsTable; + + if (file_buffer->flags & N_TagsIndirect) + { + node->flags |= N_TagsIndirect; + node->parent = file_buffer->fullpath; + } + } + + if (subfile->flags & N_IsCompressed) + node->flags |= N_IsCompressed; + + /* If TAG->nodelen hasn't been calculated yet, then we aren't + in a position to trust the entry pointer. Adjust things so + that ENTRY->nodestart gets the exact address of the start of + the node separator which starts this node, and NODE->contents + gets the address of the line defining this node. If we cannot + do that, the node isn't really here. */ + if (tag->nodelen == -1) + { + int min, max; + char *node_sep; + SEARCH_BINDING node_body; + char *buff_end; + + min = max = DEFAULT_INFO_FUDGE; + + if (tag->nodestart < DEFAULT_INFO_FUDGE) + min = tag->nodestart; + + if (DEFAULT_INFO_FUDGE > + (subfile->filesize - tag->nodestart)) + max = subfile->filesize - tag->nodestart; + + /* NODE_SEP gets the address of the separator which defines + this node, or (char *)NULL if the node wasn't found. + NODE->contents is side-effected to point to right after + the separator. */ + node_sep = adjust_nodestart (node, min, max); + if (node_sep == (char *)NULL) + { + free (node); + return ((NODE *)NULL); + } + /* Readjust tag->nodestart. */ + tag->nodestart = node_sep - subfile->contents; + + /* Calculate the length of the current node. */ + buff_end = subfile->contents + subfile->filesize; + + node_body.buffer = node->contents; + node_body.start = 0; + node_body.end = buff_end - node_body.buffer; + node_body.flags = 0; + tag->nodelen = get_node_length (&node_body); + } + else + { + /* Since we know the length of this node, we have already + adjusted tag->nodestart to point to the exact start of + it. Simply skip the node separator. */ + node->contents += skip_node_separator (node->contents); + } + + node->nodelen = tag->nodelen; + return (node); + } + } + + /* There was a tag table for this file, and the node wasn't found. + Return NULL, since this file doesn't contain the desired node. */ + return ((NODE *)NULL); +} + +/* **************************************************************** */ +/* */ +/* Managing file_buffers, nodes, and tags. */ +/* */ +/* **************************************************************** */ + +static FILE_BUFFER * +make_file_buffer () +{ + FILE_BUFFER *file_buffer; + + file_buffer = (FILE_BUFFER *)xmalloc (sizeof (FILE_BUFFER)); + file_buffer->filename = file_buffer->fullpath = (char *)NULL; + file_buffer->contents = (char *)NULL; + file_buffer->tags = (TAG **)NULL; + file_buffer->subfiles = (char **)NULL; + file_buffer->tags_slots = 0; + file_buffer->flags = 0; + + return (file_buffer); +} + +/* Add FILE_BUFFER to our list of already loaded info files. */ +static void +remember_info_file (file_buffer) + FILE_BUFFER *file_buffer; +{ + int i; + + for (i = 0; info_loaded_files && info_loaded_files[i]; i++) + ; + + add_pointer_to_array (file_buffer, i, info_loaded_files, + info_loaded_files_slots, 10, FILE_BUFFER *); +} + +/* Forget the contents, tags table, nodes list, and names of FILENAME. */ +static void +forget_info_file (filename) + char *filename; +{ + register int i; + FILE_BUFFER *file_buffer; + + if (!info_loaded_files) + return; + + for (i = 0; file_buffer = info_loaded_files[i]; i++) + if ((strcmp (filename, file_buffer->filename) == 0) || + (strcmp (filename, file_buffer->fullpath) == 0)) + { + free (file_buffer->filename); + free (file_buffer->fullpath); + + if (file_buffer->contents) + free (file_buffer->contents); + + /* Note that free_file_buffer_tags () also kills the subfiles + list, since the subfiles list is only of use in conjunction + with tags. */ + free_file_buffer_tags (file_buffer); + + while (info_loaded_files[i] = info_loaded_files[++i]) + ; + + break; + } +} + +/* Free the tags (if any) associated with FILE_BUFFER. */ +static void +free_file_buffer_tags (file_buffer) + FILE_BUFFER *file_buffer; +{ + register int i; + + if (file_buffer->tags) + { + register TAG *tag; + + for (i = 0; tag = file_buffer->tags[i]; i++) + free_info_tag (tag); + + free (file_buffer->tags); + file_buffer->tags = (TAG **)NULL; + file_buffer->tags_slots = 0; + } + + if (file_buffer->subfiles) + { + for (i = 0; file_buffer->subfiles[i]; i++) + free (file_buffer->subfiles[i]); + + free (file_buffer->subfiles); + file_buffer->subfiles = (char **)NULL; + } +} + +/* Free the data associated with TAG, as well as TAG itself. */ +static void +free_info_tag (tag) + TAG *tag; +{ + free (tag->nodename); + + /* We don't free tag->filename, because that filename is part of the + subfiles list for the containing FILE_BUFFER. free_info_tags () + will free the subfiles when it is appropriate. */ + + free (tag); +} + +/* Load the contents of FILE_BUFFER->contents. This function is called + when a file buffer was loaded, and then in order to conserve memory, the + file buffer's contents were freed and the pointer was zero'ed. Note that + the file was already loaded at least once successfully, so the tags and/or + nodes members are still correctly filled. */ +static void +info_reload_file_buffer_contents (fb) + FILE_BUFFER *fb; +{ + fb->flags &= ~N_IsCompressed; + + /* Let the filesystem do all the work for us. */ + fb->contents = + filesys_read_info_file (fb->fullpath, &(fb->filesize), &(fb->finfo)); + if (fb->filesize != fb->finfo.st_size) + fb->flags |= N_IsCompressed; +} + +/* Return the actual starting memory location of NODE, side-effecting + NODE->contents. MIN and MAX are bounds for a search if one is necessary. + Because of the way that tags are implemented, the physical nodestart may + not actually be where the tag says it is. If that is the case, but the + node was found anyway, set N_UpdateTags in NODE->flags. If the node is + found, return non-zero. NODE->contents is returned positioned right after + the node separator that precedes this node, while the return value is + position directly on the separator that precedes this node. If the node + could not be found, return a NULL pointer. */ +static char * +adjust_nodestart (node, min, max) + NODE *node; + int min, max; +{ + long position; + SEARCH_BINDING node_body; + + /* Define the node body. */ + node_body.buffer = node->contents; + node_body.start = 0; + node_body.end = max; + node_body.flags = 0; + + /* Try the optimal case first. Who knows? This file may actually be + formatted (mostly) correctly. */ + if (node_body.buffer[0] != INFO_COOKIE && min > 2) + node_body.buffer -= 3; + + position = find_node_separator (&node_body); + + /* If we found a node start, then check it out. */ + if (position != -1) + { + int sep_len; + + sep_len = skip_node_separator (node->contents); + + /* If we managed to skip a node separator, then check for this node + being the right one. */ + if (sep_len != 0) + { + char *nodedef, *nodestart; + int offset; + + nodestart = node_body.buffer + position + sep_len; + nodedef = nodestart; + offset = string_in_line (INFO_NODE_LABEL, nodedef); + + if (offset != -1) + { + nodedef += offset; + nodedef += skip_whitespace (nodedef); + offset = skip_node_characters (nodedef, DONT_SKIP_NEWLINES); + if ((offset == strlen (node->nodename)) && + (strncmp (node->nodename, nodedef, offset) == 0)) + { + node->contents = nodestart; + return (node_body.buffer + position); + } + } + } + } + + /* Oh well, I guess we have to try to find it in a larger area. */ + node_body.buffer = node->contents - min; + node_body.start = 0; + node_body.end = min + max; + node_body.flags = 0; + + position = find_node_in_binding (node->nodename, &node_body); + + /* If the node couldn't be found, we lose big. */ + if (position == -1) + return ((char *)NULL); + + /* Otherwise, the node was found, but the tags table could need updating + (if we used a tag to get here, that is). Set the flag in NODE->flags. */ + node->contents = node_body.buffer + position; + node->contents += skip_node_separator (node->contents); + if (node->flags & N_HasTagsTable) + node->flags |= N_UpdateTags; + return (node_body.buffer + position); +} diff --git a/gnu/usr.bin/texinfo/info/nodes.h b/gnu/usr.bin/texinfo/info/nodes.h new file mode 100644 index 0000000..1b8cee3 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/nodes.h @@ -0,0 +1,164 @@ +/* nodes.h -- How we represent nodes internally. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#ifndef _NODES_H_ +#define _NODES_H_ + +#include "general.h" + +/* **************************************************************** */ +/* */ +/* User Code Interface */ +/* */ +/* **************************************************************** */ + +/* Callers generally only want the node itself. This structure is used + to pass node information around. None of the information in this + structure should ever be directly freed. The structure itself can + be passed to free (). Note that NODE->parent is non-null if this + node's file is a subfile. In that case, NODE->parent is the logical + name of the file containing this node. Both names are given as full + paths, so you might have: node->filename = "/usr/gnu/info/emacs-1", + with node->parent = "/usr/gnu/info/emacs". */ +typedef struct { + char *filename; /* The physical file containing this node. */ + char *parent; /* Non-null is the logical file name. */ + char *nodename; /* The name of this node. */ + char *contents; /* Characters appearing in this node. */ + long nodelen; /* The length of the CONTENTS member. */ + int flags; /* See immediately below. */ +} NODE; + +/* Defines that can appear in NODE->flags. All informative. */ +#define N_HasTagsTable 0x01 /* This node was found through a tags table. */ +#define N_TagsIndirect 0x02 /* The tags table was an indirect one. */ +#define N_UpdateTags 0x04 /* The tags table is out of date. */ +#define N_IsCompressed 0x08 /* The file is compressed on disk. */ +#define N_IsInternal 0x10 /* This node was made by Info. */ +#define N_CannotGC 0x20 /* File buffer cannot be gc'ed. */ + +/* **************************************************************** */ +/* */ +/* Internal Data Structures */ +/* */ +/* **************************************************************** */ + +/* Some defines describing details about Info file contents. */ + +/* String Constants. */ +#define INFO_FILE_LABEL "File:" +#define INFO_NODE_LABEL "Node:" +#define INFO_PREV_LABEL "Prev:" +#define INFO_ALTPREV_LABEL "Previous:" +#define INFO_NEXT_LABEL "Next:" +#define INFO_UP_LABEL "Up:" +#define INFO_MENU_LABEL "\n* Menu:" +#define INFO_MENU_ENTRY_LABEL "\n* " +#define INFO_XREF_LABEL "*Note" +#define TAGS_TABLE_END_LABEL "\nEnd Tag Table" +#define TAGS_TABLE_BEG_LABEL "Tag Table:\n" +#define INDIRECT_TAGS_TABLE_LABEL "Indirect:\n" +#define TAGS_TABLE_IS_INDIRECT_LABEL "(Indirect)" + +/* Character Constants. */ +#define INFO_COOKIE '\037' +#define INFO_FF '\014' +#define INFO_TAGSEP '\177' + +/* For each logical file that we have loaded, we keep a list of the names + of the nodes that are found in that file. A pointer to a node in an + info file is called a "tag". For split files, the tag pointer is + "indirect"; that is, the pointer also contains the name of the split + file where the node can be found. For non-split files, the filename + member in the structure below simply contains the name of the current + file. The following structure describes a single node within a file. */ +typedef struct { + char *filename; /* The file where this node can be found. */ + char *nodename; /* The node pointed to by this tag. */ + long nodestart; /* The offset of the start of this node. */ + long nodelen; /* The length of this node. */ +} TAG; + +/* The following structure is used to remember information about the contents + of Info files that we have loaded at least once before. The FINFO member + is present so that we can reload the file if it has been modified since + last being loaded. All of the arrays appearing within this structure + are NULL terminated, and each array which can change size has a + corresponding SLOTS member which says how many slots have been allocated + (with malloc ()) for this array. */ +typedef struct { + char *filename; /* The filename used to find this file. */ + char *fullpath; /* The full pathname of this info file. */ + struct stat finfo; /* Information about this file. */ + char *contents; /* The contents of this particular file. */ + long filesize; /* The number of bytes this file expands to. */ + char **subfiles; /* If non-null, the list of subfiles. */ + TAG **tags; /* If non-null, the indirect tags table. */ + int tags_slots; /* Number of slots allocated for TAGS. */ + int flags; /* Various flags. Mimics of N_* flags. */ +} FILE_BUFFER; + +/* **************************************************************** */ +/* */ +/* Externally Visible Functions */ +/* */ +/* **************************************************************** */ + +/* Array of FILE_BUFFER * which represents the currently loaded info files. */ +extern FILE_BUFFER **info_loaded_files; + +/* The number of slots currently allocated to INFO_LOADED_FILES. */ +extern int info_loaded_files_slots; + +/* Locate the file named by FILENAME, and return the information structure + describing this file. The file may appear in our list of loaded files + already, or it may not. If it does not already appear, find the file, + and add it to the list of loaded files. If the file cannot be found, + return a NULL FILE_BUFFER *. */ +extern FILE_BUFFER *info_find_file (); + +/* Force load the file named FILENAME, and return the information structure + describing this file. Even if the file was already loaded, this loads + a new buffer, rebuilds tags and nodes, and returns a new FILE_BUFFER *. */ +extern FILE_BUFFER *info_load_file (); + +/* Return a pointer to a NODE structure for the Info node (FILENAME)NODENAME. + FILENAME can be passed as NULL, in which case the filename of "dir" is used. + NODENAME can be passed as NULL, in which case the nodename of "Top" is used. + If the node cannot be found, return a NULL pointer. */ +extern NODE *info_get_node (); + +/* Return a pointer to a NODE structure for the Info node NODENAME in + FILE_BUFFER. NODENAME can be passed as NULL, in which case the + nodename of "Top" is used. If the node cannot be found, return a + NULL pointer. */ +extern NODE *info_get_node_of_file_buffer (); + +/* Grovel FILE_BUFFER->contents finding tags and nodes, and filling in the + various slots. This can also be used to rebuild a tag or node table. */ +extern void build_tags_and_nodes (); + +/* When non-zero, this is a string describing the most recent file error. */ +extern char *info_recent_file_error; + +#endif /* !_NODES_H_ */ diff --git a/gnu/usr.bin/texinfo/info/search.c b/gnu/usr.bin/texinfo/info/search.c new file mode 100644 index 0000000..409faf3 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/search.c @@ -0,0 +1,566 @@ +/* search.c -- How to search large bodies of text. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#include <ctype.h> +#include <sys/types.h> +#include <sys/stat.h> +#include "general.h" +#include "search.h" +#include "nodes.h" + +#if !defined (NULL) +# define NULL 0x0 +#endif /* !NULL */ + +/* The search functions take two arguments: + + 1) a string to search for, and + + 2) a pointer to a SEARCH_BINDING which contains the buffer, start, + and end of the search. + + They return a long, which is the offset from the start of the buffer + at which the match was found. An offset of -1 indicates failure. */ + +/* A function which makes a binding with buffer and bounds. */ +SEARCH_BINDING * +make_binding (buffer, start, end) + char *buffer; + long start, end; +{ + SEARCH_BINDING *binding; + + binding = (SEARCH_BINDING *)xmalloc (sizeof (SEARCH_BINDING)); + binding->buffer = buffer; + binding->start = start; + binding->end = end; + binding->flags = 0; + + return (binding); +} + +/* Make a copy of BINDING without duplicating the data. */ +SEARCH_BINDING * +copy_binding (binding) + SEARCH_BINDING *binding; +{ + SEARCH_BINDING *copy; + + copy = make_binding (binding->buffer, binding->start, binding->end); + copy->flags = binding->flags; + return (copy); +} + + +/* **************************************************************** */ +/* */ +/* The Actual Searching Functions */ +/* */ +/* **************************************************************** */ + +/* Search forwards or backwards for the text delimited by BINDING. + The search is forwards if BINDING->start is greater than BINDING->end. */ +long +search (string, binding) + char *string; + SEARCH_BINDING *binding; +{ + long result; + + /* If the search is backwards, then search backwards, otherwise forwards. */ + if (binding->start > binding->end) + result = search_backward (string, binding); + else + result = search_forward (string, binding); + + return (result); +} + +/* Search forwards for STRING through the text delimited in BINDING. */ +long +search_forward (string, binding) + char *string; + SEARCH_BINDING *binding; +{ + register int c, i, len; + register char *buff, *end; + char *alternate = (char *)NULL; + + len = strlen (string); + + /* We match characters in the search buffer against STRING and ALTERNATE. + ALTERNATE is a case reversed version of STRING; this is cheaper than + case folding each character before comparison. Alternate is only + used if the case folding bit is turned on in the passed BINDING. */ + + if (binding->flags & S_FoldCase) + { + alternate = savestring (string); + + for (i = 0; i < len; i++) + { + if (islower (alternate[i])) + alternate[i] = toupper (alternate[i]); + else if (isupper (alternate[i])) + alternate[i] = tolower (alternate[i]); + } + } + + buff = binding->buffer + binding->start; + end = binding->buffer + binding->end + 1; + + while (buff < (end - len)) + { + for (i = 0; i < len; i++) + { + c = buff[i]; + + if ((c != string[i]) && (!alternate || c != alternate[i])) + break; + } + + if (!string[i]) + { + if (alternate) + free (alternate); + if (binding->flags & S_SkipDest) + buff += len; + return ((long) (buff - binding->buffer)); + } + + buff++; + } + + if (alternate) + free (alternate); + + return ((long) -1); +} + +/* Search for STRING backwards through the text delimited in BINDING. */ +long +search_backward (input_string, binding) + char *input_string; + SEARCH_BINDING *binding; +{ + register int c, i, len; + register char *buff, *end; + char *string; + char *alternate = (char *)NULL; + + len = strlen (input_string); + + /* Reverse the characters in the search string. */ + string = (char *)xmalloc (1 + len); + for (c = 0, i = len - 1; input_string[c]; c++, i--) + string[i] = input_string[c]; + + string[c] = '\0'; + + /* We match characters in the search buffer against STRING and ALTERNATE. + ALTERNATE is a case reversed version of STRING; this is cheaper than + case folding each character before comparison. ALTERNATE is only + used if the case folding bit is turned on in the passed BINDING. */ + + if (binding->flags & S_FoldCase) + { + alternate = savestring (string); + + for (i = 0; i < len; i++) + { + if (islower (alternate[i])) + alternate[i] = toupper (alternate[i]); + else if (isupper (alternate[i])) + alternate[i] = tolower (alternate[i]); + } + } + + buff = binding->buffer + binding->start; + end = binding->buffer + binding->end; + + while (buff > end + len) + { + for (i = 0; i < len; i++) + { + c = *(buff - i); + + if (c != string[i] && (alternate && c != alternate[i])) + break; + } + + if (!string[i]) + { + free (string); + if (alternate) + free (alternate); + + if (binding->flags & S_SkipDest) + buff -= len; + return ((long) (1 + (buff - binding->buffer))); + } + + buff--; + } + + free (string); + if (alternate) + free (alternate); + + return ((long) -1); +} + +/* Find STRING in LINE, returning the offset of the end of the string. + Return an offset of -1 if STRING does not appear in LINE. The search + is bound by the end of the line (i.e., either NEWLINE or 0). */ +int +string_in_line (string, line) + char *string, *line; +{ + register int end; + SEARCH_BINDING binding; + + /* Find the end of the line. */ + for (end = 0; line[end] && line[end] != '\n'; end++); + + /* Search for STRING within these confines. */ + binding.buffer = line; + binding.start = 0; + binding.end = end; + binding.flags = S_FoldCase | S_SkipDest; + + return (search_forward (string, &binding)); +} + +/* Return non-zero if STRING is the first text to appear at BINDING. */ +int +looking_at (string, binding) + char *string; + SEARCH_BINDING *binding; +{ + long search_end; + + search_end = search (string, binding); + + /* If the string was not found, SEARCH_END is -1. If the string was found, + but not right away, SEARCH_END is != binding->start. Otherwise, the + string was found at binding->start. */ + return (search_end == binding->start); +} + +/* **************************************************************** */ +/* */ +/* Small String Searches */ +/* */ +/* **************************************************************** */ + +/* Function names that start with "skip" are passed a string, and return + an offset from the start of that string. Function names that start + with "find" are passed a SEARCH_BINDING, and return an absolute position + marker of the item being searched for. "Find" functions return a value + of -1 if the item being looked for couldn't be found. */ + +/* Return the index of the first non-whitespace character in STRING. */ +int +skip_whitespace (string) + char *string; +{ + register int i; + + for (i = 0; string && whitespace (string[i]); i++); + return (i); +} + +/* Return the index of the first non-whitespace or newline character in + STRING. */ +int +skip_whitespace_and_newlines (string) + char *string; +{ + register int i; + + for (i = 0; string && (whitespace (string[i]) || string[i] == '\n'); i++); + return (i); +} + +/* Return the index of the first whitespace character in STRING. */ +int +skip_non_whitespace (string) + char *string; +{ + register int i; + + for (i = 0; string && !whitespace (string[i]); i++); + return (i); +} + +/* Return the index of the first non-node character in STRING. Note that + this function contains quite a bit of hair to ignore periods in some + special cases. This is because we here at GNU ship some info files which + contain nodenames that contain periods. No such nodename can start with + a period, or continue with whitespace, newline, or ')' immediately following + the period. If second argument NEWLINES_OKAY is non-zero, newlines should + be skipped while parsing out the nodename specification. */ +int +skip_node_characters (string, newlines_okay) + char *string; + int newlines_okay; +{ + register int c, i = 0; + int paren_seen = 0; + int paren = 0; + + /* Handle special case. This is when another function has parsed out the + filename component of the node name, and we just want to parse out the + nodename proper. In that case, a period at the start of the nodename + indicates an empty nodename. */ + if (string && *string == '.') + return (0); + + if (string && *string == '(') + { + paren++; + paren_seen++; + i++; + } + + for (; string && (c = string[i]); i++) + { + if (paren) + { + if (c == '(') + paren++; + else if (c == ')') + paren--; + + continue; + } + + /* If the character following the close paren is a space or period, + then this node name has no more characters associated with it. */ + if (c == '\t' || + c == ',' || + c == INFO_TAGSEP || + ((!newlines_okay) && (c == '\n')) || + ((paren_seen && string[i - 1] == ')') && + (c == ' ' || c == '.')) || + (c == '.' && + ((!string[i + 1]) || + (whitespace_or_newline (string[i + 1])) || + (string[i + 1] == ')')))) + break; + } + return (i); +} + +/* Unix doesn't have stricmp () functions. */ +int +stricmp (string1, string2) + char *string1, *string2; +{ + char ch1, ch2; + + for (;;) + { + ch1 = *string1++; + ch2 = *string2++; + + if (!(ch1 | ch2)) + return (0); + + ch1 = info_toupper (ch1); + ch2 = info_toupper (ch2); + + if (ch1 != ch2) + return (ch1 - ch2); + } +} + +/* Compare at most COUNT characters from string1 to string2. Case + doesn't matter. */ +int +strnicmp (string1, string2, count) + char *string1, *string2; + int count; +{ + register char ch1, ch2; + + while (count) + { + ch1 = *string1++; + ch2 = *string2++; + + ch1 = info_toupper (ch1); + ch2 = info_toupper (ch2); + + if (ch1 == ch2) + count--; + else + break; + } + return (count); +} + +/* **************************************************************** */ +/* */ +/* Searching FILE_BUFFER's */ +/* */ +/* **************************************************************** */ + +/* Return the absolute position of the first occurence of a node separator in + BINDING-buffer. The search starts at BINDING->start. Return -1 if no node + separator was found. */ +long +find_node_separator (binding) + SEARCH_BINDING *binding; +{ + register long i; + char *body; + + body = binding->buffer; + + /* A node is started by [^L]^_[^L]\n. That is to say, the C-l's are + optional, but the DELETE and NEWLINE are not. This separator holds + true for all separated elements in an Info file, including the tags + table (if present) and the indirect tags table (if present). */ + for (i = binding->start; i < binding->end - 1; i++) + if (((body[i] == INFO_FF && body[i + 1] == INFO_COOKIE) && + (body[i + 2] == '\n' || + (body[i + 2] == INFO_FF && body[i + 3] == '\n'))) || + ((body[i] == INFO_COOKIE) && + (body[i + 1] == '\n' || + (body[i + 1] == INFO_FF && body[i + 2] == '\n')))) + return (i); + return (-1); +} + +/* Return the length of the node separator characters that BODY is + currently pointing at. */ +int +skip_node_separator (body) + char *body; +{ + register int i; + + i = 0; + + if (body[i] == INFO_FF) + i++; + + if (body[i++] != INFO_COOKIE) + return (0); + + if (body[i] == INFO_FF) + i++; + + if (body[i++] != '\n') + return (0); + + return (i); +} + +/* Return the number of characters from STRING to the start of + the next line. */ +int +skip_line (string) + char *string; +{ + register int i; + + for (i = 0; string && string[i] && string[i] != '\n'; i++); + + if (string[i] == '\n') + i++; + + return (i); +} + +/* Return the absolute position of the beginning of a tags table in this + binding starting the search at binding->start. */ +long +find_tags_table (binding) + SEARCH_BINDING *binding; +{ + SEARCH_BINDING search; + long position; + + search.buffer = binding->buffer; + search.start = binding->start; + search.end = binding->end; + search.flags = S_FoldCase; + + while ((position = find_node_separator (&search)) != -1 ) + { + search.start = position; + search.start += skip_node_separator (search.buffer + search.start); + + if (looking_at (TAGS_TABLE_BEG_LABEL, &search)) + return (position); + } + return (-1); +} + +/* Return the absolute position of the node named NODENAME in BINDING. + This is a brute force search, and we wish to avoid it when possible. + This function is called when a tag (indirect or otherwise) doesn't + really point to the right node. It returns the absolute position of + the separator preceding the node. */ +long +find_node_in_binding (nodename, binding) + char *nodename; + SEARCH_BINDING *binding; +{ + register long position; + register int offset, namelen; + SEARCH_BINDING search; + + namelen = strlen (nodename); + + search.buffer = binding->buffer; + search.start = binding->start; + search.end = binding->end; + search.flags = 0; + + while ((position = find_node_separator (&search)) != -1) + { + search.start = position; + search.start += skip_node_separator (search.buffer + search.start); + + offset = string_in_line (INFO_NODE_LABEL, search.buffer + search.start); + + if (offset == -1) + continue; + + search.start += offset; + search.start += skip_whitespace (search.buffer + search.start); + offset = skip_node_characters + (search.buffer + search.start, DONT_SKIP_NEWLINES); + + /* Notice that this is an exact match. You cannot grovel through + the buffer with this function looking for random nodes. */ + if ((offset == namelen) && + (search.buffer[search.start] == nodename[0]) && + (strncmp (search.buffer + search.start, nodename, offset) == 0)) + return (position); + } + return (-1); +} diff --git a/gnu/usr.bin/texinfo/info/search.h b/gnu/usr.bin/texinfo/info/search.h new file mode 100644 index 0000000..cc1cada --- /dev/null +++ b/gnu/usr.bin/texinfo/info/search.h @@ -0,0 +1,78 @@ +/* search.h -- Structure used to search large bodies of text, with bounds. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +/* The search functions take two arguments: + + 1) a string to search for, and + + 2) a pointer to a SEARCH_BINDING which contains the buffer, start, + and end of the search. + + They return a long, which is the offset from the start of the buffer + at which the match was found. An offset of -1 indicates failure. */ + +#ifndef _SEARCH_H_ +#define _SEARCH_H_ + +typedef struct { + char *buffer; /* The buffer of text to search. */ + long start; /* Offset of the start of the search. */ + long end; /* Offset of the end of the searh. */ + int flags; /* Flags controlling the type of search. */ +} SEARCH_BINDING; + +#define S_FoldCase 0x01 /* Set means fold case in searches. */ +#define S_SkipDest 0x02 /* Set means return pointing after the dest. */ + +SEARCH_BINDING *make_binding (), *copy_binding (); +extern long search_forward (), search_backward (), search (); +extern int looking_at (); + +/* Note that STRING_IN_LINE () always returns the offset of the 1st character + after the string. */ +extern int string_in_line (); + +/* Unix doesn't have stricmp () functions. */ +/* strcmp (), but caseless. */ +extern int stricmp (); + +/* Compare at most COUNT characters from STRING1 to STRING2. Case + doesn't matter. */ +extern int strnicmp (); + +/* Function names that start with "skip" are passed a string, and return + an offset from the start of that string. Function names that start + with "find" are passed a SEARCH_BINDING, and return an absolute position + marker of the item being searched for. "Find" functions return a value + of -1 if the item being looked for couldn't be found. */ +extern int skip_whitespace (), skip_non_whitespace (); +extern int skip_whitespace_and_newlines (), skip_line (); +extern int skip_node_characters (), skip_node_separator (); +#define DONT_SKIP_NEWLINES 0 +#define SKIP_NEWLINES 1 + +extern long find_node_separator (), find_tags_table (); +extern long find_node_in_binding (); + +#endif /* !_SEARCH_H_ */ + diff --git a/gnu/usr.bin/texinfo/info/session.c b/gnu/usr.bin/texinfo/info/session.c new file mode 100644 index 0000000..0e4fb0a --- /dev/null +++ b/gnu/usr.bin/texinfo/info/session.c @@ -0,0 +1,4167 @@ +/* session.c -- The user windowing interface to Info. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#include "info.h" +#include <sys/file.h> +#include <sys/ioctl.h> +#include <fcntl.h> + +#if defined (HAVE_SYS_TIME_H) +# include <sys/time.h> +# define HAVE_STRUCT_TIMEVAL +#endif /* HAVE_SYS_TIME_H */ + +static void info_clear_pending_input (), info_set_pending_input (); +static void info_handle_pointer (); + +/* **************************************************************** */ +/* */ +/* Running an Info Session */ +/* */ +/* **************************************************************** */ + +/* The place that we are reading input from. */ +static FILE *info_input_stream = (FILE *)NULL; + +/* The last executed command. */ +VFunction *info_last_executed_command = (VFunction *)NULL; + +/* Becomes non-zero when 'q' is typed to an Info window. */ +int quit_info_immediately = 0; + +/* Array of structures describing for each window which nodes have been + visited in that window. */ +INFO_WINDOW **info_windows = (INFO_WINDOW **)NULL; + +/* Where to add the next window, if we need to add one. */ +static int info_windows_index = 0; + +/* Number of slots allocated to INFO_WINDOWS. */ +static int info_windows_slots = 0; + +void remember_window_and_node (), forget_window_and_nodes (); +void initialize_info_session (), info_session (); +void display_startup_message_and_start (); + +/* Begin an info session finding the nodes specified by FILENAME and NODENAMES. + For each loaded node, create a new window. Always split the largest of the + available windows. */ +void +begin_multiple_window_info_session (filename, nodenames) + char *filename; + char **nodenames; +{ + register int i; + WINDOW *window = (WINDOW *)NULL; + + for (i = 0; nodenames[i]; i++) + { + NODE *node; + + node = info_get_node (filename, nodenames[i]); + + if (!node) + break; + + /* If this is the first node, initialize the info session. */ + if (!window) + { + initialize_info_session (node); + window = active_window; + } + else + { + /* Find the largest window in WINDOWS, and make that be the active + one. Then split it and add our window and node to the list + of remembered windows and nodes. Then tile the windows. */ + register WINDOW *win, *largest = (WINDOW *)NULL; + int max_height = 0; + + for (win = windows; win; win = win->next) + if (win->height > max_height) + { + max_height = win->height; + largest = win; + } + + if (!largest) + { + display_update_display (windows); + info_error (CANT_FIND_WIND); + info_session (); + exit (0); + } + + active_window = largest; + window = window_make_window (node); + if (window) + { + window_tile_windows (TILE_INTERNALS); + remember_window_and_node (window, node); + } + else + { + display_update_display (windows); + info_error (WIN_TOO_SMALL); + info_session (); + exit (0); + } + } + } + display_startup_message_and_start (); +} + +/* Start an info session with INITIAL_NODE, and an error message in the echo + area made from FORMAT and ARG. */ +void +begin_info_session_with_error (initial_node, format, arg) + NODE *initial_node; + char *format; + void *arg; +{ + initialize_info_session (initial_node); + info_error (format, arg, (void *)NULL); + info_session (); +} + +/* Start an info session with INITIAL_NODE. */ +void +begin_info_session (initial_node) + NODE *initial_node; +{ + initialize_info_session (initial_node); + display_startup_message_and_start (); +} + +void +display_startup_message_and_start () +{ + char *format; + + format = replace_in_documentation + ("Welcome to Info version %s. Type \"\\[get-help-window]\" for help."); + + window_message_in_echo_area (format, version_string ()); + info_session (); +} + +/* Run an info session with an already initialized window and node. */ +void +info_session () +{ + terminal_prep_terminal (); + display_update_display (windows); + info_last_executed_command = (VFunction *)NULL; + info_read_and_dispatch (); + terminal_unprep_terminal (); + close_dribble_file (); +} + +/* Here is a window-location dependent event loop. Called from the + functions info_session (), and from read_xxx_in_echo_area (). */ +void +info_read_and_dispatch () +{ + unsigned char key; + int done; + done = 0; + + while (!done && !quit_info_immediately) + { + int lk; + + /* If we haven't just gone up or down a line, there is no + goal column for this window. */ + if ((info_last_executed_command != info_next_line) && + (info_last_executed_command != info_prev_line)) + active_window->goal_column = -1; + + if (echo_area_is_active) + { + lk = echo_area_last_command_was_kill; + echo_area_prep_read (); + } + + if (!info_any_buffered_input_p ()) + display_update_display (windows); + + display_cursor_at_point (active_window); + info_initialize_numeric_arg (); + + initialize_keyseq (); + key = info_get_input_char (); + + /* No errors yet. We just read a character, that's all. Only clear + the echo_area if it is not currently active. */ + if (!echo_area_is_active) + window_clear_echo_area (); + + info_error_was_printed = 0; + + /* Do the selected command. */ + info_dispatch_on_key (key, active_window->keymap); + + if (echo_area_is_active) + { + /* Echo area commands that do killing increment the value of + ECHO_AREA_LAST_COMMAND_WAS_KILL. Thus, if there is no + change in the value of this variable, the last command + executed was not a kill command. */ + if (lk == echo_area_last_command_was_kill) + echo_area_last_command_was_kill = 0; + + if (ea_last_executed_command == ea_newline || + info_aborted_echo_area) + { + ea_last_executed_command = (VFunction *)NULL; + done = 1; + } + + if (info_last_executed_command == info_quit) + quit_info_immediately = 1; + } + else if (info_last_executed_command == info_quit) + done = 1; + } +} + +/* Found in signals.c */ +extern void initialize_info_signal_handler (); + +/* Initialize the first info session by starting the terminal, window, + and display systems. */ +void +initialize_info_session (node) + NODE *node; +{ + char *getenv (), *term_name; + + term_name = getenv ("TERM"); + terminal_initialize_terminal (term_name); + + if (terminal_is_dumb_p) + { + if (!term_name) + term_name = "dumb"; + + info_error (TERM_TOO_DUMB, term_name); + exit (1); + } + terminal_clear_screen (); + initialize_info_keymaps (); + window_initialize_windows (screenwidth, screenheight); + initialize_info_signal_handler (); + display_initialize_display (screenwidth, screenheight); + info_set_node_of_window (active_window, node); + + /* Tell the window system how to notify us when a window needs to be + asynchronously deleted (e.g., user resizes window very small). */ + window_deletion_notifier = forget_window_and_nodes; + + /* If input has not been redirected yet, make it come from STDIN. */ + if (!info_input_stream) + info_input_stream = stdin; + + info_windows_initialized_p = 1; +} + +/* Tell Info that input is coming from the file FILENAME. */ +void +info_set_input_from_file (filename) + char *filename; +{ + FILE *stream; + + stream = fopen (filename, "r"); + + if (!stream) + return; + + if (info_input_stream != stdin) + fclose (info_input_stream); + + info_input_stream = stream; + + if (stream != stdin) + display_inhibited = 1; +} + +/* Return the INFO_WINDOW containing WINDOW, or NULL if there isn't one. */ +static INFO_WINDOW * +get_info_window_of_window (window) + WINDOW *window; +{ + register int i; + INFO_WINDOW *info_win = (INFO_WINDOW *)NULL; + + for (i = 0; info_windows && (info_win = info_windows[i]); i++) + if (info_win->window == window) + break; + + return (info_win); +} + +/* Reset the remembered pagetop and point of WINDOW to WINDOW's current + values if the window and node are the same as the current one being + displayed. */ +void +set_remembered_pagetop_and_point (window) + WINDOW *window; +{ + INFO_WINDOW *info_win; + + info_win = get_info_window_of_window (window); + + if (!info_win) + return; + + if (info_win->nodes_index && + (info_win->nodes[info_win->current] == window->node)) + { + info_win->pagetops[info_win->current] = window->pagetop; + info_win->points[info_win->current] = window->point; + } +} + +void +remember_window_and_node (window, node) + WINDOW *window; + NODE *node; +{ + INFO_WINDOW *info_win; + + /* See if we already have this window in our list. */ + info_win = get_info_window_of_window (window); + + /* If the window wasn't already on our list, then make a new entry. */ + if (!info_win) + { + info_win = (INFO_WINDOW *)xmalloc (sizeof (INFO_WINDOW)); + info_win->window = window; + info_win->nodes = (NODE **)NULL; + info_win->pagetops = (int *)NULL; + info_win->points = (long *)NULL; + info_win->current = 0; + info_win->nodes_index = 0; + info_win->nodes_slots = 0; + + add_pointer_to_array (info_win, info_windows_index, info_windows, + info_windows_slots, 10, INFO_WINDOW *); + } + + /* If this node, the current pagetop, and the current point are the + same as the last saved node and pagetop, don't really add this to + the list of history nodes. */ + { + int ni = info_win->nodes_index - 1; + + if ((ni != -1) && + (info_win->nodes[ni]->contents == node->contents) && + (info_win->pagetops[ni] == window->pagetop) && + (info_win->points[ni] == window->point)) + return; + } + + /* Remember this node, the currently displayed pagetop, and the current + location of point in this window. Because we are updating pagetops + and points as well as nodes, it is more efficient to avoid the + add_pointer_to_array macro here. */ + if (info_win->nodes_index + 2 >= info_win->nodes_slots) + { + info_win->nodes = (NODE **) + xrealloc (info_win->nodes, + (info_win->nodes_slots += 20) * sizeof (NODE *)); + + info_win->pagetops = (int *) + xrealloc (info_win->pagetops, info_win->nodes_slots * sizeof (int)); + + info_win->points = (long *) + xrealloc (info_win->points, info_win->nodes_slots * sizeof (long)); + } + + info_win->nodes[info_win->nodes_index] = node; + info_win->pagetops[info_win->nodes_index] = window->pagetop; + info_win->points[info_win->nodes_index] = window->point; + info_win->current = info_win->nodes_index++; + info_win->nodes[info_win->nodes_index] = (NODE *)NULL; + info_win->pagetops[info_win->nodes_index] = 0; + info_win->points[info_win->nodes_index] = 0; +} + +#define DEBUG_FORGET_WINDOW_AND_NODES +#if defined (DEBUG_FORGET_WINDOW_AND_NODES) +static void +consistency_check_info_windows () +{ + register int i; + INFO_WINDOW *info_win; + + for (i = 0; i < info_windows_index; i++) + { + WINDOW *win; + + for (win = windows; win; win = win->next) + if (win == info_windows[i]->window) + break; + + if (!win) + abort (); + } +} +#endif /* DEBUG_FORGET_WINDOW_AND_NODES */ + +/* Remove WINDOW and its associated list of nodes from INFO_WINDOWS. */ +void +forget_window_and_nodes (window) + WINDOW *window; +{ + register int i; + INFO_WINDOW *info_win = (INFO_WINDOW *)NULL; + + for (i = 0; info_windows && (info_win = info_windows[i]); i++) + if (info_win->window == window) + break; + + /* If we found the window to forget, then do so. */ + if (info_win) + { + while (i < info_windows_index) + info_windows[i] = info_windows[++i]; + + info_windows_index--; + info_windows[info_windows_index] = (INFO_WINDOW *)NULL; + + if (info_win->nodes) + { + for (i = 0; info_win->nodes[i]; i++) + if (internal_info_node_p (info_win->nodes[i])) + free (info_win->nodes[i]); + free (info_win->nodes); + + maybe_free (info_win->pagetops); + maybe_free (info_win->points); + } + + free (info_win); + } +#if defined (DEBUG_FORGET_WINDOW_AND_NODES) + consistency_check_info_windows (); +#endif /* DEBUG_FORGET_WINDOW_AND_NODES */ +} + +/* Set WINDOW to show NODE. Remember the new window in our list of Info + windows. If we are doing automatic footnote display, also try to display + the footnotes for this window. */ +void +info_set_node_of_window (window, node) + WINDOW *window; + NODE *node; +{ + /* Put this node into the window. */ + window_set_node_of_window (window, node); + + /* Remember this node and window in our list of info windows. */ + remember_window_and_node (window, node); + + /* If doing auto-footnote display/undisplay, show the footnotes belonging + to this window's node. */ + if (auto_footnotes_p) + info_get_or_remove_footnotes (window); +} + + +/* **************************************************************** */ +/* */ +/* Info Movement Commands */ +/* */ +/* **************************************************************** */ + +/* Change the pagetop of WINDOW to DESIRED_TOP, perhaps scrolling the screen + to do so. */ +void +set_window_pagetop (window, desired_top) + WINDOW *window; + int desired_top; +{ + int point_line, old_pagetop; + + if (desired_top < 0) + desired_top = 0; + else if (desired_top > window->line_count) + desired_top = window->line_count - 1; + + if (window->pagetop == desired_top) + return; + + old_pagetop = window->pagetop; + window->pagetop = desired_top; + + /* Make sure that point appears in this window. */ + point_line = window_line_of_point (window); + if ((point_line < window->pagetop) || + ((point_line - window->pagetop) > window->height - 1)) + window->point = + window->line_starts[window->pagetop] - window->node->contents; + + window->flags |= W_UpdateWindow; + + /* Find out which direction to scroll, and scroll the window in that + direction. Do this only if there would be a savings in redisplay + time. This is true if the amount to scroll is less than the height + of the window, and if the number of lines scrolled would be greater + than 10 % of the window's height. */ + if (old_pagetop < desired_top) + { + int start, end, amount; + + amount = desired_top - old_pagetop; + + if ((amount >= window->height) || + (((window->height - amount) * 10) < window->height)) + return; + + start = amount + window->first_row; + end = window->height + window->first_row; + + display_scroll_display (start, end, -amount); + } + else + { + int start, end, amount; + + amount = old_pagetop - desired_top; + + if ((amount >= window->height) || + (((window->height - amount) * 10) < window->height)) + return; + + start = window->first_row; + end = (window->first_row + window->height) - amount; + display_scroll_display (start, end, amount); + } +} + +/* Immediately make WINDOW->point visible on the screen, and move the + terminal cursor there. */ +static void +info_show_point (window) + WINDOW *window; +{ + int old_pagetop; + + old_pagetop = window->pagetop; + window_adjust_pagetop (window); + if (old_pagetop != window->pagetop) + { + int new_pagetop; + + new_pagetop = window->pagetop; + window->pagetop = old_pagetop; + set_window_pagetop (window, new_pagetop); + } + + if (window->flags & W_UpdateWindow) + display_update_one_window (window); + + display_cursor_at_point (window); +} + +/* Move WINDOW->point from OLD line index to NEW line index. */ +static void +move_to_new_line (old, new, window) + int old, new; + WINDOW *window; +{ + if (old == -1) + { + info_error (CANT_FIND_POINT); + } + else + { + int goal; + + if (new >= window->line_count || new < 0) + return; + + goal = window_get_goal_column (window); + window->goal_column = goal; + + window->point = window->line_starts[new] - window->node->contents; + window->point += window_chars_to_goal (window->line_starts[new], goal); + info_show_point (window); + } +} + +/* Move WINDOW's point down to the next line if possible. */ +DECLARE_INFO_COMMAND (info_next_line, "Move down to the next line") +{ + int old_line, new_line; + + if (count < 0) + info_prev_line (window, -count, key); + else + { + old_line = window_line_of_point (window); + new_line = old_line + count; + move_to_new_line (old_line, new_line, window); + } +} + +/* Move WINDOW's point up to the previous line if possible. */ +DECLARE_INFO_COMMAND (info_prev_line, "Move up to the previous line") +{ + int old_line, new_line; + + if (count < 0) + info_next_line (window, -count, key); + else + { + old_line = window_line_of_point (window); + new_line = old_line - count; + move_to_new_line (old_line, new_line, window); + } +} + +/* Move WINDOW's point to the end of the true line. */ +DECLARE_INFO_COMMAND (info_end_of_line, "Move to the end of the line") +{ + register int point, len; + register char *buffer; + + buffer = window->node->contents; + len = window->node->nodelen; + + for (point = window->point; + (point < len) && (buffer[point] != '\n'); + point++); + + if (point != window->point) + { + window->point = point; + info_show_point (window); + } +} + +/* Move WINDOW's point to the beginning of the true line. */ +DECLARE_INFO_COMMAND (info_beginning_of_line, "Move to the start of the line") +{ + register int point; + register char *buffer; + + buffer = window->node->contents; + point = window->point; + + for (; (point) && (buffer[point - 1] != '\n'); point--); + + /* If at a line start alreay, do nothing. */ + if (point != window->point) + { + window->point = point; + info_show_point (window); + } +} + +/* Move point forward in the node. */ +DECLARE_INFO_COMMAND (info_forward_char, "Move forward a character") +{ + if (count < 0) + info_backward_char (window, -count, key); + else + { + window->point += count; + + if (window->point >= window->node->nodelen) + window->point = window->node->nodelen - 1; + + info_show_point (window); + } +} + +/* Move point backward in the node. */ +DECLARE_INFO_COMMAND (info_backward_char, "Move backward a character") +{ + if (count < 0) + info_forward_char (window, -count, key); + else + { + window->point -= count; + + if (window->point < 0) + window->point = 0; + + info_show_point (window); + } +} + +#define alphabetic(c) (islower (c) || isupper (c) || isdigit (c)) + +/* Move forward a word in this node. */ +DECLARE_INFO_COMMAND (info_forward_word, "Move forward a word") +{ + long point; + char *buffer; + int end, c; + + if (count < 0) + { + info_backward_word (window, -count, key); + return; + } + + point = window->point; + buffer = window->node->contents; + end = window->node->nodelen; + + while (count) + { + if (point + 1 >= end) + return; + + /* If we are not in a word, move forward until we are in one. + Then, move forward until we hit a non-alphabetic character. */ + c = buffer[point]; + + if (!alphabetic (c)) + { + while (++point < end) + { + c = buffer[point]; + if (alphabetic (c)) + break; + } + } + + if (point >= end) return; + + while (++point < end) + { + c = buffer[point]; + if (!alphabetic (c)) + break; + } + --count; + } + window->point = point; + info_show_point (window); +} + +DECLARE_INFO_COMMAND (info_backward_word, "Move backward a word") +{ + long point; + char *buffer; + int c; + + if (count < 0) + { + info_forward_word (window, -count, key); + return; + } + + buffer = window->node->contents; + point = window->point; + + while (count) + { + if (point == 0) + break; + + /* Like info_forward_word (), except that we look at the + characters just before point. */ + + c = buffer[point - 1]; + + if (!alphabetic (c)) + { + while (--point) + { + c = buffer[point - 1]; + if (alphabetic (c)) + break; + } + } + + while (point) + { + c = buffer[point - 1]; + if (!alphabetic (c)) + break; + else + --point; + } + --count; + } + window->point = point; + info_show_point (window); +} + +/* Here is a list of time counter names which correspond to ordinal numbers. + It is used to print "once" instead of "1". */ +static char *counter_names[] = { + "not at all", "once", "twice", "three", "four", "five", "six", + (char *)NULL +}; + +/* Buffer used to return values from times_description (). */ +static char td_buffer[50]; + +/* Function returns a static string fully describing the number of times + present in COUNT. */ +static char * +times_description (count) + int count; +{ + register int i; + + td_buffer[0] = '\0'; + + for (i = 0; counter_names[i]; i++) + if (count == i) + break; + + if (counter_names[i]) + sprintf (td_buffer, "%s%s", counter_names[i], count > 2 ? " times" : ""); + else + sprintf (td_buffer, "%d times", count); + + return (td_buffer); +} + +/* Variable controlling the behaviour of default scrolling when you are + already at the bottom of a node. Possible values are defined in session.h. + The meanings are: + + IS_Continuous Try to get first menu item, or failing that, the + "Next:" pointer, or failing that, the "Up:" and + "Next:" of the up. + IS_NextOnly Try to get "Next:" menu item. + IS_PageOnly Simply give up at the bottom of a node. */ + +int info_scroll_behaviour = IS_Continuous; + +/* Choices used by the completer when reading a value for the user-visible + variable "scroll-behaviour". */ +char *info_scroll_choices[] = { + "Continuous", "Next Only", "Page Only", (char *)NULL +}; + +/* Move to 1st menu item, Next, Up/Next, or error in this window. */ +static void +forward_move_node_structure (window, behaviour) + WINDOW *window; + int behaviour; +{ + switch (behaviour) + { + case IS_PageOnly: + info_error (AT_NODE_BOTTOM); + break; + + case IS_NextOnly: + info_next_label_of_node (window->node); + if (!info_parsed_nodename && !info_parsed_filename) + info_error ("No \"Next\" pointer for this node."); + else + { + window_message_in_echo_area ("Following \"Next\" node..."); + info_handle_pointer ("Next", window); + } + break; + + case IS_Continuous: + { + /* First things first. If this node contains a menu, move down + into the menu. */ + { + REFERENCE **menu; + + menu = info_menu_of_node (window->node); + + if (menu) + { + info_free_references (menu); + window_message_in_echo_area ("Selecting first menu item..."); + info_menu_digit (window, 1, '1'); + return; + } + } + + /* Okay, this node does not contain a menu. If it contains a + "Next:" pointer, use that. */ + info_next_label_of_node (window->node); + if (info_label_was_found) + { + window_message_in_echo_area ("Selecting \"Next\" node..."); + info_handle_pointer ("Next", window); + return; + } + + /* Okay, there wasn't a "Next:" for this node. Move "Up:" until we + can move "Next:". If that isn't possible, complain that there + are no more nodes. */ + { + int up_counter, old_current; + INFO_WINDOW *info_win; + + /* Remember the current node and location. */ + info_win = get_info_window_of_window (window); + old_current = info_win->current; + + /* Back up through the "Up:" pointers until we have found a "Next:" + that isn't the same as the first menu item found in that node. */ + up_counter = 0; + while (!info_error_was_printed) + { + info_up_label_of_node (window->node); + if (info_label_was_found) + { + info_handle_pointer ("Up", window); + if (info_error_was_printed) + continue; + + up_counter++; + + info_next_label_of_node (window->node); + + /* If no "Next" pointer, keep backing up. */ + if (!info_label_was_found) + continue; + + /* If this node's first menu item is the same as this node's + Next pointer, keep backing up. */ + if (!info_parsed_filename) + { + REFERENCE **menu; + char *next_nodename; + + /* Remember the name of the Next node, since reading + the menu can overwrite the contents of the + info_parsed_xxx strings. */ + next_nodename = savestring (info_parsed_nodename); + + menu = info_menu_of_node (window->node); + if (menu && + (strcmp + (menu[0]->nodename, next_nodename) == 0)) + { + info_free_references (menu); + free (next_nodename); + continue; + } + else + { + /* Restore the world to where it was before + reading the menu contents. */ + info_free_references (menu); + free (next_nodename); + info_next_label_of_node (window->node); + } + } + + /* This node has a "Next" pointer, and it is not the + same as the first menu item found in this node. */ + window_message_in_echo_area + ("Moving \"Up\" %s, then \"Next\".", + times_description (up_counter)); + + info_handle_pointer ("Next", window); + return; + } + else + { + /* No more "Up" pointers. Print an error, and call it + quits. */ + register int i; + + for (i = 0; i < up_counter; i++) + { + info_win->nodes_index--; + free (info_win->nodes[info_win->nodes_index]); + info_win->nodes[info_win->nodes_index] = (NODE *)NULL; + } + info_win->current = old_current; + window->node = info_win->nodes[old_current]; + window->pagetop = info_win->pagetops[old_current]; + window->point = info_win->points[old_current]; + recalculate_line_starts (window); + window->flags |= W_UpdateWindow; + info_error ("No more nodes."); + } + } + } + break; + } + } +} + +/* Move Prev, Up or error in WINDOW depending on BEHAVIOUR. */ +static void +backward_move_node_structure (window, behaviour) + WINDOW *window; + int behaviour; +{ + switch (behaviour) + { + case IS_PageOnly: + info_error (AT_NODE_TOP); + break; + + case IS_NextOnly: + info_prev_label_of_node (window->node); + if (!info_parsed_nodename && !info_parsed_filename) + info_error ("No \"Prev\" for this node."); + else + { + window_message_in_echo_area ("Moving \"Prev\" in this window."); + info_handle_pointer ("Prev", window); + } + break; + + case IS_Continuous: + info_prev_label_of_node (window->node); + + if (!info_parsed_nodename && !info_parsed_filename) + { + info_up_label_of_node (window->node); + if (!info_parsed_nodename && !info_parsed_filename) + info_error ("No \"Prev\" or \"Up\" for this node."); + else + { + window_message_in_echo_area ("Moving \"Up\" in this window."); + info_handle_pointer ("Up", window); + } + } + else + { + REFERENCE **menu; + int inhibit_menu_traversing = 0; + + /* Watch out! If this node's Prev is the same as the Up, then + move Up. Otherwise, we could move Prev, and then to the last + menu item in the Prev. This would cause the user to loop + through a subsection of the info file. */ + if (!info_parsed_filename && info_parsed_nodename) + { + char *pnode; + + pnode = savestring (info_parsed_nodename); + info_up_label_of_node (window->node); + + if (!info_parsed_filename && info_parsed_nodename && + strcmp (info_parsed_nodename, pnode) == 0) + { + /* The nodes are the same. Inhibit moving to the last + menu item. */ + free (pnode); + inhibit_menu_traversing = 1; + } + else + { + free (pnode); + info_prev_label_of_node (window->node); + } + } + + /* Move to the previous node. If this node now contains a menu, + and we have not inhibited movement to it, move to the node + corresponding to the last menu item. */ + window_message_in_echo_area ("Moving \"Prev\" in this window."); + info_handle_pointer ("Prev", window); + + if (!inhibit_menu_traversing) + { + while (!info_error_was_printed && + (menu = info_menu_of_node (window->node))) + { + info_free_references (menu); + window_message_in_echo_area + ("Moving to \"Prev\"'s last menu item."); + info_menu_digit (window, 1, '0'); + } + } + } + break; + } +} + +/* Move continuously forward through the node structure of this info file. */ +DECLARE_INFO_COMMAND (info_global_next_node, + "Move forwards or down through node structure") +{ + if (count < 0) + info_global_prev_node (window, -count, key); + else + { + while (count && !info_error_was_printed) + { + forward_move_node_structure (window, IS_Continuous); + count--; + } + } +} + +/* Move continuously backward through the node structure of this info file. */ +DECLARE_INFO_COMMAND (info_global_prev_node, + "Move backwards or up through node structure") +{ + if (count < 0) + info_global_next_node (window, -count, key); + else + { + while (count && !info_error_was_printed) + { + backward_move_node_structure (window, IS_Continuous); + count--; + } + } +} + +/* Show the next screen of WINDOW's node. */ +DECLARE_INFO_COMMAND (info_scroll_forward, "Scroll forward in this window") +{ + if (count < 0) + info_scroll_backward (window, -count, key); + else + { + int desired_top; + + /* Without an explicit numeric argument, scroll the bottom two + lines to the top of this window, Or, if at bottom of window, + and the user wishes to scroll through nodes get the "Next" node + for this window. */ + if (!info_explicit_arg && count == 1) + { + desired_top = window->pagetop + (window->height - 2); + + /* If there are no more lines to scroll here, error, or get + another node, depending on INFO_SCROLL_BEHAVIOUR. */ + if (desired_top > window->line_count) + { + int behaviour = info_scroll_behaviour; + + /* Here is a hack. If the key being used is not SPC, do the + PageOnly behaviour. */ + if (key != SPC && key != DEL) + behaviour = IS_PageOnly; + + forward_move_node_structure (window, behaviour); + return; + } + } + else + desired_top = window->pagetop + count; + + if (desired_top >= window->line_count) + desired_top = window->line_count - 2; + + if (window->pagetop > desired_top) + return; + else + set_window_pagetop (window, desired_top); + } +} + +/* Show the previous screen of WINDOW's node. */ +DECLARE_INFO_COMMAND (info_scroll_backward, "Scroll backward in this window") +{ + if (count < 0) + info_scroll_forward (window, -count, key); + else + { + int desired_top; + + /* Without an explicit numeric argument, scroll the top two lines + to the bottom of this window, or move to the previous, or Up'th + node. */ + if (!info_explicit_arg && count == 1) + { + desired_top = window->pagetop - (window->height - 2); + + if ((desired_top < 0) && (window->pagetop == 0)) + { + int behaviour = info_scroll_behaviour; + + /* Same kind of hack as in info_scroll_forward. If the key + used to invoke this command is not DEL, do only the PageOnly + behaviour. */ + if (key != DEL && key != SPC) + behaviour = IS_PageOnly; + + backward_move_node_structure (window, behaviour); + return; + } + } + else + desired_top = window->pagetop - count; + + if (desired_top < 0) + desired_top = 0; + + set_window_pagetop (window, desired_top); + } +} + +/* Move to the beginning of the node. */ +DECLARE_INFO_COMMAND (info_beginning_of_node, "Move to the start of this node") +{ + window->pagetop = window->point = 0; + window->flags |= W_UpdateWindow; +} + +/* Move to the end of the node. */ +DECLARE_INFO_COMMAND (info_end_of_node, "Move to the end of this node") +{ + window->point = window->node->nodelen - 1; + info_show_point (window); +} + +/* **************************************************************** */ +/* */ +/* Commands for Manipulating Windows */ +/* */ +/* **************************************************************** */ + +/* Make the next window in the chain be the active window. */ +DECLARE_INFO_COMMAND (info_next_window, "Select the next window") +{ + if (count < 0) + { + info_prev_window (window, -count, key); + return; + } + + /* If no other window, error now. */ + if (!windows->next && !echo_area_is_active) + { + info_error (ONE_WINDOW); + return; + } + + while (count--) + { + if (window->next) + window = window->next; + else + { + if (window == the_echo_area || !echo_area_is_active) + window = windows; + else + window = the_echo_area; + } + } + + if (active_window != window) + { + if (auto_footnotes_p) + info_get_or_remove_footnotes (window); + + window->flags |= W_UpdateWindow; + active_window = window; + } +} + +/* Make the previous window in the chain be the active window. */ +DECLARE_INFO_COMMAND (info_prev_window, "Select the previous window") +{ + if (count < 0) + { + info_next_window (window, -count, key); + return; + } + + /* Only one window? */ + + if (!windows->next && !echo_area_is_active) + { + info_error (ONE_WINDOW); + return; + } + + while (count--) + { + /* If we are in the echo area, or if the echo area isn't active and we + are in the first window, find the last window in the chain. */ + if (window == the_echo_area || + (window == windows && !echo_area_is_active)) + { + register WINDOW *win, *last; + + for (win = windows; win; win = win->next) + last = win; + + window = last; + } + else + { + if (window == windows) + window = the_echo_area; + else + window = window->prev; + } + } + + if (active_window != window) + { + if (auto_footnotes_p) + info_get_or_remove_footnotes (window); + + window->flags |= W_UpdateWindow; + active_window = window; + } +} + +/* Split WINDOW into two windows, both showing the same node. If we + are automatically tiling windows, re-tile after the split. */ +DECLARE_INFO_COMMAND (info_split_window, "Split the current window") +{ + WINDOW *split, *old_active; + int pagetop; + + /* Remember the current pagetop of the window being split. If it doesn't + change, we can scroll its contents around after the split. */ + pagetop = window->pagetop; + + /* Make the new window. */ + old_active = active_window; + active_window = window; + split = window_make_window (window->node); + active_window = old_active; + + if (!split) + { + info_error (WIN_TOO_SMALL); + } + else + { +#if defined (SPLIT_BEFORE_ACTIVE) + /* Try to scroll the old window into its new postion. */ + if (pagetop == window->pagetop) + { + int start, end, amount; + + start = split->first_row; + end = start + window->height; + amount = split->height + 1; + display_scroll_display (start, end, amount); + } +#else /* !SPLIT_BEFORE_ACTIVE */ + /* Make sure point still appears in the active window. */ + info_show_point (window); +#endif /* !SPLIT_BEFORE_ACTIVE */ + + /* If the window just split was one internal to Info, try to display + something else in it. */ + if (internal_info_node_p (split->node)) + { + register int i, j; + INFO_WINDOW *iw; + NODE *node = (NODE *)NULL; + char *filename; + + for (i = 0; iw = info_windows[i]; i++) + { + for (j = 0; j < iw->nodes_index; j++) + if (!internal_info_node_p (iw->nodes[j])) + { + if (iw->nodes[j]->parent) + filename = iw->nodes[j]->parent; + else + filename = iw->nodes[j]->filename; + + node = info_get_node (filename, iw->nodes[j]->nodename); + if (node) + { + window_set_node_of_window (split, node); + i = info_windows_index - 1; + break; + } + } + } + } + split->pagetop = window->pagetop; + + if (auto_tiling_p) + window_tile_windows (DONT_TILE_INTERNALS); + else + window_adjust_pagetop (split); + + remember_window_and_node (split, split->node); + } +} + +/* Delete WINDOW, forgetting the list of last visited nodes. If we are + automatically displaying footnotes, show or remove the footnotes + window. If we are automatically tiling windows, re-tile after the + deletion. */ +DECLARE_INFO_COMMAND (info_delete_window, "Delete the current window") +{ + if (!windows->next) + { + info_error (CANT_KILL_LAST); + } + else if (window->flags & W_WindowIsPerm) + { + info_error ("Cannot delete a permanent window"); + } + else + { + info_delete_window_internal (window); + + if (auto_footnotes_p) + info_get_or_remove_footnotes (active_window); + + if (auto_tiling_p) + window_tile_windows (DONT_TILE_INTERNALS); + } +} + +/* Do the physical deletion of WINDOW, and forget this window and + associated nodes. */ +void +info_delete_window_internal (window) + WINDOW *window; +{ + if (windows->next && ((window->flags & W_WindowIsPerm) == 0)) + { + /* We not only delete the window from the display, we forget it from + our list of remembered windows. */ + forget_window_and_nodes (window); + window_delete_window (window); + + if (echo_area_is_active) + echo_area_inform_of_deleted_window (window); + } +} + +/* Just keep WINDOW, deleting all others. */ +DECLARE_INFO_COMMAND (info_keep_one_window, "Delete all other windows") +{ + int num_deleted; /* The number of windows we deleted. */ + int pagetop, start, end; + + /* Remember a few things about this window. We may be able to speed up + redisplay later by scrolling its contents. */ + pagetop = window->pagetop; + start = window->first_row; + end = start + window->height; + + num_deleted = 0; + + while (1) + { + WINDOW *win; + + /* Find an eligible window and delete it. If no eligible windows + are found, we are done. A window is eligible for deletion if + is it not permanent, and it is not WINDOW. */ + for (win = windows; win; win = win->next) + if (win != window && ((win->flags & W_WindowIsPerm) == 0)) + break; + + if (!win) + break; + + info_delete_window_internal (win); + num_deleted++; + } + + /* Scroll the contents of this window into the right place so that the + user doesn't have to wait any longer than necessary for redisplay. */ + if (num_deleted) + { + int amount; + + amount = (window->first_row - start); + amount -= (window->pagetop - pagetop); + display_scroll_display (start, end, amount); + } + + window->flags |= W_UpdateWindow; +} + +/* Scroll the "other" window of WINDOW. */ +DECLARE_INFO_COMMAND (info_scroll_other_window, "Scroll the other window") +{ + WINDOW *other; + + /* If only one window, give up. */ + if (!windows->next) + { + info_error (ONE_WINDOW); + return; + } + + other = window->next; + + if (!other) + other = window->prev; + + info_scroll_forward (other, count, key); +} + +/* Change the size of WINDOW by AMOUNT. */ +DECLARE_INFO_COMMAND (info_grow_window, "Grow (or shrink) this window") +{ + window_change_window_height (window, count); +} + +/* When non-zero, tiling takes place automatically when info_split_window + is called. */ +int auto_tiling_p = 0; + +/* Tile all of the visible windows. */ +DECLARE_INFO_COMMAND (info_tile_windows, + "Divide the available screen space among the visible windows") +{ + window_tile_windows (TILE_INTERNALS); +} + +/* Toggle the state of this window's wrapping of lines. */ +DECLARE_INFO_COMMAND (info_toggle_wrap, + "Toggle the state of line wrapping in the current window") +{ + window_toggle_wrap (window); +} + +/* **************************************************************** */ +/* */ +/* Info Node Commands */ +/* */ +/* **************************************************************** */ + +/* Using WINDOW for various defaults, select the node referenced by ENTRY + in it. If the node is selected, the window and node are remembered. */ +void +info_select_reference (window, entry) + WINDOW *window; + REFERENCE *entry; +{ + NODE *node; + char *filename, *nodename, *file_system_error; + + file_system_error = (char *)NULL; + + filename = entry->filename; + if (!filename) + filename = window->node->parent; + if (!filename) + filename = window->node->filename; + + if (filename) + filename = savestring (filename); + + if (entry->nodename) + nodename = savestring (entry->nodename); + else + nodename = savestring ("Top"); + + node = info_get_node (filename, nodename); + + /* Try something a little weird. If the node couldn't be found, and the + reference was of the form "foo::", see if the entry->label can be found + as a file, with a node of "Top". */ + if (!node) + { + if (info_recent_file_error) + file_system_error = savestring (info_recent_file_error); + + if (entry->nodename && (strcmp (entry->nodename, entry->label) == 0)) + { + node = info_get_node (entry->label, "Top"); + if (!node && info_recent_file_error) + { + maybe_free (file_system_error); + file_system_error = savestring (info_recent_file_error); + } + } + } + + if (!node) + { + if (file_system_error) + info_error (file_system_error); + else + info_error (CANT_FIND_NODE, nodename); + } + + maybe_free (file_system_error); + maybe_free (filename); + maybe_free (nodename); + + if (node) + { + set_remembered_pagetop_and_point (window); + info_set_node_of_window (window, node); + } +} + +/* Parse the node specification in LINE using WINDOW to default the filename. + Select the parsed node in WINDOW and remember it, or error if the node + couldn't be found. */ +static void +info_parse_and_select (line, window) + char *line; + WINDOW *window; +{ + REFERENCE entry; + + info_parse_node (line, DONT_SKIP_NEWLINES); + + entry.nodename = info_parsed_nodename; + entry.filename = info_parsed_filename; + entry.label = "*info-parse-and-select*"; + + info_select_reference (window, &entry); +} + +/* Given that the values of INFO_PARSED_FILENAME and INFO_PARSED_NODENAME + are previously filled, try to get the node represented by them into + WINDOW. The node should have been pointed to by the LABEL pointer of + WINDOW->node. */ +static void +info_handle_pointer (label, window) + char *label; + WINDOW *window; +{ + if (info_parsed_filename || info_parsed_nodename) + { + char *filename, *nodename; + NODE *node; + + filename = nodename = (char *)NULL; + + if (info_parsed_filename) + filename = savestring (info_parsed_filename); + else + { + if (window->node->parent) + filename = savestring (window->node->parent); + else if (window->node->filename) + filename = savestring (window->node->filename); + } + + if (info_parsed_nodename) + nodename = savestring (info_parsed_nodename); + else + nodename = savestring ("Top"); + + node = info_get_node (filename, nodename); + + if (node) + { + INFO_WINDOW *info_win; + + info_win = get_info_window_of_window (window); + if (info_win) + { + info_win->pagetops[info_win->current] = window->pagetop; + info_win->points[info_win->current] = window->point; + } + set_remembered_pagetop_and_point (window); + info_set_node_of_window (window, node); + } + else + { + if (info_recent_file_error) + info_error (info_recent_file_error); + else + info_error (CANT_FILE_NODE, filename, nodename); + } + + free (filename); + free (nodename); + } + else + { + info_error (NO_POINTER, label); + } +} + +/* Make WINDOW display the "Next:" node of the node currently being + displayed. */ +DECLARE_INFO_COMMAND (info_next_node, "Select the `Next' node") +{ + info_next_label_of_node (window->node); + info_handle_pointer ("Next", window); +} + +/* Make WINDOW display the "Prev:" node of the node currently being + displayed. */ +DECLARE_INFO_COMMAND (info_prev_node, "Select the `Prev' node") +{ + info_prev_label_of_node (window->node); + info_handle_pointer ("Prev", window); +} + +/* Make WINDOW display the "Up:" node of the node currently being + displayed. */ +DECLARE_INFO_COMMAND (info_up_node, "Select the `Up' node") +{ + info_up_label_of_node (window->node); + info_handle_pointer ("Up", window); +} + +/* Make WINDOW display the last node of this info file. */ +DECLARE_INFO_COMMAND (info_last_node, "Select the last node in this file") +{ + register int i; + FILE_BUFFER *fb = file_buffer_of_window (window); + NODE *node = (NODE *)NULL; + + if (fb && fb->tags) + { + for (i = 0; fb->tags[i]; i++); + node = info_get_node (fb->filename, fb->tags[i - 1]->nodename); + } + + if (!node) + info_error ("This window has no additional nodes"); + else + { + set_remembered_pagetop_and_point (window); + info_set_node_of_window (window, node); + } +} + +/* Make WINDOW display the first node of this info file. */ +DECLARE_INFO_COMMAND (info_first_node, "Select the first node in this file") +{ + FILE_BUFFER *fb = file_buffer_of_window (window); + NODE *node = (NODE *)NULL; + + if (fb && fb->tags) + node = info_get_node (fb->filename, fb->tags[0]->nodename); + + if (!node) + info_error ("This window has no additional nodes"); + else + { + set_remembered_pagetop_and_point (window); + info_set_node_of_window (window, node); + } +} + +/* Make WINDOW display the previous node displayed in this window. */ +DECLARE_INFO_COMMAND (info_history_node, + "Select the most recently selected node") +{ + INFO_WINDOW *info_win; + + /* Find the INFO_WINDOW which contains WINDOW. */ + info_win = get_info_window_of_window (window); + + if (!info_win) + { + info_error ("Requested window is not present!"); + return; + } + + set_remembered_pagetop_and_point (window); + if (!info_win->current) + { + if (info_win->nodes_index > 1) + { + window_message_in_echo_area + ("Now wrapped around to beginning of history."); + info_win->current = info_win->nodes_index; + } + else + { + info_error ("No earlier nodes in this window."); + return; + } + } + + info_win->current--; + window_set_node_of_window (window, info_win->nodes[info_win->current]); + window->pagetop = info_win->pagetops[info_win->current]; + window->point = info_win->points[info_win->current]; + window->flags |= W_UpdateWindow; + if (auto_footnotes_p) + info_get_or_remove_footnotes (window); +} + +/* Select the last menu item in WINDOW->node. */ +DECLARE_INFO_COMMAND (info_last_menu_item, + "Select the last item in this node's menu") +{ + info_menu_digit (window, 1, '0'); +} + +/* Use KEY (a digit) to select the Nth menu item in WINDOW->node. */ +DECLARE_INFO_COMMAND (info_menu_digit, "Select this menu item") +{ + register int i, item; + register REFERENCE *entry, **menu; + + menu = info_menu_of_node (window->node); + + if (!menu) + { + info_error (NO_MENU_NODE); + return; + } + + /* We have the menu. See if there are this many items in it. */ + item = key - '0'; + + /* Special case. Item "0" is the last item in this menu. */ + if (item == 0) + for (i = 0; menu[i + 1]; i++); + else + { + for (i = 0; entry = menu[i]; i++) + if (i == item - 1) + break; + } + + if (menu[i]) + info_select_reference (window, menu[i]); + else + info_error ("There aren't %d items in this menu.", item); + + info_free_references (menu); + return; +} + +/* Read a menu or followed reference from the user defaulting to the + reference found on the current line, and select that node. The + reading is done with completion. BUILDER is the function used + to build the list of references. ASK_P is non-zero if the user + should be prompted, or zero to select the default item. */ +static void +info_menu_or_ref_item (window, count, key, builder, ask_p) + WINDOW *window; + int count; + unsigned char key; + REFERENCE **(*builder) (); + int ask_p; +{ + REFERENCE **menu, *entry, *defentry = (REFERENCE *)NULL; + char *line; + + menu = (*builder) (window->node); + + if (!menu) + { + if (builder == info_menu_of_node) + info_error (NO_MENU_NODE); + else + info_error (NO_XREF_NODE); + return; + } + + /* Default the selected reference to the one which is on the line that + point is in. */ + { + REFERENCE **refs = (REFERENCE **)NULL; + int point_line; + + point_line = window_line_of_point (window); + + if (point_line != -1) + { + SEARCH_BINDING binding; + + binding.start = 0; + binding.buffer = window->line_starts[point_line]; + if (window->line_starts[point_line + 1]) + binding.end = window->line_starts[point_line + 1] - binding.buffer; + else + binding.end = + (window->node->contents + window->node->nodelen) - binding.buffer; + binding.flags = 0; + + if (builder == info_menu_of_node) + { + if (point_line) + { + binding.buffer--; + binding.end++; + + refs = info_menu_items (&binding); + } + } + else + refs = info_xrefs (&binding); + + if (refs) + { + if ((strcmp (refs[0]->label, "Menu") != 0) || + (builder == info_xrefs_of_node)) + { + defentry = (REFERENCE *)xmalloc (sizeof (REFERENCE)); + defentry->label = savestring (refs[0]->label); + defentry->filename = refs[0]->filename; + defentry->nodename = refs[0]->nodename; + + if (defentry->filename) + defentry->filename = savestring (defentry->filename); + if (defentry->nodename) + defentry->nodename = savestring (defentry->nodename); + } + info_free_references (refs); + } + } + } + + /* If we are going to ask the user a question, do it now. */ + if (ask_p) + { + char *prompt; + + /* Build the prompt string. */ + if (defentry) + prompt = (char *)xmalloc (20 + strlen (defentry->label)); + else + prompt = (char *)xmalloc (20); + + if (builder == info_menu_of_node) + { + if (defentry) + sprintf (prompt, "Menu item (%s): ", defentry->label); + else + sprintf (prompt, "Menu item: "); + } + else + { + if (defentry) + sprintf (prompt, "Follow xref (%s): ", defentry->label); + else + sprintf (prompt, "Follow xref: "); + } + + line = info_read_completing_in_echo_area (window, prompt, menu); + free (prompt); + + window = active_window; + + /* User aborts, just quit. */ + if (!line) + { + maybe_free (defentry); + info_free_references (menu); + info_abort_key (window, 0, 0); + return; + } + + /* If we had a default and the user accepted it, use that. */ + if (!*line) + { + free (line); + if (defentry) + line = savestring (defentry->label); + else + line = (char *)NULL; + } + } + else + { + /* Not going to ask any questions. If we have a default entry, use + that, otherwise return. */ + if (!defentry) + return; + else + line = savestring (defentry->label); + } + + if (line) + { + /* Find the selected label in the references. */ + entry = info_get_labeled_reference (line, menu); + + if (!entry && defentry) + info_error ("The reference disappeared! (%s).", line); + else + { + NODE *orig; + + orig = window->node; + info_select_reference (window, entry); + if ((builder == info_xrefs_of_node) && (window->node != orig)) + { + long offset; + long start; + + if (window->line_count > 0) + start = window->line_starts[1] - window->node->contents; + else + start = 0; + + offset = + info_target_search_node (window->node, entry->label, start); + + if (offset != -1) + { + window->point = offset; + window_adjust_pagetop (window); + } + } + } + + free (line); + if (defentry) + { + free (defentry->label); + maybe_free (defentry->filename); + maybe_free (defentry->nodename); + free (defentry); + } + } + + info_free_references (menu); + + if (!info_error_was_printed) + window_clear_echo_area (); +} + +/* Read a line (with completion) which is the name of a menu item, + and select that item. */ +DECLARE_INFO_COMMAND (info_menu_item, "Read a menu item and select its node") +{ + info_menu_or_ref_item (window, count, key, info_menu_of_node, 1); +} + +/* Read a line (with completion) which is the name of a reference to + follow, and select the node. */ +DECLARE_INFO_COMMAND + (info_xref_item, "Read a footnote or cross reference and select its node") +{ + info_menu_or_ref_item (window, count, key, info_xrefs_of_node, 1); +} + +/* Position the cursor at the start of this node's menu. */ +DECLARE_INFO_COMMAND (info_find_menu, "Move to the start of this node's menu") +{ + SEARCH_BINDING binding; + long position; + + binding.buffer = window->node->contents; + binding.start = 0; + binding.end = window->node->nodelen; + binding.flags = S_FoldCase | S_SkipDest; + + position = search (INFO_MENU_LABEL, &binding); + + if (position == -1) + info_error (NO_MENU_NODE); + else + { + window->point = position; + window_adjust_pagetop (window); + window->flags |= W_UpdateWindow; + } +} + +/* Visit as many menu items as is possible, each in a separate window. */ +DECLARE_INFO_COMMAND (info_visit_menu, + "Visit as many menu items at once as possible") +{ + register int i; + REFERENCE *entry, **menu; + + menu = info_menu_of_node (window->node); + + if (!menu) + info_error (NO_MENU_NODE); + + for (i = 0; (!info_error_was_printed) && (entry = menu[i]); i++) + { + WINDOW *new; + + new = window_make_window (window->node); + window_tile_windows (TILE_INTERNALS); + + if (!new) + info_error (WIN_TOO_SMALL); + else + { + active_window = new; + info_select_reference (new, entry); + } + } +} + +/* Read a line of input which is a node name, and go to that node. */ +DECLARE_INFO_COMMAND (info_goto_node, "Read a node name and select it") +{ + char *line; + NODE *node; + +#define GOTO_COMPLETES +#if defined (GOTO_COMPLETES) + /* Build a completion list of all of the known nodes. */ + { + register int fbi, i; + FILE_BUFFER *current; + REFERENCE **items = (REFERENCE **)NULL; + int items_index = 0; + int items_slots = 0; + + current = file_buffer_of_window (window); + + for (fbi = 0; info_loaded_files && info_loaded_files[fbi]; fbi++) + { + FILE_BUFFER *fb; + REFERENCE *entry; + int this_is_the_current_fb; + + fb = info_loaded_files[fbi]; + this_is_the_current_fb = (current == fb); + + entry = (REFERENCE *)xmalloc (sizeof (REFERENCE)); + entry->filename = entry->nodename = (char *)NULL; + entry->label = (char *)xmalloc (4 + strlen (fb->filename)); + sprintf (entry->label, "(%s)*", fb->filename); + + add_pointer_to_array + (entry, items_index, items, items_slots, 10, REFERENCE *); + + if (fb->tags) + { + for (i = 0; fb->tags[i]; i++) + { + entry = (REFERENCE *)xmalloc (sizeof (REFERENCE)); + entry->filename = entry->nodename = (char *)NULL; + entry->label = (char *) xmalloc + (4 + strlen (fb->filename) + strlen (fb->tags[i]->nodename)); + sprintf (entry->label, "(%s)%s", + fb->filename, fb->tags[i]->nodename); + + add_pointer_to_array + (entry, items_index, items, items_slots, 100, REFERENCE *); + } + + if (this_is_the_current_fb) + { + for (i = 0; fb->tags[i]; i++) + { + entry = (REFERENCE *)xmalloc (sizeof (REFERENCE)); + entry->filename = entry->nodename = (char *)NULL; + entry->label = savestring (fb->tags[i]->nodename); + add_pointer_to_array (entry, items_index, items, + items_slots, 100, REFERENCE *); + } + } + } + } + line = info_read_maybe_completing (window, "Goto Node: ", items); + info_free_references (items); + } +#else /* !GOTO_COMPLETES */ + line = info_read_in_echo_area (window, "Goto Node: "); +#endif /* !GOTO_COMPLETES */ + + /* If the user aborted, quit now. */ + if (!line) + { + info_abort_key (window, 0, 0); + return; + } + + canonicalize_whitespace (line); + + if (*line) + info_parse_and_select (line, window); + + free (line); + if (!info_error_was_printed) + window_clear_echo_area (); +} + +/* Move to the "Top" node in this file. */ +DECLARE_INFO_COMMAND (info_top_node, "Select the node `Top' in this file") +{ + info_parse_and_select ("Top", window); +} + +/* Move to the node "(dir)Top". */ +DECLARE_INFO_COMMAND (info_dir_node, "Select the node `(dir)'") +{ + info_parse_and_select ("(dir)Top", window); +} + +/* Try to delete the current node appearing in this window, showing the most + recently selected node in this window. */ +DECLARE_INFO_COMMAND (info_kill_node, "Kill this node") +{ + register int iw, i; + register INFO_WINDOW *info_win; + char *nodename = (char *)NULL; + NODE *temp = (NODE *)NULL; + + /* Read the name of a node to kill. The list of available nodes comes + from the nodes appearing in the current window configuration. */ + { + REFERENCE **menu = (REFERENCE **)NULL; + int menu_index = 0, menu_slots = 0; + char *default_nodename, *prompt; + + for (iw = 0; info_win = info_windows[iw]; iw++) + { + REFERENCE *entry; + + entry = (REFERENCE *)xmalloc (sizeof (REFERENCE)); + entry->label = savestring (info_win->window->node->nodename); + entry->filename = entry->nodename = (char *)NULL; + + add_pointer_to_array + (entry, menu_index, menu, menu_slots, 10, REFERENCE *); + } + + default_nodename = savestring (active_window->node->nodename); + prompt = (char *)xmalloc (40 + strlen (default_nodename)); + sprintf (prompt, "Kill node (%s): ", default_nodename); + + nodename = info_read_completing_in_echo_area (window, prompt, menu); + free (prompt); + info_free_references (menu); + if (nodename && !*nodename) + { + free (nodename); + nodename = default_nodename; + } + else + free (default_nodename); + } + + /* If there is no nodename to kill, quit now. */ + if (!nodename) + { + info_abort_key (window, 0, 0); + return; + } + + /* If there is a nodename, find it in our window list. */ + for (iw = 0; info_win = info_windows[iw]; iw++) + if (strcmp (nodename, info_win->nodes[info_win->current]->nodename) == 0) + break; + + if (!info_win) + { + if (*nodename) + info_error ("Cannot kill the node `%s'", nodename); + else + window_clear_echo_area (); + + return; + } + + /* If there are no more nodes left anywhere to view, complain and exit. */ + if (info_windows_index == 1 && info_windows[0]->nodes_index == 1) + { + info_error ("Cannot kill the last node"); + return; + } + + /* INFO_WIN contains the node that the user wants to stop viewing. + Delete this node from the list of nodes previously shown in this + window. */ + for (i = info_win->current; i < info_win->nodes_index; i++) + info_win->nodes[i] = info_win->nodes[i++]; + + /* There is one less node in this window's history list. */ + info_win->nodes_index--; + + /* Make this window show the most recent history node. */ + info_win->current = info_win->nodes_index - 1; + + /* If there aren't any nodes left in this window, steal one from the + next window. */ + if (info_win->current < 0) + { + INFO_WINDOW *stealer; + int which, pagetop; + long point; + + if (info_windows[iw + 1]) + stealer = info_windows[iw + 1]; + else + stealer = info_windows[0]; + + /* If the node being displayed in the next window is not the most + recently loaded one, get the most recently loaded one. */ + if ((stealer->nodes_index - 1) != stealer->current) + which = stealer->nodes_index - 1; + + /* Else, if there is another node behind the stealers current node, + use that one. */ + else if (stealer->current > 0) + which = stealer->current - 1; + + /* Else, just use the node appearing in STEALER's window. */ + else + which = stealer->current; + + /* Copy this node. */ + { + NODE *copy; + + temp = stealer->nodes[which]; + point = stealer->points[which]; + pagetop = stealer->pagetops[which]; + + copy = (NODE *)xmalloc (sizeof (NODE)); + copy->filename = temp->filename; + copy->parent = temp->parent; + copy->nodename = temp->nodename; + copy->contents = temp->contents; + copy->nodelen = temp->nodelen; + copy->flags = temp->flags; + + temp = copy; + } + + window_set_node_of_window (info_win->window, temp); + window->point = point; + window->pagetop = pagetop; + remember_window_and_node (info_win->window, temp); + } + else + { + temp = info_win->nodes[info_win->current]; + window_set_node_of_window (info_win->window, temp); + } + if (!info_error_was_printed) + window_clear_echo_area (); +} + +/* Read the name of a file and select the entire file. */ +DECLARE_INFO_COMMAND (info_view_file, "Read the name of a file and select it") +{ + char *line; + + line = info_read_in_echo_area (window, "Find file: "); + if (!line) + { + info_abort_key (active_window, 1, 0); + return; + } + + if (*line) + { + NODE *node; + + node = info_get_node (line, "*"); + if (!node) + { + if (info_recent_file_error) + info_error (info_recent_file_error); + else + info_error ("Cannot find \"%s\".", line); + } + else + { + set_remembered_pagetop_and_point (active_window); + info_set_node_of_window (window, node); + } + free (line); + } + + if (!info_error_was_printed) + window_clear_echo_area (); +} + +/* **************************************************************** */ +/* */ +/* Dumping and Printing Nodes */ +/* */ +/* **************************************************************** */ + +#define VERBOSE_NODE_DUMPING +static void write_node_to_stream (); +static void dump_node_to_stream (); +static void initialize_dumping (); + +/* Dump the nodes specified by FILENAME and NODENAMES to the file named + in OUTPUT_FILENAME. If DUMP_SUBNODES is non-zero, recursively dump + the nodes which appear in the menu of each node dumped. */ +void +dump_nodes_to_file (filename, nodenames, output_filename, dump_subnodes) + char *filename; + char **nodenames; + char *output_filename; + int dump_subnodes; +{ + register int i; + FILE *output_stream; + + /* Get the stream to print the nodes to. Special case of an output + filename of "-" means to dump the nodes to stdout. */ + if (strcmp (output_filename, "-") == 0) + output_stream = stdout; + else + output_stream = fopen (output_filename, "w"); + + if (!output_stream) + { + info_error ("Could not create output file \"%s\".", output_filename); + return; + } + + /* Print each node to stream. */ + initialize_dumping (); + for (i = 0; nodenames[i]; i++) + dump_node_to_stream (filename, nodenames[i], output_stream, dump_subnodes); + + if (output_stream != stdout) + fclose (output_stream); + +#if defined (VERBOSE_NODE_DUMPING) + info_error ("Done."); +#endif /* VERBOSE_NODE_DUMPING */ +} + +/* A place to remember already dumped nodes. */ +static char **dumped_already = (char **)NULL; +static int dumped_already_index = 0; +static int dumped_already_slots = 0; + +static void +initialize_dumping () +{ + dumped_already_index = 0; +} + +/* Get and print the node specified by FILENAME and NODENAME to STREAM. + If DUMP_SUBNODES is non-zero, recursively dump the nodes which appear + in the menu of each node dumped. */ +static void +dump_node_to_stream (filename, nodename, stream, dump_subnodes) + char *filename, *nodename; + FILE *stream; + int dump_subnodes; +{ + register int i; + NODE *node; + + node = info_get_node (filename, nodename); + + if (!node) + { + if (info_recent_file_error) + info_error (info_recent_file_error); + else + { + if (filename && *nodename != '(') + info_error + (CANT_FILE_NODE, filename_non_directory (filename), nodename); + else + info_error (CANT_FIND_NODE, nodename); + } + return; + } + + /* If we have already dumped this node, don't dump it again. */ + for (i = 0; i < dumped_already_index; i++) + if (strcmp (node->nodename, dumped_already[i]) == 0) + { + free (node); + return; + } + add_pointer_to_array (node->nodename, dumped_already_index, dumped_already, + dumped_already_slots, 50, char *); + +#if defined (VERBOSE_NODE_DUMPING) + /* Maybe we should print some information about the node being output. */ + if (node->filename) + info_error ("Writing node \"(%s)%s\"...", + filename_non_directory (node->filename), node->nodename); + else + info_error ("Writing node \"%s\"...", node->nodename); +#endif /* VERBOSE_NODE_DUMPING */ + + write_node_to_stream (node, stream); + + /* If we are dumping subnodes, get the list of menu items in this node, + and dump each one recursively. */ + if (dump_subnodes) + { + REFERENCE **menu = (REFERENCE **)NULL; + + /* If this node is an Index, do not dump the menu references. */ + if (string_in_line ("Index", node->nodename) == -1) + menu = info_menu_of_node (node); + + if (menu) + { + for (i = 0; menu[i]; i++) + { + /* We don't dump Info files which are different than the + current one. */ + if (!menu[i]->filename) + dump_node_to_stream + (filename, menu[i]->nodename, stream, dump_subnodes); + } + info_free_references (menu); + } + } + + free (node); +} + +/* Dump NODE to FILENAME. If DUMP_SUBNODES is non-zero, recursively dump + the nodes which appear in the menu of each node dumped. */ +void +dump_node_to_file (node, filename, dump_subnodes) + NODE *node; + char *filename; + int dump_subnodes; +{ + FILE *output_stream; + char *nodes_filename; + + /* Get the stream to print this node to. Special case of an output + filename of "-" means to dump the nodes to stdout. */ + if (strcmp (filename, "-") == 0) + output_stream = stdout; + else + output_stream = fopen (filename, "w"); + + if (!output_stream) + { + info_error ("Could not create output file \"%s\".", filename); + return; + } + + if (node->parent) + nodes_filename = node->parent; + else + nodes_filename = node->filename; + + initialize_dumping (); + dump_node_to_stream + (nodes_filename, node->nodename, output_stream, dump_subnodes); + + if (output_stream != stdout) + fclose (output_stream); + +#if defined (VERBOSE_NODE_DUMPING) + info_error ("Done."); +#endif /* VERBOSE_NODE_DUMPING */ +} + +#if !defined (DEFAULT_INFO_PRINT_COMMAND) +# define DEFAULT_INFO_PRINT_COMMAND "lpr" +#endif /* !DEFAULT_INFO_PRINT_COMMAND */ + +DECLARE_INFO_COMMAND (info_print_node, + "Pipe the contents of this node through INFO_PRINT_COMMAND") +{ + print_node (window->node); +} + +/* Print NODE on a printer piping it into INFO_PRINT_COMMAND. */ +void +print_node (node) + NODE *node; +{ + char *print_command, *getenv (); + FILE *printer_pipe; + + print_command = getenv ("INFO_PRINT_COMMAND"); + + if (!print_command || !*print_command) + print_command = DEFAULT_INFO_PRINT_COMMAND; + + printer_pipe = popen (print_command, "w"); + + if (!printer_pipe) + { + info_error ("Cannot open pipe to \"%s\".", print_command); + return; + } + +#if defined (VERBOSE_NODE_DUMPING) + /* Maybe we should print some information about the node being output. */ + if (node->filename) + info_error ("Printing node \"(%s)%s\"...", + filename_non_directory (node->filename), node->nodename); + else + info_error ("Printing node \"%s\"...", node->nodename); +#endif /* VERBOSE_NODE_DUMPING */ + + write_node_to_stream (node, printer_pipe); + pclose (printer_pipe); + +#if defined (VERBOSE_NODE_DUMPING) + info_error ("Done."); +#endif /* VERBOSE_NODE_DUMPING */ +} + +static void +write_node_to_stream (node, stream) + NODE *node; + FILE *stream; +{ + fwrite (node->contents, 1, node->nodelen, stream); +} + +/* **************************************************************** */ +/* */ +/* Info Searching Commands */ +/* */ +/* **************************************************************** */ + +/* Variable controlling the garbage collection of files briefly visited + during searches. Such files are normally gc'ed, unless they were + compressed to begin with. If this variable is non-zero, it says + to gc even those file buffer contents which had to be uncompressed. */ +int gc_compressed_files = 0; + +static void info_gc_file_buffers (); + +static char *search_string = (char *)NULL; +static int search_string_index = 0; +static int search_string_size = 0; +static int isearch_is_active = 0; + +/* Return the file buffer which belongs to WINDOW's node. */ +FILE_BUFFER * +file_buffer_of_window (window) + WINDOW *window; +{ + /* If this window has no node, then it has no file buffer. */ + if (!window->node) + return ((FILE_BUFFER *)NULL); + + if (window->node->parent) + return (info_find_file (window->node->parent)); + + if (window->node->filename) + return (info_find_file (window->node->filename)); + + return ((FILE_BUFFER *)NULL); +} + +/* Search for STRING in NODE starting at START. Return -1 if the string + was not found, or the location of the string if it was. If WINDOW is + passed as non-null, set the window's node to be NODE, its point to be + the found string, and readjust the window's pagetop. Final argument + DIR says which direction to search in. If it is positive, search + forward, else backwards. */ +long +info_search_in_node (string, node, start, window, dir) + char *string; + NODE *node; + long start; + WINDOW *window; + int dir; +{ + SEARCH_BINDING binding; + long offset; + + binding.buffer = node->contents; + binding.start = start; + binding.end = node->nodelen; + binding.flags = S_FoldCase; + + if (dir < 0) + { + binding.end = 0; + binding.flags |= S_SkipDest; + } + + if (binding.start < 0) + return (-1); + + /* For incremental searches, we always wish to skip past the string. */ + if (isearch_is_active) + binding.flags |= S_SkipDest; + + offset = search (string, &binding); + + if (offset != -1 && window) + { + set_remembered_pagetop_and_point (window); + if (window->node != node) + window_set_node_of_window (window, node); + window->point = offset; + window_adjust_pagetop (window); + } + return (offset); +} + +/* Search NODE, looking for the largest possible match of STRING. Start the + search at START. Return the absolute position of the match, or -1, if + no part of the string could be found. */ +long +info_target_search_node (node, string, start) + NODE *node; + char *string; + long start; +{ + register int i; + long offset; + char *target; + + target = savestring (string); + i = strlen (target); + + /* Try repeatedly searching for this string while removing words from + the end of it. */ + while (i) + { + target[i] = '\0'; + offset = info_search_in_node (target, node, start, (WINDOW *)NULL, 1); + + if (offset != -1) + break; + + /* Delete the last word from TARGET. */ + for (; i && (!whitespace (target[i]) && (target[i] != ',')); i--); + } + free (target); + return (offset); +} + +/* Search for STRING starting in WINDOW at point. If the string is found + in this node, set point to that position. Otherwise, get the file buffer + associated with WINDOW's node, and search through each node in that file. + If the search fails, return non-zero, else zero. Side-effect window + leaving the node and point where the string was found current. */ +static char *last_searched_for_string = (char *)NULL; +static int +info_search_internal (string, window, dir) + char *string; + WINDOW *window; + int dir; +{ + register int i; + FILE_BUFFER *file_buffer; + char *initial_nodename; + long ret, start = 0; + + file_buffer = file_buffer_of_window (window); + initial_nodename = window->node->nodename; + + if ((info_last_executed_command == info_search) && + (last_searched_for_string) && + (strcmp (last_searched_for_string, string) == 0)) + { + ret = info_search_in_node + (string, window->node, window->point + dir, window, dir); + } + else + { + ret = info_search_in_node + (string, window->node, window->point, window, dir); + } + + maybe_free (last_searched_for_string); + last_searched_for_string = savestring (string); + + if (ret != -1) + { + /* We won! */ + if (!echo_area_is_active && !isearch_is_active) + window_clear_echo_area (); + return (0); + } + + /* The string wasn't found in the current node. Search through the + window's file buffer, iff the current node is not "*". */ + if (!file_buffer || (strcmp (initial_nodename, "*") == 0)) + return (-1); + + /* If this file has tags, search through every subfile, starting at + this node's subfile and node. Otherwise, search through the + file's node list. */ + if (file_buffer->tags) + { + register int current_tag, number_of_tags; + char *last_subfile; + TAG *tag; + + /* Find number of tags and current tag. */ + last_subfile = (char *)NULL; + for (i = 0; file_buffer->tags[i]; i++) + if (strcmp (initial_nodename, file_buffer->tags[i]->nodename) == 0) + { + current_tag = i; + last_subfile = file_buffer->tags[i]->filename; + } + + number_of_tags = i; + + /* If there is no last_subfile, our tag wasn't found. */ + if (!last_subfile) + return (-1); + + /* Search through subsequent nodes, wrapping around to the top + of the info file until we find the string or return to this + window's node and point. */ + while (1) + { + NODE *node; + + /* Allow C-g to quit the search, failing it if pressed. */ + return_if_control_g (-1); + + current_tag += dir; + + if (current_tag < 0) + current_tag = number_of_tags - 1; + else if (current_tag == number_of_tags) + current_tag = 0; + + tag = file_buffer->tags[current_tag]; + + if (!echo_area_is_active && (last_subfile != tag->filename)) + { + window_message_in_echo_area + ("Searching subfile \"%s\"...", + filename_non_directory (tag->filename)); + + last_subfile = tag->filename; + } + + node = info_get_node (file_buffer->filename, tag->nodename); + + if (!node) + { + /* If not doing i-search... */ + if (!echo_area_is_active) + { + if (info_recent_file_error) + info_error (info_recent_file_error); + else + info_error (CANT_FILE_NODE, + filename_non_directory (file_buffer->filename), + tag->nodename); + } + return (-1); + } + + if (dir < 0) + start = tag->nodelen; + + ret = + info_search_in_node (string, node, start, window, dir); + + /* Did we find the string in this node? */ + if (ret != -1) + { + /* Yes! We win. */ + remember_window_and_node (window, node); + if (!echo_area_is_active) + window_clear_echo_area (); + return (0); + } + + /* No. Free this node, and make sure that we haven't passed + our starting point. */ + free (node); + + if (strcmp (initial_nodename, tag->nodename) == 0) + return (-1); + } + } + return (-1); +} + +DECLARE_INFO_COMMAND (info_search, "Read a string and search for it") +{ + char *line, *prompt; + int result, old_pagetop; + int direction; + + if (count < 0) + direction = -1; + else + direction = 1; + + /* Read a string from the user, defaulting the search to SEARCH_STRING. */ + if (!search_string) + { + search_string = (char *)xmalloc (search_string_size = 100); + search_string[0] = '\0'; + } + + prompt = (char *)xmalloc (50 + strlen (search_string)); + + sprintf (prompt, "%s for string [%s]: ", + direction < 0 ? "Search backward" : "Search", + search_string); + + line = info_read_in_echo_area (window, prompt); + free (prompt); + + if (!line) + { + info_abort_key (); + return; + } + + if (*line) + { + if (strlen (line) + 1 > search_string_size) + search_string = (char *) + xrealloc (search_string, (search_string_size += 50 + strlen (line))); + + strcpy (search_string, line); + search_string_index = strlen (line); + free (line); + } + + old_pagetop = active_window->pagetop; + result = info_search_internal (search_string, active_window, direction); + + if (result != 0 && !info_error_was_printed) + info_error ("Search failed."); + else if (old_pagetop != active_window->pagetop) + { + int new_pagetop; + + new_pagetop = active_window->pagetop; + active_window->pagetop = old_pagetop; + set_window_pagetop (active_window, new_pagetop); + if (auto_footnotes_p) + info_get_or_remove_footnotes (active_window); + } + + /* Perhaps free the unreferenced file buffers that were searched, but + not retained. */ + info_gc_file_buffers (); +} + +/* **************************************************************** */ +/* */ +/* Incremental Searching */ +/* */ +/* **************************************************************** */ + +static void incremental_search (); + +DECLARE_INFO_COMMAND (isearch_forward, + "Search interactively for a string as you type it") +{ + incremental_search (window, count, key); +} + +DECLARE_INFO_COMMAND (isearch_backward, + "Search interactively for a string as you type it") +{ + incremental_search (window, -count, key); +} + +/* Incrementally search for a string as it is typed. */ +/* The last accepted incremental search string. */ +static char *last_isearch_accepted = (char *)NULL; + +/* The current incremental search string. */ +static char *isearch_string = (char *)NULL; +static int isearch_string_index = 0; +static int isearch_string_size = 0; +static unsigned char isearch_terminate_search_key = ESC; + +/* Structure defining the current state of an incremental search. */ +typedef struct { + WINDOW_STATE_DECL; /* The node, pagetop and point. */ + int search_index; /* Offset of the last char in the search string. */ + int direction; /* The direction that this search is heading in. */ + int failing; /* Whether or not this search failed. */ +} SEARCH_STATE; + +/* Array of search states. */ +static SEARCH_STATE **isearch_states = (SEARCH_STATE **)NULL; +static int isearch_states_index = 0; +static int isearch_states_slots = 0; + +/* Push the state of this search. */ +static void +push_isearch (window, search_index, direction, failing) + WINDOW *window; + int search_index, direction, failing; +{ + SEARCH_STATE *state; + + state = (SEARCH_STATE *)xmalloc (sizeof (SEARCH_STATE)); + window_get_state (window, state); + state->search_index = search_index; + state->direction = direction; + state->failing = failing; + + add_pointer_to_array (state, isearch_states_index, isearch_states, + isearch_states_slots, 20, SEARCH_STATE *); +} + +/* Pop the state of this search to WINDOW, SEARCH_INDEX, and DIRECTION. */ +static void +pop_isearch (window, search_index, direction, failing) + WINDOW *window; + int *search_index, *direction, *failing; +{ + SEARCH_STATE *state; + + if (isearch_states_index) + { + isearch_states_index--; + state = isearch_states[isearch_states_index]; + window_set_state (window, state); + *search_index = state->search_index; + *direction = state->direction; + *failing = state->failing; + + free (state); + isearch_states[isearch_states_index] = (SEARCH_STATE *)NULL; + } +} + +/* Free the memory used by isearch_states. */ +static void +free_isearch_states () +{ + register int i; + + for (i = 0; i < isearch_states_index; i++) + { + free (isearch_states[i]); + isearch_states[i] = (SEARCH_STATE *)NULL; + } + isearch_states_index = 0; +} + +/* Display the current search in the echo area. */ +static void +show_isearch_prompt (dir, string, failing_p) + int dir; + unsigned char *string; + int failing_p; +{ + register int i; + char *prefix, *prompt, *p_rep; + int prompt_len, p_rep_index, p_rep_size; + + if (dir < 0) + prefix = "I-search backward: "; + else + prefix = "I-search: "; + + p_rep_index = p_rep_size = 0; + p_rep = (char *)NULL; + for (i = 0; string[i]; i++) + { + char *rep; + + switch (string[i]) + { + case ' ': rep = " "; break; + case LFD: rep = "\\n"; break; + case TAB: rep = "\\t"; break; + default: + rep = pretty_keyname (string[i]); + } + if ((p_rep_index + strlen (rep) + 1) >= p_rep_size) + p_rep = (char *)xrealloc (p_rep, p_rep_size += 100); + + strcpy (p_rep + p_rep_index, rep); + p_rep_index += strlen (rep); + } + + prompt_len = strlen (prefix) + p_rep_index + 20; + prompt = (char *)xmalloc (prompt_len); + sprintf (prompt, "%s%s%s", failing_p ? "Failing " : "", prefix, + p_rep ? p_rep : ""); + + window_message_in_echo_area ("%s", prompt); + maybe_free (p_rep); + free (prompt); + display_cursor_at_point (active_window); +} + +static void +incremental_search (window, count, ignore) + WINDOW *window; + int count; + unsigned char ignore; +{ + unsigned char key; + int last_search_result, search_result, dir; + SEARCH_STATE mystate, orig_state; + + if (count < 0) + dir = -1; + else + dir = 1; + + last_search_result = search_result = 0; + + window_get_state (window, &orig_state); + + isearch_string_index = 0; + if (!isearch_string_size) + isearch_string = (char *)xmalloc (isearch_string_size = 50); + + /* Show the search string in the echo area. */ + isearch_string[isearch_string_index] = '\0'; + show_isearch_prompt (dir, isearch_string, search_result); + + isearch_is_active = 1; + + while (isearch_is_active) + { + VFunction *func = (VFunction *)NULL; + int quoted = 0; + + /* If a recent display was interrupted, then do the redisplay now if + it is convenient. */ + if (!info_any_buffered_input_p () && display_was_interrupted_p) + { + display_update_one_window (window); + display_cursor_at_point (active_window); + } + + /* Read a character and dispatch on it. */ + key = info_get_input_char (); + window_get_state (window, &mystate); + + if (key == DEL) + { + /* User wants to delete one level of search? */ + if (!isearch_states_index) + { + terminal_ring_bell (); + continue; + } + else + { + pop_isearch + (window, &isearch_string_index, &dir, &search_result); + isearch_string[isearch_string_index] = '\0'; + show_isearch_prompt (dir, isearch_string, search_result); + goto after_search; + } + } + else if (key == Control ('q')) + { + key = info_get_input_char (); + quoted = 1; + } + + /* We are about to search again, or quit. Save the current search. */ + push_isearch (window, isearch_string_index, dir, search_result); + + if (quoted) + goto insert_and_search; + + if (!Meta_p (key) || (ISO_Latin_p && key < 160)) + { + func = window->keymap[key].function; + + /* If this key invokes an incremental search, then this means that + we will either search again in the same direction, search + again in the reverse direction, or insert the last search + string that was accepted through incremental searching. */ + if (func == isearch_forward || func == isearch_backward) + { + if ((func == isearch_forward && dir > 0) || + (func == isearch_backward && dir < 0)) + { + /* If the user has typed no characters, then insert the + last successful search into the current search string. */ + if (isearch_string_index == 0) + { + /* Of course, there must be something to insert. */ + if (last_isearch_accepted) + { + if (strlen (last_isearch_accepted) + 1 >= + isearch_string_size) + isearch_string = (char *) + xrealloc (isearch_string, + isearch_string_size += 10 + + strlen (last_isearch_accepted)); + strcpy (isearch_string, last_isearch_accepted); + isearch_string_index = strlen (isearch_string); + goto search_now; + } + else + continue; + } + else + { + /* Search again in the same direction. This means start + from a new place if the last search was successful. */ + if (search_result == 0) + window->point += dir; + } + } + else + { + /* Reverse the direction of the search. */ + dir = -dir; + } + } + else if (isprint (key) || func == (VFunction *)NULL) + { + insert_and_search: + + if (isearch_string_index + 2 >= isearch_string_size) + isearch_string = (char *)xrealloc + (isearch_string, isearch_string_size += 100); + + isearch_string[isearch_string_index++] = key; + isearch_string[isearch_string_index] = '\0'; + goto search_now; + } + else if (func == info_abort_key) + { + /* If C-g pressed, and the search is failing, pop the search + stack back to the last unfailed search. */ + if (isearch_states_index && (search_result != 0)) + { + terminal_ring_bell (); + while (isearch_states_index && (search_result != 0)) + pop_isearch + (window, &isearch_string_index, &dir, &search_result); + isearch_string[isearch_string_index] = '\0'; + show_isearch_prompt (dir, isearch_string, search_result); + continue; + } + else + goto exit_search; + } + else + goto exit_search; + } + else + { + exit_search: + /* The character is not printable, or it has a function which is + non-null. Exit the search, remembering the search string. If + the key is not the same as the isearch_terminate_search_key, + then push it into pending input. */ + if (isearch_string_index && func != info_abort_key) + { + maybe_free (last_isearch_accepted); + last_isearch_accepted = savestring (isearch_string); + } + + if (key != isearch_terminate_search_key) + info_set_pending_input (key); + + if (func == info_abort_key) + { + if (isearch_states_index) + window_set_state (window, &orig_state); + } + + if (!echo_area_is_active) + window_clear_echo_area (); + + if (auto_footnotes_p) + info_get_or_remove_footnotes (active_window); + + isearch_is_active = 0; + continue; + } + + /* Search for the contents of isearch_string. */ + search_now: + show_isearch_prompt (dir, isearch_string, search_result); + + if (search_result == 0) + { + /* Check to see if the current search string is right here. If + we are looking at it, then don't bother calling the search + function. */ + if (((dir < 0) && + (strnicmp (window->node->contents + window->point, + isearch_string, isearch_string_index) == 0)) || + ((dir > 0) && + ((window->point - isearch_string_index) >= 0) && + (strnicmp (window->node->contents + + (window->point - (isearch_string_index - 1)), + isearch_string, isearch_string_index) == 0))) + { + if (dir > 0) + window->point++; + } + else + search_result = info_search_internal (isearch_string, window, dir); + } + + /* If this search failed, and we didn't already have a failed search, + then ring the terminal bell. */ + if (search_result != 0 && last_search_result == 0) + terminal_ring_bell (); + + after_search: + show_isearch_prompt (dir, isearch_string, search_result); + + if (search_result == 0) + { + if ((mystate.node == window->node) && + (mystate.pagetop != window->pagetop)) + { + int newtop = window->pagetop; + window->pagetop = mystate.pagetop; + set_window_pagetop (window, newtop); + } + display_update_one_window (window); + display_cursor_at_point (window); + } + + last_search_result = search_result; + } + + /* Free the memory used to remember each search state. */ + free_isearch_states (); + + /* Perhaps GC some file buffers. */ + info_gc_file_buffers (); + + /* After searching, leave the window in the correct state. */ + if (!echo_area_is_active) + window_clear_echo_area (); +} + +/* GC some file buffers. A file buffer can be gc-ed if there we have + no nodes in INFO_WINDOWS that reference this file buffer's contents. + Garbage collecting a file buffer means to free the file buffers + contents. */ +static void +info_gc_file_buffers () +{ + register int fb_index, iw_index, i; + register FILE_BUFFER *fb; + register INFO_WINDOW *iw; + + if (!info_loaded_files) + return; + + for (fb_index = 0; fb = info_loaded_files[fb_index]; fb_index++) + { + int fb_referenced_p = 0; + + /* If already gc-ed, do nothing. */ + if (!fb->contents) + continue; + + /* If this file had to be uncompressed, check to see if we should + gc it. This means that the user-variable "gc-compressed-files" + is non-zero. */ + if ((fb->flags & N_IsCompressed) && !gc_compressed_files) + continue; + + /* If this file's contents are not gc-able, move on. */ + if (fb->flags & N_CannotGC) + continue; + + /* Check each INFO_WINDOW to see if it has any nodes which reference + this file. */ + for (iw_index = 0; iw = info_windows[iw_index]; iw_index++) + { + for (i = 0; iw->nodes && iw->nodes[i]; i++) + { + if ((strcmp (fb->fullpath, iw->nodes[i]->filename) == 0) || + (strcmp (fb->filename, iw->nodes[i]->filename) == 0)) + { + fb_referenced_p = 1; + break; + } + } + } + + /* If this file buffer wasn't referenced, free its contents. */ + if (!fb_referenced_p) + { + free (fb->contents); + fb->contents = (char *)NULL; + } + } +} + +/* **************************************************************** */ +/* */ +/* Traversing and Selecting References */ +/* */ +/* **************************************************************** */ + +/* Move to the next or previous cross reference in this node. */ +static void +info_move_to_xref (window, count, key, dir) + WINDOW *window; + int count; + unsigned char key; + int dir; +{ + long firstmenu, firstxref; + long nextmenu, nextxref; + long placement = -1; + long start = 0; + NODE *node = window->node; + + if (dir < 0) + start = node->nodelen; + + /* This search is only allowed to fail if there is no menu or cross + reference in the current node. Otherwise, the first menu or xref + found is moved to. */ + + firstmenu = info_search_in_node + (INFO_MENU_ENTRY_LABEL, node, start, (WINDOW *)NULL, dir); + + /* FIRSTMENU may point directly to the line defining the menu. Skip that + and go directly to the first item. */ + + if (firstmenu != -1) + { + char *text = node->contents + firstmenu; + + if (strncmp (text, INFO_MENU_LABEL, strlen (INFO_MENU_LABEL)) == 0) + firstmenu = info_search_in_node + (INFO_MENU_ENTRY_LABEL, node, firstmenu + dir, (WINDOW *)NULL, dir); + } + + firstxref = + info_search_in_node (INFO_XREF_LABEL, node, start, (WINDOW *)NULL, dir); + + if (firstmenu == -1 && firstxref == -1) + { + info_error ("No cross references in this node."); + return; + } + + /* There is at least one cross reference or menu entry in this node. + Try hard to find the next available one. */ + + nextmenu = info_search_in_node + (INFO_MENU_ENTRY_LABEL, node, window->point + dir, (WINDOW *)NULL, dir); + + nextxref = info_search_in_node + (INFO_XREF_LABEL, node, window->point + dir, (WINDOW *)NULL, dir); + + /* Ignore "Menu:" as a menu item. */ + if (nextmenu != -1) + { + char *text = node->contents + nextmenu; + + if (strncmp (text, INFO_MENU_LABEL, strlen (INFO_MENU_LABEL)) == 0) + nextmenu = info_search_in_node + (INFO_MENU_ENTRY_LABEL, node, nextmenu + dir, (WINDOW *)NULL, dir); + } + + /* If there is both a next menu entry, and a next xref entry, choose the + one which occurs first. Otherwise, select the one which actually + appears in this node following point. */ + if (nextmenu != -1 && nextxref != -1) + { + if (((dir == 1) && (nextmenu < nextxref)) || + ((dir == -1) && (nextmenu > nextxref))) + placement = nextmenu + 1; + else + placement = nextxref; + } + else if (nextmenu != -1) + placement = nextmenu + 1; + else if (nextxref != -1) + placement = nextxref; + + /* If there was neither a menu or xref entry appearing in this node after + point, choose the first menu or xref entry appearing in this node. */ + if (placement == -1) + { + if (firstmenu != -1 && firstxref != -1) + { + if (((dir == 1) && (firstmenu < firstxref)) || + ((dir == -1) && (firstmenu > firstxref))) + placement = firstmenu + 1; + else + placement = firstxref; + } + else if (firstmenu != -1) + placement = firstmenu + 1; + else + placement = firstxref; + } + window->point = placement; + window_adjust_pagetop (window); + window->flags |= W_UpdateWindow; +} + +DECLARE_INFO_COMMAND (info_move_to_prev_xref, + "Move to the previous cross reference") +{ + if (count < 0) + info_move_to_prev_xref (window, -count, key); + else + info_move_to_xref (window, count, key, -1); +} + +DECLARE_INFO_COMMAND (info_move_to_next_xref, + "Move to the next cross reference") +{ + if (count < 0) + info_move_to_next_xref (window, -count, key); + else + info_move_to_xref (window, count, key, 1); +} + +/* Select the menu item or reference that appears on this line. */ +DECLARE_INFO_COMMAND (info_select_reference_this_line, + "Select reference or menu item appearing on this line") +{ + char *line; + NODE *orig; + + line = window->line_starts[window_line_of_point (window)]; + orig = window->node; + + /* If this line contains a menu item, select that one. */ + if (strncmp ("* ", line, 2) == 0) + info_menu_or_ref_item (window, count, key, info_menu_of_node, 0); + else + info_menu_or_ref_item (window, count, key, info_xrefs_of_node, 0); +} + +/* **************************************************************** */ +/* */ +/* Miscellaneous Info Commands */ +/* */ +/* **************************************************************** */ + +/* What to do when C-g is pressed in a window. */ +DECLARE_INFO_COMMAND (info_abort_key, "Cancel current operation") +{ + /* If error printing doesn't oridinarily ring the bell, do it now, + since C-g always rings the bell. Otherwise, let the error printer + do it. */ + if (!info_error_rings_bell_p) + terminal_ring_bell (); + info_error ("Quit"); + + info_initialize_numeric_arg (); + info_clear_pending_input (); + info_last_executed_command = (VFunction *)NULL; +} + +/* Move the cursor to the desired line of the window. */ +DECLARE_INFO_COMMAND (info_move_to_window_line, + "Move to the cursor to a specific line of the window") +{ + int line; + + /* With no numeric argument of any kind, default to the center line. */ + if (!info_explicit_arg && count == 1) + line = (window->height / 2) + window->pagetop; + else + { + if (count < 0) + line = (window->height + count) + window->pagetop; + else + line = window->pagetop + count; + } + + /* If the line doesn't appear in this window, make it do so. */ + if ((line - window->pagetop) >= window->height) + line = window->pagetop + (window->height - 1); + + /* If the line is too small, make it fit. */ + if (line < window->pagetop) + line = window->pagetop; + + /* If the selected line is past the bottom of the node, force it back. */ + if (line >= window->line_count) + line = window->line_count - 1; + + window->point = (window->line_starts[line] - window->node->contents); +} + +/* Clear the screen and redraw its contents. Given a numeric argument, + move the line the cursor is on to the COUNT'th line of the window. */ +DECLARE_INFO_COMMAND (info_redraw_display, "Redraw the display") +{ + if ((!info_explicit_arg && count == 1) || echo_area_is_active) + { + terminal_clear_screen (); + display_clear_display (the_display); + window_mark_chain (windows, W_UpdateWindow); + display_update_display (windows); + } + else + { + int desired_line, point_line; + int new_pagetop; + + point_line = window_line_of_point (window) - window->pagetop; + + if (count < 0) + desired_line = window->height + count; + else + desired_line = count; + + if (desired_line < 0) + desired_line = 0; + + if (desired_line >= window->height) + desired_line = window->height - 1; + + if (desired_line == point_line) + return; + + new_pagetop = window->pagetop + (point_line - desired_line); + + set_window_pagetop (window, new_pagetop); + } +} +/* This command does nothing. It is the fact that a key is bound to it + that has meaning. See the code at the top of info_session (). */ +DECLARE_INFO_COMMAND (info_quit, "Quit using Info") +{} + + +/* **************************************************************** */ +/* */ +/* Reading Keys and Dispatching on Them */ +/* */ +/* **************************************************************** */ + +/* Declaration only. Special cased in info_dispatch_on_key (). */ +DECLARE_INFO_COMMAND (info_do_lowercase_version, "") +{} + +static void +dispatch_error (keyseq) + char *keyseq; +{ + char *rep; + + rep = pretty_keyseq (keyseq); + + if (!echo_area_is_active) + info_error ("Unknown command (%s).", rep); + else + { + char *temp; + + temp = (char *)xmalloc (1 + strlen (rep) + strlen ("\"\" is invalid")); + + sprintf (temp, "\"%s\" is invalid", rep); + terminal_ring_bell (); + inform_in_echo_area (temp); + free (temp); + } +} + +/* Keeping track of key sequences. */ +static char *info_keyseq = (char *)NULL; +static char keyseq_rep[100]; +static int info_keyseq_index = 0; +static int info_keyseq_size = 0; +static int info_keyseq_displayed_p = 0; + +/* Initialize the length of the current key sequence. */ +void +initialize_keyseq () +{ + info_keyseq_index = 0; + info_keyseq_displayed_p = 0; +} + +/* Add CHARACTER to the current key sequence. */ +void +add_char_to_keyseq (character) + char character; +{ + if (info_keyseq_index + 2 >= info_keyseq_size) + info_keyseq = (char *)xrealloc (info_keyseq, info_keyseq_size += 10); + + info_keyseq[info_keyseq_index++] = character; + info_keyseq[info_keyseq_index] = '\0'; +} + +/* Return the pretty printable string which represents KEYSEQ. */ +char * +pretty_keyseq (keyseq) + char *keyseq; +{ + register int i; + + keyseq_rep[0] = '\0'; + + for (i = 0; keyseq[i]; i++) + { + sprintf (keyseq_rep + strlen (keyseq_rep), "%s%s", + strlen (keyseq_rep) ? " " : "", + pretty_keyname (keyseq[i])); + } + + return (keyseq_rep); +} + +/* Display the current value of info_keyseq. If argument EXPECTING is + non-zero, input is expected to be read after the key sequence is + displayed, so add an additional prompting character to the sequence. */ +void +display_info_keyseq (expecting_future_input) + int expecting_future_input; +{ + char *rep; + + rep = pretty_keyseq (info_keyseq); + if (expecting_future_input) + strcat (rep, "-"); + + if (echo_area_is_active) + inform_in_echo_area (rep); + else + { + window_message_in_echo_area (rep); + display_cursor_at_point (active_window); + } + info_keyseq_displayed_p = 1; +} + +/* Called by interactive commands to read a keystroke. */ +unsigned char +info_get_another_input_char () +{ + int ready = 0; + + /* If there isn't any input currently available, then wait a + moment looking for input. If we don't get it fast enough, + prompt a little bit with the current key sequence. */ + if (!info_keyseq_displayed_p && + !info_any_buffered_input_p () && + !info_input_pending_p ()) + { +#if defined (FD_SET) + struct timeval timer; + fd_set readfds; + + FD_ZERO (&readfds); + FD_SET (fileno (info_input_stream), &readfds); + timer.tv_sec = 1; + timer.tv_usec = 750; + ready = select (1, &readfds, (fd_set *)NULL, (fd_set *)NULL, &timer); +#endif /* FD_SET */ + } + + if (!ready) + display_info_keyseq (1); + + return (info_get_input_char ()); +} + +/* Do the command associated with KEY in MAP. If the associated command is + really a keymap, then read another key, and dispatch into that map. */ +void +info_dispatch_on_key (key, map) + unsigned char key; + Keymap map; +{ + if (Meta_p (key) && (!ISO_Latin_p || map[key].function != ea_insert)) + { + if (map[ESC].type == ISKMAP) + { + map = (Keymap)map[ESC].function; + add_char_to_keyseq (ESC); + key = UnMeta (key); + info_dispatch_on_key (key, map); + } + else + { + dispatch_error (info_keyseq); + } + return; + } + + switch (map[key].type) + { + case ISFUNC: + { + VFunction *func; + + func = map[key].function; + if (func != (VFunction *)NULL) + { + /* Special case info_do_lowercase_version (). */ + if (func == info_do_lowercase_version) + { + info_dispatch_on_key (tolower (key), map); + return; + } + + add_char_to_keyseq (key); + + if (info_keyseq_displayed_p) + display_info_keyseq (0); + + { + WINDOW *where; + + where = active_window; + (*map[key].function) + (active_window, info_numeric_arg * info_numeric_arg_sign, key); + + /* If we have input pending, then the last command was a prefix + command. Don't change the value of the last function vars. + Otherwise, remember the last command executed in the var + appropriate to the window in which it was executed. */ + if (!info_input_pending_p ()) + { + if (where == the_echo_area) + ea_last_executed_command = map[key].function; + else + info_last_executed_command = map[key].function; + } + } + } + else + { + add_char_to_keyseq (key); + dispatch_error (info_keyseq); + return; + } + } + break; + + case ISKMAP: + add_char_to_keyseq (key); + if (map[key].function != (VFunction *)NULL) + { + unsigned char newkey; + + newkey = info_get_another_input_char (); + info_dispatch_on_key (newkey, (Keymap)map[key].function); + } + else + { + dispatch_error (info_keyseq); + return; + } + break; + } +} + +/* **************************************************************** */ +/* */ +/* Numeric Arguments */ +/* */ +/* **************************************************************** */ + +/* Handle C-u style numeric args, as well as M--, and M-digits. */ + +/* Non-zero means that an explicit argument has been passed to this + command, as in C-u C-v. */ +int info_explicit_arg = 0; + +/* The sign of the numeric argument. */ +int info_numeric_arg_sign = 1; + +/* The value of the argument itself. */ +int info_numeric_arg = 1; + +/* Add the current digit to the argument in progress. */ +DECLARE_INFO_COMMAND (info_add_digit_to_numeric_arg, + "Add this digit to the current numeric argument") +{ + info_numeric_arg_digit_loop (window, 0, key); +} + +/* C-u, universal argument. Multiply the current argument by 4. + Read a key. If the key has nothing to do with arguments, then + dispatch on it. If the key is the abort character then abort. */ +DECLARE_INFO_COMMAND (info_universal_argument, + "Start (or multiply by 4) the current numeric argument") +{ + info_numeric_arg *= 4; + info_numeric_arg_digit_loop (window, 0, 0); +} + +/* Create a default argument. */ +void +info_initialize_numeric_arg () +{ + info_numeric_arg = info_numeric_arg_sign = 1; + info_explicit_arg = 0; +} + +DECLARE_INFO_COMMAND (info_numeric_arg_digit_loop, "") +{ + unsigned char pure_key; + Keymap keymap = window->keymap; + + while (1) + { + if (key) + pure_key = key; + else + { + if (display_was_interrupted_p && !info_any_buffered_input_p ()) + display_update_display (windows); + + if (active_window != the_echo_area) + display_cursor_at_point (active_window); + + pure_key = key = info_get_another_input_char (); + + if (Meta_p (key)) + add_char_to_keyseq (ESC); + + add_char_to_keyseq (UnMeta (key)); + } + + if (Meta_p (key)) + key = UnMeta (key); + + if (keymap[key].type == ISFUNC && + keymap[key].function == info_universal_argument) + { + info_numeric_arg *= 4; + key = 0; + continue; + } + + if (isdigit (key)) + { + if (info_explicit_arg) + info_numeric_arg = (info_numeric_arg * 10) + (key - '0'); + else + info_numeric_arg = (key - '0'); + info_explicit_arg = 1; + } + else + { + if (key == '-' && !info_explicit_arg) + { + info_numeric_arg_sign = -1; + info_numeric_arg = 1; + } + else + { + info_keyseq_index--; + info_dispatch_on_key (pure_key, keymap); + return; + } + } + key = 0; + } +} + +/* **************************************************************** */ +/* */ +/* Input Character Buffering */ +/* */ +/* **************************************************************** */ + +/* Character waiting to be read next. */ +static int pending_input_character = 0; + +/* How to make there be no pending input. */ +static void +info_clear_pending_input () +{ + pending_input_character = 0; +} + +/* How to set the pending input character. */ +static void +info_set_pending_input (key) + unsigned char key; +{ + pending_input_character = key; +} + +/* How to see if there is any pending input. */ +unsigned char +info_input_pending_p () +{ + return (pending_input_character); +} + +/* Largest number of characters that we can read in advance. */ +#define MAX_INFO_INPUT_BUFFERING 512 + +static int pop_index = 0, push_index = 0; +static unsigned char info_input_buffer[MAX_INFO_INPUT_BUFFERING]; + +/* Add KEY to the buffer of characters to be read. */ +static void +info_push_typeahead (key) + unsigned char key; +{ + /* Flush all pending input in the case of C-g pressed. */ + if (key == Control ('g')) + { + push_index = pop_index; + info_set_pending_input (Control ('g')); + } + else + { + info_input_buffer[push_index++] = key; + if (push_index >= sizeof (info_input_buffer)) + push_index = 0; + } +} + +/* Return the amount of space available in INFO_INPUT_BUFFER for new chars. */ +static int +info_input_buffer_space_available () +{ + if (pop_index > push_index) + return (pop_index - push_index); + else + return (sizeof (info_input_buffer - (push_index - pop_index))); +} + +/* Get a key from the buffer of characters to be read. + Return the key in KEY. + Result is non-zero if there was a key, or 0 if there wasn't. */ +static int +info_get_key_from_typeahead (key) + unsigned char *key; +{ + if (push_index == pop_index) + return (0); + + *key = info_input_buffer[pop_index++]; + + if (pop_index >= sizeof (info_input_buffer)) + pop_index = 0; + + return (1); +} + +int +info_any_buffered_input_p () +{ + info_gather_typeahead (); + return (push_index != pop_index); +} + +/* Push KEY into the *front* of the input buffer. Returns non-zero if + successful, zero if there is no space left in the buffer. */ +static int +info_replace_key_to_typeahead (key) + unsigned char key; +{ + if (info_input_buffer_space_available ()) + { + pop_index--; + if (pop_index < 0) + pop_index = sizeof (info_input_buffer) - 1; + info_input_buffer[pop_index] = key; + return (1); + } + return (0); +} + +/* If characters are available to be read, then read them and stuff them into + info_input_buffer. Otherwise, do nothing. */ +void +info_gather_typeahead () +{ + int tty, space_avail; + long chars_avail; + unsigned char input[MAX_INFO_INPUT_BUFFERING]; + + tty = fileno (info_input_stream); + chars_avail = 0; + + space_avail = info_input_buffer_space_available (); + + /* If we can just find out how many characters there are to read, do so. */ +#if defined (FIONREAD) + { + ioctl (tty, FIONREAD, &chars_avail); + + if (chars_avail > space_avail) + chars_avail = space_avail; + + if (chars_avail) + read (tty, &input[0], chars_avail); + } +#else /* !FIONREAD */ +# if defined (O_NDELAY) + { + int flags; + + flags = fcntl (tty, F_GETFL, 0); + + fcntl (tty, F_SETFL, (flags | O_NDELAY)); + chars_avail = read (tty, &input[0], space_avail); + fcntl (tty, F_SETFL, flags); + + if (chars_avail == -1) + chars_avail = 0; + } +# endif /* O_NDELAY */ +#endif /* !FIONREAD */ + + /* Store the input characters just read into our input buffer. */ + { + register int i; + + for (i = 0; i < chars_avail; i++) + info_push_typeahead (input[i]); + } +} + +/* How to read a single character. */ +unsigned char +info_get_input_char () +{ + unsigned char keystroke; + + info_gather_typeahead (); + + if (pending_input_character) + { + keystroke = pending_input_character; + pending_input_character = 0; + } + else if (info_get_key_from_typeahead (&keystroke) == 0) + { + int rawkey; + + rawkey = getc (info_input_stream); + keystroke = rawkey; + + if (rawkey == EOF) + { + if (info_input_stream != stdin) + { + fclose (info_input_stream); + info_input_stream = stdin; + display_inhibited = 0; + display_update_display (windows); + display_cursor_at_point (active_window); + rawkey = getc (info_input_stream); + keystroke = rawkey; + } + + if (rawkey == EOF) + { + terminal_unprep_terminal (); + close_dribble_file (); + exit (0); + } + } + } + + if (info_dribble_file) + dribble (keystroke); + + return (keystroke); +} diff --git a/gnu/usr.bin/texinfo/info/session.h b/gnu/usr.bin/texinfo/info/session.h new file mode 100644 index 0000000..08042dd --- /dev/null +++ b/gnu/usr.bin/texinfo/info/session.h @@ -0,0 +1,146 @@ +/* session.h -- Functions found in session.c. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#ifndef _SESSION_H_ +#define _SESSION_H_ + +#include "general.h" +#include "dribble.h" + +/* All commands that can be invoked from within info_session () receive + arguments in the same way. This simple define declares the header + of a function named NAME, with associated documentation DOC. The + documentation string is groveled out of the source files by the + utility program `builddoc', which is also responsible for making + the documentation/function-pointer maps. */ +#define DECLARE_INFO_COMMAND(name, doc) \ +void name (window, count, key) WINDOW *window; int count; unsigned char key; + +/* Variables found in session.h. */ +extern VFunction *info_last_executed_command; + +/* Variable controlling the garbage collection of files briefly visited + during searches. Such files are normally gc'ed, unless they were + compressed to begin with. If this variable is non-zero, it says + to gc even those file buffer contents which had to be uncompressed. */ +extern int gc_compressed_files; + +/* When non-zero, tiling takes place automatically when info_split_window + is called. */ +extern int auto_tiling_p; + +/* Variable controlling the behaviour of default scrolling when you are + already at the bottom of a node. */ +extern int info_scroll_behaviour; +extern char *info_scroll_choices[]; + +/* Values for info_scroll_behaviour. */ +#define IS_Continuous 0 /* Try to get first menu item, or failing that, the + "Next:" pointer, or failing that, the "Up:" and + "Next:" of the up. */ +#define IS_NextOnly 1 /* Try to get "Next:" menu item. */ +#define IS_PageOnly 2 /* Simply give up at the bottom of a node. */ + +/* Utility functions found in session.c */ +extern void info_dispatch_on_key (); +extern unsigned char info_get_input_char (), info_get_another_input_char (); +extern unsigned char info_input_pending_p (); +extern void remember_window_and_node (), set_remembered_pagetop_and_point (); +extern void set_window_pagetop (), info_set_node_of_window (); +extern char *pretty_keyseq (); +extern void initialize_keyseq (), add_char_to_keyseq (); +extern void info_gather_typeahead (); +extern FILE_BUFFER *file_buffer_of_window (); +extern long info_search_in_node (), info_target_search_node (); +extern void info_select_reference (); +extern int info_any_buffered_input_p (); +extern void print_node (); +extern void dump_node_to_file (), dump_nodes_to_file (); + +/* Do the physical deletion of WINDOW, and forget this window and + associated nodes. */ +extern void info_delete_window_internal (); + +/* Tell Info that input is coming from the file FILENAME. */ +extern void info_set_input_from_file (); + +#define return_if_control_g(val) \ + do { \ + info_gather_typeahead (); \ + if (info_input_pending_p () == Control ('g')) \ + return (val); \ + } while (0) + +/* The names of the functions that run an info session. */ + +/* Starting an info session. */ +extern void begin_multiple_window_info_session (), begin_info_session (); +extern void begin_info_session_with_error (), info_session (); +extern void info_read_and_dispatch (); + +/* Moving the point within a node. */ +extern void info_next_line (), info_prev_line (); +extern void info_end_of_line (), info_beginning_of_line (); +extern void info_forward_char (), info_backward_char (); +extern void info_forward_word (), info_backward_word (); +extern void info_beginning_of_node (), info_end_of_node (); +extern void info_move_to_prev_xref (), info_move_to_next_xref (); + +/* Scrolling text within a window. */ +extern void info_scroll_forward (), info_scroll_backward (); +extern void info_redraw_display (), info_toggle_wrap (); +extern void info_move_to_window_line (); + +/* Manipulating multiple windows. */ +extern void info_split_window (), info_delete_window (); +extern void info_keep_one_window (), info_grow_window (); +extern void info_scroll_other_window (), info_tile_windows (); +extern void info_next_window (), info_prev_window (); + +/* Selecting nodes. */ +extern void info_next_node (), info_prev_node (), info_up_node (); +extern void info_last_node (), info_first_node (), info_history_node (); +extern void info_goto_node (), info_top_node (), info_dir_node (); +extern void info_global_next_node (), info_global_prev_node (); +extern void info_kill_node (), info_view_file (); + +/* Selecting cross references. */ +extern void info_menu_digit (), info_menu_item (), info_xref_item (); +extern void info_find_menu (), info_select_reference_this_line (); + +/* Hacking numeric arguments. */ +extern int info_explicit_arg, info_numeric_arg, info_numeric_arg_sign; + +extern void info_add_digit_to_numeric_arg (), info_universal_argument (); +extern void info_initialize_numeric_arg (), info_numeric_arg_digit_loop (); + +/* Searching commands. */ +extern void info_search (), isearch_forward (), isearch_backward (); + +/* Dumping and printing nodes. */ +extern void info_print_node (); + +/* Miscellaneous commands. */ +extern void info_abort_key (), info_quit (), info_do_lowercase_version (); + +#endif /* _SESSION_H_ */ diff --git a/gnu/usr.bin/texinfo/info/signals.c b/gnu/usr.bin/texinfo/info/signals.c new file mode 100644 index 0000000..a14b6c3 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/signals.c @@ -0,0 +1,177 @@ +/* signals.c -- Install and maintain Info signal handlers. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#include "info.h" +#include "signals.h" + +/* **************************************************************** */ +/* */ +/* Pretending That We Have POSIX Signals */ +/* */ +/* **************************************************************** */ + +#if !defined (_POSIX_VERSION) +/* Perform OPERATION on NEWSET, perhaps leaving information in OLDSET. */ +static void +sigprocmask (operation, newset, oldset) + int operation, *newset, *oldset; +{ + switch (operation) + { + case SIG_UNBLOCK: +#if defined (HAVE_SIGSETMASK) + sigsetmask (sigblock (0) & ~(*newset)); +#endif /* HAVE_SIGSETMASK */ + break; + + case SIG_BLOCK: + *oldset = sigblock (*newset); + break; + + case SIG_SETMASK: +#if defined (HAVE_SIGSETMASK) + sigsetmask (*newset); +#endif /* HAVE_SIGSETMASK */ + break; + + default: + abort (); + } +} +#endif /* !_POSIX_VERSION */ + +/* **************************************************************** */ +/* */ +/* Signal Handling for Info */ +/* */ +/* **************************************************************** */ + +typedef void SigHandlerType; +typedef SigHandlerType SigHandler (); + +static SigHandlerType info_signal_handler (); +static SigHandler *old_TSTP, *old_TTOU, *old_TTIN; +static SigHandler *old_WINCH, *old_INT; + +void +initialize_info_signal_handler () +{ +#if defined (SIGTSTP) + old_TSTP = (SigHandler *) signal (SIGTSTP, info_signal_handler); + old_TTOU = (SigHandler *) signal (SIGTTOU, info_signal_handler); + old_TTIN = (SigHandler *) signal (SIGTTIN, info_signal_handler); +#endif /* SIGTSTP */ + +#if defined (SIGWINCH) + old_WINCH = (SigHandler *) signal (SIGWINCH, info_signal_handler); +#endif + +#if defined (SIGINT) + old_INT = (SigHandler *) signal (SIGINT, info_signal_handler); +#endif +} + +static void +redisplay_after_signal () +{ + terminal_clear_screen (); + display_clear_display (the_display); + window_mark_chain (windows, W_UpdateWindow); + display_update_display (windows); + display_cursor_at_point (active_window); + fflush (stdout); +} + +static SigHandlerType +info_signal_handler (sig) + int sig; +{ + SigHandler **old_signal_handler; + + switch (sig) + { +#if defined (SIGTSTP) + case SIGTSTP: + case SIGTTOU: + case SIGTTIN: +#endif +#if defined (SIGINT) + case SIGINT: +#endif + { +#if defined (SIGTSTP) + if (sig == SIGTSTP) + old_signal_handler = &old_TSTP; + if (sig == SIGTTOU) + old_signal_handler = &old_TTOU; + if (sig == SIGTTIN) + old_signal_handler = &old_TTIN; +#endif /* SIGTSTP */ + if (sig == SIGINT) + old_signal_handler = &old_INT; + + /* For stop signals, restore the terminal IO, leave the cursor + at the bottom of the window, and stop us. */ + terminal_goto_xy (0, screenheight - 1); + terminal_clear_to_eol (); + fflush (stdout); + terminal_unprep_terminal (); + signal (sig, *old_signal_handler); + UNBLOCK_SIGNAL (sig); + kill (getpid (), sig); + + /* The program is returning now. Restore our signal handler, + turn on terminal handling, redraw the screen, and place the + cursor where it belongs. */ + terminal_prep_terminal (); + *old_signal_handler = (SigHandler *) signal (sig, info_signal_handler); + redisplay_after_signal (); + fflush (stdout); + } + break; + +#if defined (SIGWINCH) + case SIGWINCH: + { + /* Turn off terminal IO, tell our parent that the window has changed, + then reinitialize the terminal and rebuild our windows. */ + old_signal_handler = &old_WINCH; + terminal_goto_xy (0, 0); + fflush (stdout); + terminal_unprep_terminal (); + signal (sig, *old_signal_handler); + UNBLOCK_SIGNAL (sig); + kill (getpid (), sig); + + /* After our old signal handler returns... */ + terminal_get_screen_size (); + terminal_prep_terminal (); + display_initialize_display (screenwidth, screenheight); + window_new_screen_size (screenwidth, screenheight, (VFunction *)NULL); + *old_signal_handler = (SigHandler *) signal (sig, info_signal_handler); + redisplay_after_signal (); + } + break; +#endif /* SIGWINCH */ + } +} diff --git a/gnu/usr.bin/texinfo/info/signals.h b/gnu/usr.bin/texinfo/info/signals.h new file mode 100644 index 0000000..8fb77f8 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/signals.h @@ -0,0 +1,85 @@ +/* signals.h -- Header to include system dependent signal definitions. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#ifndef _SIGNALS_H_ +#define _SIGNALS_H_ + +#include <signal.h> + +#define HAVE_SIGSETMASK + +#if !defined (_POSIX_VERSION) && !defined (sigmask) +# define sigmask(x) (1 << ((x)-1)) +#endif /* !POSIX && !sigmask */ + +#if !defined (_POSIX_VERSION) +# if !defined (SIG_BLOCK) +# define SIG_UNBLOCK 1 +# define SIG_BLOCK 2 +# define SIG_SETMASK 3 +# endif /* SIG_BLOCK */ + +/* Type of a signal set. */ +# define sigset_t int + +/* Make SET have no signals in it. */ +# define sigemptyset(set) (*(set) = (sigset_t)0x0) + +/* Make SET have the full range of signal specifications possible. */ +# define sigfillset(set) (*(set) = (sigset_t)0xffffffffff) + +/* Add SIG to the contents of SET. */ +# define sigaddset(set, sig) *(set) |= sigmask (sig) + +/* Delete SIG from the contents of SET. */ +# define sigdelset(set, sig) *(set) &= ~(sigmask (sig)) + +/* Tell if SET contains SIG. */ +# define sigismember(set, sig) (*(set) & (sigmask (sig))) + +/* Suspend the process until the reception of one of the signals + not present in SET. */ +# define sigsuspend(set) sigpause (*(set)) +#endif /* !_POSIX_VERSION */ + +/* These definitions are used both in POSIX and non-POSIX implementations. */ + +#define BLOCK_SIGNAL(sig) \ + do { \ + sigset_t nvar, ovar; \ + sigemptyset (&nvar); \ + sigemptyset (&ovar); \ + sigaddset (&nvar, sig); \ + sigprocmask (SIG_BLOCK, &nvar, &ovar); \ + } while (0) + +#define UNBLOCK_SIGNAL(sig) \ + do { \ + sigset_t nvar, ovar; \ + sigemptyset (&ovar); \ + sigemptyset (&nvar); \ + sigaddset (&nvar, sig); \ + sigprocmask (SIG_UNBLOCK, &nvar, &ovar); \ + } while (0) + +#endif /* !_SIGNALS_H_ */ diff --git a/gnu/usr.bin/texinfo/info/termdep.h b/gnu/usr.bin/texinfo/info/termdep.h new file mode 100644 index 0000000..f4b6634 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/termdep.h @@ -0,0 +1,64 @@ +/* termdep.h -- System things that terminal.c depends on. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#if defined (HAVE_SYS_FCNTL_H) +#include <sys/fcntl.h> +#else +#include <fcntl.h> +#endif /* !HAVE_SYS_FCNTL_H */ + +#if defined (HAVE_TERMIO_H) +#include <termio.h> +#include <string.h> +#if defined (HAVE_SYS_PTEM_H) +#if !defined (M_XENIX) +#include <sys/stream.h> +#include <sys/ptem.h> +#undef TIOCGETC +#else /* M_XENIX */ +#define tchars tc +#endif /* M_XENIX */ +#endif /* HAVE_SYS_PTEM_H */ +#else /* !HAVE_TERMIO_H */ +#include <sys/file.h> +#include <sgtty.h> +#include <strings.h> +#endif /* !HAVE_TERMIO_H */ + +#if defined (HAVE_SYS_TTOLD_H) +#include <sys/ttold.h> +#endif /* HAVE_SYS_TTOLD_H */ + +#if !defined (HAVE_RINDEX) +#undef index +#undef rindex +#define index strchr +#define rindex strrchr +#endif + +#if !defined (HAVE_BCOPY) +#undef bcopy +#define bcopy(source, dest, count) memcpy(dest, source, count) +#endif + +/* eof */ diff --git a/gnu/usr.bin/texinfo/info/terminal.c b/gnu/usr.bin/texinfo/info/terminal.c new file mode 100644 index 0000000..4b63424 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/terminal.c @@ -0,0 +1,745 @@ +/* terminal.c -- How to handle the physical terminal for Info. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + This file has appeared in prior works by the Free Software Foundation; + thus it carries copyright dates from 1988 through 1993. + + Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#include <stdio.h> +#include <sys/types.h> +#include "terminal.h" +#include "termdep.h" + +extern void *xmalloc (), *xrealloc (); + +/* The Unix termcap interface code. */ + +extern int tgetnum (), tgetflag (), tgetent (); +extern char *tgetstr (), *tgoto (); +extern char *getenv (); +extern void tputs (); + +/* Function "hooks". If you make one of these point to a function, that + function is called when appropriate instead of its namesake. Your + function is called with exactly the same arguments that were passed + to the namesake function. */ +VFunction *terminal_begin_inverse_hook = (VFunction *)NULL; +VFunction *terminal_end_inverse_hook = (VFunction *)NULL; +VFunction *terminal_prep_terminal_hook = (VFunction *)NULL; +VFunction *terminal_unprep_terminal_hook = (VFunction *)NULL; +VFunction *terminal_up_line_hook = (VFunction *)NULL; +VFunction *terminal_down_line_hook = (VFunction *)NULL; +VFunction *terminal_clear_screen_hook = (VFunction *)NULL; +VFunction *terminal_clear_to_eol_hook = (VFunction *)NULL; +VFunction *terminal_get_screen_size_hook = (VFunction *)NULL; +VFunction *terminal_goto_xy_hook = (VFunction *)NULL; +VFunction *terminal_initialize_terminal_hook = (VFunction *)NULL; +VFunction *terminal_new_terminal_hook = (VFunction *)NULL; +VFunction *terminal_put_text_hook = (VFunction *)NULL; +VFunction *terminal_ring_bell_hook = (VFunction *)NULL; +VFunction *terminal_write_chars_hook = (VFunction *)NULL; +VFunction *terminal_scroll_terminal_hook = (VFunction *)NULL; + +/* **************************************************************** */ +/* */ +/* Terminal and Termcap */ +/* */ +/* **************************************************************** */ + +/* On Solaris2, sys/types.h #includes sys/reg.h, which #defines PC. + Unfortunately, PC is a global variable used by the termcap library. */ +#undef PC + +/* TERMCAP requires these variables, whether we access them or not. */ +char PC; +char *BC, *UP; +short ospeed; + +/* A buffer which holds onto the current terminal description, and a pointer + used to float within it. */ +static char *term_buffer = (char *)NULL; +static char *term_string_buffer = (char *)NULL; + +/* Some strings to control terminal actions. These are output by tputs (). */ +static char *term_goto, *term_clreol, *term_cr, *term_clrpag; +static char *term_begin_use, *term_end_use; +static char *term_AL, *term_DL, *term_al, *term_dl; + +/* How to go up a line. */ +static char *term_up; + +/* How to go down a line. */ +static char *term_dn; + +/* An audible bell, if the terminal can be made to make noise. */ +static char *audible_bell; + +/* A visible bell, if the terminal can be made to flash the screen. */ +static char *visible_bell; + +/* The string to write to turn on the meta key, if this term has one. */ +static char *term_mm; + +/* The string to write to turn off the meta key, if this term has one. */ +static char *term_mo; + +/* The string to turn on inverse mode, if this term has one. */ +static char *term_invbeg; + +/* The string to turn off inverse mode, if this term has one. */ +static char *term_invend; + +static void +output_character_function (c) + int c; +{ + putc (c, stdout); +} + +/* Macro to send STRING to the terminal. */ +#define send_to_terminal(string) \ + do { \ + if (string) \ + tputs (string, 1, output_character_function); \ + } while (0) + +/* Tell the terminal that we will be doing cursor addressable motion. */ +static void +terminal_begin_using_terminal () +{ + send_to_terminal (term_begin_use); +} + +/* Tell the terminal that we will not be doing any more cursor addressable + motion. */ +static void +terminal_end_using_terminal () +{ + send_to_terminal (term_end_use); +} + +/* **************************************************************** */ +/* */ +/* Necessary Terminal Functions */ +/* */ +/* **************************************************************** */ + +/* The functions and variables on this page implement the user visible + portion of the terminal interface. */ + +/* The width and height of the terminal. */ +int screenwidth, screenheight; + +/* Non-zero means this terminal can't really do anything. */ +int terminal_is_dumb_p = 0; + +/* Non-zero means that this terminal has a meta key. */ +int terminal_has_meta_p = 0; + +/* Non-zero means that this terminal can produce a visible bell. */ +int terminal_has_visible_bell_p = 0; + +/* Non-zero means to use that visible bell if at all possible. */ +int terminal_use_visible_bell_p = 0; + +/* Non-zero means that the terminal can do scrolling. */ +int terminal_can_scroll = 0; + +/* The key sequences output by the arrow keys, if this terminal has any. */ +char *term_ku, *term_kd, *term_kr, *term_kl; + +/* Move the cursor to the terminal location of X and Y. */ +void +terminal_goto_xy (x, y) + int x, y; +{ + if (terminal_goto_xy_hook) + (*terminal_goto_xy_hook) (x, y); + else + { + if (term_goto) + tputs (tgoto (term_goto, x, y), 1, output_character_function); + } +} + +/* Print STRING to the terminal at the current position. */ +void +terminal_put_text (string) + char *string; +{ + if (terminal_put_text_hook) + (*terminal_put_text_hook) (string); + else + { + printf ("%s", string); + } +} + +/* Print NCHARS from STRING to the terminal at the current position. */ +void +terminal_write_chars (string, nchars) + char *string; + int nchars; +{ + if (terminal_write_chars_hook) + (*terminal_write_chars_hook) (string, nchars); + else + { + if (nchars) + fwrite (string, 1, nchars, stdout); + } +} + +/* Clear from the current position of the cursor to the end of the line. */ +void +terminal_clear_to_eol () +{ + if (terminal_clear_to_eol_hook) + (*terminal_clear_to_eol_hook) (); + else + { + send_to_terminal (term_clreol); + } +} + +/* Clear the entire terminal screen. */ +void +terminal_clear_screen () +{ + if (terminal_clear_screen_hook) + (*terminal_clear_screen_hook) (); + else + { + send_to_terminal (term_clrpag); + } +} + +/* Move the cursor up one line. */ +void +terminal_up_line () +{ + if (terminal_up_line_hook) + (*terminal_up_line_hook) (); + else + { + send_to_terminal (term_up); + } +} + +/* Move the cursor down one line. */ +void +terminal_down_line () +{ + if (terminal_down_line_hook) + (*terminal_down_line_hook) (); + else + { + send_to_terminal (term_dn); + } +} + +/* Turn on reverse video if possible. */ +void +terminal_begin_inverse () +{ + if (terminal_begin_inverse_hook) + (*terminal_begin_inverse_hook) (); + else + { + send_to_terminal (term_invbeg); + } +} + +/* Turn off reverse video if possible. */ +void +terminal_end_inverse () +{ + if (terminal_end_inverse_hook) + (*terminal_end_inverse_hook) (); + else + { + send_to_terminal (term_invend); + } +} + +/* Ring the terminal bell. The bell is run visibly if it both has one and + terminal_use_visible_bell_p is non-zero. */ +void +terminal_ring_bell () +{ + if (terminal_ring_bell_hook) + (*terminal_ring_bell_hook) (); + else + { + if (terminal_has_visible_bell_p && terminal_use_visible_bell_p) + send_to_terminal (visible_bell); + else + send_to_terminal (audible_bell); + } +} + +/* At the line START, delete COUNT lines from the terminal display. */ +static void +terminal_delete_lines (start, count) + int start, count; +{ + int lines; + + /* Normalize arguments. */ + if (start < 0) + start = 0; + + lines = screenheight - start; + terminal_goto_xy (0, start); + if (term_DL) + tputs (tgoto (term_DL, 0, count), lines, output_character_function); + else + { + while (count--) + tputs (term_dl, lines, output_character_function); + } + + fflush (stdout); +} + +/* At the line START, insert COUNT lines in the terminal display. */ +static void +terminal_insert_lines (start, count) + int start, count; +{ + int lines; + + /* Normalize arguments. */ + if (start < 0) + start = 0; + + lines = screenheight - start; + terminal_goto_xy (0, start); + + if (term_AL) + tputs (tgoto (term_AL, 0, count), lines, output_character_function); + else + { + while (count--) + tputs (term_al, lines, output_character_function); + } + + fflush (stdout); +} + +/* Scroll an area of the terminal, starting with the region from START + to END, AMOUNT lines. If AMOUNT is negative, the lines are scrolled + towards the top of the screen, else they are scrolled towards the + bottom of the screen. */ +void +terminal_scroll_terminal (start, end, amount) + int start, end, amount; +{ + if (!terminal_can_scroll) + return; + + /* Any scrolling at all? */ + if (amount == 0) + return; + + if (terminal_scroll_terminal_hook) + (*terminal_scroll_terminal_hook) (start, end, amount); + else + { + /* If we are scrolling down, delete AMOUNT lines at END. Then insert + AMOUNT lines at START. */ + if (amount > 0) + { + terminal_delete_lines (end, amount); + terminal_insert_lines (start, amount); + } + + /* If we are scrolling up, delete AMOUNT lines before START. This + actually does the upwards scroll. Then, insert AMOUNT lines + after the already scrolled region (i.e., END - AMOUNT). */ + if (amount < 0) + { + int abs_amount = -amount; + terminal_delete_lines (start - abs_amount, abs_amount); + terminal_insert_lines (end - abs_amount, abs_amount); + } + } +} + +/* Re-initialize the terminal considering that the TERM/TERMCAP variable + has changed. */ +void +terminal_new_terminal (terminal_name) + char *terminal_name; +{ + if (terminal_new_terminal_hook) + (*terminal_new_terminal_hook) (terminal_name); + else + { + terminal_initialize_terminal (terminal_name); + } +} + +/* Set the global variables SCREENWIDTH and SCREENHEIGHT. */ +void +terminal_get_screen_size () +{ + if (terminal_get_screen_size_hook) + (*terminal_get_screen_size_hook) (); + else + { + screenwidth = screenheight = 0; + +#if defined (TIOCGWINSZ) + { + struct winsize window_size; + + if (ioctl (fileno (stdout), TIOCGWINSZ, &window_size) == 0) + { + screenwidth = (int) window_size.ws_col; + screenheight = (int) window_size.ws_row; + } + } +#endif /* TIOCGWINSZ */ + + /* Environment variable COLUMNS overrides setting of "co". */ + if (screenwidth <= 0) + { + char *sw = getenv ("COLUMNS"); + + if (sw) + screenwidth = atoi (sw); + + if (screenwidth <= 0) + screenwidth = tgetnum ("co"); + } + + /* Environment variable LINES overrides setting of "li". */ + if (screenheight <= 0) + { + char *sh = getenv ("LINES"); + + if (sh) + screenheight = atoi (sh); + + if (screenheight <= 0) + screenheight = tgetnum ("li"); + } + + /* If all else fails, default to 80x24 terminal. */ + if (screenwidth <= 0) + screenwidth = 80; + + if (screenheight <= 0) + screenheight = 24; + } +} + +/* Initialize the terminal which is known as TERMINAL_NAME. If this terminal + doesn't have cursor addressability, TERMINAL_IS_DUMB_P becomes non-zero. + The variables SCREENHEIGHT and SCREENWIDTH are set to the dimensions that + this terminal actually has. The variable TERMINAL_HAS_META_P becomes non- + zero if this terminal supports a Meta key. Finally, the terminal screen is + cleared. */ +void +terminal_initialize_terminal (terminal_name) + char *terminal_name; +{ + char *term, *buffer; + + terminal_is_dumb_p = 0; + + if (terminal_initialize_terminal_hook) + { + (*terminal_initialize_terminal_hook) (terminal_name); + return; + } + + term = terminal_name ? terminal_name : getenv ("TERM"); + + if (!term_string_buffer) + term_string_buffer = (char *)xmalloc (2048); + + if (!term_buffer) + term_buffer = (char *)xmalloc (2048); + + buffer = term_string_buffer; + + term_clrpag = term_cr = term_clreol = (char *)NULL; + + if (!term) + term = "dumb"; + + if (tgetent (term_buffer, term) <= 0) + { + terminal_is_dumb_p = 1; + screenwidth = 80; + screenheight = 24; + term_cr = "\r"; + term_up = term_dn = audible_bell = visible_bell = (char *)NULL; + term_ku = term_kd = term_kl = term_kr = (char *)NULL; + return; + } + + BC = tgetstr ("pc", &buffer); + PC = BC ? *BC : 0; + +#if defined (TIOCGETP) + { + struct sgttyb sg; + + if (ioctl (fileno (stdout), TIOCGETP, &sg) != -1) + ospeed = sg.sg_ospeed; + else + ospeed = B9600; + } +#else + ospeed = B9600; +#endif /* !TIOCGETP */ + + term_cr = tgetstr ("cr", &buffer); + term_clreol = tgetstr ("ce", &buffer); + term_clrpag = tgetstr ("cl", &buffer); + term_goto = tgetstr ("cm", &buffer); + + /* Find out about this terminals scrolling capability. */ + term_AL = tgetstr ("AL", &buffer); + term_DL = tgetstr ("DL", &buffer); + term_al = tgetstr ("al", &buffer); + term_dl = tgetstr ("dl", &buffer); + + terminal_can_scroll = ((term_AL || term_al) && (term_DL || term_dl)); + + term_invbeg = tgetstr ("mr", &buffer); + if (term_invbeg) + term_invend = tgetstr ("me", &buffer); + else + term_invend = (char *)NULL; + + if (!term_cr) + term_cr = "\r"; + + terminal_get_screen_size (); + + term_up = tgetstr ("up", &buffer); + term_dn = tgetstr ("dn", &buffer); + visible_bell = tgetstr ("vb", &buffer); + terminal_has_visible_bell_p = (visible_bell != (char *)NULL); + audible_bell = tgetstr ("bl", &buffer); + if (!audible_bell) + audible_bell = "\007"; + term_begin_use = tgetstr ("ti", &buffer); + term_end_use = tgetstr ("te", &buffer); + + /* Check to see if this terminal has a meta key. */ + terminal_has_meta_p = (tgetflag ("km") || tgetflag ("MT")); + if (terminal_has_meta_p) + { + term_mm = tgetstr ("mm", &buffer); + term_mo = tgetstr ("mo", &buffer); + } + else + { + term_mm = (char *)NULL; + term_mo = (char *)NULL; + } + + /* Attempt to find the arrow keys. */ + term_ku = tgetstr ("ku", &buffer); + term_kd = tgetstr ("kd", &buffer); + term_kr = tgetstr ("kr", &buffer); + term_kl = tgetstr ("kl", &buffer); + + /* If this terminal is not cursor addressable, then it is really dumb. */ + if (!term_goto) + terminal_is_dumb_p = 1; + + terminal_begin_using_terminal (); +} + +/* **************************************************************** */ +/* */ +/* How to Read Characters From the Terminal */ +/* */ +/* **************************************************************** */ + +#if defined (TIOCGETC) +/* A buffer containing the terminal interrupt characters upon entry + to Info. */ +struct tchars original_tchars; +#endif + +#if defined (TIOCGLTC) +/* A buffer containing the local terminal mode characters upon entry + to Info. */ +struct ltchars original_ltchars; +#endif + +#if defined (HAVE_TERMIO_H) +/* A buffer containing the terminal mode flags upon entry to info. */ +struct termio original_termio, ttybuff; +#else /* !HAVE_TERMIO_H */ +/* Buffers containing the terminal mode flags upon entry to info. */ +int original_tty_flags = 0; +int original_lmode; +struct sgttyb ttybuff; +#endif /* !HAVE_TERMIO_H */ + +/* Prepare to start using the terminal to read characters singly. */ +void +terminal_prep_terminal () +{ + int tty; + + if (terminal_prep_terminal_hook) + { + (*terminal_prep_terminal_hook) (); + return; + } + + tty = fileno (stdin); + +#if defined (HAVE_TERMIO_H) + ioctl (tty, TCGETA, &original_termio); + ioctl (tty, TCGETA, &ttybuff); + ttybuff.c_iflag &= (~ISTRIP & ~INLCR & ~IGNCR & ~ICRNL & ~IXON); + ttybuff.c_oflag &= (~ONLCR & ~OCRNL); + ttybuff.c_lflag &= (~ICANON & ~ECHO); + + ttybuff.c_cc[VMIN] = 1; + ttybuff.c_cc[VTIME] = 0; + + if (ttybuff.c_cc[VINTR] = '\177') + ttybuff.c_cc[VINTR] = -1; + + if (ttybuff.c_cc[VQUIT] = '\177') + ttybuff.c_cc[VQUIT] = -1; + + ioctl (tty, TCSETA, &ttybuff); + +#else /* !HAVE_TERMIO_H */ + + ioctl (tty, TIOCGETP, &ttybuff); + + if (!original_tty_flags) + original_tty_flags = ttybuff.sg_flags; + + /* Make this terminal pass 8 bits around while we are using it. */ +#if defined (PASS8) + ttybuff.sg_flags |= PASS8; +#endif /* PASS8 */ + +#if defined (TIOCLGET) && defined (LPASS8) + { + int flags; + ioctl (tty, TIOCLGET, &flags); + original_lmode = flags; + flags |= LPASS8; + ioctl (tty, TIOCLSET, &flags); + } +#endif /* TIOCLGET && LPASS8 */ + +#if defined (TIOCGETC) + { + struct tchars temp; + + ioctl (tty, TIOCGETC, &original_tchars); + temp = original_tchars; + + /* C-s and C-q. */ + temp.t_startc = temp.t_stopc = -1; + + /* Often set to C-d. */ + temp.t_eofc = -1; + + /* If the a quit or interrupt character conflicts with one of our + commands, then make it go away. */ + if (temp.t_intrc == '\177') + temp.t_intrc = -1; + + if (temp.t_quitc == '\177') + temp.t_quitc = -1; + + ioctl (tty, TIOCSETC, &temp); + } +#endif /* TIOCGETC */ + +#if defined (TIOCGLTC) + { + struct ltchars temp; + + ioctl (tty, TIOCGLTC, &original_ltchars); + temp = original_ltchars; + + /* Make the interrupt keys go away. Just enough to make people happy. */ + temp.t_lnextc = -1; /* C-v. */ + temp.t_dsuspc = -1; /* C-y. */ + temp.t_flushc = -1; /* C-o. */ + ioctl (tty, TIOCSLTC, &temp); + } +#endif /* TIOCGLTC */ + + ttybuff.sg_flags &= ~ECHO; + ttybuff.sg_flags |= CBREAK; + ioctl (tty, TIOCSETN, &ttybuff); +#endif /* !HAVE_TERMIO_H */ +} + +/* Restore the tty settings back to what they were before we started using + this terminal. */ +void +terminal_unprep_terminal () +{ + int tty; + + if (terminal_unprep_terminal_hook) + { + (*terminal_unprep_terminal_hook) (); + return; + } + + tty = fileno (stdin); + +#if defined (HAVE_TERMIO_H) + ioctl (tty, TCSETA, &original_termio); +#else /* !HAVE_TERMIO_H */ + ioctl (tty, TIOCGETP, &ttybuff); + ttybuff.sg_flags = original_tty_flags; + ioctl (tty, TIOCSETN, &ttybuff); + +#if defined (TIOCGETC) + ioctl (tty, TIOCSETC, &original_tchars); +#endif /* TIOCGETC */ + +#if defined (TIOCGLTC) + ioctl (tty, TIOCSLTC, &original_ltchars); +#endif /* TIOCGLTC */ + +#if defined (TIOCLGET) && defined (LPASS8) + ioctl (tty, TIOCLSET, &original_lmode); +#endif /* TIOCLGET && LPASS8 */ + +#endif /* !HAVE_TERMIO_H */ + terminal_end_using_terminal (); +} + diff --git a/gnu/usr.bin/texinfo/info/terminal.h b/gnu/usr.bin/texinfo/info/terminal.h new file mode 100644 index 0000000..a86a23c --- /dev/null +++ b/gnu/usr.bin/texinfo/info/terminal.h @@ -0,0 +1,126 @@ +/* terminal.h -- The external interface to terminal I/O. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#ifndef _TERMINAL_H_ +#define _TERMINAL_H_ + +/* We use the following data type to talk about pointers to functions. */ +#if !defined (__FUNCTION_DEF) +# define __FUNCTION_DEF +typedef int Function (); +typedef void VFunction (); +#endif /* _FUNCTION_DEF */ + +/* For almost every function externally visible from terminal.c, there is + a corresponding "hook" function which can be bound in order to replace + the functionality of the one found in terminal.c. This is how we go + about implemented X window display. */ + +/* The width and height of the terminal. */ +extern int screenwidth, screenheight; + +/* Non-zero means this terminal can't really do anything. */ +extern int terminal_is_dumb_p; + +/* Non-zero means that this terminal has a meta key. */ +extern int terminal_has_meta_p; + +/* Non-zero means that this terminal can produce a visible bell. */ +extern int terminal_has_visible_bell_p; + +/* Non-zero means to use that visible bell if at all possible. */ +extern int terminal_use_visible_bell_p; + +/* Non-zero means that this terminal can scroll lines up and down. */ +extern int terminal_can_scroll; + +/* Initialize the terminal which is known as TERMINAL_NAME. If this terminal + doesn't have cursor addressability, TERMINAL_IS_DUMB_P becomes non-zero. + The variables SCREENHEIGHT and SCREENWIDTH are set to the dimensions that + this terminal actually has. The variable TERMINAL_HAS_META_P becomes non- + zero if this terminal supports a Meta key. */ +extern void terminal_initialize_terminal (); +extern VFunction *terminal_initialize_terminal_hook; + +/* Return the current screen width and height in the variables + SCREENWIDTH and SCREENHEIGHT. */ +extern void terminal_get_screen_size (); +extern VFunction *terminal_get_screen_size_hook; + +/* Save and restore tty settings. */ +extern void terminal_prep_terminal (), terminal_unprep_terminal (); +extern VFunction *terminal_prep_terminal_hook, *terminal_unprep_terminal_hook; + +/* Re-initialize the terminal to TERMINAL_NAME. */ +extern void terminal_new_terminal (); +extern VFunction *terminal_new_terminal_hook; + +/* Move the cursor to the terminal location of X and Y. */ +extern void terminal_goto_xy (); +extern VFunction *terminal_goto_xy_hook; + +/* Print STRING to the terminal at the current position. */ +extern void terminal_put_text (); +extern VFunction *terminal_put_text_hook; + +/* Print NCHARS from STRING to the terminal at the current position. */ +extern void terminal_write_chars (); +extern VFunction *terminal_write_chars_hook; + +/* Clear from the current position of the cursor to the end of the line. */ +extern void terminal_clear_to_eol (); +extern VFunction *terminal_clear_to_eol_hook; + +/* Clear the entire terminal screen. */ +extern void terminal_clear_screen (); +extern VFunction *terminal_clear_screen_hook; + +/* Move the cursor up one line. */ +extern void terminal_up_line (); +extern VFunction *terminal_up_line_hook; + +/* Move the cursor down one line. */ +extern void terminal_down_line (); +extern VFunction *terminal_down_line_hook; + +/* Turn on reverse video if possible. */ +extern void terminal_begin_inverse (); +extern VFunction *terminal_begin_inverse_hook; + +/* Turn off reverse video if possible. */ +extern void terminal_end_inverse (); +extern VFunction *terminal_end_inverse_hook; + +/* Scroll an area of the terminal, starting with the region from START + to END, AMOUNT lines. If AMOUNT is negative, the lines are scrolled + towards the top of the screen, else they are scrolled towards the + bottom of the screen. */ +extern void terminal_scroll_terminal (); +extern VFunction *terminal_scroll_terminal_hook; + +/* Ring the terminal bell. The bell is run visibly if it both has one and + terminal_use_visible_bell_p is non-zero. */ +extern void terminal_ring_bell (); +extern VFunction *terminal_ring_bell_hook; + +#endif /* !_TERMINAL_H_ */ diff --git a/gnu/usr.bin/texinfo/info/tilde.c b/gnu/usr.bin/texinfo/info/tilde.c new file mode 100644 index 0000000..c01951b --- /dev/null +++ b/gnu/usr.bin/texinfo/info/tilde.c @@ -0,0 +1,379 @@ +/* tilde.c -- Tilde expansion code (~/foo := $HOME/foo). */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + This file has appeared in prior works by the Free Software Foundation; + thus it carries copyright dates from 1988 through 1993. + + Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#if defined (__GNUC__) +# define alloca __builtin_alloca +#else /* !__GNUC__ */ +# if defined (_AIX) + #pragma alloca +# else /* !_AIX */ +# if defined (HAVE_ALLOCA_H) +# include <alloca.h> +# endif /* HAVE_ALLOCA_H */ +# endif /* !AIX */ +#endif /* !__GNUC__ */ + +#include "tilde.h" +#include <pwd.h> + +#if !defined (savestring) +#define savestring(x) (char *)strcpy (xmalloc (1 + strlen (x)), (x)) +#endif /* !savestring */ + +#if !defined (NULL) +# define NULL 0x0 +#endif + +#if defined (TEST) || defined (STATIC_MALLOC) +static char *xmalloc (), *xrealloc (); +#else +extern char *xmalloc (), *xrealloc (); +#endif /* TEST || STATIC_MALLOC */ + +/* The default value of tilde_additional_prefixes. This is set to + whitespace preceding a tilde so that simple programs which do not + perform any word separation get desired behaviour. */ +static char *default_prefixes[] = + { " ~", "\t~", (char *)NULL }; + +/* The default value of tilde_additional_suffixes. This is set to + whitespace or newline so that simple programs which do not + perform any word separation get desired behaviour. */ +static char *default_suffixes[] = + { " ", "\n", (char *)NULL }; + +/* If non-null, this contains the address of a function to call if the + standard meaning for expanding a tilde fails. The function is called + with the text (sans tilde, as in "foo"), and returns a malloc()'ed string + which is the expansion, or a NULL pointer if there is no expansion. */ +Function *tilde_expansion_failure_hook = (Function *)NULL; + +/* When non-null, this is a NULL terminated array of strings which + are duplicates for a tilde prefix. Bash uses this to expand + `=~' and `:~'. */ +char **tilde_additional_prefixes = default_prefixes; + +/* When non-null, this is a NULL terminated array of strings which match + the end of a username, instead of just "/". Bash sets this to + `:' and `=~'. */ +char **tilde_additional_suffixes = default_suffixes; + +/* Find the start of a tilde expansion in STRING, and return the index of + the tilde which starts the expansion. Place the length of the text + which identified this tilde starter in LEN, excluding the tilde itself. */ +static int +tilde_find_prefix (string, len) + char *string; + int *len; +{ + register int i, j, string_len; + register char **prefixes = tilde_additional_prefixes; + + string_len = strlen (string); + *len = 0; + + if (!*string || *string == '~') + return (0); + + if (prefixes) + { + for (i = 0; i < string_len; i++) + { + for (j = 0; prefixes[j]; j++) + { + if (strncmp (string + i, prefixes[j], strlen (prefixes[j])) == 0) + { + *len = strlen (prefixes[j]) - 1; + return (i + *len); + } + } + } + } + return (string_len); +} + +/* Find the end of a tilde expansion in STRING, and return the index of + the character which ends the tilde definition. */ +static int +tilde_find_suffix (string) + char *string; +{ + register int i, j, string_len; + register char **suffixes = tilde_additional_suffixes; + + string_len = strlen (string); + + for (i = 0; i < string_len; i++) + { + if (string[i] == '/' || !string[i]) + break; + + for (j = 0; suffixes && suffixes[j]; j++) + { + if (strncmp (string + i, suffixes[j], strlen (suffixes[j])) == 0) + return (i); + } + } + return (i); +} + +/* Return a new string which is the result of tilde expanding STRING. */ +char * +tilde_expand (string) + char *string; +{ + char *result, *tilde_expand_word (); + int result_size, result_index; + + result_size = result_index = 0; + result = (char *)NULL; + + /* Scan through STRING expanding tildes as we come to them. */ + while (1) + { + register int start, end; + char *tilde_word, *expansion; + int len; + + /* Make START point to the tilde which starts the expansion. */ + start = tilde_find_prefix (string, &len); + + /* Copy the skipped text into the result. */ + if ((result_index + start + 1) > result_size) + result = (char *)xrealloc (result, 1 + (result_size += (start + 20))); + + strncpy (result + result_index, string, start); + result_index += start; + + /* Advance STRING to the starting tilde. */ + string += start; + + /* Make END be the index of one after the last character of the + username. */ + end = tilde_find_suffix (string); + + /* If both START and END are zero, we are all done. */ + if (!start && !end) + break; + + /* Expand the entire tilde word, and copy it into RESULT. */ + tilde_word = (char *)xmalloc (1 + end); + strncpy (tilde_word, string, end); + tilde_word[end] = '\0'; + string += end; + + expansion = tilde_expand_word (tilde_word); + free (tilde_word); + + len = strlen (expansion); + if ((result_index + len + 1) > result_size) + result = (char *)xrealloc (result, 1 + (result_size += (len + 20))); + + strcpy (result + result_index, expansion); + result_index += len; + free (expansion); + } + + result[result_index] = '\0'; + + return (result); +} + +/* Do the work of tilde expansion on FILENAME. FILENAME starts with a + tilde. If there is no expansion, call tilde_expansion_failure_hook. */ +char * +tilde_expand_word (filename) + char *filename; +{ + char *dirname; + + dirname = filename ? savestring (filename) : (char *)NULL; + + if (dirname && *dirname == '~') + { + char *temp_name; + if (!dirname[1] || dirname[1] == '/') + { + /* Prepend $HOME to the rest of the string. */ + char *temp_home = (char *)getenv ("HOME"); + + /* If there is no HOME variable, look up the directory in + the password database. */ + if (!temp_home) + { +/* extern struct passwd *getpwuid (); */ + struct passwd *entry; + + entry = getpwuid (getuid ()); + if (entry) + temp_home = entry->pw_dir; + } + + temp_name = (char *)alloca (1 + strlen (&dirname[1]) + + (temp_home ? strlen (temp_home) : 0)); + temp_name[0] = '\0'; + if (temp_home) + strcpy (temp_name, temp_home); + strcat (temp_name, &dirname[1]); + free (dirname); + dirname = savestring (temp_name); + } + else + { + struct passwd *getpwnam (), *user_entry; + char *username = (char *)alloca (257); + int i, c; + + for (i = 1; c = dirname[i]; i++) + { + if (c == '/') + break; + else + username[i - 1] = c; + } + username[i - 1] = '\0'; + + if (!(user_entry = getpwnam (username))) + { + /* If the calling program has a special syntax for + expanding tildes, and we couldn't find a standard + expansion, then let them try. */ + if (tilde_expansion_failure_hook) + { + char *expansion; + + expansion = + (char *)(*tilde_expansion_failure_hook) (username); + + if (expansion) + { + temp_name = (char *)alloca (1 + strlen (expansion) + + strlen (&dirname[i])); + strcpy (temp_name, expansion); + strcat (temp_name, &dirname[i]); + free (expansion); + goto return_name; + } + } + /* We shouldn't report errors. */ + } + else + { + temp_name = (char *)alloca (1 + strlen (user_entry->pw_dir) + + strlen (&dirname[i])); + strcpy (temp_name, user_entry->pw_dir); + strcat (temp_name, &dirname[i]); + return_name: + free (dirname); + dirname = savestring (temp_name); + } + endpwent (); + } + } + return (dirname); +} + + +#if defined (TEST) +#undef NULL +#include <stdio.h> + +main (argc, argv) + int argc; + char **argv; +{ + char *result, line[512]; + int done = 0; + + while (!done) + { + printf ("~expand: "); + fflush (stdout); + + if (!gets (line)) + strcpy (line, "done"); + + if ((strcmp (line, "done") == 0) || + (strcmp (line, "quit") == 0) || + (strcmp (line, "exit") == 0)) + { + done = 1; + break; + } + + result = tilde_expand (line); + printf (" --> %s\n", result); + free (result); + } + exit (0); +} + +static void memory_error_and_abort (); + +static char * +xmalloc (bytes) + int bytes; +{ + char *temp = (char *)malloc (bytes); + + if (!temp) + memory_error_and_abort (); + return (temp); +} + +static char * +xrealloc (pointer, bytes) + char *pointer; + int bytes; +{ + char *temp; + + if (!pointer) + temp = (char *)malloc (bytes); + else + temp = (char *)realloc (pointer, bytes); + + if (!temp) + memory_error_and_abort (); + + return (temp); +} + +static void +memory_error_and_abort () +{ + fprintf (stderr, "readline: Out of virtual memory!\n"); + abort (); +} + +/* + * Local variables: + * compile-command: "gcc -g -DTEST -o tilde tilde.c" + * end: + */ +#endif /* TEST */ + diff --git a/gnu/usr.bin/texinfo/info/tilde.h b/gnu/usr.bin/texinfo/info/tilde.h new file mode 100644 index 0000000..b48fc19 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/tilde.h @@ -0,0 +1,62 @@ +/* tilde.h: Externally available variables and function in libtilde.a. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + This file has appeared in prior works by the Free Software Foundation; + thus it carries copyright dates from 1988 through 1993. + + Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#ifndef _TILDE_H_ +#define _TILDE_H_ + +/* Function pointers can be declared as (Function *)foo. */ +#if !defined (__FUNCTION_DEF) +# define __FUNCTION_DEF +typedef int Function (); +typedef void VFunction (); +#endif /* _FUNCTION_DEF */ + +/* If non-null, this contains the address of a function to call if the + standard meaning for expanding a tilde fails. The function is called + with the text (sans tilde, as in "foo"), and returns a malloc()'ed string + which is the expansion, or a NULL pointer if there is no expansion. */ +extern Function *tilde_expansion_failure_hook; + +/* When non-null, this is a NULL terminated array of strings which + are duplicates for a tilde prefix. Bash uses this to expand + `=~' and `:~'. */ +extern char **tilde_additional_prefixes; + +/* When non-null, this is a NULL terminated array of strings which match + the end of a username, instead of just "/". Bash sets this to + `:' and `=~'. */ +extern char **tilde_additional_suffixes; + +/* Return a new string which is the result of tilde expanding STRING. */ +extern char *tilde_expand (); + +/* Do the work of tilde expansion on FILENAME. FILENAME starts with a + tilde. If there is no expansion, call tilde_expansion_failure_hook. */ +extern char *tilde_expand_word (); + +#endif + diff --git a/gnu/usr.bin/texinfo/info/variables.c b/gnu/usr.bin/texinfo/info/variables.c new file mode 100644 index 0000000..b70af83 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/variables.c @@ -0,0 +1,272 @@ +/* variables.c -- How to manipulate user visible variables in Info. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#include "info.h" +#include "variables.h" + +/* **************************************************************** */ +/* */ +/* User Visible Variables in Info */ +/* */ +/* **************************************************************** */ + +/* Choices used by the completer when reading a zero/non-zero value for + a variable. */ +static char *on_off_choices[] = { "Off", "On", (char *)NULL }; + +VARIABLE_ALIST info_variables[] = { + { "automatic-footnotes", + "When \"On\", footnotes appear and disappear automatically", + &auto_footnotes_p, (char **)on_off_choices }, + + { "automatic-tiling", + "When \"On\", creating or deleting a window resizes other windows", + &auto_tiling_p, (char **)on_off_choices }, + + { "visible-bell", + "When \"On\", flash the screen instead of ringing the bell", + &terminal_use_visible_bell_p, (char **)on_off_choices }, + + { "errors-ring-bell", + "When \"On\", errors cause the bell to ring", + &info_error_rings_bell_p, (char **)on_off_choices }, + + { "gc-compressed-files", + "When \"On\", Info garbage collects files which had to be uncompressed", + &gc_compressed_files, (char **)on_off_choices }, + { "show-index-match", + "When \"On\", the portion of the matched search string is highlighted", + &show_index_match, (char **)on_off_choices }, + + { "scroll-behaviour", + "Controls what happens when scrolling is requested at the end of a node", + &info_scroll_behaviour, (char **)info_scroll_choices }, + + { "scroll-step", + "The number lines to scroll when the cursor moves out of the window", + &window_scroll_step, (char **)NULL }, + + { "ISO-Latin", + "When \"On\", Info accepts and displays ISO Latin characters", + &ISO_Latin_p, (char **)on_off_choices }, + + { (char *)NULL, (char *)NULL, (int *)NULL, (char **)NULL } +}; + +DECLARE_INFO_COMMAND (describe_variable, "Explain the use of a variable") +{ + VARIABLE_ALIST *var; + char *description; + + /* Get the variable's name. */ + var = read_variable_name ("Describe variable: ", window); + + if (!var) + return; + + description = (char *)xmalloc (20 + strlen (var->name) + strlen (var->doc)); + + if (var->choices) + sprintf (description, "%s (%s): %s.", + var->name, var->choices[*(var->value)], var->doc); + else + sprintf (description, "%s (%d): %s.", var->name, *(var->value), var->doc); + + window_message_in_echo_area ("%s", description); + free (description); +} + +DECLARE_INFO_COMMAND (set_variable, "Set the value of an Info variable") +{ + VARIABLE_ALIST *var; + char *line; + + /* Get the variable's name and value. */ + var = read_variable_name ("Set variable: ", window); + + if (!var) + return; + + /* Read a new value for this variable. */ + { + char prompt[100]; + + if (!var->choices) + { + int potential_value; + + if (info_explicit_arg || count != 1) + potential_value = count; + else + potential_value = *(var->value); + + sprintf (prompt, "Set %s to value (%d): ", + var->name, potential_value); + line = info_read_in_echo_area (active_window, prompt); + + /* If no error was printed, clear the echo area. */ + if (!info_error_was_printed) + window_clear_echo_area (); + + /* User aborted? */ + if (!line) + return; + + /* If the user specified a value, get that, otherwise, we are done. */ + canonicalize_whitespace (line); + if (*line) + *(var->value) = atoi (line); + else + *(var->value) = potential_value; + + free (line); + } + else + { + register int i; + REFERENCE **array = (REFERENCE **)NULL; + int array_index = 0; + int array_slots = 0; + + for (i = 0; var->choices[i]; i++) + { + REFERENCE *entry; + + entry = (REFERENCE *)xmalloc (sizeof (REFERENCE)); + entry->label = savestring (var->choices[i]); + entry->nodename = (char *)NULL; + entry->filename = (char *)NULL; + + add_pointer_to_array + (entry, array_index, array, array_slots, 10, REFERENCE *); + } + + sprintf (prompt, "Set %s to value (%s): ", + var->name, var->choices[*(var->value)]); + + /* Ask the completer to read a variable value for us. */ + line = info_read_completing_in_echo_area (window, prompt, array); + + info_free_references (array); + + if (!echo_area_is_active) + window_clear_echo_area (); + + /* User aborted? */ + if (!line) + { + info_abort_key (active_window, 0, 0); + return; + } + + /* User accepted default choice? If so, no change. */ + if (!*line) + { + free (line); + return; + } + + /* Find the choice in our list of choices. */ + for (i = 0; var->choices[i]; i++) + if (strcmp (var->choices[i], line) == 0) + break; + + if (var->choices[i]) + *(var->value) = i; + } + } +} + +/* Read the name of an Info variable in the echo area and return the + address of a VARIABLE_ALIST member. A return value of NULL indicates + that no variable could be read. */ +VARIABLE_ALIST * +read_variable_name (prompt, window) + char *prompt; + WINDOW *window; +{ + register int i; + char *line; + REFERENCE **variables; + + /* Get the completion array of variable names. */ + variables = make_variable_completions_array (); + + /* Ask the completer to read a variable for us. */ + line = + info_read_completing_in_echo_area (window, prompt, variables); + + info_free_references (variables); + + if (!echo_area_is_active) + window_clear_echo_area (); + + /* User aborted? */ + if (!line) + { + info_abort_key (active_window, 0, 0); + return ((VARIABLE_ALIST *)NULL); + } + + /* User accepted "default"? (There is none.) */ + if (!*line) + { + free (line); + return ((VARIABLE_ALIST *)NULL); + } + + /* Find the variable in our list of variables. */ + for (i = 0; info_variables[i].name; i++) + if (strcmp (info_variables[i].name, line) == 0) + break; + + if (!info_variables[i].name) + return ((VARIABLE_ALIST *)NULL); + else + return (&(info_variables[i])); +} + +/* Make an array of REFERENCE which actually contains the names of the + variables available in Info. */ +REFERENCE ** +make_variable_completions_array () +{ + register int i; + REFERENCE **array = (REFERENCE **)NULL; + int array_index = 0, array_slots = 0; + + for (i = 0; info_variables[i].name; i++) + { + REFERENCE *entry; + + entry = (REFERENCE *)xmalloc (sizeof (REFERENCE)); + entry->label = savestring (info_variables[i].name); + entry->nodename = (char *)NULL; + entry->filename = (char *)NULL; + + add_pointer_to_array + (entry, array_index, array, array_slots, 200, REFERENCE *); + } + + return (array); +} diff --git a/gnu/usr.bin/texinfo/info/variables.h b/gnu/usr.bin/texinfo/info/variables.h new file mode 100644 index 0000000..ce40fa5 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/variables.h @@ -0,0 +1,64 @@ +/* variables.h -- Description of user visible variables in Info. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#ifndef _VARIABLES_H_ +#define _VARIABLES_H_ + +/* A variable (in the Info sense) is an integer value with a user-visible + name. You may supply an array of strings to complete over when the + variable is set; in that case, the variable is set to the index of the + string that the user chose. If you supply a null list, the user can + set the variable to a numeric value. */ + +/* Structure describing a user visible variable. */ +typedef struct { + char *name; /* Polite name. */ + char *doc; /* Documentation string. */ + int *value; /* Address of value. */ + char **choices; /* Array of strings or NULL if numeric only. */ +} VARIABLE_ALIST; + +/* Read the name of an Info variable in the echo area and return the + address of a VARIABLE_ALIST member. A return value of NULL indicates + that no variable could be read. */ +extern VARIABLE_ALIST *read_variable_name (); + +/* Make an array of REFERENCE which actually contains the names of the + variables available in Info. */ +extern REFERENCE **make_variable_completions_array (); + +/* Set the value of an info variable. */ +extern void set_variable (); + +/* The list of user-visible variables. */ +extern int auto_footnotes_p; +extern int auto_tiling_p; +extern int terminal_use_visible_bell_p; +extern int info_error_rings_bell_p; +extern int gc_compressed_files; +extern int show_index_match; +extern int info_scroll_behaviour; +extern int window_scroll_step; +extern int ISO_Latin_p; + +#endif /* _VARIABLES_H_ */ diff --git a/gnu/usr.bin/texinfo/info/window.c b/gnu/usr.bin/texinfo/info/window.c new file mode 100644 index 0000000..9035bd4 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/window.c @@ -0,0 +1,1478 @@ +/* window.c -- Windows in Info. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#include <stdio.h> +#include <ctype.h> +#include <sys/types.h> +#include <sys/stat.h> +#include "nodes.h" +#include "window.h" +#include "display.h" +#include "info-utils.h" +#include "infomap.h" + +/* The window which describes the screen. */ +WINDOW *the_screen = (WINDOW *)NULL; + +/* The window which describes the echo area. */ +WINDOW *the_echo_area = (WINDOW *)NULL; + +/* The list of windows in Info. */ +WINDOW *windows = (WINDOW *)NULL; + +/* Pointer to the active window in WINDOW_LIST. */ +WINDOW *active_window = (WINDOW *)NULL; + +/* The size of the echo area in Info. It never changes, irregardless of the + size of the screen. */ +#define ECHO_AREA_HEIGHT 1 + +/* Macro returns the amount of space that the echo area truly requires relative + to the entire screen. */ +#define echo_area_required (1 + the_echo_area->height) + +/* Initalize the window system by creating THE_SCREEN and THE_ECHO_AREA. + Create the first window ever. + You pass the dimensions of the total screen size. */ +void +window_initialize_windows (width, height) + int width, height; +{ + the_screen = (WINDOW *)xmalloc (sizeof (WINDOW)); + the_echo_area = (WINDOW *)xmalloc (sizeof (WINDOW)); + windows = (WINDOW *)xmalloc (sizeof (WINDOW)); + active_window = windows; + + zero_mem (the_screen, sizeof (WINDOW)); + zero_mem (the_echo_area, sizeof (WINDOW)); + zero_mem (active_window, sizeof (WINDOW)); + + /* None of these windows has a goal column yet. */ + the_echo_area->goal_column = -1; + active_window->goal_column = -1; + the_screen->goal_column = -1; + + /* The active and echo_area windows are visible. + The echo_area is permanent. + The screen is permanent. */ + active_window->flags = W_WindowVisible; + the_echo_area->flags = W_WindowIsPerm | W_InhibitMode | W_WindowVisible; + the_screen->flags = W_WindowIsPerm; + + /* The height of the echo area never changes. It is statically set right + here, and it must be at least 1 line for display. The size of the + initial window cannot be the same size as the screen, since the screen + includes the echo area. So, we make the height of the initial window + equal to the screen's displayable region minus the height of the echo + area. */ + the_echo_area->height = ECHO_AREA_HEIGHT; + active_window->height = the_screen->height - 1 - the_echo_area->height; + window_new_screen_size (width, height, (VFunction *)NULL); + + /* The echo area uses a different keymap than normal info windows. */ + the_echo_area->keymap = echo_area_keymap; + active_window->keymap = info_keymap; +} + +/* Given that the size of the screen has changed to WIDTH and HEIGHT + from whatever it was before (found in the_screen->height, ->width), + change the size (and possibly location) of each window in the screen. + If a window would become too small, call the function DELETER on it, + after deleting the window from our chain of windows. If DELETER is NULL, + nothing extra is done. The last window can never be deleted, but it can + become invisible. */ + +/* If non-null, a function to call with WINDOW as argument when the function + window_new_screen_size () has deleted WINDOW. */ +VFunction *window_deletion_notifier = (VFunction *)NULL; + +void +window_new_screen_size (width, height) + int width, height; +{ + register WINDOW *win; + int delta_height, delta_each, delta_leftover; + int numwins; + + /* If no change, do nothing. */ + if (width == the_screen->width && height == the_screen->height) + return; + + /* If the new window height is too small, make it be zero. */ + if (height < (WINDOW_MIN_SIZE + the_echo_area->height)) + height = 0; + if (width < 0) + width = 0; + + /* Find out how many windows will change. */ + for (numwins = 0, win = windows; win; win = win->next, numwins++); + + /* See if some windows will need to be deleted. This is the case if + the screen is getting smaller, and the available space divided by + the number of windows is less than WINDOW_MIN_SIZE. In that case, + delete some windows and try again until there is either enough + space to divy up among the windows, or until there is only one + window left. */ + while ((height - echo_area_required) / numwins <= WINDOW_MIN_SIZE) + { + /* If only one window, make the size of it be zero, and return + immediately. */ + if (!windows->next) + { + windows->height = 0; + maybe_free (windows->line_starts); + windows->line_starts = (char **)NULL; + windows->line_count = 0; + break; + } + + /* If we have some temporary windows, delete one of them. */ + for (win = windows; win; win = win->next) + if (win->flags & W_TempWindow) + break; + + /* Otherwise, delete the first window, and try again. */ + if (!win) + win = windows; + + if (window_deletion_notifier) + (*window_deletion_notifier) (win); + + window_delete_window (win); + numwins--; + } + + /* The screen has changed height and width. */ + delta_height = height - the_screen->height; /* This is how much. */ + the_screen->height = height; /* This is the new height. */ + the_screen->width = width; /* This is the new width. */ + + /* Set the start of the echo area. */ + the_echo_area->first_row = height - the_echo_area->height; + the_echo_area->width = width; + + /* Check to see if the screen can really be changed this way. */ + if ((!windows->next) && ((windows->height == 0) && (delta_height < 0))) + return; + + /* Divide the change in height among the available windows. */ + delta_each = delta_height / numwins; + delta_leftover = delta_height - (delta_each * numwins); + + /* Change the height of each window in the chain by delta_each. Change + the height of the last window in the chain by delta_each and by the + leftover amount of change. Change the width of each window to be + WIDTH. */ + for (win = windows; win; win = win->next) + { + if ((win->width != width) && ((win->flags & W_InhibitMode) == 0)) + { + win->width = width; + maybe_free (win->modeline); + win->modeline = (char *)xmalloc (1 + width); + } + + win->height += delta_each; + + /* If the previous height of this window was zero, it was the only + window, and it was not visible. Thus we need to compensate for + the echo_area. */ + if (win->height == delta_each) + win->height -= (1 + the_echo_area->height); + + /* If this is not the first window in the chain, then change the + first row of it. We cannot just add delta_each to the first row, + since this window's first row is the sum of the collective increases + that have gone before it. So we just add one to the location of the + previous window's modeline. */ + if (win->prev) + win->first_row = (win->prev->first_row + win->prev->height) + 1; + + /* The last window in the chain gets the extra space (or shrinkage). */ + if (!win->next) + win->height += delta_leftover; + + if (win->node) + recalculate_line_starts (win); + + win->flags |= W_UpdateWindow; + } + + /* If the screen got smaller, check over the windows just shrunk to + keep them within bounds. Some of the windows may have gotten smaller + than WINDOW_MIN_HEIGHT in which case some of the other windows are + larger than the available display space in the screen. Because of our + intial test above, we know that there is enough space for all of the + windows. */ + if ((delta_each < 0) && ((windows->height != 0) && windows->next)) + { + int avail; + + avail = the_screen->height - (numwins + the_echo_area->height); + win = windows; + + while (win) + { + if ((win->height < WINDOW_MIN_HEIGHT) || + (win->height > avail)) + { + WINDOW *lastwin; + + /* Split the space among the available windows. */ + delta_each = avail / numwins; + delta_leftover = avail - (delta_each * numwins); + + for (win = windows; win; win = win->next) + { + lastwin = win; + if (win->prev) + win->first_row = + (win->prev->first_row + win->prev->height) + 1; + win->height = delta_each; + } + + /* Give the leftover space (if any) to the last window. */ + lastwin->height += delta_leftover; + break; + } + else + win= win->next; + } + } +} + +/* Make a new window showing NODE, and return that window structure. + If NODE is passed as NULL, then show the node showing in the active + window. If the window could not be made return a NULL pointer. The + active window is not changed.*/ +WINDOW * +window_make_window (node) + NODE *node; +{ + WINDOW *window; + + if (!node) + node = active_window->node; + + /* If there isn't enough room to make another window, return now. */ + if ((active_window->height / 2) < WINDOW_MIN_SIZE) + return ((WINDOW *)NULL); + + /* Make and initialize the new window. + The fudging about with -1 and +1 is because the following window in the + chain cannot start at window->height, since that is where the modeline + for the previous window is displayed. The inverse adjustment is made + in window_delete_window (). */ + window = (WINDOW *)xmalloc (sizeof (WINDOW)); + window->width = the_screen->width; + window->height = (active_window->height / 2) - 1; +#if defined (SPLIT_BEFORE_ACTIVE) + window->first_row = active_window->first_row; +#else + window->first_row = active_window->first_row + + (active_window->height - window->height); +#endif + window->keymap = info_keymap; + window->goal_column = -1; + window->modeline = (char *)xmalloc (1 + window->width); + window->line_starts = (char **)NULL; + window->flags = W_UpdateWindow | W_WindowVisible; + window_set_node_of_window (window, node); + + /* Adjust the height of the old active window. */ + active_window->height -= (window->height + 1); +#if defined (SPLIT_BEFORE_ACTIVE) + active_window->first_row += (window->height + 1); +#endif + active_window->flags |= W_UpdateWindow; + + /* Readjust the new and old windows so that their modelines and contents + will be displayed correctly. */ +#if defined (NOTDEF) + /* We don't have to do this for WINDOW since window_set_node_of_window () + already did. */ + window_adjust_pagetop (window); + window_make_modeline (window); +#endif /* NOTDEF */ + + /* We do have to readjust the existing active window. */ + window_adjust_pagetop (active_window); + window_make_modeline (active_window); + +#if defined (SPLIT_BEFORE_ACTIVE) + /* This window is just before the active one. The active window gets + bumped down one. The active window is not changed. */ + window->next = active_window; + + window->prev = active_window->prev; + active_window->prev = window; + + if (window->prev) + window->prev->next = window; + else + windows = window; +#else + /* This window is just after the active one. Which window is active is + not changed. */ + window->prev = active_window; + window->next = active_window->next; + active_window->next = window; + if (window->next) + window->next->prev = window; +#endif /* !SPLIT_BEFORE_ACTIVE */ + return (window); +} + +/* These useful macros make it possible to read the code in + window_change_window_height (). */ +#define grow_me_shrinking_next(me, next, diff) \ + do { \ + me->height += diff; \ + next->height -= diff; \ + next->first_row += diff; \ + window_adjust_pagetop (next); \ + } while (0) + +#define grow_me_shrinking_prev(me, prev, diff) \ + do { \ + me->height += diff; \ + prev->height -= diff; \ + me->first_row -=diff; \ + window_adjust_pagetop (prev); \ + } while (0) + +#define shrink_me_growing_next(me, next, diff) \ + do { \ + me->height -= diff; \ + next->height += diff; \ + next->first_row -= diff; \ + window_adjust_pagetop (next); \ + } while (0) + +#define shrink_me_growing_prev(me, prev, diff) \ + do { \ + me->height -= diff; \ + prev->height += diff; \ + me->first_row += diff; \ + window_adjust_pagetop (prev); \ + } while (0) + +/* Change the height of WINDOW by AMOUNT. This also automagically adjusts + the previous and next windows in the chain. If there is only one user + window, then no change takes place. */ +void +window_change_window_height (window, amount) + WINDOW *window; + int amount; +{ + register WINDOW *win, *prev, *next; + + /* If there is only one window, or if the amount of change is zero, + return immediately. */ + if (!windows->next || amount == 0) + return; + + /* Find this window in our chain. */ + for (win = windows; win; win = win->next) + if (win == window) + break; + + /* If the window is isolated (i.e., doesn't appear in our window list, + then quit now. */ + if (!win) + return; + + /* Change the height of this window by AMOUNT, if that is possible. + It can be impossible if there isn't enough available room on the + screen, or if the resultant window would be too small. */ + + prev = window->prev; + next = window->next; + + /* WINDOW decreasing in size? */ + if (amount < 0) + { + int abs_amount = -amount; /* It is easier to deal with this way. */ + + /* If the resultant window would be too small, stop here. */ + if ((window->height - abs_amount) < WINDOW_MIN_HEIGHT) + return; + + /* If we have two neighboring windows, choose the smaller one to get + larger. */ + if (next && prev) + { + if (prev->height < next->height) + shrink_me_growing_prev (window, prev, abs_amount); + else + shrink_me_growing_next (window, next, abs_amount); + } + else if (next) + shrink_me_growing_next (window, next, abs_amount); + else + shrink_me_growing_prev (window, prev, abs_amount); + } + + /* WINDOW increasing in size? */ + if (amount > 0) + { + int total_avail, next_avail = 0, prev_avail = 0; + + if (next) + next_avail = next->height - WINDOW_MIN_SIZE; + + if (prev) + prev_avail = prev->height - WINDOW_MIN_SIZE; + + total_avail = next_avail + prev_avail; + + /* If there isn't enough space available to grow this window, give up. */ + if (amount > total_avail) + return; + + /* If there aren't two neighboring windows, or if one of the neighbors + is larger than the other one by at least AMOUNT, grow that one. */ + if ((next && !prev) || ((next_avail - amount) >= prev_avail)) + grow_me_shrinking_next (window, next, amount); + else if ((prev && !next) || ((prev_avail - amount) >= next_avail)) + grow_me_shrinking_prev (window, prev, amount); + else + { + int change; + + /* This window has two neighbors. They both must be shrunk in to + make enough space for WINDOW to grow. Make them both the same + size. */ + if (prev_avail > next_avail) + { + change = prev_avail - next_avail; + grow_me_shrinking_prev (window, prev, change); + amount -= change; + } + else + { + change = next_avail - prev_avail; + grow_me_shrinking_next (window, next, change); + amount -= change; + } + + /* Both neighbors are the same size. Split the difference in + AMOUNT between them. */ + while (amount) + { + window->height++; + amount--; + + /* Odd numbers grow next, even grow prev. */ + if (amount & 1) + { + prev->height--; + window->first_row--; + } + else + { + next->height--; + next->first_row++; + } + } + window_adjust_pagetop (prev); + window_adjust_pagetop (next); + } + } + if (prev) + prev->flags |= W_UpdateWindow; + + if (next) + next->flags |= W_UpdateWindow; + + window->flags |= W_UpdateWindow; + window_adjust_pagetop (window); +} + +/* Tile all of the windows currently displayed in the global variable + WINDOWS. If argument STYLE is TILE_INTERNALS, tile windows displaying + internal nodes as well, otherwise do not change the height of such + windows. */ +void +window_tile_windows (style) + int style; +{ + WINDOW *win, *last_adjusted; + int numwins, avail, per_win_height, leftover; + int do_internals; + + numwins = avail = 0; + do_internals = (style == TILE_INTERNALS); + + for (win = windows; win; win = win->next) + if (do_internals || !win->node || + (win->node->flags & N_IsInternal) == 0) + { + avail += win->height; + numwins++; + } + + if (numwins <= 1 || !the_screen->height) + return; + + /* Find the size for each window. Divide the size of the usable portion + of the screen by the number of windows. */ + per_win_height = avail / numwins; + leftover = avail - (per_win_height * numwins); + + last_adjusted = (WINDOW *)NULL; + for (win = windows; win; win = win->next) + { + if (do_internals || !win->node || + (win->node->flags & N_IsInternal) == 0) + { + last_adjusted = win; + win->height = per_win_height; + } + } + + if (last_adjusted) + last_adjusted->height += leftover; + + /* Readjust the first_row of every window in the chain. */ + for (win = windows; win; win = win->next) + { + if (win->prev) + win->first_row = win->prev->first_row + win->prev->height + 1; + + window_adjust_pagetop (win); + win->flags |= W_UpdateWindow; + } +} + +/* Toggle the state of line wrapping in WINDOW. This can do a bit of fancy + redisplay. */ +void +window_toggle_wrap (window) + WINDOW *window; +{ + if (window->flags & W_NoWrap) + window->flags &= ~W_NoWrap; + else + window->flags |= W_NoWrap; + + if (window != the_echo_area) + { + char **old_starts; + int old_lines, old_pagetop; + + old_starts = window->line_starts; + old_lines = window->line_count; + old_pagetop = window->pagetop; + + calculate_line_starts (window); + + /* Make sure that point appears within this window. */ + window_adjust_pagetop (window); + + /* If the pagetop hasn't changed maybe we can do some scrolling now + to speed up the display. Many of the line starts will be the same, + so scrolling here is a very good optimization.*/ + if (old_pagetop == window->pagetop) + display_scroll_line_starts + (window, old_pagetop, old_starts, old_lines); + maybe_free (old_starts); + } + window->flags |= W_UpdateWindow; +} + +/* Set WINDOW to display NODE. */ +void +window_set_node_of_window (window, node) + WINDOW *window; + NODE *node; +{ + window->node = node; + window->pagetop = 0; + window->point = 0; + recalculate_line_starts (window); + window->flags |= W_UpdateWindow; + window_adjust_pagetop (window); + window_make_modeline (window); +} + +/* Delete WINDOW from the list of known windows. If this window was the + active window, make the next window in the chain be the active window. + If the active window is the next or previous window, choose that window + as the recipient of the extra space. Otherwise, prefer the next window. */ +void +window_delete_window (window) + WINDOW *window; +{ + WINDOW *next, *prev, *window_to_fix; + + next = window->next; + prev = window->prev; + + /* You cannot delete the only window or a permanent window. */ + if ((!next && !prev) || (window->flags & W_WindowIsPerm)) + return; + + if (next) + next->prev = prev; + + if (!prev) + windows = next; + else + prev->next = next; + + if (window->line_starts) + free (window->line_starts); + + if (window->modeline) + free (window->modeline); + + if (window == active_window) + { + /* If there isn't a next window, then there must be a previous one, + since we cannot delete the last window. If there is a next window, + prefer to use that as the active window. */ + if (next) + active_window = next; + else + active_window = prev; + } + + if (next && active_window == next) + window_to_fix = next; + else if (prev && active_window == prev) + window_to_fix = prev; + else if (next) + window_to_fix = next; + else if (prev) + window_to_fix = prev; + else + window_to_fix = windows; + + if (window_to_fix->first_row > window->first_row) + { + int diff; + + /* Try to adjust the visible part of the node so that as little + text as possible has to move. */ + diff = window_to_fix->first_row - window->first_row; + window_to_fix->first_row = window->first_row; + + window_to_fix->pagetop -= diff; + if (window_to_fix->pagetop < 0) + window_to_fix->pagetop = 0; + } + + /* The `+ 1' is to offset the difference between the first_row locations. + See the code in window_make_window (). */ + window_to_fix->height += window->height + 1; + window_to_fix->flags |= W_UpdateWindow; + + free (window); +} + +/* For every window in CHAIN, set the flags member to have FLAG set. */ +void +window_mark_chain (chain, flag) + WINDOW *chain; + int flag; +{ + register WINDOW *win; + + for (win = chain; win; win = win->next) + win->flags |= flag; +} + +/* For every window in CHAIN, clear the flags member of FLAG. */ +void +window_unmark_chain (chain, flag) + WINDOW *chain; + int flag; +{ + register WINDOW *win; + + for (win = chain; win; win = win->next) + win->flags &= ~flag; +} + +/* Return the number of characters it takes to display CHARACTER on the + screen at HPOS. */ +int +character_width (character, hpos) + int character, hpos; +{ + int printable_limit = 127; + int width = 1; + + if (ISO_Latin_p) + printable_limit = 160; + + if (character > printable_limit) + width = 3; + else if (iscntrl (character)) + { + switch (character) + { + case '\r': + case '\n': + width = the_screen->width - hpos; + break; + case '\t': + width = ((hpos + 8) & 0xf8) - hpos; + break; + default: + width = 2; + } + } + else if (character == DEL) + width = 2; + + return (width); +} + +/* Return the number of characters it takes to display STRING on the screen + at HPOS. */ +int +string_width (string, hpos) + char *string; + int hpos; +{ + register int i, width, this_char_width; + + for (width = 0, i = 0; string[i]; i++) + { + this_char_width = character_width (string[i], hpos); + width += this_char_width; + hpos += this_char_width; + } + return (width); +} + +/* Quickly guess the approximate number of lines to that NODE would + take to display. This really only counts carriage returns. */ +int +window_physical_lines (node) + NODE *node; +{ + register int i, lines; + char *contents; + + if (!node) + return (0); + + contents = node->contents; + for (i = 0, lines = 1; i < node->nodelen; i++) + if (contents[i] == '\n') + lines++; + + return (lines); +} + +/* Calculate a list of line starts for the node belonging to WINDOW. The line + starts are pointers to the actual text within WINDOW->NODE. */ +void +calculate_line_starts (window) + WINDOW *window; +{ + register int i, hpos; + char **line_starts = (char **)NULL; + int line_starts_index = 0, line_starts_slots = 0; + int bump_index; + NODE *node; + + window->line_starts = (char **)NULL; + window->line_count = 0; + node = window->node; + + if (!node) + return; + + /* Grovel the node starting at the top, and for each line calculate the + width of the characters appearing in that line. Add each line start + to our array. */ + i = 0; + hpos = 0; + bump_index = 0; + + while (i < node->nodelen) + { + char *line = node->contents + i; + unsigned int cwidth, c; + + add_pointer_to_array (line, line_starts_index, line_starts, + line_starts_slots, 100, char *); + if (bump_index) + { + i++; + bump_index = 0; + } + + while (1) + { + c = node->contents[i]; + cwidth = character_width (c, hpos); + + /* If this character fits within this line, just do the next one. */ + if ((hpos + cwidth) < window->width) + { + i++; + hpos += cwidth; + continue; + } + else + { + /* If this character would position the cursor at the start of + the next printed screen line, then do the next line. */ + if (c == '\n' || c == '\r' || c == '\t') + { + i++; + hpos = 0; + break; + } + else + { + /* This character passes the window width border. Postion + the cursor after the printed character, but remember this + line start as where this character is. A bit tricky. */ + + /* If this window doesn't wrap lines, proceed to the next + physical line here. */ + if (window->flags & W_NoWrap) + { + hpos = 0; + while (i < node->nodelen && node->contents[i] != '\n') + i++; + + if (node->contents[i] == '\n') + i++; + } + else + { + hpos = the_screen->width - hpos; + bump_index++; + } + break; + } + } + } + } + window->line_starts = line_starts; + window->line_count = line_starts_index; +} + +/* Given WINDOW, recalculate the line starts for the node it displays. */ +void +recalculate_line_starts (window) + WINDOW *window; +{ + maybe_free (window->line_starts); + calculate_line_starts (window); +} + +/* Global variable control redisplay of scrolled windows. If non-zero, it + is the desired number of lines to scroll the window in order to make + point visible. A user might set this to 1 for smooth scrolling. If + set to zero, the line containing point is centered within the window. */ +int window_scroll_step = 0; + +/* Adjust the pagetop of WINDOW such that the cursor point will be visible. */ +void +window_adjust_pagetop (window) + WINDOW *window; +{ + register int line = 0; + char *contents; + + if (!window->node) + return; + + contents = window->node->contents; + + /* Find the first printed line start which is after WINDOW->point. */ + for (line = 0; line < window->line_count; line++) + { + char *line_start; + + line_start = window->line_starts[line]; + + if ((line_start - contents) > window->point) + break; + } + + /* The line index preceding the line start which is past point is the + one containing point. */ + line--; + + /* If this line appears in the current displayable page, do nothing. + Otherwise, adjust the top of the page to make this line visible. */ + if ((line < window->pagetop) || + (line - window->pagetop > (window->height - 1))) + { + /* The user-settable variable "scroll-step" is used to attempt + to make point visible, iff it is non-zero. If that variable + is zero, then the line containing point is centered within + the window. */ + if (window_scroll_step < window->height) + { + if ((line < window->pagetop) && + ((window->pagetop - window_scroll_step) <= line)) + window->pagetop -= window_scroll_step; + else if ((line - window->pagetop > (window->height - 1)) && + ((line - (window->pagetop + window_scroll_step) + < window->height))) + window->pagetop += window_scroll_step; + else + window->pagetop = line - ((window->height - 1) / 2); + } + else + window->pagetop = line - ((window->height - 1) / 2); + + if (window->pagetop < 0) + window->pagetop = 0; + window->flags |= W_UpdateWindow; + } +} + +/* Return the index of the line containing point. */ +int +window_line_of_point (window) + WINDOW *window; +{ + register int i, start = 0; + + /* Try to optimize. Check to see if point is past the pagetop for + this window, and if so, start searching forward from there. */ + if ((window->pagetop > -1 && window->pagetop < window->line_count) && + (window->line_starts[window->pagetop] - window->node->contents) + <= window->point) + start = window->pagetop; + + for (i = start; i < window->line_count; i++) + { + if ((window->line_starts[i] - window->node->contents) > window->point) + break; + } + + return (i - 1); +} + +/* Get and return the goal column for this window. */ +int +window_get_goal_column (window) + WINDOW *window; +{ + if (!window->node) + return (-1); + + if (window->goal_column != -1) + return (window->goal_column); + + /* Okay, do the work. Find the printed offset of the cursor + in this window. */ + return (window_get_cursor_column (window)); +} + +/* Get and return the printed column offset of the cursor in this window. */ +int +window_get_cursor_column (window) + WINDOW *window; +{ + int i, hpos, end; + char *line; + + i = window_line_of_point (window); + + if (i < 0) + return (-1); + + line = window->line_starts[i]; + end = window->point - (line - window->node->contents); + + for (hpos = 0, i = 0; i < end; i++) + hpos += character_width (line[i], hpos); + + return (hpos); +} + +/* Count the number of characters in LINE that precede the printed column + offset of GOAL. */ +int +window_chars_to_goal (line, goal) + char *line; + int goal; +{ + register int i, check, hpos; + + for (hpos = 0, i = 0; line[i] != '\n'; i++) + { + + check = hpos + character_width (line[i], hpos); + + if (check > goal) + break; + + hpos = check; + } + return (i); +} + +/* Create a modeline for WINDOW, and store it in window->modeline. */ +void +window_make_modeline (window) + WINDOW *window; +{ + register int i; + char *modeline; + char location_indicator[4]; + int lines_remaining; + + /* Only make modelines for those windows which have one. */ + if (window->flags & W_InhibitMode) + return; + + /* Find the number of lines actually displayed in this window. */ + lines_remaining = window->line_count - window->pagetop; + + if (window->pagetop == 0) + { + if (lines_remaining <= window->height) + strcpy (location_indicator, "All"); + else + strcpy (location_indicator, "Top"); + } + else + { + if (lines_remaining <= window->height) + strcpy (location_indicator, "Bot"); + else + { + float pt, lc; + int percentage; + + pt = (float)window->pagetop; + lc = (float)window->line_count; + + percentage = 100 * (pt / lc); + + sprintf (location_indicator, "%2d%%", percentage); + } + } + + /* Calculate the maximum size of the information to stick in MODELINE. */ + { + int modeline_len = 0; + char *parent = (char *)NULL, *filename = "*no file*"; + char *nodename = "*no node*"; + char *update_message = (char *)NULL; + NODE *node = window->node; + + if (node) + { + if (node->nodename) + nodename = node->nodename; + + if (node->parent) + { + parent = filename_non_directory (node->parent); + modeline_len += strlen ("Subfile: ") + strlen (node->filename); + } + + if (node->filename) + filename = filename_non_directory (node->filename); + + if (node->flags & N_UpdateTags) + update_message = "--*** Tags out of Date ***"; + } + + if (update_message) + modeline_len += strlen (update_message); + modeline_len += strlen (filename); + modeline_len += strlen (nodename); + modeline_len += 4; /* strlen (location_indicator). */ + + /* 10 for the decimal representation of the number of lines in this + node, and the remainder of the text that can appear in the line. */ + modeline_len += 10 + strlen ("-----Info: (), lines ----, "); + modeline_len += window->width; + + modeline = (char *)xmalloc (1 + modeline_len); + + /* Special internal windows have no filename. */ + if (!parent && !*filename) + sprintf (modeline, "-%s---Info: %s, %d lines --%s--", + (window->flags & W_NoWrap) ? "$" : "-", + nodename, window->line_count, location_indicator); + else + sprintf (modeline, "-%s%s-Info: (%s)%s, %d lines --%s--", + (window->flags & W_NoWrap) ? "$" : "-", + (node && (node->flags & N_IsCompressed)) ? "zz" : "--", + parent ? parent : filename, + nodename, window->line_count, location_indicator); + + if (parent) + sprintf (modeline + strlen (modeline), " Subfile: %s", filename); + + if (update_message) + sprintf (modeline + strlen (modeline), "%s", update_message); + + i = strlen (modeline); + + if (i >= window->width) + modeline[window->width] = '\0'; + else + { + while (i < window->width) + modeline[i++] = '-'; + modeline[i] = '\0'; + } + + strcpy (window->modeline, modeline); + free (modeline); + } +} + +/* Make WINDOW start displaying at PERCENT percentage of its node. */ +void +window_goto_percentage (window, percent) + WINDOW *window; + int percent; +{ + int desired_line; + + if (!percent) + desired_line = 0; + else + desired_line = + (int) ((float)window->line_count * ((float)percent / 100.0)); + + window->pagetop = desired_line; + window->point = + window->line_starts[window->pagetop] - window->node->contents; + window->flags |= W_UpdateWindow; + window_make_modeline (window); +} + +/* Get the state of WINDOW, and save it in STATE. */ +void +window_get_state (window, state) + WINDOW *window; + WINDOW_STATE *state; +{ + state->node = window->node; + state->pagetop = window->pagetop; + state->point = window->point; +} + +/* Set the node, pagetop, and point of WINDOW. */ +void +window_set_state (window, state) + WINDOW *window; + WINDOW_STATE *state; +{ + if (window->node != state->node) + window_set_node_of_window (window, state->node); + window->pagetop = state->pagetop; + window->point = state->point; +} + + +/* **************************************************************** */ +/* */ +/* Manipulating Home-Made Nodes */ +/* */ +/* **************************************************************** */ + +/* A place to buffer echo area messages. */ +static NODE *echo_area_node = (NODE *)NULL; + +/* Make the node of the_echo_area be an empty one. */ +static void +free_echo_area () +{ + if (echo_area_node) + { + maybe_free (echo_area_node->contents); + free (echo_area_node); + } + + echo_area_node = (NODE *)NULL; + window_set_node_of_window (the_echo_area, echo_area_node); +} + +/* Clear the echo area, removing any message that is already present. + The echo area is cleared immediately. */ +void +window_clear_echo_area () +{ + free_echo_area (); + display_update_one_window (the_echo_area); +} + +/* Make a message appear in the echo area, built from FORMAT, ARG1 and ARG2. + The arguments are treated similar to printf () arguments, but not all of + printf () hair is present. The message appears immediately. If there was + already a message appearing in the echo area, it is removed. */ +void +window_message_in_echo_area (format, arg1, arg2) + char *format; + void *arg1, *arg2; +{ + free_echo_area (); + echo_area_node = build_message_node (format, arg1, arg2); + window_set_node_of_window (the_echo_area, echo_area_node); + display_update_one_window (the_echo_area); +} + +/* Place a temporary message in the echo area built from FORMAT, ARG1 + and ARG2. The message appears immediately, but does not destroy + any existing message. A future call to unmessage_in_echo_area () + restores the old contents. */ +static NODE **old_echo_area_nodes = (NODE **)NULL; +static int old_echo_area_nodes_index = 0; +static int old_echo_area_nodes_slots = 0; + +void +message_in_echo_area (format, arg1, arg2) + char *format; + void *arg1, *arg2; +{ + if (echo_area_node) + { + add_pointer_to_array (echo_area_node, old_echo_area_nodes_index, + old_echo_area_nodes, old_echo_area_nodes_slots, + 4, NODE *); + } + echo_area_node = (NODE *)NULL; + window_message_in_echo_area (format, arg1, arg2); +} + +void +unmessage_in_echo_area () +{ + free_echo_area (); + + if (old_echo_area_nodes_index) + echo_area_node = old_echo_area_nodes[--old_echo_area_nodes_index]; + + window_set_node_of_window (the_echo_area, echo_area_node); + display_update_one_window (the_echo_area); +} + +/* A place to build a message. */ +static char *message_buffer = (char *)NULL; +static int message_buffer_index = 0; +static int message_buffer_size = 0; + +/* Ensure that there is enough space to stuff LENGTH characters into + MESSAGE_BUFFER. */ +static void +message_buffer_resize (length) + int length; +{ + if (!message_buffer) + { + message_buffer_size = length + 1; + message_buffer = (char *)xmalloc (message_buffer_size); + message_buffer_index = 0; + } + + while (message_buffer_size <= message_buffer_index + length) + message_buffer = (char *) + xrealloc (message_buffer, + message_buffer_size += 100 + (2 * length)); +} + +/* Format MESSAGE_BUFFER with the results of printing FORMAT with ARG1 and + ARG2. */ +static void +build_message_buffer (format, arg1, arg2) + char *format; + void *arg1, *arg2; +{ + register int i, len; + void *args[2]; + int arg_index = 0; + + args[0] = arg1; + args[1] = arg2; + + len = strlen (format); + + message_buffer_resize (len); + + for (i = 0; format[i]; i++) + { + if (format[i] != '%') + { + message_buffer[message_buffer_index++] = format[i]; + len--; + } + else + { + char c; + + c = format[++i]; + + switch (c) + { + case '%': /* Insert a percent sign. */ + message_buffer_resize (len + 1); + message_buffer[message_buffer_index++] = '%'; + break; + + case 's': /* Insert the current arg as a string. */ + { + char *string; + int string_len; + + string = (char *)args[arg_index++]; + string_len = strlen (string); + + message_buffer_resize (len + string_len); + sprintf + (message_buffer + message_buffer_index, "%s", string); + message_buffer_index += string_len; + } + break; + + case 'd': /* Insert the current arg as an integer. */ + { + int integer; + + integer = (int)args[arg_index++]; + + message_buffer_resize (len + 32); + sprintf + (message_buffer + message_buffer_index, "%d", integer); + message_buffer_index = strlen (message_buffer); + } + break; + + case 'c': /* Insert the current arg as a character. */ + { + int character; + + character = (int)args[arg_index++]; + + message_buffer_resize (len + 1); + message_buffer[message_buffer_index++] = character; + } + break; + + default: + abort (); + } + } + } + message_buffer[message_buffer_index] = '\0'; +} + +/* Build a new node which has FORMAT printed with ARG1 and ARG2 as the + contents. */ +NODE * +build_message_node (format, arg1, arg2) + char *format; + void *arg1, *arg2; +{ + NODE *node; + + message_buffer_index = 0; + build_message_buffer (format, arg1, arg2); + + node = message_buffer_to_node (); + return (node); +} + +/* Convert the contents of the message buffer to a node. */ +NODE * +message_buffer_to_node () +{ + NODE *node; + + node = (NODE *)xmalloc (sizeof (NODE)); + node->filename = (char *)NULL; + node->parent = (char *)NULL; + node->nodename = (char *)NULL; + node->flags = 0; + + /* Make sure that this buffer ends with a newline. */ + node->nodelen = 1 + strlen (message_buffer); + node->contents = (char *)xmalloc (1 + node->nodelen); + strcpy (node->contents, message_buffer); + node->contents[node->nodelen - 1] = '\n'; + node->contents[node->nodelen] = '\0'; + return (node); +} + +/* Useful functions can be called from outside of window.c. */ +void +initialize_message_buffer () +{ + message_buffer_index = 0; +} + +/* Print FORMAT with ARG1,2 to the end of the current message buffer. */ +void +printf_to_message_buffer (format, arg1, arg2) + char *format; + void *arg1, *arg2; +{ + build_message_buffer (format, arg1, arg2); +} + +/* Return the current horizontal position of the "cursor" on the most + recently output message buffer line. */ +int +message_buffer_length_this_line () +{ + register int i; + + if (!message_buffer_index) + return (0); + + for (i = message_buffer_index; i && message_buffer[i - 1] != '\n'; i--); + + return (string_width (message_buffer + i, 0)); +} + +/* Pad STRING to COUNT characters by inserting blanks. */ +int +pad_to (count, string) + int count; + char *string; +{ + register int i; + + i = strlen (string); + + if (i >= count) + string[i++] = ' '; + else + { + while (i < count) + string[i++] = ' '; + } + string[i] = '\0'; + + return (i); +} diff --git a/gnu/usr.bin/texinfo/info/window.h b/gnu/usr.bin/texinfo/info/window.h new file mode 100644 index 0000000..3e82570 --- /dev/null +++ b/gnu/usr.bin/texinfo/info/window.h @@ -0,0 +1,229 @@ +/* window.h -- Structure and flags used in manipulating Info windows. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#ifndef _WINDOW_H_ +#define _WINDOW_H_ + +#include "nodes.h" +#include "infomap.h" + +/* Smallest number of visible lines in a window. The actual height is + always one more than this number because each window has a modeline. */ +#define WINDOW_MIN_HEIGHT 2 + +/* Smallest number of screen lines that can be used to fully present a + window. This number includes the modeline of the window. */ +#define WINDOW_MIN_SIZE (WINDOW_MIN_HEIGHT + 1) + +/* The exact same elements are used within the WINDOW_STATE structure and a + subsection of the WINDOW structure. We could define a structure which + contains this elements, and include that structure in each of WINDOW_STATE + and WINDOW. But that would lead references in the code such as + window->state->node which we would like to avoid. Instead, we #define the + elements here, and simply include the define in both data structures. Thus, + if you need to change window state information, here is where you would + do it. NB> The last element does NOT end with a semi-colon. */ +#define WINDOW_STATE_DECL \ + NODE *node; /* The node displayed in this window. */ \ + int pagetop; /* LINE_STARTS[PAGETOP] is first line in WINDOW. */ \ + long point /* Offset within NODE of the cursor position. */ + +/* Structure which defines a window. Windows are doubly linked, next + and prev. The list of windows is kept on WINDOWS. The structure member + window->height is the total height of the window. The position location + (0, window->height + window->first_row) is the first character of this + windows modeline. The number of lines that can be displayed in a window + is equal to window->height - 1. */ +typedef struct __window__ { + struct __window__ *next; /* Next window in this chain. */ + struct __window__ *prev; /* Previous window in this chain. */ + int width; /* Width of this window. */ + int height; /* Height of this window. */ + int first_row; /* Offset of the first line in the_screen. */ + int goal_column; /* The column we would like the cursor to appear in. */ + Keymap keymap; /* Keymap used to read commands in this window. */ + WINDOW_STATE_DECL; /* Node, pagetop and point. */ + char *modeline; /* Calculated text of the modeline for this window. */ + char **line_starts; /* Array of printed line starts for this node. */ + int line_count; /* Number of lines appearing in LINE_STARTS. */ + int flags; /* See below for details. */ +} WINDOW; + +typedef struct { + WINDOW_STATE_DECL; /* What gets saved. */ +} WINDOW_STATE; + +#define W_UpdateWindow 0x01 /* WINDOW needs updating. */ +#define W_WindowIsPerm 0x02 /* This WINDOW is a permanent object. */ +#define W_WindowVisible 0x04 /* This WINDOW is currently visible. */ +#define W_InhibitMode 0x08 /* This WINDOW has no modeline. */ +#define W_NoWrap 0x10 /* Lines do not wrap in this window. */ +#define W_InputWindow 0x20 /* Window accepts input. */ +#define W_TempWindow 0x40 /* Window is less important. */ + +extern WINDOW *windows; /* List of visible Info windows. */ +extern WINDOW *active_window; /* The currently active window. */ +extern WINDOW *the_screen; /* The Info screen is just another window. */ +extern WINDOW *the_echo_area; /* THE_ECHO_AREA is a window in THE_SCREEN. */ + +/* Global variable control redisplay of scrolled windows. If non-zero, it + is the desired number of lines to scroll the window in order to make + point visible. A user might set this to 1 for smooth scrolling. If + set to zero, the line containing point is centered within the window. */ +extern int window_scroll_step; + + /* Make the modeline member for WINDOW. */ +extern void window_make_modeline (); + +/* Initalize the window system by creating THE_SCREEN and THE_ECHO_AREA. + Create the first window ever, and make it permanent. + You pass WIDTH and HEIGHT; the dimensions of the total screen size. */ +extern void window_initialize_windows (); + +/* Make a new window showing NODE, and return that window structure. + The new window is made to be the active window. If NODE is passed + as NULL, then show the node showing in the active window. If the + window could not be made return a NULL pointer. The active window + is not changed.*/ +extern WINDOW *window_make_window (); + +/* Delete WINDOW from the list of known windows. If this window was the + active window, make the next window in the chain be the active window, + or the previous window in the chain if there is no next window. */ +extern void window_delete_window (); + +/* A function to call when the screen changes size, and some windows have + to get deleted. The function is called with the window to be deleted + as an argument, and it can't do anything about the window getting deleted; + it can only clean up dangling references to that window. */ +extern VFunction *window_deletion_notifier; + +/* Set WINDOW to display NODE. */ +extern void window_set_node_of_window (); + +/* Tell the window system that the size of the screen has changed. This + causes lots of interesting things to happen. The permanent windows + are resized, as well as every visible window. You pass WIDTH and HEIGHT; + the dimensions of the total screen size. */ +extern void window_new_screen_size (); + +/* Change the height of WINDOW by AMOUNT. This also automagically adjusts + the previous and next windows in the chain. If there is only one user + window, then no change takes place. */ +extern void window_change_window_height (); + +/* Adjust the pagetop of WINDOW such that the cursor point will be visible. */ +extern void window_adjust_pagetop (); + +/* Tile all of the windows currently displayed in the global variable + WINDOWS. If argument DO_INTERNALS is non-zero, tile windows displaying + internal nodes as well. */ +#define DONT_TILE_INTERNALS 0 +#define TILE_INTERNALS 1 +extern void window_tile_windows (); + +/* Toggle the state of line wrapping in WINDOW. This can do a bit of fancy + redisplay. */ +extern void window_toggle_wrap (); + +/* For every window in CHAIN, set the flags member to have FLAG set. */ +extern void window_mark_chain (); + +/* For every window in CHAIN, clear the flags member of FLAG. */ +extern void window_unmark_chain (); + +/* Make WINDOW start displaying at PERCENT percentage of its node. */ +extern void window_goto_percentage (); + +/* Build a new node which has FORMAT printed with ARG1 and ARG2 as the + contents. */ +extern NODE *build_message_node (); + +/* Useful functions can be called from outside of window.c. */ +extern void initialize_message_buffer (); + +/* Print FORMAT with ARG1,2 to the end of the current message buffer. */ +extern void printf_to_message_buffer (); + +/* Convert the contents of the message buffer to a node. */ +extern NODE *message_buffer_to_node (); + +/* Return the length of the most recently printed line in message buffer. */ +extern int message_buffer_length_this_line (); + +/* Pad STRING to COUNT characters by inserting blanks. */ +extern int pad_to (); + +/* Make a message appear in the echo area, built from FORMAT, ARG1 and ARG2. + The arguments are treated similar to printf () arguments, but not all of + printf () hair is present. The message appears immediately. If there was + already a message appearing in the echo area, it is removed. */ +extern void window_message_in_echo_area (); + +/* Place a temporary message in the echo area built from FORMAT, ARG1 + and ARG2. The message appears immediately, but does not destroy + any existing message. A future call to unmessage_in_echo_area () + restores the old contents. */ +extern void message_in_echo_area (); +extern void unmessage_in_echo_area (); + +/* Clear the echo area, removing any message that is already present. + The echo area is cleared immediately. */ +extern void window_clear_echo_area (); + +/* Quickly guess the approximate number of lines to that NODE would + take to display. This really only counts carriage returns. */ +extern int window_physical_lines (); + +/* Calculate a list of line starts for the node belonging to WINDOW. The line + starts are pointers to the actual text within WINDOW->NODE. */ +extern void calculate_line_starts (); + +/* Given WINDOW, recalculate the line starts for the node it displays. */ +extern void recalculate_line_starts (); + +/* Return the number of characters it takes to display CHARACTER on the + screen at HPOS. */ +extern int character_width (); + +/* Return the number of characters it takes to display STRING on the + screen at HPOS. */ +extern int string_width (); + +/* Return the index of the line containing point. */ +extern int window_line_of_point (); + +/* Get and return the goal column for this window. */ +extern int window_get_goal_column (); + +/* Get and return the printed column offset of the cursor in this window. */ +extern int window_get_cursor_column (); + +/* Get and Set the node, pagetop, and point of WINDOW. */ +extern void window_get_state (), window_set_state (); + +/* Count the number of characters in LINE that precede the printed column + offset of GOAL. */ +extern int window_chars_to_goal (); + +#endif /* !_WINDOW_H_ */ diff --git a/gnu/usr.bin/texinfo/info/xmalloc.c b/gnu/usr.bin/texinfo/info/xmalloc.c new file mode 100644 index 0000000..6ebb84c --- /dev/null +++ b/gnu/usr.bin/texinfo/info/xmalloc.c @@ -0,0 +1,78 @@ +/* xmalloc.c -- safe versions of malloc and realloc */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + This file has appeared in prior works by the Free Software Foundation; + thus it carries copyright dates from 1988 through 1993. + + Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#if !defined (ALREADY_HAVE_XMALLOC) +#include <stdio.h> + +static void memory_error_and_abort (); + +/* **************************************************************** */ +/* */ +/* Memory Allocation and Deallocation. */ +/* */ +/* **************************************************************** */ + +/* Return a pointer to free()able block of memory large enough + to hold BYTES number of bytes. If the memory cannot be allocated, + print an error message and abort. */ +void * +xmalloc (bytes) + int bytes; +{ + void *temp = (void *)malloc (bytes); + + if (!temp) + memory_error_and_abort ("xmalloc"); + return (temp); +} + +void * +xrealloc (pointer, bytes) + void *pointer; + int bytes; +{ + void *temp; + + if (!pointer) + temp = (void *)malloc (bytes); + else + temp = (void *)realloc (pointer, bytes); + + if (!temp) + memory_error_and_abort ("xrealloc"); + + return (temp); +} + +static void +memory_error_and_abort (fname) + char *fname; +{ + fprintf (stderr, "%s: Out of virtual memory!\n", fname); + abort (); +} +#endif /* !ALREADY_HAVE_XMALLOC */ diff --git a/gnu/usr.bin/texinfo/makedoc/Makefile b/gnu/usr.bin/texinfo/makedoc/Makefile new file mode 100644 index 0000000..528e439 --- /dev/null +++ b/gnu/usr.bin/texinfo/makedoc/Makefile @@ -0,0 +1,20 @@ +# +# Bmakefile for GNU info +# +# $id$ +# + +PROG= makedoc + +SRCS+= makedoc.c xmalloc.c + +CFLAGS+= -I${.CURDIR}/../info -I${.CURDIR} +CFLAGS+= -DNAMED_FUNCTIONS=1 -DSTDC_HEADERS=1 +CFLAGS+= -DHAVE_UNISTD_H=1 -DHAVE_STRING_H=1 -DHAVE_VARARGS_H=1 +CFLAGS+= -DHAVE_SYS_FCNTL_H=1 -DHAVE_SETVBUF=1 -DHAVE_GETCWD=1 -DHAVE_BZERO=1 +CFLAGS+= -DHAVE_RINDEX=1 -DHAVE_VFPRINTF=1 -DHAVE_VSPRINTF=1 +CFLAGS+= -DHAVE_SYS_TIME_H=1 -DDEFAULT_INFOPATH='"${INFODIR}"' + +.include "../../Makefile.inc" +.include <bsd.prog.mk> + diff --git a/gnu/usr.bin/texinfo/makedoc/makedoc.c b/gnu/usr.bin/texinfo/makedoc/makedoc.c new file mode 100644 index 0000000..68b2199 --- /dev/null +++ b/gnu/usr.bin/texinfo/makedoc/makedoc.c @@ -0,0 +1,477 @@ +/* makedoc.c -- Make DOC.C and FUNS.H from input files. */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + Copyright (C) 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +/* This program grovels the contents of the source files passed as arguments + and writes out a file of function pointers and documentation strings, and + a header file which describes the contents. This only does the functions + declared with DECLARE_INFO_COMMAND. */ + +#include <stdio.h> +#include <ctype.h> +#include <sys/types.h> +#include <sys/file.h> +#include <sys/stat.h> +#include "general.h" + +#if !defined (O_RDONLY) +#if defined (HAVE_SYS_FCNTL_H) +#include <sys/fcntl.h> +#else /* !HAVE_SYS_FCNTL_H */ +#include <fcntl.h> +#endif /* !HAVE_SYS_FCNTL_H */ +#endif /* !O_RDONLY */ + +extern void *xmalloc (), *xrealloc (); +static void fatal_file_error (); + +/* Name of the header file which receives the declarations of functions. */ +static char *funs_filename = "funs.h"; + +/* Name of the documentation to function pointer file. */ +static char *doc_filename = "doc.c"; + +static char *doc_header[] = { + "/* doc.c -- Generated structure containing function names and doc strings.", + "", + " This file was automatically made from various source files with the", + " command \"%s\". DO NOT EDIT THIS FILE, only \"%s.c\".", + (char *)NULL +}; + +static char *doc_header_1[] = { + " An entry in the array FUNCTION_DOC_ARRAY is made for each command", + " found in the above files; each entry consists of a function pointer,", +#if defined (NAMED_FUNCTIONS) + " a string which is the user-visible name of the function,", +#endif /* NAMED_FUNCTIONS */ + " and a string which documents its purpose. */", + "", + "#include \"doc.h\"", + "#include \"funs.h\"", + "", + "FUNCTION_DOC function_doc_array[] = {", + "", + (char *)NULL +}; + +/* How to remember the locations of the functions found so that Emacs + can use the information in a tag table. */ +typedef struct { + char *name; /* Name of the tag. */ + int line; /* Line number at which it appears. */ + long char_offset; /* Character offset at which it appears. */ +} EMACS_TAG; + +typedef struct { + char *filename; /* Name of the file containing entries. */ + long entrylen; /* Total number of characters in tag block. */ + EMACS_TAG **entries; /* Entries found in FILENAME. */ + int entries_index; + int entries_slots; +} EMACS_TAG_BLOCK; + +EMACS_TAG_BLOCK **emacs_tags = (EMACS_TAG_BLOCK **)NULL; +int emacs_tags_index = 0; +int emacs_tags_slots = 0; + +#define DECLARATION_STRING "\nDECLARE_INFO_COMMAND" + +static void process_one_file (); +static void maybe_dump_tags (); +static FILE *must_fopen (); + +int +main (argc, argv) + int argc; + char **argv; +{ + register int i; + int tags_only = 0; + FILE *funs_stream, *doc_stream; + + for (i = 1; i < argc; i++) + if (strcmp (argv[i], "-tags") == 0) + { + tags_only++; + break; + } + + if (tags_only) + { + funs_filename = "/dev/null"; + doc_filename = "/dev/null"; + } + + funs_stream = must_fopen (funs_filename, "w"); + doc_stream = must_fopen (doc_filename, "w"); + + fprintf (funs_stream, + "/* %s -- Generated declarations for Info commands. */\n", + funs_filename); + + for (i = 0; doc_header[i]; i++) + { + fprintf (doc_stream, doc_header[i], argv[0], argv[0]); + fprintf (doc_stream, "\n"); + } + + fprintf (doc_stream, + " Source files groveled to make this file include:\n\n"); + + for (i = 1; i < argc; i++) + fprintf (doc_stream, "\t%s\n", argv[i]); + + fprintf (doc_stream, "\n"); + + for (i = 0; doc_header_1[i]; i++) + fprintf (doc_stream, "%s\n", doc_header_1[i]); + + + for (i = 1; i < argc; i++) + { + char *curfile; + curfile = argv[i]; + + if (*curfile == '-') + continue; + + fprintf (doc_stream, "/* Commands found in \"%s\". */\n", curfile); + fprintf (funs_stream, "\n/* Functions declared in \"%s\". */\n", + curfile); + + process_one_file (curfile, doc_stream, funs_stream); + } + + fprintf (doc_stream, + " { (VFunction *)NULL, (char *)NULL, (char *)NULL }\n};\n"); + + fclose (funs_stream); + fclose (doc_stream); + + if (tags_only) + maybe_dump_tags (stdout); + exit (0); +} + +/* Dumping out the contents of an Emacs tags table. */ +static void +maybe_dump_tags (stream) + FILE *stream; +{ + register int i; + + /* Print out the information for each block. */ + for (i = 0; i < emacs_tags_index; i++) + { + register int j; + register EMACS_TAG_BLOCK *block; + register EMACS_TAG *etag; + long block_len; + + block_len = 0; + block = emacs_tags[i]; + + /* Calculate the length of the dumped block first. */ + for (j = 0; j < block->entries_index; j++) + { + char digits[30]; + etag = block->entries[j]; + block_len += 3 + strlen (etag->name); + sprintf (digits, "%d,%d", etag->line, etag->char_offset); + block_len += strlen (digits); + } + + /* Print out the defining line. */ + fprintf (stream, "\f\n%s,%d\n", block->filename, block_len); + + /* Print out the individual tags. */ + for (j = 0; j < block->entries_index; j++) + { + etag = block->entries[j]; + + fprintf (stream, "%s,\177%d,%d\n", + etag->name, etag->line, etag->char_offset); + } + } +} + +/* Keeping track of names, line numbers and character offsets of functions + found in source files. */ +static EMACS_TAG_BLOCK * +make_emacs_tag_block (filename) + char *filename; +{ + EMACS_TAG_BLOCK *block; + + block = (EMACS_TAG_BLOCK *)xmalloc (sizeof (EMACS_TAG_BLOCK)); + block->filename = savestring (filename); + block->entrylen = 0; + block->entries = (EMACS_TAG **)NULL; + block->entries_index = 0; + block->entries_slots = 0; + return (block); +} + +static void +add_tag_to_block (block, name, line, char_offset) + EMACS_TAG_BLOCK *block; + char *name; + int line; + long char_offset; +{ + EMACS_TAG *tag; + + tag = (EMACS_TAG *)xmalloc (sizeof (EMACS_TAG)); + tag->name = name; + tag->line = line; + tag->char_offset = char_offset; + add_pointer_to_array (tag, block->entries_index, block->entries, + block->entries_slots, 50, EMACS_TAG *); +} + +/* Read the file represented by FILENAME into core, and search it for Info + function declarations. Output the declarations in various forms to the + DOC_STREAM and FUNS_STREAM. */ +static void +process_one_file (filename, doc_stream, funs_stream) + char *filename; + FILE *doc_stream, *funs_stream; +{ + int descriptor, decl_len; + char *buffer, *decl_str; + struct stat finfo; + long offset; + EMACS_TAG_BLOCK *block; + + if (stat (filename, &finfo) == -1) + fatal_file_error (filename); + + descriptor = open (filename, O_RDONLY, 0666); + + if (descriptor == -1) + fatal_file_error (filename); + + buffer = (char *)xmalloc (1 + finfo.st_size); + read (descriptor, buffer, finfo.st_size); + close (descriptor); + + offset = 0; + decl_str = DECLARATION_STRING; + decl_len = strlen (decl_str); + + block = make_emacs_tag_block (filename); + + while (1) + { + long point = 0; + long line_start = 0; + int line_number = 0; + + char *func, *doc; +#if defined (NAMED_FUNCTIONS) + char *func_name; +#endif /* NAMED_FUNCTIONS */ + + for (; offset < (finfo.st_size - decl_len); offset++) + { + if (buffer[offset] == '\n') + { + line_number++; + line_start = offset + 1; + } + + if (strncmp (buffer + offset, decl_str, decl_len) == 0) + { + offset += decl_len; + point = offset; + break; + } + } + + if (!point) + break; + + /* Skip forward until we find the open paren. */ + while (point < finfo.st_size) + { + if (buffer[point] == '\n') + { + line_number++; + line_start = point + 1; + } + else if (buffer[point] == '(') + break; + + point++; + } + + while (point++ < finfo.st_size) + { + if (!whitespace_or_newline (buffer[point])) + break; + else if (buffer[point] == '\n') + { + line_number++; + line_start = point + 1; + } + } + + if (point >= finfo.st_size) + break; + + /* Now looking at name of function. Get it. */ + for (offset = point; buffer[offset] != ','; offset++); + func = (char *)xmalloc (1 + (offset - point)); + strncpy (func, buffer + point, offset - point); + func[offset - point] = '\0'; + + /* Remember this tag in the current block. */ + { + char *tag_name; + + tag_name = (char *)xmalloc (1 + (offset - line_start)); + strncpy (tag_name, buffer + line_start, offset - line_start); + tag_name[offset - line_start] = '\0'; + add_tag_to_block (block, tag_name, line_number, point); + } + +#if defined (NAMED_FUNCTIONS) + /* Generate the user-visible function name from the function's name. */ + { + register int i; + char *name_start; + + name_start = func; + + if (strncmp (name_start, "info_", 5) == 0) + name_start += 5; + + func_name = savestring (name_start); + + /* Fix up "ea" commands. */ + if (strncmp (func_name, "ea_", 3) == 0) + { + char *temp_func_name; + + temp_func_name = (char *)xmalloc (10 + strlen (func_name)); + strcpy (temp_func_name, "echo_area_"); + strcat (temp_func_name, func_name + 3); + free (func_name); + func_name = temp_func_name; + } + + for (i = 0; func_name[i]; i++) + if (func_name[i] == '_') + func_name[i] = '-'; + } +#endif /* NAMED_FUNCTIONS */ + + /* Find doc string. */ + point = offset + 1; + + while (point < finfo.st_size) + { + if (buffer[point] == '\n') + { + line_number++; + line_start = point + 1; + } + + if (buffer[point] == '"') + break; + else + point++; + } + + offset = point + 1; + + while (offset < finfo.st_size) + { + if (buffer[offset] == '\n') + { + line_number++; + line_start = offset + 1; + } + + if (buffer[offset] == '\\') + offset += 2; + else if (buffer[offset] == '"') + break; + else + offset++; + } + + offset++; + if (offset >= finfo.st_size) + break; + + doc = (char *)xmalloc (1 + (offset - point)); + strncpy (doc, buffer + point, offset - point); + doc[offset - point] = '\0'; + +#if defined (NAMED_FUNCTIONS) + fprintf (doc_stream, " { %s, \"%s\", %s },\n", func, func_name, doc); + free (func_name); +#else /* !NAMED_FUNCTIONS */ + fprintf (doc_stream, " { %s, %s },\n", func, doc); +#endif /* !NAMED_FUNCTIONS */ + + fprintf (funs_stream, "extern void %s ();\n", func); + free (func); + free (doc); + } + free (buffer); + + /* If we created any tags, remember this file on our global list. Otherwise, + free the memory already allocated to it. */ + if (block->entries) + add_pointer_to_array (block, emacs_tags_index, emacs_tags, + emacs_tags_slots, 10, EMACS_TAG_BLOCK *); + else + { + free (block->filename); + free (block); + } +} + +static void +fatal_file_error (filename) + char *filename; +{ + fprintf (stderr, "Couldn't manipulate the file %s.\n", filename); + exit (2); +} + +static FILE * +must_fopen (filename, mode) + char *filename, *mode; +{ + FILE *stream; + + stream = fopen (filename, mode); + if (!stream) + fatal_file_error (filename); + + return (stream); +} + diff --git a/gnu/usr.bin/texinfo/makedoc/xmalloc.c b/gnu/usr.bin/texinfo/makedoc/xmalloc.c new file mode 100644 index 0000000..6ebb84c --- /dev/null +++ b/gnu/usr.bin/texinfo/makedoc/xmalloc.c @@ -0,0 +1,78 @@ +/* xmalloc.c -- safe versions of malloc and realloc */ + +/* This file is part of GNU Info, a program for reading online documentation + stored in Info format. + + This file has appeared in prior works by the Free Software Foundation; + thus it carries copyright dates from 1988 through 1993. + + Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993 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. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#if !defined (ALREADY_HAVE_XMALLOC) +#include <stdio.h> + +static void memory_error_and_abort (); + +/* **************************************************************** */ +/* */ +/* Memory Allocation and Deallocation. */ +/* */ +/* **************************************************************** */ + +/* Return a pointer to free()able block of memory large enough + to hold BYTES number of bytes. If the memory cannot be allocated, + print an error message and abort. */ +void * +xmalloc (bytes) + int bytes; +{ + void *temp = (void *)malloc (bytes); + + if (!temp) + memory_error_and_abort ("xmalloc"); + return (temp); +} + +void * +xrealloc (pointer, bytes) + void *pointer; + int bytes; +{ + void *temp; + + if (!pointer) + temp = (void *)malloc (bytes); + else + temp = (void *)realloc (pointer, bytes); + + if (!temp) + memory_error_and_abort ("xrealloc"); + + return (temp); +} + +static void +memory_error_and_abort (fname) + char *fname; +{ + fprintf (stderr, "%s: Out of virtual memory!\n", fname); + abort (); +} +#endif /* !ALREADY_HAVE_XMALLOC */ diff --git a/gnu/usr.bin/texinfo/makeinfo/Makefile b/gnu/usr.bin/texinfo/makeinfo/Makefile new file mode 100644 index 0000000..0a42b86 --- /dev/null +++ b/gnu/usr.bin/texinfo/makeinfo/Makefile @@ -0,0 +1,21 @@ +# +# Bmakefile for GNU info +# +# $id$ +# + +PROG= makeinfo + +SRCS+= makeinfo.c getopt1.c getopt.c +.PATH: ${.CURDIR}/../info + +CFLAGS+= -I${.CURDIR}/../info -I${.CURDIR} +CFLAGS+= -DNAMED_FUNCTIONS=1 -DSTDC_HEADERS=1 +CFLAGS+= -DHAVE_UNISTD_H=1 -DHAVE_STRING_H=1 -DHAVE_VARARGS_H=1 +CFLAGS+= -DHAVE_SYS_FCNTL_H=1 -DHAVE_SETVBUF=1 -DHAVE_GETCWD=1 -DHAVE_BZERO=1 +CFLAGS+= -DHAVE_RINDEX=1 -DHAVE_VFPRINTF=1 -DHAVE_VSPRINTF=1 +CFLAGS+= -DHAVE_SYS_TIME_H=1 -DDEFAULT_INFOPATH='"${INFODIR}"' + +.include "../../Makefile.inc" +.include <bsd.prog.mk> + diff --git a/gnu/usr.bin/texinfo/makeinfo/makeinfo.c b/gnu/usr.bin/texinfo/makeinfo/makeinfo.c new file mode 100644 index 0000000..6b810b9 --- /dev/null +++ b/gnu/usr.bin/texinfo/makeinfo/makeinfo.c @@ -0,0 +1,7549 @@ +/* Makeinfo -- convert texinfo format files into info files. + + Copyright (C) 1987, 1992, 1993 Free Software Foundation, Inc. + + This file is part of GNU Info. + + Makeinfo is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY. No author or distributor accepts + responsibility to anyone for the consequences of using it or for + whether it serves any particular purpose or works at all, unless he + says so in writing. Refer to the GNU Emacs General Public License + for full details. + + Everyone is granted permission to copy, modify and redistribute + Makeinfo, but only under the conditions described in the GNU Emacs + General Public License. A copy of this license is supposed to + have been given to you along with GNU Emacs so you can know your + rights and responsibilities. It should be in a file named COPYING. + Among other things, the copyright notice and this notice must be + preserved on all copies. */ + +/* This is Makeinfo version 1.55. If you change the version number of + Makeinfo, please change it here and at the lines reading: + + int major_version = 1; + int minor_version = 55; + + in the code below. + + Makeinfo is authored by Brian Fox (bfox@ai.mit.edu). */ + +/* You can change some of the behaviour of Makeinfo by changing the + following defines: */ + +/* Define INDENT_PARAGRAPHS_IN_TABLE if you want the paragraphs which + appear within an @table, @ftable, or @itemize environment to have + standard paragraph indentation. Without this, such paragraphs have + no starting indentation. */ +/* #define INDENT_PARAGRAPHS_IN_TABLE */ + +/* Define DEFAULT_INDENTATION_INCREMENT as an integer which is the amount + that @example should increase indentation by. This incremement is used + for all insertions which indent the enclosed text. */ +#define DEFAULT_INDENTATION_INCREMENT 5 + +/* Define PARAGRAPH_START_INDENT to be the amount of indentation that + the first lines of paragraphs receive by default, where no other + value has been specified. Users can change this value on the command + line, with the +paragraph-indent option, or within the texinfo file, + with the @paragraphindent command. */ +#define PARAGRAPH_START_INDENT 3 + +/* Define DEFAULT_PARAGRAPH_SPACING as the number of blank lines that you + wish to appear between paragraphs. A value of 1 creates a single blank + line between paragraphs. Paragraphs are defined by 2 or more consecutive + newlines in the input file (i.e., one or more blank lines). */ +#define DEFAULT_PARAGRAPH_SPACING 1 + +/* **************************************************************** */ +/* */ +/* Include File Declarations */ +/* */ +/* **************************************************************** */ + +/* Indent #pragma so that older Cpp's don't try to parse it. */ +#if defined (_AIX) + # pragma alloca +#endif /* _AIX */ + +#include <stdio.h> +#include <sys/types.h> +#include <ctype.h> +#include <sys/stat.h> +#include <ctype.h> +#include <pwd.h> +#include <errno.h> +#if defined (HAVE_VARARGS_H) +#include <varargs.h> +#endif /* HAVE_VARARGS_H */ +#include "getopt.h" + +#if defined (VMS) +#include <perror.h> +#endif + +#if defined (HAVE_STRING_H) +#include <string.h> +#else +#include <strings.h> +#endif /* !HAVE_STRING_H */ + +#if defined (TM_IN_SYS_TIME) +#include <sys/time.h> +#else +#include <time.h> +#endif /* !TM_IN_SYS_TIME */ + +#if defined (HAVE_SYS_FCNTL_H) +#include <sys/fcntl.h> +#else +#include <fcntl.h> +#endif /* !HAVE_SYS_FCNTL_H */ + +#include <sys/file.h> + +#if defined (__GNUC__) +#define alloca __builtin_alloca +#else +#if defined(HAVE_ALLOCA_H) +#include <alloca.h> +#else /* !HAVE_ALLOCA_H */ +#if !defined (_AIX) +extern char *alloca (); +#endif /* !_AIX */ +#endif /* !HAVE_ALLOCA_H */ +#endif /* !__GNUC__ */ + +void *xmalloc (), *xrealloc (); +static void isolate_nodename (); + +/* Non-zero means that we are currently hacking the insides of an + insertion which would use a fixed width font. */ +static int in_fixed_width_font = 0; + +/* Non-zero means that start_paragraph () MUST be called before we pay + any attention to close_paragraph () calls. */ +int must_start_paragraph = 0; + +/* Some systems don't declare this function in pwd.h. */ +struct passwd *getpwnam (); + + +/* **************************************************************** */ +/* */ +/* Global Defines */ +/* */ +/* **************************************************************** */ + +/* Error levels */ +#define NO_ERROR 0 +#define SYNTAX 2 +#define FATAL 4 + +/* How to allocate permanent storage for STRING. */ +#define savestring(x) \ + ((char *)strcpy ((char *)xmalloc (1 + ((x) ? strlen (x) : 0)), \ + (x) ? (x) : "")) + +/* C's standard macros don't check to make sure that the characters being + changed are within range. So I have to check explicitly. */ + +/* GNU Library doesn't have toupper(). Until GNU gets this fixed, I will + have to do it. */ +#ifndef toupper +#define toupper(c) ((c) - 32) +#endif + +#define coerce_to_upper(c) ((islower(c) ? toupper(c) : (c))) +#define coerce_to_lower(c) ((isupper(c) ? tolower(c) : (c))) + +#define control_character_bit 0x40 /* %01000000, must be off. */ +#define meta_character_bit 0x080/* %10000000, must be on. */ +#define CTL(c) ((c) & (~control_character_bit)) +#define UNCTL(c) coerce_to_upper(((c)|control_character_bit)) +#define META(c) ((c) | (meta_character_bit)) +#define UNMETA(c) ((c) & (~meta_character_bit)) + +#define whitespace(c) (((c) == '\t') || ((c) == ' ')) +#define sentence_ender(c) ((c) == '.' || (c) == '?' || (c) == '!') +#define cr_or_whitespace(c) (((c) == '\t') || ((c) == ' ') || ((c) == '\n')) + +#ifndef isletter +#define isletter(c) (((c) >= 'A' && (c) <= 'Z') || ((c) >= 'a' && (c) <= 'z')) +#endif + +#ifndef isupper +#define isupper(c) ((c) >= 'A' && (c) <= 'Z') +#endif + +#ifndef isdigit +#define isdigit(c) ((c) >= '0' && (c) <= '9') +#endif + +#ifndef digit_value +#define digit_value(c) ((c) - '0') +#endif + +#define member(c, s) (strchr (s, c) != NULL) + +#define COMMAND_PREFIX '@' + +/* Stuff for splitting large files. */ +#define SPLIT_SIZE_THRESHOLD 70000 /* What's good enough for Stallman... */ +#define DEFAULT_SPLIT_SIZE 50000 /* Is probably good enough for me. */ +int splitting = 1; /* Always true for now. */ + +typedef int FUNCTION (); /* So I can say FUNCTION *foo; */ + + +/* **************************************************************** */ +/* */ +/* Global Variables */ +/* */ +/* **************************************************************** */ + +/* Global pointer to argv[0]. */ +char *progname; + +/* The current input file state. */ +char *input_filename; +char *input_text; +int size_of_input_text; +int input_text_offset; +int line_number; + +#define curchar() input_text[input_text_offset] + +#define command_char(c) ((!whitespace(c)) && \ + ((c) != '\n') && \ + ((c) != '{') && \ + ((c) != '}') && \ + ((c) != '=')) + +#define skip_whitespace() while (input_text_offset != size_of_input_text \ + && whitespace(curchar()))\ + input_text_offset++ + +/* Return non-zero if STRING is the text at input_text + input_text_offset, + else zero. */ +#define looking_at(string) \ + (strncmp (input_text + input_text_offset, string, strlen (string)) == 0) + +/* And writing to the output. */ + +/* The output file name. */ +char *output_filename = (char *)NULL; +char *pretty_output_filename; + +/* Name of the output file that the user elected to pass on the command line. + Such a name overrides any name found with the @setfilename command. */ +char *command_output_filename = (char *)NULL; + +/* A colon separated list of directories to search for files included + with @include. This can be controlled with the `-I' option to makeinfo. */ +char *include_files_path = (char *)NULL; + +/* Current output stream. */ +FILE *output_stream; + +/* Position in the output file. */ +int output_position; + +/* Output paragraph buffer. */ +unsigned char *output_paragraph; + +/* Offset into OUTPUT_PARAGRAPH. */ +int output_paragraph_offset; + +/* The output paragraph "cursor" horizontal position. */ +int output_column = 0; + +/* Non-zero means output_paragraph contains text. */ +int paragraph_is_open = 0; + +#define INITIAL_PARAGRAPH_SPACE 5000 +int paragraph_buffer_len = INITIAL_PARAGRAPH_SPACE; + +/* Filling.. */ +/* Non-zero indicates that filling will take place on long lines. */ +int filling_enabled = 1; + +/* Non-zero means that words are not to be split, even in long lines. This + gets changed for cm_w (). */ +int non_splitting_words = 0; + +/* Non-zero indicates that filling a line also indents the new line. */ +int indented_fill = 0; + +/* The column at which long lines are broken. */ +int fill_column = 72; + +/* The amount of indentation to apply at the start of each line. */ +int current_indent = 0; + +/* The amount of indentation to add at the starts of paragraphs. + 0 means don't change existing indentation at paragraph starts. + > 0 is amount to indent new paragraphs by. + < 0 means indent to column zero by removing indentation if necessary. + + This is normally zero, but some people prefer paragraph starts to be + somewhat more indented than paragraph bodies. A pretty value for + this is 3. */ +int paragraph_start_indent = PARAGRAPH_START_INDENT; + +/* Non-zero means that the use of paragraph_start_indent is inhibited. + @example uses this to line up the left columns of the example text. + A negative value for this variable is incremented each time it is used. + @noindent uses this to inhibit indentation for a single paragraph. */ +int inhibit_paragraph_indentation = 0; + +/* Indentation that is pending insertion. We have this for hacking lines + which look blank, but contain whitespace. We want to treat those as + blank lines. */ +int pending_indent = 0; + +/* The amount that indentation increases/decreases by. */ +int default_indentation_increment = DEFAULT_INDENTATION_INCREMENT; + +/* Non-zero indicates that indentation is temporarily turned off. */ +int no_indent = 1; + +/* Non-zero means forcing output text to be flushright. */ +int force_flush_right = 0; + +/* Non-zero means that the footnote style for this document was set on + the command line, which overrides any other settings. */ +int footnote_style_preset = 0; + +/* Non-zero means that we automatically number footnotes that have no + specified marker. */ +int number_footnotes = 1; + +/* The current footnote number in this node. Each time a new node is + started this is reset to 1. */ +int current_footnote_number = 1; + +/* Command name in the process of being hacked. */ +char *command; + +/* The index in our internal command table of the currently + executing command. */ +int command_index; + +/* A stack of file information records. If a new file is read in with + "@input", we remember the old input file state on this stack. */ +typedef struct fstack +{ + struct fstack *next; + char *filename; + char *text; + int size; + int offset; + int line_number; +} FSTACK; + +FSTACK *filestack = (FSTACK *) NULL; + +/* Stuff for nodes. */ +/* The current nodes node name. */ +char *current_node = (char *)NULL; + +/* The current nodes section level. */ +int current_section = 0; + +/* The filename of the current input file. This is never freed. */ +char *node_filename = (char *)NULL; + +/* What we remember for each node. */ +typedef struct tentry +{ + struct tentry *next_ent; + char *node; /* name of this node. */ + char *prev; /* name of "Prev:" for this node. */ + char *next; /* name of "Next:" for this node. */ + char *up; /* name of "Up:" for this node. */ + int position; /* output file position of this node. */ + int line_no; /* defining line in source file. */ + char *filename; /* The file that this node was found in. */ + int touched; /* non-zero means this node has been referenced. */ + int flags; /* Room for growth. Right now, contains 1 bit. */ +} TAG_ENTRY; + +/* If node-a has a "Next" for node-b, but node-b has no "Prev" for node-a, + we turn on this flag bit in node-b's tag entry. This means that when + it is time to validate node-b, we don't report an additional error + if there was no "Prev" field. */ +#define PREV_ERROR 0x1 +#define NEXT_ERROR 0x2 +#define UP_ERROR 0x4 +#define NO_WARN 0x8 +#define IS_TOP 0x10 + +TAG_ENTRY *tag_table = (TAG_ENTRY *) NULL; + +#define HAVE_MACROS +#if defined (HAVE_MACROS) +/* Macro definitions for user-defined commands. */ +typedef struct { + char *name; /* Name of the macro. */ + char *definition; /* Definition text. */ + char *filename; /* File where this macro is defined. */ + int lineno; /* Line number within FILENAME. */ +} MACRO_DEF; + +void add_macro (), execute_macro (); +MACRO_DEF *find_macro (), *delete_macro (); +#endif /* HAVE_MACROS */ + +/* Menu reference, *note reference, and validation hacking. */ + +/* The various references that we know about. */ +enum reftype +{ + menu_reference, followed_reference +}; + +/* A structure to remember references with. A reference to a node is + either an entry in a menu, or a cross-reference made with [px]ref. */ +typedef struct node_ref +{ + struct node_ref *next; + char *node; /* Name of node referred to. */ + char *containing_node; /* Name of node containing this reference. */ + int line_no; /* Line number where the reference occurs. */ + int section; /* Section level where the reference occurs. */ + char *filename; /* Name of file where the reference occurs. */ + enum reftype type; /* Type of reference, either menu or note. */ +} NODE_REF; + +/* The linked list of such structures. */ +NODE_REF *node_references = (NODE_REF *) NULL; + +/* Flag which tells us whether to examine menu lines or not. */ +int in_menu = 0; + +/* Flags controlling the operation of the program. */ + +/* Default is to notify users of bad choices. */ +int print_warnings = 1; + +/* Default is to check node references. */ +int validating = 1; + +/* Non-zero means do not output "Node: Foo" for node separations. */ +int no_headers = 0; + +/* Number of errors that we tolerate on a given fileset. */ +int max_error_level = 100; + +/* Maximum number of references to a single node before complaining. */ +int reference_warning_limit = 1000; + +/* Non-zero means print out information about what is going on when it + is going on. */ +int verbose_mode = 0; + +/* The list of commands that we hack in texinfo. Each one + has an associated function. When the command is encountered in the + text, the associated function is called with START as the argument. + If the function expects arguments in braces, it remembers itself on + the stack. When the corresponding close brace is encountered, the + function is called with END as the argument. */ + +#define START 0 +#define END 1 + +typedef struct brace_element +{ + struct brace_element *next; + FUNCTION *proc; + int pos, line; +} BRACE_ELEMENT; + +BRACE_ELEMENT *brace_stack = (BRACE_ELEMENT *) NULL; + +/* Forward declarations. */ + +int insert_self (), cm_ignore_line (); + +int + cm_tex (), cm_asterisk (), cm_dots (), cm_bullet (), cm_TeX (), + cm_copyright (), cm_code (), cm_samp (), cm_file (), cm_kbd (), + cm_key (), cm_ctrl (), cm_var (), cm_dfn (), cm_emph (), cm_strong (), + cm_cite (), cm_italic (), cm_bold (), cm_roman (), cm_title (), cm_w (), + cm_refill (), cm_titlefont (); + +int + cm_chapter (), cm_unnumbered (), cm_appendix (), cm_top (), + cm_section (), cm_unnumberedsec (), cm_appendixsec (), + cm_subsection (), cm_unnumberedsubsec (), cm_appendixsubsec (), + cm_subsubsection (), cm_unnumberedsubsubsec (), cm_appendixsubsubsec (), + cm_heading (), cm_chapheading (), cm_subheading (), cm_subsubheading (), + cm_majorheading (), cm_raisesections (), cm_lowersections (); + +/* All @defxxx commands map to cm_defun (). */ +int cm_defun (); + +int + cm_node (), cm_menu (), cm_xref (), cm_ftable (), cm_vtable (), cm_pxref (), + cm_inforef (), cm_quotation (), cm_display (), cm_itemize (), + cm_enumerate (), cm_table (), cm_itemx (), cm_noindent (), cm_setfilename (), + cm_br (), cm_sp (), cm_page (), cm_group (), cm_center (), cm_include (), + cm_bye (), cm_item (), cm_end (), cm_infoinclude (), cm_ifinfo (), + cm_kindex (), cm_cindex (), cm_findex (), cm_pindex (), cm_vindex (), + cm_tindex (), cm_asis (), cm_synindex (), cm_printindex (), cm_minus (), + cm_footnote (), cm_force_abbreviated_whitespace (), cm_example (), + cm_smallexample (), cm_lisp (), cm_format (), cm_exdent (), cm_defindex (), + cm_defcodeindex (), cm_sc (), cm_result (), cm_expansion (), cm_equiv (), + cm_print (), cm_error (), cm_point (), cm_today (), cm_flushleft (), + cm_flushright (), cm_smalllisp (), cm_finalout (), cm_math (), + cm_cartouche (), cm_ignore_sentence_ender (); + +/* Conditionals. */ +int cm_set (), cm_clear (), cm_ifset (), cm_ifclear (), cm_value (); + +#if defined (HAVE_MACROS) +/* Define a user-defined command which is simple substitution. */ +int cm_macro (), cm_unmacro (); +#endif /* HAVE_MACROS */ + +/* Options. */ +int cm_paragraphindent (), cm_footnotestyle (); + +/* Internals. */ +int do_nothing (), command_name_condition (); +int misplaced_brace (), cm_obsolete (); + +typedef struct +{ + char *name; + FUNCTION *proc; + int argument_in_braces; +} COMMAND; + +/* Stuff for defining commands on the fly. */ +COMMAND **user_command_array = (COMMAND **) NULL; +int user_command_array_len = 0; + +#define NO_BRACE_ARGS 0 +#define BRACE_ARGS 1 + +static COMMAND CommandTable[] = { + { "!", cm_ignore_sentence_ender, NO_BRACE_ARGS }, + { "'", insert_self, NO_BRACE_ARGS }, + { "*", cm_asterisk, NO_BRACE_ARGS }, + { ".", cm_ignore_sentence_ender, NO_BRACE_ARGS }, + { ":", cm_force_abbreviated_whitespace, NO_BRACE_ARGS }, + { "?", cm_ignore_sentence_ender, NO_BRACE_ARGS }, + { "|", do_nothing, NO_BRACE_ARGS }, + { "@", insert_self, NO_BRACE_ARGS }, + { " ", insert_self, NO_BRACE_ARGS }, + { "\n", insert_self, NO_BRACE_ARGS }, + { "TeX", cm_TeX, BRACE_ARGS }, + { "`", insert_self, NO_BRACE_ARGS }, + { "appendix", cm_appendix, NO_BRACE_ARGS }, + { "appendixsection", cm_appendixsec, NO_BRACE_ARGS }, + { "appendixsec", cm_appendixsec, NO_BRACE_ARGS }, + { "appendixsubsec", cm_appendixsubsec, NO_BRACE_ARGS }, + { "appendixsubsubsec", cm_appendixsubsubsec, NO_BRACE_ARGS }, + { "asis", cm_asis, BRACE_ARGS }, + { "b", cm_bold, BRACE_ARGS }, + { "br", cm_br, NO_BRACE_ARGS }, + { "bullet", cm_bullet, BRACE_ARGS }, + { "bye", cm_bye, NO_BRACE_ARGS }, + { "c", cm_ignore_line, NO_BRACE_ARGS }, + { "cartouche", cm_cartouche, NO_BRACE_ARGS }, + { "center", cm_center, NO_BRACE_ARGS }, + { "chapheading", cm_chapheading, NO_BRACE_ARGS }, + { "chapter", cm_chapter, NO_BRACE_ARGS }, + { "cindex", cm_cindex, NO_BRACE_ARGS }, + { "cite", cm_cite, BRACE_ARGS }, + { "clear", cm_clear, NO_BRACE_ARGS }, + { "code", cm_code, BRACE_ARGS }, + { "comment", cm_ignore_line, NO_BRACE_ARGS }, + { "contents", do_nothing, NO_BRACE_ARGS }, + { "copyright", cm_copyright, BRACE_ARGS }, + { "ctrl", cm_ctrl, BRACE_ARGS }, + { "defcodeindex", cm_defcodeindex, NO_BRACE_ARGS }, + { "defindex", cm_defindex, NO_BRACE_ARGS }, + { "dfn", cm_dfn, BRACE_ARGS }, + +/* The `def' commands. */ + { "deffn", cm_defun, NO_BRACE_ARGS }, + { "deffnx", cm_defun, NO_BRACE_ARGS }, + { "defun", cm_defun, NO_BRACE_ARGS }, + { "defunx", cm_defun, NO_BRACE_ARGS }, + { "defmac", cm_defun, NO_BRACE_ARGS }, + { "defmacx", cm_defun, NO_BRACE_ARGS }, + { "defspec", cm_defun, NO_BRACE_ARGS }, + { "defspecx", cm_defun, NO_BRACE_ARGS }, + { "defvr", cm_defun, NO_BRACE_ARGS }, + { "defvrx", cm_defun, NO_BRACE_ARGS }, + { "defvar", cm_defun, NO_BRACE_ARGS }, + { "defvarx", cm_defun, NO_BRACE_ARGS }, + { "defopt", cm_defun, NO_BRACE_ARGS }, + { "defoptx", cm_defun, NO_BRACE_ARGS }, + { "deftypefn", cm_defun, NO_BRACE_ARGS }, + { "deftypefnx", cm_defun, NO_BRACE_ARGS }, + { "deftypefun", cm_defun, NO_BRACE_ARGS }, + { "deftypefunx", cm_defun, NO_BRACE_ARGS }, + { "deftypevr", cm_defun, NO_BRACE_ARGS }, + { "deftypevrx", cm_defun, NO_BRACE_ARGS }, + { "deftypevar", cm_defun, NO_BRACE_ARGS }, + { "deftypevarx", cm_defun, NO_BRACE_ARGS }, + { "defcv", cm_defun, NO_BRACE_ARGS }, + { "defcvx", cm_defun, NO_BRACE_ARGS }, + { "defivar", cm_defun, NO_BRACE_ARGS }, + { "defivarx", cm_defun, NO_BRACE_ARGS }, + { "defop", cm_defun, NO_BRACE_ARGS }, + { "defopx", cm_defun, NO_BRACE_ARGS }, + { "defmethod", cm_defun, NO_BRACE_ARGS }, + { "defmethodx", cm_defun, NO_BRACE_ARGS }, + { "deftypemethod", cm_defun, NO_BRACE_ARGS }, + { "deftypemethodx", cm_defun, NO_BRACE_ARGS }, + { "deftp", cm_defun, NO_BRACE_ARGS }, + { "deftpx", cm_defun, NO_BRACE_ARGS }, +/* The end of the `def' commands. */ + + { "display", cm_display, NO_BRACE_ARGS }, + { "dots", cm_dots, BRACE_ARGS }, + { "dmn", do_nothing, BRACE_ARGS }, + { "emph", cm_emph, BRACE_ARGS }, + { "end", cm_end, NO_BRACE_ARGS }, + { "enumerate", cm_enumerate, NO_BRACE_ARGS }, + { "equiv", cm_equiv, BRACE_ARGS }, + { "error", cm_error, BRACE_ARGS }, + { "example", cm_example, NO_BRACE_ARGS }, + { "exdent", cm_exdent, NO_BRACE_ARGS }, + { "expansion", cm_expansion, BRACE_ARGS }, + { "file", cm_file, BRACE_ARGS }, + { "findex", cm_findex, NO_BRACE_ARGS }, + { "finalout", do_nothing, NO_BRACE_ARGS }, + { "flushleft", cm_flushleft, NO_BRACE_ARGS }, + { "flushright", cm_flushright, NO_BRACE_ARGS }, + { "format", cm_format, NO_BRACE_ARGS }, + { "ftable", cm_ftable, NO_BRACE_ARGS }, + { "group", cm_group, NO_BRACE_ARGS }, + { "heading", cm_heading, NO_BRACE_ARGS }, + { "headings", cm_ignore_line, NO_BRACE_ARGS }, + { "i", cm_italic, BRACE_ARGS }, + { "iappendix", cm_appendix, NO_BRACE_ARGS }, + { "iappendixsection", cm_appendixsec, NO_BRACE_ARGS }, + { "iappendixsec", cm_appendixsec, NO_BRACE_ARGS }, + { "iappendixsubsec", cm_appendixsubsec, NO_BRACE_ARGS }, + { "iappendixsubsubsec", cm_appendixsubsubsec, NO_BRACE_ARGS }, + { "ichapter", cm_chapter, NO_BRACE_ARGS }, + { "ifclear", cm_ifclear, NO_BRACE_ARGS }, + { "ifinfo", cm_ifinfo, NO_BRACE_ARGS }, + { "ifset", cm_ifset, NO_BRACE_ARGS }, + { "iftex", command_name_condition, NO_BRACE_ARGS }, + { "ignore", command_name_condition, NO_BRACE_ARGS }, + { "include", cm_include, NO_BRACE_ARGS }, + { "inforef", cm_inforef, BRACE_ARGS }, + { "input", cm_include, NO_BRACE_ARGS }, + { "isection", cm_section, NO_BRACE_ARGS }, + { "isubsection", cm_subsection, NO_BRACE_ARGS }, + { "isubsubsection", cm_subsubsection, NO_BRACE_ARGS }, + { "item", cm_item, NO_BRACE_ARGS }, + { "itemize", cm_itemize, NO_BRACE_ARGS }, + { "itemx", cm_itemx, NO_BRACE_ARGS }, + { "iunnumbered", cm_unnumbered, NO_BRACE_ARGS }, + { "iunnumberedsec", cm_unnumberedsec, NO_BRACE_ARGS }, + { "iunnumberedsubsec", cm_unnumberedsubsec, NO_BRACE_ARGS }, + { "iunnumberedsubsubsec", cm_unnumberedsubsubsec, NO_BRACE_ARGS }, + { "kbd", cm_kbd, BRACE_ARGS }, + { "key", cm_key, BRACE_ARGS }, + { "kindex", cm_kindex, NO_BRACE_ARGS }, + { "lowersections", cm_lowersections, NO_BRACE_ARGS }, + { "lisp", cm_lisp, NO_BRACE_ARGS }, + { "macro", cm_macro, NO_BRACE_ARGS }, + { "majorheading", cm_majorheading, NO_BRACE_ARGS }, + { "math", cm_math, BRACE_ARGS }, + { "menu", cm_menu, NO_BRACE_ARGS }, + { "minus", cm_minus, BRACE_ARGS }, + { "need", cm_ignore_line, NO_BRACE_ARGS }, + { "node", cm_node, NO_BRACE_ARGS }, + { "noindent", cm_noindent, NO_BRACE_ARGS }, + { "nwnode", cm_node, NO_BRACE_ARGS }, + { "overfullrule", cm_ignore_line, NO_BRACE_ARGS }, + { "page", do_nothing, NO_BRACE_ARGS }, + { "pindex", cm_pindex, NO_BRACE_ARGS }, + { "point", cm_point, BRACE_ARGS }, + { "print", cm_print, BRACE_ARGS }, + { "printindex", cm_printindex, NO_BRACE_ARGS }, + { "pxref", cm_pxref, BRACE_ARGS }, + { "quotation", cm_quotation, NO_BRACE_ARGS }, + { "r", cm_roman, BRACE_ARGS }, + { "raisesections", cm_raisesections, NO_BRACE_ARGS }, + { "ref", cm_xref, BRACE_ARGS }, + { "refill", cm_refill, NO_BRACE_ARGS }, + { "result", cm_result, BRACE_ARGS }, + { "samp", cm_samp, BRACE_ARGS }, + { "sc", cm_sc, BRACE_ARGS }, + { "section", cm_section, NO_BRACE_ARGS }, + { "set", cm_set, NO_BRACE_ARGS }, + { "setchapternewpage", cm_ignore_line, NO_BRACE_ARGS }, + { "setchapterstyle", cm_ignore_line, NO_BRACE_ARGS }, + { "setfilename", cm_setfilename, NO_BRACE_ARGS }, + { "settitle", cm_ignore_line, NO_BRACE_ARGS }, + { "shortcontents", do_nothing, NO_BRACE_ARGS }, + { "shorttitlepage", command_name_condition, NO_BRACE_ARGS }, + { "smallbook", cm_ignore_line, NO_BRACE_ARGS }, + { "smallexample", cm_smallexample, NO_BRACE_ARGS }, + { "smalllisp", cm_smalllisp, NO_BRACE_ARGS }, + { "sp", cm_sp, NO_BRACE_ARGS }, + { "strong", cm_strong, BRACE_ARGS }, + { "subheading", cm_subheading, NO_BRACE_ARGS }, + { "subsection", cm_subsection, NO_BRACE_ARGS }, + { "subsubheading", cm_subsubheading, NO_BRACE_ARGS }, + { "subsubsection", cm_subsubsection, NO_BRACE_ARGS }, + { "summarycontents", do_nothing, NO_BRACE_ARGS }, + { "syncodeindex", cm_synindex, NO_BRACE_ARGS }, + { "synindex", cm_synindex, NO_BRACE_ARGS }, + { "t", cm_title, BRACE_ARGS }, + { "table", cm_table, NO_BRACE_ARGS }, + { "tex", command_name_condition, NO_BRACE_ARGS }, + { "tindex", cm_tindex, NO_BRACE_ARGS }, + { "titlefont", cm_titlefont, BRACE_ARGS }, + { "titlepage", command_name_condition, NO_BRACE_ARGS }, + { "titlespec", command_name_condition, NO_BRACE_ARGS }, + { "today", cm_today, BRACE_ARGS }, + { "top", cm_top, NO_BRACE_ARGS }, + { "unmacro", cm_unmacro, NO_BRACE_ARGS }, + { "unnumbered", cm_unnumbered, NO_BRACE_ARGS }, + { "unnumberedsec", cm_unnumberedsec, NO_BRACE_ARGS }, + { "unnumberedsubsec", cm_unnumberedsubsec, NO_BRACE_ARGS }, + { "unnumberedsubsubsec", cm_unnumberedsubsubsec, NO_BRACE_ARGS }, + { "value", cm_value, BRACE_ARGS }, + { "var", cm_var, BRACE_ARGS }, + { "vindex", cm_vindex, NO_BRACE_ARGS }, + { "vtable", cm_vtable, NO_BRACE_ARGS }, + { "w", cm_w, BRACE_ARGS }, + { "xref", cm_xref, BRACE_ARGS }, + { "{", insert_self, NO_BRACE_ARGS }, + { "}", insert_self, NO_BRACE_ARGS }, + + /* Some obsoleted commands. */ + { "infotop", cm_obsolete, NO_BRACE_ARGS }, + { "infounnumbered", cm_obsolete, NO_BRACE_ARGS }, + { "infounnumberedsec", cm_obsolete, NO_BRACE_ARGS }, + { "infounnumberedsubsec", cm_obsolete, NO_BRACE_ARGS }, + { "infounnumberedsubsubsec", cm_obsolete, NO_BRACE_ARGS }, + { "infoappendix", cm_obsolete, NO_BRACE_ARGS }, + { "infoappendixsec", cm_obsolete, NO_BRACE_ARGS }, + { "infoappendixsubsec", cm_obsolete, NO_BRACE_ARGS }, + { "infoappendixsubsubsec", cm_obsolete, NO_BRACE_ARGS }, + { "infochapter", cm_obsolete, NO_BRACE_ARGS }, + { "infosection", cm_obsolete, NO_BRACE_ARGS }, + { "infosubsection", cm_obsolete, NO_BRACE_ARGS }, + { "infosubsubsection", cm_obsolete, NO_BRACE_ARGS }, + + /* Now @include does what this was supposed to. */ + { "infoinclude", cm_infoinclude, NO_BRACE_ARGS }, + { "footnote", cm_footnote, NO_BRACE_ARGS}, /* self-arg eater */ + { "footnotestyle", cm_footnotestyle, NO_BRACE_ARGS }, + { "paragraphindent", cm_paragraphindent, NO_BRACE_ARGS }, + + {(char *) NULL, (FUNCTION *) NULL}, NO_BRACE_ARGS}; + +int major_version = 1; +int minor_version = 55; + +struct option long_options[] = +{ + { "error-limit", 1, 0, 'e' }, /* formerly -el */ + { "fill-column", 1, 0, 'f' }, /* formerly -fc */ + { "footnote-style", 1, 0, 's' }, /* formerly -ft */ + { "no-headers", 0, &no_headers, 1 }, /* Do not output Node: foo */ + { "no-pointer-validate", 0, &validating, 0 }, /* formerly -nv */ + { "no-validate", 0, &validating, 0 }, /* formerly -nv */ + { "no-split", 0, &splitting, 0 }, /* formerly -ns */ + { "no-warn", 0, &print_warnings, 0 }, /* formerly -nw */ + { "number-footnotes", 0, &number_footnotes, 1 }, + { "no-number-footnotes", 0, &number_footnotes, 0 }, + { "output", 1, 0, 'o' }, + { "paragraph-indent", 1, 0, 'p' }, /* formerly -pi */ + { "reference-limit", 1, 0, 'r' }, /* formerly -rl */ + { "verbose", 0, &verbose_mode, 1 }, /* formerly -verbose */ + { "version", 0, 0, 'V' }, + {NULL, 0, NULL, 0} +}; + +/* Values for calling handle_variable_internal (). */ +#define SET 1 +#define CLEAR 2 +#define IFSET 3 +#define IFCLEAR 4 + +/* **************************************************************** */ +/* */ +/* Main () Start of code */ +/* */ +/* **************************************************************** */ + +/* For each file mentioned in the command line, process it, turning + texinfo commands into wonderfully formatted output text. */ +main (argc, argv) + int argc; + char **argv; +{ + extern int errors_printed; + char *filename_part (); + int c, ind; + + /* The name of this program is the last filename in argv[0]. */ + progname = filename_part (argv[0]); + + /* Parse argument flags from the input line. */ + while ((c = getopt_long + (argc, argv, "D:U:I:f:o:p:e:r:s:V", long_options, &ind)) + != EOF) + { + if (c == 0 && long_options[ind].flag == 0) + c = long_options[ind].val; + + switch (c) + { + /* User specified variable to set or clear? */ + case 'D': + case 'U': + handle_variable_internal ((c == 'D') ? SET : CLEAR, optarg); + break; + + /* User specified include file path? */ + case 'I': + if (!include_files_path) + include_files_path = savestring ("."); + + include_files_path = (char *) + xrealloc (include_files_path, + 2 + strlen (include_files_path) + strlen (optarg)); + strcat (include_files_path, ":"); + strcat (include_files_path, optarg); + break; + + /* User specified fill_column? */ + case 'f': + if (sscanf (optarg, "%d", &fill_column) != 1) + usage (); + break; + + /* User specified output file? */ + case 'o': + command_output_filename = savestring (optarg); + break; + + /* User specified paragraph indent (paragraph_start_index)? */ + case 'p': + if (set_paragraph_indent (optarg) < 0) + usage (); + break; + + /* User specified error level? */ + case 'e': + if (sscanf (optarg, "%d", &max_error_level) != 1) + usage (); + break; + + /* User specified reference warning limit? */ + case 'r': + if (sscanf (optarg, "%d", &reference_warning_limit) != 1) + usage (); + break; + + /* User specified footnote style? */ + case 's': + if (set_footnote_style (optarg) < 0) + usage (); + footnote_style_preset = 1; + break; + + /* User requested version info? */ + case 'V': + print_version_info (); + exit (NO_ERROR); + break; + + case '?': + usage (); + } + } + + if (optind == argc) + usage (); + else if (verbose_mode) + print_version_info (); + + /* Remaining arguments are file names of texinfo files. + Convert them, one by one. */ + while (optind != argc) + convert (argv[optind++]); + + if (errors_printed) + exit (SYNTAX); + else + exit (NO_ERROR); +} + +/* Display the version info of this invocation of Makeinfo. */ +print_version_info () +{ + fprintf (stderr, "This is GNU Makeinfo version %d.%d.\n", + major_version, minor_version); +} + +/* **************************************************************** */ +/* */ +/* Generic Utilities */ +/* */ +/* **************************************************************** */ + +/* 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 (); +} + +/* Tell the user how to use this program. */ +usage () +{ + fprintf (stderr, "Usage: %s [options] texinfo-file...\n\ +\n\ +This program accepts as input files of texinfo commands and text\n\ +and outputs a file suitable for reading with GNU Info.\n\ +\n\ +The options are:\n\ +`-I DIR' to add DIR to the directory search list for including\n\ + files with the `@include' command.\n\ +-D VAR to define a variable, as with `@set'.\n\ +-U VAR to undefine a variable, as with `@clear'.\n\ +`--no-validate' to suppress node cross reference validation.\n\ +`--no-warn' to suppress warning messages (errors are still output).\n\ +`--no-split' to suppress the splitting of large files.\n\ +`--no-headers' to suppress the output of Node: Foo headers.\n\ +`--verbose' to print information about what is being done.\n\ +`--version' to print the version number of Makeinfo.\n\ +`--output FILE' or `-o FILE'\n\ + to specify the output file. When you specify the\n\ + output file in this way, any `@setfilename' in the\n\ + input file is ignored.\n\ +`--paragraph-indent NUM'\n\ + to set the paragraph indent to NUM (default %d).\n\ +`--fill-column NUM' to set the filling column to NUM (default %d).\n\ +`--error-limit NUM' to set the error limit to NUM (default %d).\n\ +`--reference-limit NUM'\n\ + to set the reference warning limit to NUM (default %d).\n\ +`--footnote-style STYLE'\n\ + to set the footnote style to STYLE. STYLE should\n\ + either be `separate' to place footnotes in their own\n\ + node, or `end', to place the footnotes at the end of\n\ + the node in which they are defined (the default).\n\n", + progname, paragraph_start_indent, + fill_column, max_error_level, reference_warning_limit); + exit (FATAL); +} + +/* **************************************************************** */ +/* */ +/* Manipulating Lists */ +/* */ +/* **************************************************************** */ + +typedef struct generic_list { + struct generic_list *next; +} GENERIC_LIST; + +/* Reverse the chain of structures in LIST. Output the new head + of the chain. You should always assign the output value of this + function to something, or you will lose the chain. */ +GENERIC_LIST * +reverse_list (list) + register GENERIC_LIST *list; +{ + register GENERIC_LIST *next; + register GENERIC_LIST *prev = (GENERIC_LIST *) NULL; + + while (list) + { + next = list->next; + list->next = prev; + prev = list; + list = next; + } + return (prev); +} + + +/* **************************************************************** */ +/* */ +/* Pushing and Popping Files */ +/* */ +/* **************************************************************** */ + +/* Find and load the file named FILENAME. Return a pointer to + the loaded file, or NULL if it can't be loaded. */ +char * +find_and_load (filename) + char *filename; +{ + struct stat fileinfo; + int file = -1, n, i, count = 0; + char *fullpath, *result, *get_file_info_in_path (); + + result = fullpath = (char *)NULL; + + fullpath = get_file_info_in_path (filename, include_files_path, &fileinfo); + + if (!fullpath) + goto error_exit; + + filename = fullpath; + + file = open (filename, O_RDONLY); + if (file < 0) + goto error_exit; + + /* Load the file. */ + result = (char *)xmalloc (1 + fileinfo.st_size); + + /* VMS stat lies about the st_size value. The actual number of + readable bytes is always less than this value. The arcane + mysteries of VMS/RMS are too much to probe, so this hack + suffices to make things work. */ +#if defined (VMS) + while ((n = read (file, result + count, fileinfo.st_size)) > 0) + count += n; + if (n == -1) +#else /* !VMS */ + count = fileinfo.st_size; + if (read (file, result, fileinfo.st_size) != fileinfo.st_size) +#endif /* !VMS */ + error_exit: + { + if (result) + free (result); + + if (fullpath) + free (fullpath); + + if (file != -1) + close (file); + + return ((char *) NULL); + } + close (file); + + /* Set the globals to the new file. */ + input_text = result; + size_of_input_text = count; + input_filename = savestring (fullpath); + node_filename = savestring (fullpath); + input_text_offset = 0; + line_number = 1; + /* Not strictly necessary. This magic prevents read_token () from doing + extra unnecessary work each time it is called (that is a lot of times). + The SIZE_OF_INPUT_TEXT is one past the actual end of the text. */ + input_text[size_of_input_text] = '\n'; + return (result); +} + +/* Save the state of the current input file. */ +pushfile () +{ + FSTACK *newstack = (FSTACK *) xmalloc (sizeof (FSTACK)); + newstack->filename = input_filename; + newstack->text = input_text; + newstack->size = size_of_input_text; + newstack->offset = input_text_offset; + newstack->line_number = line_number; + newstack->next = filestack; + + filestack = newstack; + push_node_filename (); +} + +/* Make the current file globals be what is on top of the file stack. */ +popfile () +{ + extern int executing_string; + FSTACK *temp = filestack; + + if (!filestack) + abort (); /* My fault. I wonder what I did? */ + + /* Make sure that commands with braces have been satisfied. */ + if (!executing_string) + discard_braces (); + + /* Get the top of the stack into the globals. */ + input_filename = filestack->filename; + input_text = filestack->text; + size_of_input_text = filestack->size; + input_text_offset = filestack->offset; + line_number = filestack->line_number; + + /* Pop the stack. */ + filestack = filestack->next; + free (temp); + pop_node_filename (); +} + +/* Flush all open files on the file stack. */ +flush_file_stack () +{ + while (filestack) + { + free (input_filename); + free (input_text); + popfile (); + } +} + +int node_filename_stack_index = 0; +int node_filename_stack_size = 0; +char **node_filename_stack = (char **)NULL; + +push_node_filename () +{ + if (node_filename_stack_index + 1 > node_filename_stack_size) + { + if (!node_filename_stack) + node_filename_stack = + (char **)xmalloc ((node_filename_stack_size += 10) + * sizeof (char *)); + else + node_filename_stack = + (char **)xrealloc (node_filename_stack, + (node_filename_stack_size + 10) + * sizeof (char *)); + } + + node_filename_stack[node_filename_stack_index] = node_filename; + node_filename_stack_index++; +} + +pop_node_filename () +{ + node_filename = node_filename_stack[--node_filename_stack_index]; +} + +/* Return just the simple part of the filename; i.e. the + filename without the path information, or extensions. + This conses up a new string. */ +char * +filename_part (filename) + char *filename; +{ + char *basename; + + basename = strrchr (filename, '/'); + if (!basename) + basename = filename; + else + basename++; + + basename = savestring (basename); +#if defined (REMOVE_OUTPUT_EXTENSIONS) + + /* See if there is an extension to remove. If so, remove it. */ + { + char *temp; + + temp = strrchr (basename, '.'); + if (temp) + *temp = '\0'; + } +#endif /* REMOVE_OUTPUT_EXTENSIONS */ + return (basename); +} + +/* Return the pathname part of filename. This can be NULL. */ +char * +pathname_part (filename) + char *filename; +{ + char *expand_filename (); + char *result = (char *) NULL; + register int i; + + filename = expand_filename (filename, ""); + + i = strlen (filename) - 1; + + while (i && filename[i] != '/') + i--; + if (filename[i] == '/') + i++; + + if (i) + { + result = (char *)xmalloc (1 + i); + strncpy (result, filename, i); + result[i] = '\0'; + } + free (filename); + return (result); +} + +/* Return the expansion of FILENAME. */ +char * +expand_filename (filename, input_name) + char *filename, *input_name; +{ + char *full_pathname (); + filename = full_pathname (filename); + + if (filename[0] == '.') + return (filename); + + if (filename[0] != '/' && input_name[0] == '/') + { + /* Make it so that relative names work. */ + char *result; + int i = strlen (input_name) - 1; + + result = (char *)xmalloc (1 + strlen (input_name) + strlen (filename)); + strcpy (result, input_name); + + while (result[i] != '/' && i) + i--; + + if (result[i] == '/') + i++; + + strcpy (&result[i], filename); + free (filename); + return (result); + } + return (filename); +} + +/* Return the full path to FILENAME. */ +char * +full_pathname (filename) + char *filename; +{ + int initial_character; + + if (filename && (initial_character = *filename)) + { + if (initial_character == '/') + return (savestring (filename)); + if (initial_character != '~') + { + return (savestring (filename)); + } + else + { + if (filename[1] == '/') + { + /* Return the concatenation of HOME and the rest of the string. */ + char *temp_home; + char *temp_name; + + temp_home = (char *) getenv ("HOME"); + temp_name = (char *)xmalloc (strlen (&filename[2]) + + 1 + + temp_home ? strlen (temp_home) + : 0); + if (temp_home) + strcpy (temp_name, temp_home); + + strcat (temp_name, &filename[2]); + return (temp_name); + } + else + { + struct passwd *user_entry; + int i, c; + char *username = (char *)xmalloc (257); + char *temp_name; + + for (i = 1; c = filename[i]; i++) + { + if (c == '/') + break; + else + username[i - 1] = c; + } + if (c) + username[i - 1] = '\0'; + + user_entry = getpwnam (username); + + if (!user_entry) + return (savestring (filename)); + + temp_name = (char *)xmalloc (1 + strlen (user_entry->pw_dir) + + strlen (&filename[i])); + strcpy (temp_name, user_entry->pw_dir); + strcat (temp_name, &filename[i]); + return (temp_name); + } + } + } + else + { + return (savestring (filename)); + } +} + +/* **************************************************************** */ +/* */ +/* Error Handling */ +/* */ +/* **************************************************************** */ + +/* Number of errors encountered. */ +int errors_printed = 0; + +/* Print the last error gotten from the file system. */ +fs_error (filename) + char *filename; +{ + remember_error (); + perror (filename); + return (0); +} + +/* Print an error message, and return false. */ +#if defined (HAVE_VARARGS_H) && defined (HAVE_VFPRINTF) + +int +error (va_alist) + va_dcl +{ + char *format; + va_list args; + + remember_error (); + va_start (args); + format = va_arg (args, char *); + vfprintf (stderr, format, args); + va_end (args); + fprintf (stderr, "\n"); +} + +/* Just like error (), but print the line number as well. */ +int +line_error (va_alist) + va_dcl +{ + char *format; + va_list args; + + remember_error (); + va_start (args); + format = va_arg (args, char *); + fprintf (stderr, "%s:%d: ", input_filename, line_number); + vfprintf (stderr, format, args); + fprintf (stderr, ".\n"); + va_end (args); + return ((int) 0); +} + +int +warning (va_alist) + va_dcl +{ + char *format; + va_list args; + + va_start (args); + format = va_arg (args, char *); + if (print_warnings) + { + fprintf (stderr, "%s:%d: Warning: ", input_filename, line_number); + vfprintf (stderr, format, args); + fprintf (stderr, ".\n"); + } + va_end (args); + return ((int) 0); +} + +#else /* !(HAVE_VARARGS_H && HAVE_VFPRINTF) */ + +int +error (format, arg1, arg2, arg3, arg4, arg5) + char *format; +{ + remember_error (); + fprintf (stderr, format, arg1, arg2, arg3, arg4, arg5); + fprintf (stderr, "\n"); + return ((int) 0); +} + +/* Just like error (), but print the line number as well. */ +int +line_error (format, arg1, arg2, arg3, arg4, arg5) + char *format; +{ + remember_error (); + fprintf (stderr, "%s:%d: ", input_filename, line_number); + fprintf (stderr, format, arg1, arg2, arg3, arg4, arg5); + fprintf (stderr, ".\n"); + return ((int) 0); +} + +int +warning (format, arg1, arg2, arg3, arg4, arg5) + char *format; +{ + if (print_warnings) + { + fprintf (stderr, "%s:%d: Warning: ", input_filename, line_number); + fprintf (stderr, format, arg1, arg2, arg3, arg4, arg5); + fprintf (stderr, ".\n"); + } + return ((int) 0); +} + +#endif /* !(HAVE_VARARGS_H && HAVE_VFPRINTF) */ + +/* Remember that an error has been printed. If this is the first + error printed, then tell them which program is printing them. + If more than max_error_level have been printed, then exit the + program. */ +remember_error () +{ + errors_printed++; + if (max_error_level && (errors_printed > max_error_level)) + { + fprintf (stderr, "Too many errors! Gave up.\n"); + flush_file_stack (); + cm_bye (); + exit (1); + } +} + +/* **************************************************************** */ +/* */ +/* Hacking Tokens and Strings */ +/* */ +/* **************************************************************** */ + +/* Return the next token as a string pointer. We cons the + string. */ +char * +read_token () +{ + int i, character; + char *result; + + /* If the first character to be read is self-delimiting, then that + is the command itself. */ + character = curchar (); + if (self_delimiting (character)) + { + input_text_offset++; + result = savestring (" "); + *result = character; + return (result); + } + + for (i = 0; ((input_text_offset != size_of_input_text) + && (character = curchar ()) + && command_char (character)); + i++, input_text_offset++); + result = (char *)xmalloc (i + 1); + memcpy (result, &input_text[input_text_offset - i], i); + result[i] = '\0'; + return (result); +} + +/* Return non-zero if CHARACTER is self-delimiting. */ +int +self_delimiting (character) + int character; +{ + return (member (character, "{}:.@*'`,!?; \n")); +} + +/* Clear whitespace from the front and end of string. */ +canon_white (string) + char *string; +{ + int len = strlen (string); + int x; + + if (!len) + return; + + for (x = 0; x < len; x++) + { + if (!cr_or_whitespace (string[x])) + { + strcpy (string, string + x); + break; + } + } + len = strlen (string); + if (len) + len--; + while (len > -1 && cr_or_whitespace (string[len])) + len--; + string[len + 1] = '\0'; +} + +/* Bash STRING, replacing all whitespace with just one space. */ +fix_whitespace (string) + char *string; +{ + char *temp = (char *)xmalloc (strlen (string) + 1); + int string_index = 0; + int temp_index = 0; + int c; + + canon_white (string); + + while (string[string_index]) + { + c = temp[temp_index++] = string[string_index++]; + + if (c == ' ' || c == '\n' || c == '\t') + { + temp[temp_index - 1] = ' '; + while ((c = string[string_index]) && (c == ' ' || + c == '\t' || + c == '\n')) + string_index++; + } + } + temp[temp_index] = '\0'; + strcpy (string, temp); + free (temp); +} + +/* Discard text until the desired string is found. The string is + included in the discarded text. */ +discard_until (string) + char *string; +{ + int temp = search_forward (string, input_text_offset); + + int tt = (temp < 0) ? size_of_input_text : temp + strlen (string); + int from = input_text_offset; + + /* Find out what line we are on. */ + while (from != tt) + if (input_text[from++] == '\n') + line_number++; + + if (temp < 0) + { + input_text_offset = size_of_input_text - strlen (string); + + if (strcmp (string, "\n") != 0) + { + line_error ("Expected `%s'", string); + return; + } + } + else + input_text_offset = temp; + + input_text_offset += strlen (string); +} + +/* Read characters from the file until we are at MATCH. + Place the characters read into STRING. + On exit input_text_offset is after the match string. + Return the offset where the string starts. */ +int +get_until (match, string) + char *match, **string; +{ + int len, current_point, x, new_point, tem; + + current_point = x = input_text_offset; + new_point = search_forward (match, input_text_offset); + + if (new_point < 0) + new_point = size_of_input_text; + len = new_point - current_point; + + /* Keep track of which line number we are at. */ + tem = new_point + (strlen (match) - 1); + while (x != tem) + if (input_text[x++] == '\n') + line_number++; + + *string = (char *)xmalloc (len + 1); + + memcpy (*string, &input_text[current_point], len); + (*string)[len] = '\0'; + + /* Now leave input_text_offset in a consistent state. */ + input_text_offset = tem; + + if (input_text_offset > size_of_input_text) + input_text_offset = size_of_input_text; + + return (new_point); +} + +/* Read characters from the file until we are at MATCH or end of line. + Place the characters read into STRING. */ +get_until_in_line (match, string) + char *match, **string; +{ + int real_bottom, temp; + + real_bottom = size_of_input_text; + temp = search_forward ("\n", input_text_offset); + + if (temp < 0) + temp = size_of_input_text; + + size_of_input_text = temp; + get_until (match, string); + size_of_input_text = real_bottom; +} + +get_rest_of_line (string) + char **string; +{ + get_until ("\n", string); + canon_white (*string); + + if (curchar () == '\n') /* as opposed to the end of the file... */ + { + line_number++; + input_text_offset++; + } +} + +/* Backup the input pointer to the previous character, keeping track + of the current line number. */ +backup_input_pointer () +{ + if (input_text_offset) + { + input_text_offset--; + if (curchar () == '\n') + line_number--; + } +} + +/* Read characters from the file until we are at MATCH or closing brace. + Place the characters read into STRING. */ +get_until_in_braces (match, string) + char *match, **string; +{ + int i, brace = 0; + int match_len = strlen (match); + char *temp; + + for (i = input_text_offset; i < size_of_input_text; i++) + { + if (input_text[i] == '{') + brace++; + else if (input_text[i] == '}') + brace--; + else if (input_text[i] == '\n') + line_number++; + + if (brace < 0 || + (brace == 0 && strncmp (input_text + i, match, match_len) == 0)) + break; + } + + match_len = i - input_text_offset; + temp = (char *)xmalloc (2 + match_len); + strncpy (temp, input_text + input_text_offset, match_len); + temp[match_len] = '\0'; + input_text_offset = i; + *string = temp; +} + +/* **************************************************************** */ +/* */ +/* Converting the File */ +/* */ +/* **************************************************************** */ + +/* Convert the file named by NAME. The output is saved on the file + named as the argument to the @setfilename command. */ +static char *suffixes[] = { + "", + ".texinfo", + ".texi", + ".txinfo", + (char *)NULL +}; + +convert (name) + char *name; +{ + char *real_output_filename, *expand_filename (), *filename_part (); + char *filename = (char *)xmalloc (strlen (name) + 50); + register int i; + + init_tag_table (); + init_indices (); + init_internals (); + init_paragraph (); + + /* Try to load the file specified by NAME. If the file isn't found, and + there is no suffix in NAME, then try NAME.texinfo, and NAME.texi. */ + for (i = 0; suffixes[i]; i++) + { + strcpy (filename, name); + strcat (filename, suffixes[i]); + + if (find_and_load (filename)) + break; + + if (!suffixes[i][0] && strrchr (filename, '.')) + { + fs_error (filename); + free (filename); + return; + } + } + + if (!suffixes[i]) + { + fs_error (name); + free (filename); + return; + } + + input_filename = filename; + + /* Search this file looking for the special string which starts conversion. + Once found, we may truly begin. */ + + input_text_offset = search_forward ("@setfilename", 0); + + if (input_text_offset < 0) + { + if (!command_output_filename) + { + error ("No `@setfilename' found in `%s'", name); + goto finished; + } + } + else + input_text_offset += strlen ("@setfilename"); + + real_output_filename = (char *)NULL; + + if (!command_output_filename) + get_until ("\n", &output_filename); + else + { + if (input_text_offset != -1) + discard_until ("\n"); + else + input_text_offset = 0; + + real_output_filename = output_filename = command_output_filename; + command_output_filename = (char *)NULL; + } + + canon_white (output_filename); + printf ("Making info file `%s' from `%s'.\n", output_filename, name); + + if (verbose_mode) + fprintf (stderr, " The input file contains %d characters.\n", + size_of_input_text); + + if (real_output_filename && + strcmp (real_output_filename, "-") == 0) + { + output_stream = stdout; + } + else + { + if (!real_output_filename) + real_output_filename = expand_filename (output_filename, name); + + output_stream = fopen (real_output_filename, "w"); + } + + if (output_stream == NULL) + { + fs_error (real_output_filename); + goto finished; + } + + /* Make the displayable filename from output_filename. Only the base + portion of the filename need be displayed. */ + pretty_output_filename = filename_part (output_filename); + + /* For this file only, count the number of newlines from the top of + the file to here. This way, we keep track of line numbers for + error reporting. Line_number starts at 1, since the user isn't + zero-based. */ + { + int temp = 0; + line_number = 1; + while (temp != input_text_offset) + if (input_text[temp++] == '\n') + line_number++; + } + + if (!no_headers) + { + add_word_args ("This is Info file %s, produced by Makeinfo-%d.%d from ", + output_filename, major_version, minor_version); + add_word_args ("the input file %s.\n", input_filename); + } + + close_paragraph (); + reader_loop (); + +finished: + close_paragraph (); + flush_file_stack (); + if (output_stream != NULL) + { + output_pending_notes (); + free_pending_notes (); + if (tag_table != NULL) + { + tag_table = (TAG_ENTRY *) reverse_list (tag_table); + if (!no_headers) + write_tag_table (); + } + + if (output_stream != stdout) + fclose (output_stream); + + /* If validating, then validate the entire file right now. */ + if (validating) + validate_file (real_output_filename, tag_table); + + /* This used to test && !errors_printed. + But some files might have legit warnings. So split anyway. */ + if (splitting) + split_file (real_output_filename, 0); + } +} + +free_and_clear (pointer) + char **pointer; +{ + if ((*pointer) != (char *) NULL) + { + free (*pointer); + *pointer = (char *) NULL; + } +} + + /* Initialize some state. */ +init_internals () +{ + free_and_clear (¤t_node); + free_and_clear (&output_filename); + free_and_clear (&command); + free_and_clear (&input_filename); + free_node_references (); + init_insertion_stack (); + init_brace_stack (); + command_index = 0; + in_menu = 0; +} + +init_paragraph () +{ + free_and_clear (&output_paragraph); + output_paragraph = (unsigned char *)xmalloc (paragraph_buffer_len); + output_position = 0; + output_paragraph[0] = '\0'; + output_paragraph_offset = 0; + output_column = 0; + paragraph_is_open = 0; + current_indent = 0; +} + +/* Okay, we are ready to start the conversion. Call the reader on + some text, and fill the text as it is output. Handle commands by + remembering things like open braces and the current file position on a + stack, and when the corresponding close brace is found, you can call + the function with the proper arguments. */ +reader_loop () +{ + int character; + int done = 0; + int dash_count = 0; + + while (!done) + { + if (input_text_offset >= size_of_input_text) + { + if (filestack) + { + free (input_filename); + free (input_text); + popfile (); + } + else + break; + } + + character = curchar (); + + if (!in_fixed_width_font && + (character == '\'' || character == '`') && + input_text[input_text_offset + 1] == character) + { + input_text_offset++; + character = '"'; + } + + if (character == '-') + { + dash_count++; + if (dash_count == 2 && !in_fixed_width_font) + { + input_text_offset++; + continue; + } + } + else + { + dash_count = 0; + } + + /* If this is a whitespace character, then check to see if the line + is blank. If so, advance to the carriage return. */ + if (whitespace (character)) + { + register int i = input_text_offset + 1; + + while (i < size_of_input_text && whitespace (input_text[i])) + i++; + + if (i == size_of_input_text || input_text[i] == '\n') + { + if (i == size_of_input_text) + i--; + + input_text_offset = i; + character = curchar (); + } + } + + if (character == '\n') + { + line_number++; + + /* Check for a menu entry here, since the "escape sequence" + that begins menu entrys is "\n* ". */ + if (in_menu && input_text_offset + 1 < size_of_input_text) + { + char *glean_node_from_menu (), *tem; + + /* Note that the value of TEM is discarded, since it is + gauranteed to be NULL when glean_node_from_menu () is + called with a non-zero argument. */ + tem = glean_node_from_menu (1); + } + } + + switch (character) + { + case COMMAND_PREFIX: + read_command (); + if (strcmp (command, "bye") == 0) + { + done = 1; + continue; + } + break; + + case '{': + + /* Special case. I'm not supposed to see this character by itself. + If I do, it means there is a syntax error in the input text. + Report the error here, but remember this brace on the stack so + you can ignore its partner. */ + + line_error ("Misplaced `{'"); + remember_brace (misplaced_brace); + + /* Don't advance input_text_offset since this happens in + remember_brace (). + input_text_offset++; + */ + break; + + case '}': + pop_and_call_brace (); + input_text_offset++; + break; + + default: + add_char (character); + input_text_offset++; + } + } +} + +/* Find the command corresponding to STRING. If the command + is found, return a pointer to the data structure. Otherwise + return (-1). */ +COMMAND * +get_command_entry (string) + char *string; +{ + register int i; + + for (i = 0; CommandTable[i].name; i++) + if (strcmp (CommandTable[i].name, string) == 0) + return (&CommandTable[i]); + + /* This command is not in our predefined command table. Perhaps + it is a user defined command. */ + for (i = 0; i < user_command_array_len; i++) + if (user_command_array[i] && + (strcmp (user_command_array[i]->name, string) == 0)) + return (user_command_array[i]); + + /* Nope, we never heard of this command. */ + return ((COMMAND *) -1); +} + +/* input_text_offset is right at the command prefix character. + Read the next token to determine what to do. */ +read_command () +{ + COMMAND *entry; + input_text_offset++; + free_and_clear (&command); + command = read_token (); + +#if defined (HAVE_MACROS) + /* Check to see if this command is a macro. If so, execute it here. */ + { + MACRO_DEF *def; + + def = find_macro (command); + + if (def) + { + execute_macro (def); + return; + } + } +#endif /* HAVE_MACROS */ + + entry = get_command_entry (command); + + if ((int) entry == -1) + { + line_error ("Unknown info command `%s'", command); + return; + } + + if (entry->argument_in_braces) + remember_brace (entry->proc); + + (*(entry->proc)) (START); +} + +/* Return the string which invokes PROC; a pointer to a function. */ +char * +find_proc_name (proc) + FUNCTION *proc; +{ + register int i; + + for (i = 0; CommandTable[i].name; i++) + if (proc == CommandTable[i].proc) + return (CommandTable[i].name); + return ("NO_NAME!"); +} + +init_brace_stack () +{ + brace_stack = (BRACE_ELEMENT *) NULL; +} + +remember_brace (proc) + FUNCTION *proc; +{ + if (curchar () != '{') + line_error ("@%s expected `{..}'", command); + else + input_text_offset++; + remember_brace_1 (proc, output_paragraph_offset); +} + +/* Remember the current output position here. Save PROC + along with it so you can call it later. */ +remember_brace_1 (proc, position) + FUNCTION *proc; + int position; +{ + BRACE_ELEMENT *new = (BRACE_ELEMENT *) xmalloc (sizeof (BRACE_ELEMENT)); + new->next = brace_stack; + new->proc = proc; + new->pos = position; + new->line = line_number; + brace_stack = new; +} + +/* Pop the top of the brace stack, and call the associated function + with the args END and POS. */ +pop_and_call_brace () +{ + BRACE_ELEMENT *temp; + FUNCTION *proc; + int pos; + + if (brace_stack == (BRACE_ELEMENT *) NULL) + return (line_error ("Unmatched close brace")); + + pos = brace_stack->pos; + proc = brace_stack->proc; + temp = brace_stack->next; + free (brace_stack); + brace_stack = temp; + + return ((*proc) (END, pos, output_paragraph_offset)); +} + +/* You call discard_braces () when you shouldn't have any braces on the stack. + I used to think that this happens for commands that don't take arguments + in braces, but that was wrong because of things like @code{foo @@}. So now + I only detect it at the beginning of nodes. */ +discard_braces () +{ + int temp_line_number = line_number; + char *proc_name; + + if (!brace_stack) + return; + + while (brace_stack) + { + line_number = brace_stack->line; + proc_name = find_proc_name (brace_stack->proc); + line_error ("@%s missing close brace", proc_name); + line_number = temp_line_number; + pop_and_call_brace (); + } +} + +get_char_len (character) + int character; +{ + /* Return the printed length of the character. */ + int len; + + switch (character) + { + case '\t': + len = (output_column + 8) & 0xf7; + if (len > fill_column) + len = fill_column - output_column; + else + len = len - output_column; + break; + + case '\n': + len = fill_column - output_column; + break; + + default: + if (character < ' ') + len = 2; + else + len = 1; + } + return (len); +} + +#if defined (HAVE_VARARGS_H) && defined (HAVE_VSPRINTF) + +add_word_args (va_alist) + va_dcl +{ + char buffer[1000]; + char *format; + va_list args; + + va_start (args); + format = va_arg (args, char *); + vsprintf (buffer, format, args); + va_end (args); + add_word (buffer); +} + +#else /* !(HAVE_VARARGS_H && HAVE_VSPRINTF) */ + +add_word_args (format, arg1, arg2, arg3, arg4, arg5) + char *format; +{ + char buffer[1000]; + sprintf (buffer, format, arg1, arg2, arg3, arg4, arg5); + add_word (buffer); +} + +#endif /* !(HAVE_VARARGS_H && HAVE_VSPRINTF) */ + +/* Add STRING to output_paragraph. */ +add_word (string) + char *string; +{ + while (*string) + add_char (*string++); +} + +/* Non-zero if the last character inserted has the syntax class of NEWLINE. */ +int last_char_was_newline = 1; + +/* The actual last inserted character. Note that this may be something + other than NEWLINE even if last_char_was_newline is 1. */ +int last_inserted_character = 0; + +/* Non-zero means that a newline character has already been + inserted, so close_paragraph () should insert one less. */ +int line_already_broken = 0; + +/* When non-zero we have finished an insertion (see end_insertion ()) and we + want to ignore false continued paragraph closings. */ +int insertion_paragraph_closed = 0; + +/* Add the character to the current paragraph. If filling_enabled is + non-zero, then do filling as well. */ +add_char (character) + int character; +{ + /* If we are avoiding outputting headers, and we are currently + in a menu, then simply return. */ + if (no_headers && in_menu) + return; + + /* If we are adding a character now, then we don't have to + ignore close_paragraph () calls any more. */ + if (must_start_paragraph && character != '\n') + { + must_start_paragraph = 0; + line_already_broken = 0; /* The line is no longer broken. */ + if (current_indent > output_column) + { + indent (current_indent - output_column); + output_column = current_indent; + } + } + + if (non_splitting_words && member (character, " \t\n")) + character = ' ' | 0x80; + + insertion_paragraph_closed = 0; + + switch (character) + { + case '\n': + if (!filling_enabled) + { + insert ('\n'); + + if (force_flush_right) + { + close_paragraph (); + /* Hack to force single blank lines out in this mode. */ + flush_output (); + } + + output_column = 0; + + if (!no_indent && paragraph_is_open) + indent (output_column = current_indent); + break; + } + else /* CHARACTER is newline, and filling is enabled. */ + { + if (sentence_ender (last_inserted_character)) + { + insert (' '); + output_column++; + last_inserted_character = character; + } + } + + if (last_char_was_newline) + { + close_paragraph (); + pending_indent = 0; + } + else + { + last_char_was_newline = 1; + insert (' '); + output_column++; + } + break; + + default: + { + int len = get_char_len (character); + int suppress_insert = 0; + + if ((character == ' ') && (last_char_was_newline)) + { + if (!paragraph_is_open) + { + pending_indent++; + return; + } + } + + if (!paragraph_is_open) + { + start_paragraph (); + + /* If the paragraph is supposed to be indented a certain way, + then discard all of the pending whitespace. Otherwise, we + let the whitespace stay. */ + if (!paragraph_start_indent) + indent (pending_indent); + pending_indent = 0; + } + + if ((output_column += len) > fill_column) + { + if (filling_enabled) + { + int temp = output_paragraph_offset; + while (--temp > 0 && output_paragraph[temp] != '\n') + { + /* If we have found a space, we have the place to break + the line. */ + if (output_paragraph[temp] == ' ') + { + /* Remove trailing whitespace from output. */ + while (temp && whitespace (output_paragraph[temp - 1])) + temp--; + + output_paragraph[temp++] = '\n'; + + /* We have correctly broken the line where we want + to. What we don't want is spaces following where + we have decided to break the line. We get rid of + them. */ + { + int t1 = temp; + + for (;; t1++) + { + if (t1 == output_paragraph_offset) + { + if (whitespace (character)) + suppress_insert = 1; + break; + } + if (!whitespace (output_paragraph[t1])) + break; + } + + if (t1 != temp) + { + strncpy ((char *) &output_paragraph[temp], + (char *) &output_paragraph[t1], + (output_paragraph_offset - t1)); + output_paragraph_offset -= (t1 - temp); + } + } + + /* Filled, but now indent if that is right. */ + if (indented_fill && current_indent) + { + int buffer_len = ((output_paragraph_offset - temp) + + current_indent); + char *temp_buffer = (char *)xmalloc (buffer_len); + int indentation = 0; + + /* We have to shift any markers that are in + front of the wrap point. */ + { + register BRACE_ELEMENT *stack = brace_stack; + + while (stack) + { + if (stack->pos >= temp) + stack->pos += current_indent; + stack = stack->next; + } + } + + while (current_indent > 0 && + indentation != current_indent) + temp_buffer[indentation++] = ' '; + + strncpy ((char *) &temp_buffer[current_indent], + (char *) &output_paragraph[temp], + buffer_len - current_indent); + + if (output_paragraph_offset + buffer_len + >= paragraph_buffer_len) + { + unsigned char *tt = xrealloc + (output_paragraph, + (paragraph_buffer_len += buffer_len)); + output_paragraph = tt; + } + strncpy ((char *) &output_paragraph[temp], + temp_buffer, buffer_len); + output_paragraph_offset += current_indent; + free (temp_buffer); + } + output_column = 0; + while (temp < output_paragraph_offset) + output_column += + get_char_len (output_paragraph[temp++]); + output_column += len; + break; + } + } + } + } + + if (!suppress_insert) + { + insert (character); + last_inserted_character = character; + } + last_char_was_newline = 0; + line_already_broken = 0; + } + } +} + +/* Insert CHARACTER into OUTPUT_PARAGRAPH. */ +insert (character) + int character; +{ + output_paragraph[output_paragraph_offset++] = character; + if (output_paragraph_offset == paragraph_buffer_len) + { + output_paragraph = + xrealloc (output_paragraph, (paragraph_buffer_len += 100)); + } +} + +/* Remove upto COUNT characters of whitespace from the + the current output line. If COUNT is less than zero, + then remove until none left. */ +kill_self_indent (count) + int count; +{ + /* Handle infinite case first. */ + if (count < 0) + { + output_column = 0; + while (output_paragraph_offset) + { + if (whitespace (output_paragraph[output_paragraph_offset - 1])) + output_paragraph_offset--; + else + break; + } + } + else + { + while (output_paragraph_offset && count--) + if (whitespace (output_paragraph[output_paragraph_offset - 1])) + output_paragraph_offset--; + else + break; + } +} + +/* Non-zero means do not honor calls to flush_output (). */ +static int flushing_ignored = 0; + +/* Prevent calls to flush_output () from having any effect. */ +inhibit_output_flushing () +{ + flushing_ignored++; +} + +/* Allow calls to flush_output () to write the paragraph data. */ +uninhibit_output_flushing () +{ + flushing_ignored--; +} + +flush_output () +{ + register int i; + + if (!output_paragraph_offset || flushing_ignored) + return; + + for (i = 0; i < output_paragraph_offset; i++) + { + if (output_paragraph[i] == (unsigned char)(' ' | 0x80) || + output_paragraph[i] == (unsigned char)('\t' | 0x80) || + output_paragraph[i] == (unsigned char)('\n' | 0x80) || + sentence_ender (UNMETA (output_paragraph[i]))) + output_paragraph[i] &= 0x7f; + } + + fwrite (output_paragraph, 1, output_paragraph_offset, output_stream); + + output_position += output_paragraph_offset; + output_paragraph_offset = 0; +} + +/* How to close a paragraph controlling the number of lines between + this one and the last one. */ + +/* Paragraph spacing is controlled by this variable. It is the number of + blank lines that you wish to appear between paragraphs. A value of + 1 creates a single blank line between paragraphs. */ +int paragraph_spacing = DEFAULT_PARAGRAPH_SPACING; + +/* Close the current paragraph, leaving no blank lines between them. */ +close_single_paragraph () +{ + close_paragraph_with_lines (0); +} + +/* Close a paragraph after an insertion has ended. */ +close_insertion_paragraph () +{ + if (!insertion_paragraph_closed) + { + /* Close the current paragraph, breaking the line. */ + close_single_paragraph (); + + /* Start a new paragraph here, inserting whatever indention is correct + for the now current insertion level (one above the one that we are + ending). */ + start_paragraph (); + + /* Tell close_paragraph () that the previous line has already been + broken, so it should insert one less newline. */ + line_already_broken = 1; + + /* Let functions such as add_char () know that we have already found a + newline. */ + ignore_blank_line (); + } + else + { + /* If the insertion paragraph is closed already, then we are seeing + two `@end' commands in a row. Note that the first one we saw was + handled in the first part of this if-then-else clause, and at that + time start_paragraph () was called, partially to handle the proper + indentation of the current line. However, the indentation level + may have just changed again, so we may have to outdent the current + line to the new indentation level. */ + if (current_indent < output_column) + kill_self_indent (output_column - current_indent); + } + + insertion_paragraph_closed = 1; +} + +close_paragraph_with_lines (lines) + int lines; +{ + int old_spacing = paragraph_spacing; + paragraph_spacing = lines; + close_paragraph (); + paragraph_spacing = old_spacing; +} + +/* Close the currently open paragraph. */ +close_paragraph () +{ + register int i; + + /* The insertion paragraph is no longer closed. */ + insertion_paragraph_closed = 0; + + if (paragraph_is_open && !must_start_paragraph) + { + register int tindex, c; + + tindex = output_paragraph_offset; + + /* Back up to last non-newline/space character, forcing all such + subsequent characters to be newlines. This isn't strictly + necessary, but a couple of functions use the presence of a newline + to make decisions. */ + for (tindex = output_paragraph_offset - 1; tindex >= 0; --tindex) + { + c = output_paragraph[tindex]; + + if (c == ' '|| c == '\n') + output_paragraph[tindex] = '\n'; + else + break; + } + + /* All trailing whitespace is ignored. */ + output_paragraph_offset = ++tindex; + + /* Break the line if that is appropriate. */ + if (paragraph_spacing >= 0) + insert ('\n'); + + /* Add as many blank lines as is specified in PARAGRAPH_SPACING. */ + if (!force_flush_right) + { + for (i = 0; i < (paragraph_spacing - line_already_broken); i++) + insert ('\n'); + } + + /* If we are doing flush right indentation, then do it now + on the paragraph (really a single line). */ + if (force_flush_right) + do_flush_right_indentation (); + + flush_output (); + paragraph_is_open = 0; + no_indent = 0; + output_column = 0; + } + ignore_blank_line (); +} + +/* Make the last line just read look as if it were only a newline. */ +ignore_blank_line () +{ + last_inserted_character = '\n'; + last_char_was_newline = 1; +} + +/* Align the end of the text in output_paragraph with fill_column. */ +do_flush_right_indentation () +{ + char *temp; + int temp_len; + + kill_self_indent (-1); + + if (output_paragraph[0] != '\n') + { + output_paragraph[output_paragraph_offset] = '\0'; + + if (output_paragraph_offset < fill_column) + { + register int i; + + if (fill_column >= paragraph_buffer_len) + output_paragraph = + xrealloc (output_paragraph, + (paragraph_buffer_len += fill_column)); + + temp_len = strlen ((char *)output_paragraph); + temp = (char *)xmalloc (temp_len + 1); + memcpy (temp, (char *)output_paragraph, temp_len); + + for (i = 0; i < fill_column - output_paragraph_offset; i++) + output_paragraph[i] = ' '; + + memcpy ((char *)output_paragraph + i, temp, temp_len); + free (temp); + output_paragraph_offset = fill_column; + } + } +} + +/* Begin a new paragraph. */ +start_paragraph () +{ + /* First close existing one. */ + if (paragraph_is_open) + close_paragraph (); + + /* In either case, the insertion paragraph is no longer closed. */ + insertion_paragraph_closed = 0; + + /* However, the paragraph is open! */ + paragraph_is_open = 1; + + /* If we MUST_START_PARAGRAPH, that simply means that start_paragraph () + had to be called before we would allow any other paragraph operations + to have an effect. */ + if (!must_start_paragraph) + { + int amount_to_indent = 0; + + /* If doing indentation, then insert the appropriate amount. */ + if (!no_indent) + { + if (inhibit_paragraph_indentation) + { + amount_to_indent = current_indent; + if (inhibit_paragraph_indentation < 0) + inhibit_paragraph_indentation++; + } + else if (paragraph_start_indent < 0) + amount_to_indent = current_indent; + else + amount_to_indent = current_indent + paragraph_start_indent; + + if (amount_to_indent >= output_column) + { + amount_to_indent -= output_column; + indent (amount_to_indent); + output_column += amount_to_indent; + } + } + } + else + must_start_paragraph = 0; +} + +/* Insert the indentation specified by AMOUNT. */ +indent (amount) + int amount; +{ + register BRACE_ELEMENT *elt = brace_stack; + + /* For every START_POS saved within the brace stack which will be affected + by this indentation, bump that start pos forward. */ + while (elt) + { + if (elt->pos >= output_paragraph_offset) + elt->pos += amount; + elt = elt->next; + } + + while (--amount >= 0) + insert (' '); +} + +/* Search forward for STRING in input_text. + FROM says where where to start. */ +search_forward (string, from) + char *string; + int from; +{ + int len = strlen (string); + + while (from < size_of_input_text) + { + if (strncmp (input_text + from, string, len) == 0) + return (from); + from++; + } + return (-1); +} + +/* Whoops, Unix doesn't have stricmp. */ + +/* Case independent string compare. */ +stricmp (string1, string2) + char *string1, *string2; +{ + char ch1, ch2; + + for (;;) + { + ch1 = *string1++; + ch2 = *string2++; + + if (!(ch1 | ch2)) + return (0); + + ch1 = coerce_to_upper (ch1); + ch2 = coerce_to_upper (ch2); + + if (ch1 != ch2) + return (ch1 - ch2); + } +} + +enum insertion_type { menu, quotation, lisp, smalllisp, example, + smallexample, display, itemize, format, enumerate, cartouche, table, + ftable, vtable, group, ifinfo, flushleft, flushright, ifset, ifclear, deffn, + defun, defmac, defspec, defvr, defvar, defopt, deftypefn, + deftypefun, deftypevr, deftypevar, defcv, defivar, defop, defmethod, + deftypemethod, deftp, bad_type }; + +char *insertion_type_names[] = { "menu", "quotation", "lisp", + "smalllisp", "example", "smallexample", "display", "itemize", + "format", "enumerate", "cartouche", "table", "ftable", "vtable", "group", + "ifinfo", "flushleft", "flushright", "ifset", "ifclear", "deffn", + "defun", "defmac", "defspec", "defvr", "defvar", "defopt", + "deftypefn", "deftypefun", "deftypevr", "deftypevar", "defcv", + "defivar", "defop", "defmethod", "deftypemethod", "deftp", + "bad_type" }; + +int insertion_level = 0; +typedef struct istack_elt +{ + struct istack_elt *next; + char *item_function; + int line_number; + int filling_enabled; + int indented_fill; + enum insertion_type insertion; + int inhibited; +} INSERTION_ELT; + +INSERTION_ELT *insertion_stack = (INSERTION_ELT *) NULL; + +init_insertion_stack () +{ + insertion_stack = (INSERTION_ELT *) NULL; +} + +/* Return the type of the current insertion. */ +enum insertion_type +current_insertion_type () +{ + if (!insertion_level) + return (bad_type); + else + return (insertion_stack->insertion); +} + +/* Return a pointer to the string which is the function to wrap around + items. */ +char * +current_item_function () +{ + register int level, done; + register INSERTION_ELT *elt; + + level = insertion_level; + elt = insertion_stack; + done = 0; + + /* Skip down through the stack until we find a non-conditional insertion. */ + while (!done) + { + switch (elt->insertion) + { + case ifinfo: + case ifset: + case ifclear: + case cartouche: + elt = elt->next; + level--; + break; + + default: + done = 1; + } + } + + if (!level) + return ((char *) NULL); + else + return (elt->item_function); +} + +char * +get_item_function () +{ + char *item_function; + get_rest_of_line (&item_function); + backup_input_pointer (); + canon_white (item_function); + return (item_function); +} + + /* Push the state of the current insertion on the stack. */ +push_insertion (type, item_function) + enum insertion_type type; + char *item_function; +{ + INSERTION_ELT *new = (INSERTION_ELT *) xmalloc (sizeof (INSERTION_ELT)); + + new->item_function = item_function; + new->filling_enabled = filling_enabled; + new->indented_fill = indented_fill; + new->insertion = type; + new->line_number = line_number; + new->inhibited = inhibit_paragraph_indentation; + new->next = insertion_stack; + insertion_stack = new; + insertion_level++; +} + + /* Pop the value on top of the insertion stack into the + global variables. */ +pop_insertion () +{ + INSERTION_ELT *temp = insertion_stack; + + if (temp == (INSERTION_ELT *) NULL) + return; + + inhibit_paragraph_indentation = temp->inhibited; + filling_enabled = temp->filling_enabled; + indented_fill = temp->indented_fill; + free_and_clear (&(temp->item_function)); + insertion_stack = insertion_stack->next; + free (temp); + insertion_level--; +} + + /* Return a pointer to the print name of this + enumerated type. */ +char * +insertion_type_pname (type) + enum insertion_type type; +{ + if ((int) type < (int) bad_type) + return (insertion_type_names[(int) type]); + else + return ("Broken-Type in insertion_type_pname"); +} + +/* Return the insertion_type associated with NAME. + If the type is not one of the known ones, return BAD_TYPE. */ +enum insertion_type +find_type_from_name (name) + char *name; +{ + int index = 0; + while (index < (int) bad_type) + { + if (strcmp (name, insertion_type_names[index]) == 0) + return (enum insertion_type) index; + index++; + } + return (bad_type); +} + +do_nothing () +{ +} + +int +defun_insertion (type) + enum insertion_type type; +{ + return + ((type == deffn) + || (type == defun) + || (type == defmac) + || (type == defspec) + || (type == defvr) + || (type == defvar) + || (type == defopt) + || (type == deftypefn) + || (type == deftypefun) + || (type == deftypevr) + || (type == deftypevar) + || (type == defcv) + || (type == defivar) + || (type == defop) + || (type == defmethod) + || (type == deftypemethod) + || (type == deftp)); +} + +/* MAX_NS is the maximum nesting level for enumerations. I picked 100 + which seemed reasonable. This doesn't control the number of items, + just the number of nested lists. */ +#define max_stack_depth 100 +#define ENUM_DIGITS 1 +#define ENUM_ALPHA 2 +typedef struct { + int enumtype; + int enumval; +} DIGIT_ALPHA; + +DIGIT_ALPHA enumstack[max_stack_depth]; +int enumstack_offset = 0; +int current_enumval = 1; +int current_enumtype = ENUM_DIGITS; +char *enumeration_arg = (char *)NULL; + +start_enumerating (at, type) + int at, type; +{ + if ((enumstack_offset + 1) == max_stack_depth) + { + line_error ("Enumeration stack overflow"); + return; + } + enumstack[enumstack_offset].enumtype = current_enumtype; + enumstack[enumstack_offset].enumval = current_enumval; + enumstack_offset++; + current_enumval = at; + current_enumtype = type; +} + +stop_enumerating () +{ + --enumstack_offset; + if (enumstack_offset < 0) + enumstack_offset = 0; + + current_enumval = enumstack[enumstack_offset].enumval; + current_enumtype = enumstack[enumstack_offset].enumtype; +} + +/* Place a letter or digits into the output stream. */ +enumerate_item () +{ + char temp[10]; + + if (current_enumtype == ENUM_ALPHA) + { + if (current_enumval == ('z' + 1) || current_enumval == ('Z' + 1)) + { + current_enumval = ((current_enumval - 1) == 'z' ? 'a' : 'A'); + warning ("Lettering overflow, restarting at %c", current_enumval); + } + sprintf (temp, "%c. ", current_enumval); + } + else + sprintf (temp, "%d. ", current_enumval); + + indent (output_column += (current_indent - strlen (temp))); + add_word (temp); + current_enumval++; +} + +/* This is where the work for all the "insertion" style + commands is done. A huge switch statement handles the + various setups, and generic code is on both sides. */ +begin_insertion (type) + enum insertion_type type; +{ + int no_discard = 0; + + if (defun_insertion (type)) + { + push_insertion (type, savestring ("")); + no_discard++; + } + else + push_insertion (type, get_item_function ()); + + switch (type) + { + case menu: + if (!no_headers) + close_paragraph (); + + filling_enabled = no_indent = 0; + inhibit_paragraph_indentation = 1; + + if (!no_headers) + add_word ("* Menu:\n"); + + in_menu++; + no_discard++; + break; + + /* I think @quotation is meant to do filling. + If you don't want filling, then use @example. */ + case quotation: + close_single_paragraph (); + last_char_was_newline = no_indent = 0; + indented_fill = filling_enabled = 1; + inhibit_paragraph_indentation = 1; + current_indent += default_indentation_increment; + break; + + case display: + case example: + case smallexample: + case lisp: + case smalllisp: + /* Just like @example, but no indentation. */ + case format: + + close_single_paragraph (); + inhibit_paragraph_indentation = 1; + in_fixed_width_font++; + filling_enabled = 0; + last_char_was_newline = 0; + + if (type != format) + current_indent += default_indentation_increment; + + break; + + case table: + case ftable: + case vtable: + case itemize: + close_single_paragraph (); + current_indent += default_indentation_increment; + filling_enabled = indented_fill = 1; +#if defined (INDENT_PARAGRAPHS_IN_TABLE) + inhibit_paragraph_indentation = 0; +#else + inhibit_paragraph_indentation = 1; +#endif /* !INDENT_PARAGRAPHS_IN_TABLE */ + + /* Make things work for losers who forget the itemize syntax. */ + if (type == itemize) + { + if (!(*insertion_stack->item_function)) + { + free (insertion_stack->item_function); + insertion_stack->item_function = savestring ("@bullet"); + } + } + break; + + case enumerate: + close_single_paragraph (); + no_indent = 0; +#if defined (INDENT_PARAGRAPHS_IN_TABLE) + inhibit_paragraph_indentation = 0; +#else + inhibit_paragraph_indentation = 1; +#endif /* !INDENT_PARAGRAPHS_IN_TABLE */ + + current_indent += default_indentation_increment; + filling_enabled = indented_fill = 1; + + if (isdigit (*enumeration_arg)) + start_enumerating (atoi (enumeration_arg), ENUM_DIGITS); + else + start_enumerating (*enumeration_arg, ENUM_ALPHA); + break; + + /* Does nothing special in makeinfo. */ + case group: + /* Only close the paragraph if we are not inside of an @example. */ + if (!insertion_stack->next || + insertion_stack->next->insertion != example) + close_single_paragraph (); + break; + + /* Insertions that are no-ops in info, but do something in TeX. */ + case ifinfo: + case ifset: + case ifclear: + case cartouche: + if (in_menu) + no_discard++; + break; + + case deffn: + case defun: + case defmac: + case defspec: + case defvr: + case defvar: + case defopt: + case deftypefn: + case deftypefun: + case deftypevr: + case deftypevar: + case defcv: + case defivar: + case defop: + case defmethod: + case deftypemethod: + case deftp: + inhibit_paragraph_indentation = 1; + filling_enabled = indented_fill = 1; + current_indent += default_indentation_increment; + no_indent = 0; + break; + + case flushleft: + close_single_paragraph (); + inhibit_paragraph_indentation = 1; + filling_enabled = indented_fill = no_indent = 0; + break; + + case flushright: + close_single_paragraph (); + filling_enabled = indented_fill = no_indent = 0; + inhibit_paragraph_indentation = 1; + force_flush_right++; + break; + } + + if (!no_discard) + discard_until ("\n"); +} + +/* Try to end the insertion with the specified TYPE. + TYPE, with a value of bad_type, gets translated to match + the value currently on top of the stack. + Otherwise, if TYPE doesn't match the top of the insertion stack, + give error. */ +end_insertion (type) + enum insertion_type type; +{ + enum insertion_type temp_type; + + if (!insertion_level) + return; + + temp_type = current_insertion_type (); + + if (type == bad_type) + type = temp_type; + + if (type != temp_type) + { + line_error + ("`%cend' expected `%s', but saw `%s'.", COMMAND_PREFIX, + insertion_type_pname (temp_type), insertion_type_pname (type)); + return; + } + + pop_insertion (); + + switch (type) + { + /* Insertions which have no effect on paragraph formatting. */ + case ifinfo: + case ifset: + case ifclear: + break; + + case menu: + in_menu--; /* No longer hacking menus. */ + if (!no_headers) + close_insertion_paragraph (); + break; + + case enumerate: + stop_enumerating (); + close_insertion_paragraph (); + current_indent -= default_indentation_increment; + break; + + case flushleft: + case group: + case cartouche: + close_insertion_paragraph (); + break; + + case format: + case display: + case example: + case smallexample: + case lisp: + case smalllisp: + case quotation: + + /* @quotation is the only one of the above without a fixed width + font. */ + if (type != quotation) + in_fixed_width_font--; + + /* @format is the only fixed_width insertion without a change + in indentation. */ + if (type != format) + current_indent -= default_indentation_increment; + + /* The ending of one of these insertions always marks the + start of a new paragraph. */ + close_insertion_paragraph (); + break; + + case table: + case ftable: + case vtable: + case itemize: + current_indent -= default_indentation_increment; + break; + + case flushright: + force_flush_right--; + close_insertion_paragraph (); + break; + + /* Handle the @defun style insertions with a default clause. */ + default: + current_indent -= default_indentation_increment; + close_insertion_paragraph (); + break; + } +} + +/* Insertions cannot cross certain boundaries, such as node beginnings. In + code that creates such boundaries, you should call discard_insertions () + before doing anything else. It prints the errors for you, and cleans up + the insertion stack. */ +discard_insertions () +{ + int real_line_number = line_number; + while (insertion_stack) + { + if (insertion_stack->insertion == ifinfo || + insertion_stack->insertion == ifset || + insertion_stack->insertion == ifclear || + insertion_stack->insertion == cartouche) + break; + else + { + char *offender = (char *) + insertion_type_pname (insertion_stack->insertion); + + line_number = insertion_stack->line_number; + line_error ("This `%s' doesn't have a matching `%cend %s'", offender, + COMMAND_PREFIX, offender); + pop_insertion (); + } + } + line_number = real_line_number; +} + +/* The actual commands themselves. */ + +/* Commands which insert themselves. */ +insert_self () +{ + add_word (command); +} + +/* Force a line break in the output. */ +cm_asterisk () +{ + close_single_paragraph (); +#if !defined (ASTERISK_NEW_PARAGRAPH) + cm_noindent (); +#endif /* ASTERISK_NEW_PARAGRAPH */ +} + +/* Insert ellipsis. */ +cm_dots (arg) + int arg; +{ + if (arg == START) + add_word ("..."); +} + +cm_bullet (arg) + int arg; +{ + if (arg == START) + add_char ('*'); +} + +cm_minus (arg) + int arg; +{ + if (arg == START) + add_char ('-'); +} + +/* Insert "TeX". */ +cm_TeX (arg) + int arg; +{ + if (arg == START) + add_word ("TeX"); +} + +cm_copyright (arg) + int arg; +{ + if (arg == START) + add_word ("(C)"); +} + +cm_today (arg) + int arg; +{ + static char * months [12] = + { "January", "February", "March", "April", "May", "June", "July", + "August", "September", "October", "November", "December" }; + if (arg == START) + { + long timer = (time (0)); + struct tm *ts = (localtime (&timer)); + add_word_args + ("%d %s %d", + (ts -> tm_mday), + (months [ts -> tm_mon]), + ((ts -> tm_year) + 1900)); + } +} + +cm_code (arg) + int arg; +{ + extern int printing_index; + + if (printing_index) + return; + + if (arg == START) + { + in_fixed_width_font++; + add_char ('`'); + } + else + { + add_word ("'"); + in_fixed_width_font--; + } +} + +cm_samp (arg) + int arg; +{ + cm_code (arg); +} + +cm_file (arg) + int arg; +{ + cm_code (arg); +} + +cm_kbd (arg) + int arg; +{ + cm_code (arg); +} + +cm_key (arg) + int arg; +{ +} + +/* Convert the character at position into CTL. */ +cm_ctrl (arg, position) + int arg, position; +{ + if (arg == END) + output_paragraph[position - 1] = CTL (output_paragraph[position]); +} + +/* Small Caps in makeinfo just does all caps. */ +cm_sc (arg, start_pos, end_pos) + int arg, start_pos, end_pos; +{ + if (arg == END) + { + while (start_pos < end_pos) + { + output_paragraph[start_pos] = + coerce_to_upper (output_paragraph[start_pos]); + start_pos++; + } + } +} + +/* @var in makeinfo just uppercases the text. */ +cm_var (arg, start_pos, end_pos) + int arg, start_pos, end_pos; +{ + if (arg == END) + { + while (start_pos < end_pos) + { + output_paragraph[start_pos] = + coerce_to_upper (output_paragraph[start_pos]); + start_pos++; + } + } +} + +cm_dfn (arg, position) + int arg, position; +{ + add_char ('"'); +} + +cm_emph (arg) + int arg; +{ + add_char ('*'); +} + +cm_strong (arg, position) + int arg, position; +{ + cm_emph (arg); +} + +cm_cite (arg, position) + int arg, position; +{ + if (arg == START) + add_word ("`"); + else + add_word ("'"); +} + +/* Current text is italicized. */ +cm_italic (arg, start, end) + int arg, start, end; +{ +} + +/* Current text is highlighted. */ +cm_bold (arg, start, end) + int arg, start, end; +{ + cm_italic (arg); +} + +/* Current text is in roman font. */ +cm_roman (arg, start, end) + int arg, start, end; +{ +} + +/* Current text is in roman font. */ +cm_titlefont (arg, start, end) + int arg, start, end; +{ +} + +/* Italicize titles. */ +cm_title (arg, start, end) + int arg, start, end; +{ + cm_italic (arg); +} + +/* @refill is a NOP. */ +cm_refill () +{ +} + +/* Prevent the argument from being split across two lines. */ +cm_w (arg, start, end) + int arg, start, end; +{ + if (arg == START) + non_splitting_words++; + else + non_splitting_words--; +} + + +/* Explain that this command is obsolete, thus the user shouldn't + do anything with it. */ +cm_obsolete (arg, start, end) + int arg, start, end; +{ + if (arg == START) + warning ("The command `@%s' is obsolete", command); +} + +/* Insert the text following input_text_offset up to the end of the line + in a new, separate paragraph. Directly underneath it, insert a + line of WITH_CHAR, the same length of the inserted text. */ +insert_and_underscore (with_char) + int with_char; +{ + int len, i, old_no_indent; + int starting_pos, ending_pos; + char *temp; + + close_paragraph (); + filling_enabled = indented_fill = 0; + old_no_indent = no_indent; + no_indent = 1; + get_rest_of_line (&temp); + + starting_pos = output_position + output_paragraph_offset; + execute_string ("%s\n", temp); + ending_pos = output_position + output_paragraph_offset; + free (temp); + + len = (ending_pos - starting_pos) - 1; + for (i = 0; i < len; i++) + add_char (with_char); + insert ('\n'); + close_paragraph (); + filling_enabled = 1; + no_indent = old_no_indent; +} + +/* Here is a structure which associates sectioning commands with + an integer, hopefully to reflect the `depth' of the current + section. */ +struct { + char *name; + int level; +} section_alist[] = { + { "unnumberedsubsubsec", 5 }, + { "unnumberedsubsec", 4 }, + { "unnumberedsec", 3 }, + { "unnumbered", 2 }, + { "appendixsubsubsec", 5 }, + { "appendixsubsec", 4 }, + { "appendixsec", 3 }, + { "appendixsection", 3 }, + { "appendix", 2 }, + { "subsubsec", 5 }, + { "subsubsection", 5 }, + { "subsection", 4 }, + { "section", 3 }, + { "chapter", 2 }, + { "top", 1 }, + + { (char *)NULL, 0 } +}; + +/* Amount to offset the name of sectioning commands to levels by. */ +int section_alist_offset = 0; + +/* Shift the meaning of @section to @chapter. */ +cm_raisesections () +{ + discard_until ("\n"); + section_alist_offset--; +} + +/* Shift the meaning of @chapter to @section. */ +cm_lowersections () +{ + discard_until ("\n"); + section_alist_offset++; +} + +/* Return an integer which identifies the type section present in TEXT. */ +int +what_section (text) + char *text; +{ + register int i, j; + char *t; + + find_section_command: + for (j = 0; text[j] && cr_or_whitespace (text[j]); j++); + if (text[j] != '@') + return (-1); + + text = text + j + 1; + + /* We skip @c, @comment, and @?index commands. */ + if ((strncmp (text, "comment", strlen ("comment")) == 0) || + (text[0] == 'c' && cr_or_whitespace (text[1])) || + (strcmp (text + 1, "index") == 0)) + { + while (*text++ != '\n'); + goto find_section_command; + } + + /* Handle italicized sectioning commands. */ + if (*text == 'i') + text++; + + for (j = 0; text[j] && !cr_or_whitespace (text[j]); j++); + + for (i = 0; t = section_alist[i].name; i++) + { + if (j == strlen (t) && strncmp (t, text, j) == 0) + { + int return_val; + + return_val = (section_alist[i].level + section_alist_offset); + + if (return_val < 0) + return_val = 0; + else if (return_val > 5) + return_val = 5; + return (return_val); + } + } + return (-1); +} + +/* Treat this just like @unnumbered. The only difference is + in node defaulting. */ +cm_top () +{ + static int top_encountered = 0; + cm_unnumbered (); + + /* It is an error to have more than one @top. */ + if (top_encountered) + { + TAG_ENTRY *tag = tag_table; + + line_error ("There already is a node having @top as a section"); + + while (tag != (TAG_ENTRY *)NULL) + { + if ((tag->flags & IS_TOP)) + { + int old_line_number = line_number; + char *old_input_filename = input_filename; + + line_number = tag->line_no; + input_filename = tag->filename; + line_error ("Here is the @top node."); + input_filename = old_input_filename; + line_number = old_line_number; + return; + } + tag = tag->next_ent; + } + } + else + { + top_encountered = 1; + + /* The most recently defined node is the top node. */ + if (tag_table) + tag_table->flags |= IS_TOP; + + /* Now set the logical hierarchical level of the Top node. */ + { + int orig_offset = input_text_offset; + + input_text_offset = search_forward ("\n@node", orig_offset); + + if (input_text_offset > 0) + { + int this_section; + + /* Move to the end of this line, and find out what the + sectioning command is here. */ + while (input_text[input_text_offset] != '\n') + input_text_offset++; + + if (input_text_offset < size_of_input_text) + input_text_offset++; + + this_section = what_section (input_text + input_text_offset); + + /* If we found a sectioning command, then give the top section + a level of this section - 1. */ + if (this_section != -1) + { + register int i; + + for (i = 0; section_alist[i].name; i++) + if (strcmp (section_alist[i].name, "Top") == 0) + { + section_alist[i].level = this_section - 1; + break; + } + } + } + input_text_offset = orig_offset; + } + } +} + +/* Organized by level commands. That is, "*" == chapter, "=" == section. */ +char *scoring_characters = "*=-."; + +void +sectioning_underscore (command) + char *command; +{ + char character; + int level; + + level = what_section (command); + level -= 2; + + if (level < 0) + level = 0; + + character = scoring_characters[level]; + + insert_and_underscore (character); +} + +/* The remainder of the text on this line is a chapter heading. */ +cm_chapter () +{ + sectioning_underscore ("@chapter"); +} + +/* The remainder of the text on this line is a section heading. */ +cm_section () +{ + sectioning_underscore ("@section"); +} + +/* The remainder of the text on this line is a subsection heading. */ +cm_subsection () +{ + sectioning_underscore ("@subsection"); +} + +/* The remainder of the text on this line is a subsubsection heading. */ +cm_subsubsection () +{ + sectioning_underscore ("@subsubsection"); +} + +/* The remainder of the text on this line is an unnumbered heading. */ +cm_unnumbered () +{ + cm_chapter (); +} + +/* The remainder of the text on this line is an unnumbered section heading. */ +cm_unnumberedsec () +{ + cm_section (); +} + +/* The remainder of the text on this line is an unnumbered + subsection heading. */ +cm_unnumberedsubsec () +{ + cm_subsection (); +} + +/* The remainder of the text on this line is an unnumbered + subsubsection heading. */ +cm_unnumberedsubsubsec () +{ + cm_subsubsection (); +} + +/* The remainder of the text on this line is an appendix heading. */ +cm_appendix () +{ + cm_chapter (); +} + +/* The remainder of the text on this line is an appendix section heading. */ +cm_appendixsec () +{ + cm_section (); +} + +/* The remainder of the text on this line is an appendix subsection heading. */ +cm_appendixsubsec () +{ + cm_subsection (); +} + +/* The remainder of the text on this line is an appendix + subsubsection heading. */ +cm_appendixsubsubsec () +{ + cm_subsubsection (); +} + +/* Compatibility functions substitute for chapter, section, etc. */ +cm_majorheading () +{ + cm_chapheading (); +} + +cm_chapheading () +{ + cm_chapter (); +} + +cm_heading () +{ + cm_section (); +} + +cm_subheading () +{ + cm_subsection (); +} + +cm_subsubheading () +{ + cm_subsubsection (); +} + + +/* **************************************************************** */ +/* */ +/* Adding nodes, and making tags */ +/* */ +/* **************************************************************** */ + +/* Start a new tag table. */ +init_tag_table () +{ + while (tag_table != (TAG_ENTRY *) NULL) + { + TAG_ENTRY *temp = tag_table; + free (temp->node); + free (temp->prev); + free (temp->next); + free (temp->up); + tag_table = tag_table->next_ent; + free (temp); + } +} + +write_tag_table () +{ + return (write_tag_table_internal (0)); /* Not indirect. */ +} + +write_tag_table_indirect () +{ + return (write_tag_table_internal (1)); +} + +/* Write out the contents of the existing tag table. + INDIRECT_P says how to format the output. */ +write_tag_table_internal (indirect_p) + int indirect_p; +{ + TAG_ENTRY *node = tag_table; + int old_indent = no_indent; + + no_indent = 1; + filling_enabled = 0; + must_start_paragraph = 0; + close_paragraph (); + + if (!indirect_p) + { + no_indent = 1; + insert ('\n'); + } + + add_word_args ("\037\nTag Table:\n%s", indirect_p ? "(Indirect)\n" : ""); + + while (node != (TAG_ENTRY *) NULL) + { + add_word_args ("Node: %s\177%d\n", node->node, node->position); + node = node->next_ent; + } + + add_word ("\037\nEnd Tag Table\n"); + flush_output (); + no_indent = old_indent; +} + +char * +get_node_token () +{ + char *string; + + get_until_in_line (",", &string); + + if (curchar () == ',') + input_text_offset++; + + canon_white (string); + + /* Allow things like @@nodename. */ + normalize_node_name (string); + + return (string); +} + +/* Given a node name in STRING, remove double @ signs, replacing them + with just one. Convert "top" and friends into "Top". */ +normalize_node_name (string) + char *string; +{ + register int i, l = strlen (string); + + for (i = 0; i < l; i++) + { + if (string[i] == '@' && string[i + 1] == '@') + { + strncpy (string + i, string + i + 1, l - i); + l--; + } + } + if (stricmp (string, "Top") == 0) + strcpy (string, "Top"); +} + +/* Look up NAME in the tag table, and return the associated + tag_entry. If the node is not in the table return NULL. */ +TAG_ENTRY * +find_node (name) + char *name; +{ + TAG_ENTRY *tag = tag_table; + + while (tag != (TAG_ENTRY *) NULL) + { + if (strcmp (tag->node, name) == 0) + return (tag); + tag = tag->next_ent; + } + return ((TAG_ENTRY *) NULL); +} + +/* Remember NODE and associates. */ +remember_node (node, prev, next, up, position, line_no, no_warn) + char *node, *prev, *next, *up; + int position, line_no, no_warn; +{ + /* Check for existence of this tag already. */ + if (validating) + { + register TAG_ENTRY *tag = find_node (node); + if (tag) + { + line_error ("Node `%s' multiply defined (%d is first definition)", + node, tag->line_no); + return; + } + } + + /* First, make this the current node. */ + current_node = node; + + /* Now add it to the list. */ + { + TAG_ENTRY *new = (TAG_ENTRY *) xmalloc (sizeof (TAG_ENTRY)); + new->node = node; + new->prev = prev; + new->next = next; + new->up = up; + new->position = position; + new->line_no = line_no; + new->filename = node_filename; + new->touched = 0; /* not yet referenced. */ + new->flags = 0; + if (no_warn) + new->flags |= NO_WARN; + new->next_ent = tag_table; + tag_table = new; + } +} + +/* The order is: nodename, nextnode, prevnode, upnode. + If all of the NEXT, PREV, and UP fields are empty, they are defaulted. + You must follow a node command which has those fields defaulted + with a sectioning command (e.g. @chapter) giving the "level" of that node. + It is an error not to do so. + The defaults come from the menu in this nodes parent. */ +cm_node () +{ + char *node, *prev, *next, *up; + int new_node_pos, defaulting, this_section, no_warn = 0; + extern int already_outputting_pending_notes; + + if (strcmp (command, "nwnode") == 0) + no_warn = 1; + + /* Get rid of unmatched brace arguments from previous commands. */ + discard_braces (); + + /* There also might be insertions left lying around that haven't been + ended yet. Do that also. */ + discard_insertions (); + + if (!already_outputting_pending_notes) + { + close_paragraph (); + output_pending_notes (); + free_pending_notes (); + } + + filling_enabled = indented_fill = 0; + new_node_pos = output_position; + current_footnote_number = 1; + + node = get_node_token (); + next = get_node_token (); + prev = get_node_token (); + up = get_node_token (); + + no_indent = 1; + if (!no_headers) + add_word_args ("\037\nFile: %s, Node: %s", pretty_output_filename, node); + + /* Check for defaulting of this node's next, prev, and up fields. */ + defaulting = ((strlen (next) == 0) && + (strlen (prev) == 0) && + (strlen (up) == 0)); + + this_section = what_section (input_text + input_text_offset); + + /* If we are defaulting, then look at the immediately following + sectioning command (error if none) to determine the node's + level. Find the node that contains the menu mentioning this node + that is one level up (error if not found). That node is the "Up" + of this node. Default the "Next" and "Prev" from the menu. */ + if (defaulting) + { + NODE_REF *last_ref = (NODE_REF *)NULL; + NODE_REF *ref = node_references; + + if (this_section < 0) + { + char *polite_section_name = "top"; + int i; + + for (i = 0; section_alist[i].name; i++) + if (section_alist[i].level == current_section + 1) + { + polite_section_name = section_alist[i].name; + break; + } + + line_error + ("Node `%s' requires a sectioning command (e.g. @%s)", + node, polite_section_name); + } + else + { + if (stricmp (node, "Top") == 0) + { + /* Default the NEXT pointer to be the first menu item in + this node, if there is a menu in this node. */ + { + int orig_offset, orig_size; + char *glean_node_from_menu (); + + orig_offset = input_text_offset; + orig_size = search_forward ("\n@node ", orig_offset); + + if (orig_size < 0) + orig_size = size_of_input_text; + + input_text_offset = search_forward ("\n@menu", orig_offset); + if (input_text_offset > -1) + { + char *nodename_from_menu = (char *)NULL; + + input_text_offset = + search_forward ("\n* ", input_text_offset); + + if (input_text_offset != -1) + nodename_from_menu = glean_node_from_menu (0); + + if (nodename_from_menu) + { + free (next); + next = nodename_from_menu; + prev = savestring ("(DIR)"); + up = savestring ("(DIR)"); + } + } + input_text_offset = orig_offset; + } + } + + while (ref) + { + if (ref->section == (this_section - 1) && + ref->type == menu_reference && + strcmp (ref->node, node) == 0) + { + char *containing_node = ref->containing_node; + + free (up); + up = savestring (containing_node); + + if (last_ref && + last_ref->type == menu_reference && + (strcmp (last_ref->containing_node, + containing_node) == 0)) + { + free (next); + next = savestring (last_ref->node); + } + + while ((ref->section == this_section - 1) && + (ref->next) && + (ref->next->type != menu_reference)) + ref = ref->next; + + if (ref->next && ref->type == menu_reference && + (strcmp (ref->next->containing_node, + containing_node) == 0)) + { + free (prev); + prev = savestring (ref->next->node); + } + else if (!ref->next && + stricmp (ref->containing_node, "Top") == 0) + { + free (prev); + prev = savestring (ref->containing_node); + } + break; + } + last_ref = ref; + ref = ref->next; + } + } + } + + if (!no_headers) + { + if (*next) + add_word_args (", Next: %s", next); + + if (*prev) + add_word_args (", Prev: %s", prev); + + if (*up) + add_word_args (", Up: %s", up); + } + + close_paragraph (); + no_indent = 0; + + if (!*node) + { + line_error ("No node name specified for `@%s' command", command); + free (node); + free (next); + free (prev); + free (up); + } + else + { + if (!*next) { free (next); next = (char *)NULL; } + if (!*prev) { free (prev); prev = (char *)NULL; } + if (!*up) { free (up); up = (char *)NULL; } + remember_node (node, prev, next, up, new_node_pos, line_number, no_warn); + } + + /* Change the section only if there was a sectioning command. */ + if (this_section >= 0) + current_section = this_section; + + filling_enabled = 1; +} + +/* Validation of an info file. + Scan through the list of tag entrys touching the Prev, Next, and Up + elements of each. It is an error not to be able to touch one of them, + except in the case of external node references, such as "(DIR)". + + If the Prev is different from the Up, + then the Prev node must have a Next pointing at this node. + + Every node except Top must have an Up. + The Up node must contain some sort of reference, other than a Next, + to this node. + + If the Next is different from the Next of the Up, + then the Next node must have a Prev pointing at this node. */ +validate_file (filename, tag_table) + char *filename; + TAG_ENTRY *tag_table; +{ + char *old_input_filename = input_filename; + TAG_ENTRY *tags = tag_table; + + while (tags != (TAG_ENTRY *) NULL) + { + register TAG_ENTRY *temp_tag; + + input_filename = tags->filename; + line_number = tags->line_no; + + /* If this is a "no warn" node, don't validate it in any way. */ + if (tags->flags & NO_WARN) + { + tags = tags->next_ent; + continue; + } + + /* If this node has a Next, then make sure that the Next exists. */ + if (tags->next) + { + validate (tags->next, tags->line_no, "Next"); + + /* If the Next node exists, and there is no Up, then make + sure that the Prev of the Next points back. */ + if (temp_tag = find_node (tags->next)) + { + char *prev; + + if (temp_tag->flags & NO_WARN) + { + /* Do nothing if we aren't supposed to issue warnings + about this node. */ + } + else + { + prev = temp_tag->prev; + if (!prev || (strcmp (prev, tags->node) != 0)) + { + line_error ("Node `%s''s Next field not pointed back to", + tags->node); + line_number = temp_tag->line_no; + input_filename = temp_tag->filename; + line_error + ("This node (`%s') is the one with the bad `Prev'", + temp_tag->node); + input_filename = tags->filename; + line_number = tags->line_no; + temp_tag->flags |= PREV_ERROR; + } + } + } + } + + /* Validate the Prev field if there is one, and we haven't already + complained about it in some way. You don't have to have a Prev + field at this stage. */ + if (!(tags->flags & PREV_ERROR) && tags->prev) + { + int valid = validate (tags->prev, tags->line_no, "Prev"); + + if (!valid) + tags->flags |= PREV_ERROR; + else + { + /* If the Prev field is not the same as the Up field, + then the node pointed to by the Prev field must have + a Next field which points to this node. */ + if (tags->up && (strcmp (tags->prev, tags->up) != 0)) + { + temp_tag = find_node (tags->prev); + + /* If we aren't supposed to issue warnings about the + target node, do nothing. */ + if (!temp_tag || (temp_tag->flags & NO_WARN)) + { + /* Do nothing. */ + } + else + { + if (!temp_tag->next || + (strcmp (temp_tag->next, tags->node) != 0)) + { + line_error + ("Node `%s''s Prev field not pointed back to", + tags->node); + line_number = temp_tag->line_no; + input_filename = temp_tag->filename; + line_error + ("This node (`%s') is the one with the bad `Next'", + temp_tag->node); + input_filename = tags->filename; + line_number = tags->line_no; + temp_tag->flags |= NEXT_ERROR; + } + } + } + } + } + + if (!tags->up && (stricmp (tags->node, "Top") != 0)) + line_error ("Node `%s' is missing an \"Up\" field", tags->node); + else if (tags->up) + { + int valid = validate (tags->up, tags->line_no, "Up"); + + /* If node X has Up: Y, then warn if Y fails to have a menu item + or note pointing at X, if Y isn't of the form "(Y)". */ + if (valid && *tags->up != '(') + { + NODE_REF *nref, *tref, *list; + NODE_REF *find_node_reference (); + + tref = (NODE_REF *) NULL; + list = node_references; + + for (;;) + { + if (!(nref = find_node_reference (tags->node, list))) + break; + + if (strcmp (nref->containing_node, tags->up) == 0) + { + if (nref->type != menu_reference) + { + tref = nref; + list = nref->next; + } + else + break; + } + list = nref->next; + } + + if (!nref) + { + temp_tag = find_node (tags->up); + line_number = temp_tag->line_no; + filename = temp_tag->filename; + if (!tref) + line_error ( +"`%s' has an Up field of `%s', but `%s' has no menu item for `%s'", + tags->node, tags->up, tags->up, tags->node); + line_number = tags->line_no; + filename = tags->filename; + } + } + } + tags = tags->next_ent; + } + + validate_other_references (node_references); + /* We have told the user about the references which didn't exist. + Now tell him about the nodes which aren't referenced. */ + + tags = tag_table; + while (tags != (TAG_ENTRY *) NULL) + { + /* If this node is a "no warn" node, do nothing. */ + if (tags->flags & NO_WARN) + { + tags = tags->next_ent; + continue; + } + + /* Special hack. If the node in question appears to have + been referenced more than REFERENCE_WARNING_LIMIT times, + give a warning. */ + if (tags->touched > reference_warning_limit) + { + input_filename = tags->filename; + line_number = tags->line_no; + warning ("Node `%s' has been referenced %d times", + tags->node, tags->touched); + } + + if (tags->touched == 0) + { + input_filename = tags->filename; + line_number = tags->line_no; + + /* Notice that the node "Top" is special, and doesn't have to + be referenced. */ + if (stricmp (tags->node, "Top") != 0) + warning ("Unreferenced node `%s'", tags->node); + } + tags = tags->next_ent; + } + input_filename = old_input_filename; +} + +/* Return 1 if tag correctly validated, or 0 if not. */ +validate (tag, line, label) + char *tag; + int line; + char *label; +{ + TAG_ENTRY *result; + + /* If there isn't a tag to verify, or if the tag is in another file, + then it must be okay. */ + if (!tag || !*tag || *tag == '(') + return (1); + + /* Otherwise, the tag must exist. */ + result = find_node (tag); + + if (!result) + { + line_number = line; + line_error ( +"Validation error. `%s' field points to node `%s', which doesn't exist", + label, tag); + return (0); + } + result->touched++; + return (1); +} + +/* Split large output files into a series of smaller files. Each file + is pointed to in the tag table, which then gets written out as the + original file. The new files have the same name as the original file + with a "-num" attached. SIZE is the largest number of bytes to allow + in any single split file. */ +split_file (filename, size) + char *filename; + int size; +{ + char *root_filename, *root_pathname; + char *the_file, *filename_part (); + struct stat fileinfo; + char *the_header; + int header_size; + + /* Can only do this to files with tag tables. */ + if (!tag_table) + return; + + if (size == 0) + size = DEFAULT_SPLIT_SIZE; + + if ((stat (filename, &fileinfo) != 0) || + (fileinfo.st_size < SPLIT_SIZE_THRESHOLD)) + return; + + the_file = find_and_load (filename); + if (!the_file) + return; + + root_filename = filename_part (filename); + root_pathname = pathname_part (filename); + + if (!root_pathname) + root_pathname = savestring (""); + + /* Start splitting the file. Walk along the tag table + outputting sections of the file. When we have written + all of the nodes in the tag table, make the top-level + pointer file, which contains indirect pointers and + tags for the nodes. */ + { + int which_file = 1; + TAG_ENTRY *tags = tag_table; + char *indirect_info = (char *)NULL; + + /* Remember the `header' of this file. The first tag in the file is + the bottom of the header; the top of the file is the start. */ + the_header = (char *)xmalloc (1 + (header_size = tags->position)); + memcpy (the_header, the_file, header_size); + + while (tags) + { + int file_top, file_bot, limit; + + /* Have to include the Control-_. */ + file_top = file_bot = tags->position; + limit = file_top + size; + + /* If the rest of this file is only one node, then + that is the entire subfile. */ + if (!tags->next_ent) + { + int i = tags->position + 1; + char last_char = the_file[i]; + + while (i < fileinfo.st_size) + { + if ((the_file[i] == '\037') && + ((last_char == '\n') || + (last_char == '\014'))) + break; + else + last_char = the_file[i]; + i++; + } + file_bot = i; + tags = tags->next_ent; + goto write_region; + } + + /* Otherwise, find the largest number of nodes that can fit in + this subfile. */ + for (; tags; tags = tags->next_ent) + { + if (!tags->next_ent) + { + /* This entry is the last node. Search forward for the end + of this node, and that is the end of this file. */ + int i = tags->position + 1; + char last_char = the_file[i]; + + while (i < fileinfo.st_size) + { + if ((the_file[i] == '\037') && + ((last_char == '\n') || + (last_char == '\014'))) + break; + else + last_char = the_file[i]; + i++; + } + file_bot = i; + + if (file_bot < limit) + { + tags = tags->next_ent; + goto write_region; + } + else + { + /* Here we want to write out everything before the last + node, and then write the last node out in a file + by itself. */ + file_bot = tags->position; + goto write_region; + } + } + + if (tags->next_ent->position > limit) + { + if (tags->position == file_top) + tags = tags->next_ent; + + file_bot = tags->position; + + write_region: + { + int fd; + char *split_filename; + + split_filename = (char *) xmalloc + (10 + strlen (root_pathname) + strlen (root_filename)); + sprintf + (split_filename, + "%s%s-%d", root_pathname, root_filename, which_file); + + fd = open + (split_filename, O_WRONLY | O_TRUNC | O_CREAT, 0666); + + if ((fd < 0) || + (write (fd, the_header, header_size) != header_size) || + (write (fd, the_file + file_top, file_bot - file_top) + != (file_bot - file_top)) || + ((close (fd)) < 0)) + { + perror (split_filename); + if (fd != -1) + close (fd); + exit (FATAL); + } + + if (!indirect_info) + { + indirect_info = the_file + file_top; + sprintf (indirect_info, "\037\nIndirect:\n"); + indirect_info += strlen (indirect_info); + } + + sprintf (indirect_info, "%s-%d: %d\n", + root_filename, which_file, file_top); + + free (split_filename); + indirect_info += strlen (indirect_info); + which_file++; + break; + } + } + } + } + + /* We have sucessfully created the subfiles. Now write out the + original again. We must use `output_stream', or + write_tag_table_indirect () won't know where to place the output. */ + output_stream = fopen (filename, "w"); + if (!output_stream) + { + perror (filename); + exit (FATAL); + } + + { + int distance = indirect_info - the_file; + fwrite (the_file, 1, distance, output_stream); + + /* Inhibit newlines. */ + paragraph_is_open = 0; + + write_tag_table_indirect (); + fclose (output_stream); + free (the_header); + free (the_file); + return; + } + } +} + +/* Some menu hacking. This is used to remember menu references while + reading the input file. After the output file has been written, if + validation is on, then we use the contents of NODE_REFERENCES as a + list of nodes to validate. */ +char * +reftype_type_string (type) + enum reftype type; +{ + switch (type) + { + case menu_reference: + return ("Menu"); + case followed_reference: + return ("Followed-Reference"); + default: + return ("Internal-bad-reference-type"); + } +} + +/* Remember this node name for later validation use. */ +remember_node_reference (node, line, type) + char *node; + int line; + enum reftype type; +{ + NODE_REF *temp = (NODE_REF *) xmalloc (sizeof (NODE_REF)); + + temp->next = node_references; + temp->node = savestring (node); + temp->line_no = line; + temp->section = current_section; + temp->type = type; + temp->containing_node = savestring (current_node); + temp->filename = node_filename; + + node_references = temp; +} + +validate_other_references (ref_list) + register NODE_REF *ref_list; +{ + char *old_input_filename = input_filename; + + while (ref_list != (NODE_REF *) NULL) + { + input_filename = ref_list->filename; + validate (ref_list->node, ref_list->line_no, + reftype_type_string (ref_list->type)); + ref_list = ref_list->next; + } + input_filename = old_input_filename; +} + +/* Find NODE in REF_LIST. */ +NODE_REF * +find_node_reference (node, ref_list) + char *node; + register NODE_REF *ref_list; +{ + while (ref_list) + { + if (strcmp (node, ref_list->node) == 0) + break; + ref_list = ref_list->next; + } + return (ref_list); +} + +free_node_references () +{ + register NODE_REF *list, *temp; + + list = node_references; + + while (list) + { + temp = list; + free (list->node); + free (list->containing_node); + list = list->next; + free (temp); + } + node_references = (NODE_REF *) NULL; +} + + /* This function gets called at the start of every line while inside of + a menu. It checks to see if the line starts with "* ", and if so, + remembers the node reference that this menu refers to. + input_text_offset is at the \n just before the line start. */ +#define menu_starter "* " +char * +glean_node_from_menu (remember_reference) + int remember_reference; +{ + int i, orig_offset = input_text_offset; + char *nodename; + + if (strncmp (&input_text[input_text_offset + 1], + menu_starter, + strlen (menu_starter)) != 0) + return ((char *)NULL); + else + input_text_offset += strlen (menu_starter) + 1; + + get_until_in_line (":", &nodename); + if (curchar () == ':') + input_text_offset++; + canon_white (nodename); + + if (curchar () == ':') + goto save_node; + + free (nodename); + get_rest_of_line (&nodename); + + /* Special hack: If the nodename follows the menu item name, + then we have to read the rest of the line in order to find + out what the nodename is. But we still have to read the + line later, in order to process any formatting commands that + might be present. So un-count the carriage return that has just + been counted. */ + line_number--; + + isolate_nodename (nodename); + +save_node: + input_text_offset = orig_offset; + normalize_node_name (nodename); + i = strlen (nodename); + if (i && nodename[i - 1] == ':') + nodename[i - 1] = '\0'; + + if (remember_reference) + { + remember_node_reference (nodename, line_number, menu_reference); + free (nodename); + return ((char *)NULL); + } + else + return (nodename); +} + +static void +isolate_nodename (nodename) + char *nodename; +{ + register int i, c; + int paren_seen, paren; + + if (!nodename) + return; + + canon_white (nodename); + paren_seen = paren = i = 0; + + if (*nodename == '.' || !*nodename) + { + *nodename = '\0'; + return; + } + + if (*nodename == '(') + { + paren++; + paren_seen++; + i++; + } + + for (; c = nodename[i]; i++) + { + if (paren) + { + if (c == '(') + paren++; + else if (c == ')') + paren--; + + continue; + } + + /* If the character following the close paren is a space, then this + node has no more characters associated with it. */ + if (c == '\t' || + c == '\n' || + c == ',' || + ((paren_seen && nodename[i - 1] == ')') && + (c == ' ' || c == '.')) || + (c == '.' && + ((!nodename[i + 1] || + (cr_or_whitespace (nodename[i + 1])) || + (nodename[i + 1] == ')'))))) + break; + } + nodename[i] = '\0'; +} + +cm_menu () +{ + begin_insertion (menu); +} + + +/* **************************************************************** */ +/* */ +/* Cross Reference Hacking */ +/* */ +/* **************************************************************** */ + +char * +get_xref_token () +{ + char *string; + + get_until_in_braces (",", &string); + if (curchar () == ',') + input_text_offset++; + fix_whitespace (string); + return (string); +} + +int px_ref_flag = 0; /* Controls initial output string. */ + +/* Make a cross reference. */ +cm_xref (arg) +{ + if (arg == START) + { + char *arg1, *arg2, *arg3, *arg4, *arg5; + + arg1 = get_xref_token (); + arg2 = get_xref_token (); + arg3 = get_xref_token (); + arg4 = get_xref_token (); + arg5 = get_xref_token (); + + add_word_args ("%s", px_ref_flag ? "*note " : "*Note "); + + if (*arg5 || *arg4) + { + char *node_name; + + if (!*arg2) + { + if (*arg3) + node_name = arg3; + else + node_name = arg1; + } + else + node_name = arg2; + + execute_string ("%s: (%s)%s", node_name, arg4, arg1); + return; + } + else + remember_node_reference (arg1, line_number, followed_reference); + + if (*arg3) + { + if (!*arg2) + execute_string ("%s: %s", arg3, arg1); + else + execute_string ("%s: %s", arg2, arg1); + return; + } + + if (*arg2) + execute_string ("%s: %s", arg2, arg1); + else + execute_string ("%s::", arg1); + } + else + { + + /* Check to make sure that the next non-whitespace character is either + a period or a comma. input_text_offset is pointing at the "}" which + ended the xref or pxref command. */ + int temp = input_text_offset + 1; + + if (output_paragraph[output_paragraph_offset - 2] == ':' && + output_paragraph[output_paragraph_offset - 1] == ':') + return; + while (temp < size_of_input_text) + { + if (cr_or_whitespace (input_text[temp])) + temp++; + else + { + if (input_text[temp] == '.' || + input_text[temp] == ',' || + input_text[temp] == '\t') + return; + else + { + line_error ( + "Cross-reference must be terminated with a period or a comma"); + return; + } + } + } + } +} + +cm_pxref (arg) + int arg; +{ + if (arg == START) + { + px_ref_flag++; + cm_xref (arg); + px_ref_flag--; + } + else + add_char ('.'); +} + +cm_inforef (arg) + int arg; +{ + if (arg == START) + { + char *node, *pname, *file; + + node = get_xref_token (); + pname = get_xref_token (); + file = get_xref_token (); + + execute_string ("*note %s: (%s)%s", pname, file, node); + } +} + +/* **************************************************************** */ +/* */ +/* Insertion Command Stubs */ +/* */ +/* **************************************************************** */ + +cm_quotation () +{ + begin_insertion (quotation); +} + +cm_example () +{ + begin_insertion (example); +} + +cm_smallexample () +{ + begin_insertion (smallexample); +} + +cm_lisp () +{ + begin_insertion (lisp); +} + +cm_smalllisp () +{ + begin_insertion (smalllisp); +} + +/* @cartouche/@end cartouche draws box with rounded corners in + TeX output. Right now, just a NOP insertion. */ +cm_cartouche () +{ + begin_insertion (cartouche); +} + +cm_format () +{ + begin_insertion (format); +} + +cm_display () +{ + begin_insertion (display); +} + +cm_itemize () +{ + begin_insertion (itemize); +} + +cm_enumerate () +{ + do_enumeration (enumerate, "1"); +} + +/* Start an enumeration insertion of type TYPE. If the user supplied + no argument on the line, then use DEFAULT_STRING as the initial string. */ +do_enumeration (type, default_string) + int type; + char *default_string; +{ + get_until_in_line (".", &enumeration_arg); + canon_white (enumeration_arg); + + if (!*enumeration_arg) + { + free (enumeration_arg); + enumeration_arg = savestring (default_string); + } + + if (!isdigit (*enumeration_arg) && !isletter (*enumeration_arg)) + { + warning ("%s requires a letter or a digit", insertion_type_pname (type)); + + switch (type) + { + case enumerate: + default_string = "1"; + break; + } + enumeration_arg = savestring (default_string); + } + begin_insertion (type); +} + +cm_table () +{ + begin_insertion (table); +} + +cm_ftable () +{ + begin_insertion (ftable); +} + +cm_vtable () +{ + begin_insertion (vtable); +} + +cm_group () +{ + begin_insertion (group); +} + +cm_ifinfo () +{ + begin_insertion (ifinfo); +} + +/* Begin an insertion where the lines are not filled or indented. */ +cm_flushleft () +{ + begin_insertion (flushleft); +} + +/* Begin an insertion where the lines are not filled, and each line is + forced to the right-hand side of the page. */ +cm_flushright () +{ + begin_insertion (flushright); +} + + +/* **************************************************************** */ +/* */ +/* Conditional Handling */ +/* */ +/* **************************************************************** */ + +/* A structure which contains `defined' variables. */ +typedef struct _defines { + struct _defines *next; + char *name; + char *value; +} DEFINE; + +/* The linked list of `set' defines. */ +DEFINE *defines = (DEFINE *)NULL; + +/* Add NAME to the list of `set' defines. */ +set (name, value) + char *name; + char *value; +{ + DEFINE *temp; + + for (temp = defines; temp; temp = temp->next) + if (strcmp (name, temp->name) == 0) + { + free (temp->value); + temp->value = savestring (value); + return; + } + + temp = (DEFINE *)xmalloc (sizeof (DEFINE)); + temp->next = defines; + temp->name = savestring (name); + temp->value = savestring (value); + defines = temp; +} + +/* Remove NAME from the list of `set' defines. */ +clear (name) + char *name; +{ + register DEFINE *temp, *last; + + last = (DEFINE *)NULL; + temp = defines; + + while (temp) + { + if (strcmp (temp->name, name) == 0) + { + if (last) + last->next = temp->next; + else + defines = temp->next; + + free (temp->name); + free (temp->value); + free (temp); + break; + } + last = temp; + temp = temp->next; + } +} + +/* Return the value of NAME. The return value is NULL if NAME is unset. */ +char * +set_p (name) + char *name; +{ + register DEFINE *temp; + + for (temp = defines; temp; temp = temp->next) + if (strcmp (temp->name, name) == 0) + return (temp->value); + + return ((char *)NULL); +} + +/* Conditionally parse based on the current command name. */ +command_name_condition () +{ + char *discarder; + + discarder = (char *)xmalloc (8 + strlen (command)); + + sprintf (discarder, "\n@end %s", command); + discard_until (discarder); + discard_until ("\n"); + + free (discarder); +} + +/* Create a variable whose name appears as the first word on this line. */ +cm_set () +{ + handle_variable (SET); +} + +/* Remove a variable whose name appears as the first word on this line. */ +cm_clear () +{ + handle_variable (CLEAR); +} + +cm_ifset () +{ + handle_variable (IFSET); +} + +cm_ifclear () +{ + handle_variable (IFCLEAR); +} + +cm_value (arg, start_pos, end_pos) + int arg, start_pos, end_pos; +{ + if (arg == END) + { + char *name, *value; + name = (char *)&output_paragraph[start_pos]; + output_paragraph[end_pos] = '\0'; + name = savestring (name); + value = set_p (name); + output_column -= end_pos - start_pos; + output_paragraph_offset = start_pos; + + if (value) + execute_string ("%s", value); + else + add_word_args ("{No Value For \"%s\"}", name); + + free (name); + } +} + +/* Set, clear, or conditionalize based on ACTION. */ +handle_variable (action) + int action; +{ + char *name; + + get_rest_of_line (&name); + backup_input_pointer (); + canon_white (name); + handle_variable_internal (action, name); + free (name); +} + +handle_variable_internal (action, name) + int action; + char *name; +{ + char *temp; + int delimiter, additional_text_present = 0; + + /* Only the first word of NAME is a valid tag. */ + temp = name; + delimiter = 0; + while (*temp && (delimiter || !whitespace (*temp))) + { +#if defined (SET_WITH_EQUAL) + if (*temp == '"' || *temp == '\'') + { + if (*temp == delimiter) + delimiter = 0; + else + delimiter = *temp; + } +#endif /* SET_WITH_EQUAL */ + temp++; + } + + if (*temp) + additional_text_present++; + + *temp = '\0'; + + if (!*name) + line_error ("@%s requires a name", command); + else + { + switch (action) + { + case SET: + { + char *value; + +#if defined (SET_WITH_EQUAL) + /* Allow a value to be saved along with a variable. The value is + the text following an `=' sign in NAME, if any is present. */ + + for (value = name; *value && *value != '='; value++); + + if (*value) + *value++ = '\0'; + + if (*value == '"' || *value == '\'') + { + value++; + value[strlen (value) - 1] = '\0'; + } + +#else /* !SET_WITH_EQUAL */ + /* The VALUE of NAME is the remainder of the line sans + whitespace. */ + if (additional_text_present) + { + value = temp + 1; + canon_white (value); + } + else + value = ""; +#endif /* !SET_WITH_VALUE */ + + set (name, value); + } + break; + + case CLEAR: + clear (name); + break; + + case IFSET: + case IFCLEAR: + /* If IFSET and NAME is not set, or if IFCLEAR and NAME is set, + read lines from the the file until we reach a matching + "@end CONDITION". This means that we only take note of + "@ifset/clear" and "@end" commands. */ + { + char condition[8]; + int condition_len; + + if (action == IFSET) + strcpy (condition, "ifset"); + else + strcpy (condition, "ifclear"); + + condition_len = strlen (condition); + + if ((action == IFSET && !set_p (name)) || + (action == IFCLEAR && set_p (name))) + { + int level = 0, done = 0; + + while (!done) + { + char *freeable_line, *line; + + get_rest_of_line (&freeable_line); + + for (line = freeable_line; whitespace (*line); line++); + + if (*line == COMMAND_PREFIX && + (strncmp (line + 1, condition, condition_len) == 0)) + level++; + else if (strncmp (line, "@end", 4) == 0) + { + char *cname = line + 4; + char *temp; + + while (*cname && whitespace (*cname)) + cname++; + temp = cname; + + while (*temp && !whitespace (*temp)) + temp++; + *temp = '\0'; + + if (strcmp (cname, condition) == 0) + { + if (!level) + { + done = 1; + } + else + level--; + } + } + free (freeable_line); + } + /* We found the end of a false @ifset/ifclear. If we are + in a menu, back up over the newline that ends the ifset, + since that newline may also begin the next menu entry. */ + break; + } + else + { + if (action == IFSET) + begin_insertion (ifset); + else + begin_insertion (ifclear); + } + } + break; + } + } +} + +/* **************************************************************** */ +/* */ +/* @itemx, @item */ +/* */ +/* **************************************************************** */ + +/* Non-zero means a string is in execution, as opposed to a file. */ +int executing_string = 0; + +/* Execute the string produced by formatting the ARGs with FORMAT. This + is like submitting a new file with @include. */ +#if defined (HAVE_VARARGS_H) && defined(HAVE_VSPRINTF) + +execute_string (va_alist) + va_dcl +{ + static char temp_string[4000]; + char *format; + va_list args; + + va_start (args); + format = va_arg (args, char *); + vsprintf (temp_string, format, args); + va_end (args); + +#else /* !(HAVE_VARARGS_H && HAVE_VSPRINTF) */ + +execute_string (format, arg1, arg2, arg3, arg4, arg5) + char *format; +{ + static char temp_string[4000]; + sprintf (temp_string, format, arg1, arg2, arg3, arg4, arg5); + +#endif /* !(HAVE_VARARGS_H && HAVE_VSPRINTF) */ + + strcat (temp_string, "@bye\n"); + pushfile (); + input_text_offset = 0; + input_text = temp_string; + input_filename = savestring (input_filename); + size_of_input_text = strlen (temp_string); + + executing_string++; + reader_loop (); + + popfile (); + executing_string--; + + free_and_clear (&command); + command = savestring ("not bye"); +} + +int itemx_flag = 0; + +cm_itemx () +{ + itemx_flag++; + cm_item (); + itemx_flag--; +} + +cm_item () +{ + char *rest_of_line, *item_func; + + /* Can only hack "@item" while inside of an insertion. */ + if (insertion_level) + { + INSERTION_ELT *stack = insertion_stack; + int original_input_text_offset; + + skip_whitespace (); + original_input_text_offset = input_text_offset; + + get_rest_of_line (&rest_of_line); + canon_white (rest_of_line); + item_func = current_item_function (); + + /* Okay, do the right thing depending on which insertion function + is active. */ + + switch_top: + switch (stack->insertion) + { + case ifinfo: + case ifset: + case ifclear: + case cartouche: + stack = stack->next; + if (!stack) + goto no_insertion; + else + goto switch_top; + break; + + case menu: + case quotation: + case example: + case smallexample: + case lisp: + case format: + case display: + case group: + line_error ("The `@%s' command is meaningless within a `@%s' block", + command, + insertion_type_pname (current_insertion_type ())); + break; + + case itemize: + case enumerate: + if (itemx_flag) + { + line_error ("@itemx is not meaningful inside of a `%s' block", + insertion_type_pname (current_insertion_type ())); + } + else + { + start_paragraph (); + kill_self_indent (-1); + filling_enabled = indented_fill = 1; + + if (current_insertion_type () == itemize) + { + indent (output_column = current_indent - 2); + + /* I need some way to determine whether this command + takes braces or not. I believe the user can type + either "@bullet" or "@bullet{}". Of course, they + can also type "o" or "#" or whatever else they want. */ + if (item_func && *item_func) + { + if (*item_func == '@') + if (item_func[strlen (item_func) - 1] != '}') + execute_string ("%s{}", item_func); + else + execute_string ("%s", item_func); + else + execute_string ("%s", item_func); + } + insert (' '); + output_column++; + } + else + enumerate_item (); + + /* Special hack. This makes close paragraph ignore you until + the start_paragraph () function has been called. */ + must_start_paragraph = 1; + + /* Ultra special hack. It appears that some people incorrectly + place text directly after the @item, instead of on a new line + by itself. This happens to work in TeX, so I make it work + here. */ + if (*rest_of_line) + { + line_number--; + input_text_offset = original_input_text_offset; + } + } + break; + + case table: + case ftable: + case vtable: + { + /* Get rid of extra characters. */ + kill_self_indent (-1); + + /* close_paragraph () almost does what we want. The problem + is when paragraph_is_open, and last_char_was_newline, and + the last newline has been turned into a space, because + filling_enabled. I handle it here. */ + if (last_char_was_newline && filling_enabled && paragraph_is_open) + insert ('\n'); + close_paragraph (); + +#if defined (INDENT_PARAGRAPHS_IN_TABLE) + /* Indent on a new line, but back up one indentation level. */ + { + int t; + + t = inhibit_paragraph_indentation; + inhibit_paragraph_indentation = 1; + /* At this point, inserting any non-whitespace character will + force the existing indentation to be output. */ + add_char ('i'); + inhibit_paragraph_indentation = t; + } +#else /* !INDENT_PARAGRAPHS_IN_TABLE */ + add_char ('i'); +#endif /* !INDENT_PARAGRAPHS_IN_TABLE */ + + output_paragraph_offset--; + kill_self_indent (default_indentation_increment + 1); + + /* Add item's argument to the line. */ + filling_enabled = 0; + if (item_func && *item_func) + execute_string ("%s{%s}", item_func, rest_of_line); + else + execute_string ("%s", rest_of_line); + + if (current_insertion_type () == ftable) + execute_string ("@findex %s\n", rest_of_line); + + if (current_insertion_type () == vtable) + execute_string ("@vindex %s\n", rest_of_line); + + /* Start a new line, and let start_paragraph () + do the indenting of it for you. */ + close_single_paragraph (); + indented_fill = filling_enabled = 1; + } + } + free (rest_of_line); + } + else + { + no_insertion: + line_error ("@%s found outside of an insertion block", command); + } +} + + +/* **************************************************************** */ +/* */ +/* Defun and Friends */ +/* */ +/* **************************************************************** */ + +#define DEFUN_SELF_DELIMITING(c) \ + (((c) == '(') \ + || ((c) == ')') \ + || ((c) == '[') \ + || ((c) == ']')) + +struct token_accumulator +{ + unsigned int length; + unsigned int index; + char **tokens; +}; + +void +initialize_token_accumulator (accumulator) + struct token_accumulator *accumulator; +{ + (accumulator->length) = 0; + (accumulator->index) = 0; + (accumulator->tokens) = NULL; +} + +void +accumulate_token (accumulator, token) + struct token_accumulator *accumulator; + char *token; +{ + if ((accumulator->index) >= (accumulator->length)) + { + (accumulator->length) += 10; + (accumulator->tokens) = (char **) xrealloc + (accumulator->tokens, (accumulator->length * sizeof (char *))); + } + accumulator->tokens[accumulator->index] = token; + accumulator->index += 1; +} + +char * +copy_substring (start, end) + char *start; + char *end; +{ + char *result, *scan, *scan_result; + + result = (char *) xmalloc ((end - start) + 1); + scan_result = result; + scan = start; + + while (scan < end) + *scan_result++ = *scan++; + + *scan_result = '\0'; + return (result); +} + +/* Given `string' pointing at an open brace, skip forward and return a + pointer to just past the matching close brace. */ +int +scan_group_in_string (string_pointer) + char **string_pointer; +{ + register int c; + register char *scan_string; + register unsigned int level = 1; + + scan_string = (*string_pointer) + 1; + + while (1) + { + if (level == 0) + { + (*string_pointer) = scan_string; + return (1); + } + c = (*scan_string++); + if (c == '\0') + { + /* Tweak line_number to compensate for fact that + we gobbled the whole line before coming here. */ + line_number -= 1; + line_error ("Missing `}' in @def arg"); + line_number += 1; + (*string_pointer) = (scan_string - 1); + return (0); + } + if (c == '{') + level += 1; + if (c == '}') + level -= 1; + } +} + +/* Return a list of tokens from the contents of `string'. + Commands and brace-delimited groups count as single tokens. + Contiguous whitespace characters are converted to a token + consisting of a single space. */ +char ** +args_from_string (string) + char *string; +{ + struct token_accumulator accumulator; + register char *scan_string = string; + char *token_start, *token_end; + + initialize_token_accumulator (&accumulator); + + while ((*scan_string) != '\0') + { + /* Replace arbitrary whitespace by a single space. */ + if (whitespace (*scan_string)) + { + scan_string += 1; + while (whitespace (*scan_string)) + scan_string += 1; + accumulate_token ((&accumulator), (savestring (" "))); + continue; + } + + /* Commands count as single tokens. */ + if ((*scan_string) == COMMAND_PREFIX) + { + token_start = scan_string; + scan_string += 1; + if (self_delimiting (*scan_string)) + scan_string += 1; + else + { + register int c; + while (1) + { + c = *scan_string++; + + if ((c == '\0') || (c == '{') || (whitespace (c))) + { + scan_string -= 1; + break; + } + } + + if (*scan_string == '{') + { + char *s = scan_string; + (void) scan_group_in_string (&s); + scan_string = s; + } + } + token_end = scan_string; + } + + /* Parentheses and brackets are self-delimiting. */ + else if (DEFUN_SELF_DELIMITING (*scan_string)) + { + token_start = scan_string; + scan_string += 1; + token_end = scan_string; + } + + /* Open brace introduces a group that is a single token. */ + else if (*scan_string == '{') + { + char *s = scan_string; + int balanced = scan_group_in_string (&s); + + token_start = scan_string + 1; + scan_string = s; + token_end = balanced ? (scan_string - 1) : scan_string; + } + + /* Otherwise a token is delimited by whitespace, parentheses, + brackets, or braces. A token is also ended by a command. */ + else + { + token_start = scan_string; + + while (1) + { + register int c; + + c = *scan_string++; + + if (!c || + (whitespace (c) || DEFUN_SELF_DELIMITING (c) || + c == '{' || c == '}')) + { + scan_string--; + break; + } + + /* If we encounter a command imbedded within a token, + then end the token. */ + if (c == COMMAND_PREFIX) + { + scan_string--; + break; + } + } + token_end = scan_string; + } + + accumulate_token + (&accumulator, copy_substring (token_start, token_end)); + } + accumulate_token (&accumulator, NULL); + return (accumulator.tokens); +} + +void +process_defun_args (defun_args, auto_var_p) + char **defun_args; + int auto_var_p; +{ + int pending_space = 0; + + while (1) + { + char *defun_arg = *defun_args++; + + if (defun_arg == NULL) + break; + + if (defun_arg[0] == ' ') + { + pending_space = 1; + continue; + } + + if (pending_space) + { + add_char (' '); + pending_space = 0; + } + + if (DEFUN_SELF_DELIMITING (defun_arg[0])) + add_char (defun_arg[0]); + else if (defun_arg[0] == '&') + add_word (defun_arg); + else if (defun_arg[0] == COMMAND_PREFIX) + execute_string ("%s", defun_arg); + else if (auto_var_p) + execute_string ("@var{%s}", defun_arg); + else + add_word (defun_arg); + } +} + +char * +next_nonwhite_defun_arg (arg_pointer) + char ***arg_pointer; +{ + char **scan = (*arg_pointer); + char *arg = (*scan++); + + if ((arg != 0) && (*arg == ' ')) + arg = *scan++; + + if (arg == 0) + scan -= 1; + + *arg_pointer = scan; + + return ((arg == 0) ? "" : arg); +} + +/* Make the defun type insertion. + TYPE says which insertion this is. + X_P says not to start a new insertion if non-zero. */ +void +defun_internal (type, x_p) + enum insertion_type type; + int x_p; +{ + enum insertion_type base_type; + char **defun_args, **scan_args; + char *category, *defined_name, *type_name, *type_name2; + + { + char *line; + get_rest_of_line (&line); + defun_args = (args_from_string (line)); + free (line); + } + + scan_args = defun_args; + + switch (type) + { + case defun: + category = "Function"; + base_type = deffn; + break; + case defmac: + category = "Macro"; + base_type = deffn; + break; + case defspec: + category = "Special Form"; + base_type = deffn; + break; + case defvar: + category = "Variable"; + base_type = defvr; + break; + case defopt: + category = "User Option"; + base_type = defvr; + break; + case deftypefun: + category = "Function"; + base_type = deftypefn; + break; + case deftypevar: + category = "Variable"; + base_type = deftypevr; + break; + case defivar: + category = "Instance Variable"; + base_type = defcv; + break; + case defmethod: + category = "Method"; + base_type = defop; + break; + case deftypemethod: + category = "Method"; + base_type = deftypemethod; + break; + default: + category = next_nonwhite_defun_arg (&scan_args); + base_type = type; + break; + } + + if ((base_type == deftypefn) + || (base_type == deftypevr) + || (base_type == defcv) + || (base_type == defop) + || (base_type == deftypemethod)) + type_name = next_nonwhite_defun_arg (&scan_args); + + if (base_type == deftypemethod) + type_name2 = next_nonwhite_defun_arg (&scan_args); + + defined_name = next_nonwhite_defun_arg (&scan_args); + + /* This hack exists solely for the purposes of formatting the texinfo + manual. I couldn't think of a better way. The token might be + a simple @@ followed immediately by more text. If this is the case, + then the next defun arg is part of this one, and we should concatenate + them. */ + if (*scan_args && **scan_args && !whitespace (**scan_args) && + (strcmp (defined_name, "@@") == 0)) + { + char *tem = (char *)xmalloc (3 + strlen (scan_args[0])); + + sprintf (tem, "@@%s", scan_args[0]); + + free (scan_args[0]); + scan_args[0] = tem; + scan_args++; + defined_name = tem; + } + + if (!x_p) + begin_insertion (type); + + /* Write the definition header line. + This should start at the normal indentation. */ + current_indent -= default_indentation_increment; + start_paragraph (); + + switch (base_type) + { + case deffn: + case defvr: + case deftp: + execute_string (" -- %s: %s", category, defined_name); + break; + case deftypefn: + case deftypevr: + execute_string (" -- %s: %s %s", category, type_name, defined_name); + break; + case defcv: + execute_string (" -- %s of %s: %s", category, type_name, defined_name); + break; + case defop: + execute_string (" -- %s on %s: %s", category, type_name, defined_name); + break; + case deftypemethod: + execute_string (" -- %s on %s: %s %s", category, type_name, type_name2, + defined_name); + break; + } + current_indent += default_indentation_increment; + + /* Now process the function arguments, if any. + If these carry onto the next line, they should be indented by two + increments to distinguish them from the body of the definition, + which is indented by one increment. */ + current_indent += default_indentation_increment; + + switch (base_type) + { + case deffn: + case defop: + process_defun_args (scan_args, 1); + break; + case deftp: + case deftypefn: + case deftypemethod: + process_defun_args (scan_args, 0); + break; + } + current_indent -= default_indentation_increment; + close_single_paragraph (); + + /* Make an entry in the appropriate index. */ + switch (base_type) + { + case deffn: + case deftypefn: + execute_string ("@findex %s\n", defined_name); + break; + case defvr: + case deftypevr: + case defcv: + execute_string ("@vindex %s\n", defined_name); + break; + case defop: + case deftypemethod: + execute_string ("@findex %s on %s\n", defined_name, type_name); + break; + case deftp: + execute_string ("@tindex %s\n", defined_name); + break; + } + + /* Deallocate the token list. */ + scan_args = defun_args; + while (1) + { + char * arg = (*scan_args++); + if (arg == NULL) + break; + free (arg); + } + free (defun_args); +} + +/* Add an entry for a function, macro, special form, variable, or option. + If the name of the calling command ends in `x', then this is an extra + entry included in the body of an insertion of the same type. */ +cm_defun () +{ + int x_p; + enum insertion_type type; + char *temp = savestring (command); + + x_p = (command[strlen (command) - 1] == 'x'); + + if (x_p) + temp[strlen (temp) - 1] = '\0'; + + type = find_type_from_name (temp); + free (temp); + + /* If we are adding to an already existing insertion, then make sure + that we are already in an insertion of type TYPE. */ + if (x_p && + (!insertion_level || insertion_stack->insertion != type)) + { + line_error ("Must be in a `%s' insertion in order to use `%s'x", + command, command); + discard_until ("\n"); + return; + } + + defun_internal (type, x_p); +} + +/* End existing insertion block. */ +cm_end () +{ + char *temp; + enum insertion_type type; + + if (!insertion_level) + { + line_error ("Unmatched `@%s'", command); + return; + } + + get_rest_of_line (&temp); + canon_white (temp); + + if (strlen (temp) == 0) + line_error ("`@%s' needs something after it", command); + + type = find_type_from_name (temp); + + if (type == bad_type) + { + line_error ("Bad argument to `%s', `%s', using `%s'", + command, temp, insertion_type_pname (current_insertion_type ())); + } + end_insertion (type); + free (temp); +} + + +/* **************************************************************** */ +/* */ +/* Other Random Commands */ +/* */ +/* **************************************************************** */ + +/* This says to inhibit the indentation of the next paragraph, but + not of following paragraphs. */ +cm_noindent () +{ + if (!inhibit_paragraph_indentation) + inhibit_paragraph_indentation = -1; +} + +/* I don't know exactly what to do with this. Should I allow + someone to switch filenames in the middle of output? Since the + file could be partially written, this doesn't seem to make sense. + Another option: ignore it, since they don't *really* want to + switch files. Finally, complain, or at least warn. */ +cm_setfilename () +{ + char *filename; + get_rest_of_line (&filename); + /* warning ("`@%s %s' encountered and ignored", command, filename); */ + free (filename); +} + +cm_ignore_line () +{ + discard_until ("\n"); +} + +/* @br can be immediately followed by `{}', so we have to read those here. + It should simply close the paragraph. */ +cm_br () +{ + if (looking_at ("{}")) + input_text_offset += 2; + + if (curchar () == '\n') + { + input_text_offset++; + line_number++; + } + + close_paragraph (); +} + + /* Insert the number of blank lines passed as argument. */ +cm_sp () +{ + int lines; + char *line; + + get_rest_of_line (&line); + + if (sscanf (line, "%d", &lines) != 1) + { + line_error ("%csp requires a positive numeric argument", COMMAND_PREFIX); + } + else + { + if (lines < 0) + lines = 0; + + while (lines--) + add_char ('\n'); + } + free (line); +} + +/* Start a new line with just this text on it. + Then center the line of text. + This always ends the current paragraph. */ +cm_center () +{ + register int i, start, length; + int fudge_factor = 1; + unsigned char *line; + + close_paragraph (); + filling_enabled = indented_fill = 0; + cm_noindent (); + start = output_paragraph_offset; + inhibit_output_flushing (); + get_rest_of_line ((char **)&line); + execute_string ((char *)line); + free (line); + uninhibit_output_flushing (); + + i = output_paragraph_offset - 1; + while (i > (start - 1) && output_paragraph[i] == '\n') + i--; + + output_paragraph_offset = ++i; + length = output_paragraph_offset - start; + + if (length < (fill_column - fudge_factor)) + { + line = (unsigned char *)xmalloc (1 + length); + memcpy (line, (char *)(output_paragraph + start), length); + + i = (fill_column - fudge_factor - length) / 2; + output_paragraph_offset = start; + + while (i--) + insert (' '); + + for (i = 0; i < length; i++) + insert (line[i]); + + free (line); + } + + insert ('\n'); + close_paragraph (); + filling_enabled = 1; +} + +/* Show what an expression returns. */ +cm_result (arg) + int arg; +{ + if (arg == END) + add_word ("=>"); +} + +/* What an expression expands to. */ +cm_expansion (arg) + int arg; +{ + if (arg == END) + add_word ("==>"); +} + +/* Indicates two expressions are equivalent. */ +cm_equiv (arg) + int arg; +{ + if (arg == END) + add_word ("=="); +} + +/* What an expression may print. */ +cm_print (arg) + int arg; +{ + if (arg == END) + add_word ("-|"); +} + +/* An error signaled. */ +cm_error (arg) + int arg; +{ + if (arg == END) + add_word ("error-->"); +} + +/* The location of point in an example of a buffer. */ +cm_point (arg) + int arg; +{ + if (arg == END) + add_word ("-!-"); +} + +/* Start a new line with just this text on it. + The text is outdented one level if possible. */ +cm_exdent () +{ + char *line; + int i = current_indent; + + if (current_indent) + current_indent -= default_indentation_increment; + + get_rest_of_line (&line); + close_single_paragraph (); + execute_string ("%s", line); + current_indent = i; + free (line); + close_single_paragraph (); +} + +cm_include () +{ + cm_infoinclude (); +} + +/* Remember this file, and move onto the next. */ +cm_infoinclude () +{ + char *filename; + + close_paragraph (); + get_rest_of_line (&filename); + pushfile (); + + /* In verbose mode we print info about including another file. */ + if (verbose_mode) + { + register int i = 0; + register FSTACK *stack = filestack; + + for (i = 0, stack = filestack; stack; stack = stack->next, i++); + + i *= 2; + + printf ("%*s", i, ""); + printf ("%c%s %s\n", COMMAND_PREFIX, command, filename); + fflush (stdout); + } + + if (!find_and_load (filename)) + { + extern const char * const sys_errlist[]; + extern int errno, sys_nerr; + popfile (); + + /* Cannot "@include foo", in line 5 of "/wh/bar". */ + line_error ("`%c%s %s': %s", COMMAND_PREFIX, command, filename, + ((errno < sys_nerr) ? + sys_errlist[errno] : "Unknown file system error")); + } + free (filename); +} + +/* The other side of a malformed expression. */ +misplaced_brace () +{ + line_error ("Misplaced `}'"); +} + +/* Don't let the filling algorithm insert extra whitespace here. */ +cm_force_abbreviated_whitespace () +{ +} + +/* Do not let this character signify the end of a sentence, though + if it was seen without the command prefix it normally would. We + do this by turning on the 8th bit of the character. */ +cm_ignore_sentence_ender () +{ + add_char (META ((*command))); +} + +/* Signals end of processing. Easy to make this happen. */ +cm_bye () +{ + input_text_offset = size_of_input_text; +} + +cm_asis () +{ +} + +cm_math () +{ +} + + +/* **************************************************************** */ +/* */ +/* Indexing Stuff */ +/* */ +/* **************************************************************** */ + + +/* An index element... */ +typedef struct index_elt +{ + struct index_elt *next; + char *entry; /* The index entry itself. */ + char *node; /* The node from whence it came. */ + int code; /* Non-zero means add `@code{...}' when + printing this element. */ + int defining_line; /* Line number where this entry was written. */ +} INDEX_ELT; + +/* A list of short-names for each index, and the index to that index in our + index array, the_indices. In addition, for each index, it is remembered + whether that index is a code index or not. Code indices have @code{} + inserted around the first word when they are printed with printindex. */ +typedef struct +{ + char *name; + int index; + int code; +} INDEX_ALIST; + +INDEX_ALIST **name_index_alist = (INDEX_ALIST **) NULL; + +/* An array of pointers. Each one is for a different index. The + "synindex" command changes which array slot is pointed to by a + given "index". */ +INDEX_ELT **the_indices = (INDEX_ELT **) NULL; + +/* The number of defined indices. */ +int defined_indices = 0; + +/* We predefine these. */ +#define program_index 0 +#define function_index 1 +#define concept_index 2 +#define variable_index 3 +#define datatype_index 4 +#define key_index 5 + +init_indices () +{ + int i; + + /* Create the default data structures. */ + + /* Initialize data space. */ + if (!the_indices) + { + the_indices = (INDEX_ELT **) xmalloc ((1 + defined_indices) * + sizeof (INDEX_ELT *)); + the_indices[defined_indices] = (INDEX_ELT *) NULL; + + name_index_alist = (INDEX_ALIST **) xmalloc ((1 + defined_indices) * + sizeof (INDEX_ALIST *)); + name_index_alist[defined_indices] = (INDEX_ALIST *) NULL; + } + + /* If there were existing indices, get rid of them now. */ + for (i = 0; i < defined_indices; i++) + undefindex (name_index_alist[i]->name); + + /* Add the default indices. */ + defindex ("pg", 0); + defindex ("fn", 1); /* "fn" is a code index. */ + defindex ("cp", 0); + defindex ("vr", 0); + defindex ("tp", 0); + defindex ("ky", 0); + +} + +/* Find which element in the known list of indices has this name. + Returns -1 if NAME isn't found. */ +int +find_index_offset (name) + char *name; +{ + register int i; + for (i = 0; i < defined_indices; i++) + if (name_index_alist[i] && + strcmp (name, name_index_alist[i]->name) == 0) + return (name_index_alist[i]->index); + return (-1); +} + +/* Return a pointer to the entry of (name . index) for this name. + Return NULL if the index doesn't exist. */ +INDEX_ALIST * +find_index (name) + char *name; +{ + int offset = find_index_offset (name); + if (offset > -1) + return (name_index_alist[offset]); + else + return ((INDEX_ALIST *) NULL); +} + +/* Given an index name, return the offset in the_indices of this index, + or -1 if there is no such index. */ +translate_index (name) + char *name; +{ + INDEX_ALIST *which = find_index (name); + + if (which) + return (which->index); + else + return (-1); +} + +/* Return the index list which belongs to NAME. */ +INDEX_ELT * +index_list (name) + char *name; +{ + int which = translate_index (name); + if (which < 0) + return ((INDEX_ELT *) - 1); + else + return (the_indices[which]); +} + +/* Please release me, let me go... */ +free_index (index) + INDEX_ELT *index; +{ + INDEX_ELT *temp; + + while ((temp = index) != (INDEX_ELT *) NULL) + { + free (temp->entry); + free (temp->node); + index = index->next; + free (temp); + } +} + +/* Flush an index by name. */ +undefindex (name) + char *name; +{ + int i; + int which = find_index_offset (name); + + if (which < 0) + return (which); + + i = name_index_alist[which]->index; + + + free_index (the_indices[i]); + the_indices[i] = (INDEX_ELT *) NULL; + + free (name_index_alist[which]->name); + free (name_index_alist[which]); + name_index_alist[which] = (INDEX_ALIST *) NULL; +} + +/* Define an index known as NAME. We assign the slot number. + CODE if non-zero says to make this a code index. */ +defindex (name, code) + char *name; + int code; +{ + register int i, slot; + + /* If it already exists, flush it. */ + undefindex (name); + + /* Try to find an empty slot. */ + slot = -1; + for (i = 0; i < defined_indices; i++) + if (!name_index_alist[i]) + { + slot = i; + break; + } + + if (slot < 0) + { + /* No such luck. Make space for another index. */ + slot = defined_indices; + defined_indices++; + + name_index_alist = (INDEX_ALIST **) + xrealloc ((char *)name_index_alist, + (1 + defined_indices) * sizeof (INDEX_ALIST *)); + the_indices = (INDEX_ELT **) + xrealloc ((char *)the_indices, + (1 + defined_indices) * sizeof (INDEX_ELT *)); + } + + /* We have a slot. Start assigning. */ + name_index_alist[slot] = (INDEX_ALIST *) xmalloc (sizeof (INDEX_ALIST)); + name_index_alist[slot]->name = savestring (name); + name_index_alist[slot]->index = slot; + name_index_alist[slot]->code = code; + + the_indices[slot] = (INDEX_ELT *) NULL; +} + +/* Add the arguments to the current index command to the index NAME. */ +index_add_arg (name) + char *name; +{ + int which; + char *index_entry; + INDEX_ALIST *tem; + + tem = find_index (name); + + which = tem ? tem->index : -1; + + get_rest_of_line (&index_entry); + ignore_blank_line (); + + if (which < 0) + { + line_error ("Unknown index reference `%s'", name); + free (index_entry); + } + else + { + INDEX_ELT *new = (INDEX_ELT *) xmalloc (sizeof (INDEX_ELT)); + new->next = the_indices[which]; + new->entry = index_entry; + new->node = current_node; + new->code = tem->code; + new->defining_line = line_number - 1; + the_indices[which] = new; + } +} + +#define INDEX_COMMAND_SUFFIX "index" + +/* The function which user defined index commands call. */ +gen_index () +{ + char *name = savestring (command); + if (strlen (name) >= strlen ("index")) + name[strlen (name) - strlen ("index")] = '\0'; + index_add_arg (name); + free (name); +} + +/* Define a new index command. Arg is name of index. */ +cm_defindex () +{ + gen_defindex (0); +} + +cm_defcodeindex () +{ + gen_defindex (1); +} + +gen_defindex (code) + int code; +{ + char *name; + get_rest_of_line (&name); + + if (find_index (name)) + { + line_error ("Index `%s' already exists", name); + free (name); + return; + } + else + { + char *temp = (char *) alloca (1 + strlen (name) + strlen ("index")); + sprintf (temp, "%sindex", name); + define_user_command (temp, gen_index, 0); + defindex (name, code); + free (name); + } +} + +/* Append LIST2 to LIST1. Return the head of the list. */ +INDEX_ELT * +index_append (head, tail) + INDEX_ELT *head, *tail; +{ + register INDEX_ELT *t_head = head; + + if (!t_head) + return (tail); + + while (t_head->next) + t_head = t_head->next; + t_head->next = tail; + return (head); +} + +/* Expects 2 args, on the same line. Both are index abbreviations. + Make the first one be a synonym for the second one, i.e. make the + first one have the same index as the second one. */ +cm_synindex () +{ + int redirector, redirectee; + char *temp; + + skip_whitespace (); + get_until_in_line (" ", &temp); + redirectee = find_index_offset (temp); + skip_whitespace (); + free_and_clear (&temp); + get_until_in_line (" ", &temp); + redirector = find_index_offset (temp); + free (temp); + if (redirector < 0 || redirectee < 0) + { + line_error ("Unknown index reference"); + } + else + { + /* I think that we should let the user make indices synonymous to + each other without any lossage of info. This means that one can + say @synindex cp dt anywhere in the file, and things that used to + be in cp will go into dt. */ + INDEX_ELT *i1 = the_indices[redirectee], *i2 = the_indices[redirector]; + + if (i1 || i2) + { + if (i1) + the_indices[redirectee] = index_append (i1, i2); + else + the_indices[redirectee] = index_append (i2, i1); + } + + name_index_alist[redirectee]->index = + name_index_alist[redirector]->index; + } +} + +cm_pindex () /* Pinhead index. */ +{ + index_add_arg ("pg"); +} + +cm_vindex () /* Variable index. */ +{ + index_add_arg ("vr"); +} + +cm_kindex () /* Key index. */ +{ + index_add_arg ("ky"); +} + +cm_cindex () /* Concept index. */ +{ + index_add_arg ("cp"); +} + +cm_findex () /* Function index. */ +{ + index_add_arg ("fn"); +} + +cm_tindex () /* Data Type index. */ +{ + index_add_arg ("tp"); +} + +/* Sorting the index. */ +index_element_compare (element1, element2) + INDEX_ELT **element1, **element2; +{ + /* This needs to ignore leading non-text characters. */ + return (stricmp ((*element1)->entry, (*element2)->entry)); +} + +/* Sort the index passed in INDEX, returning an array of + pointers to elements. The array is terminated with a NULL + pointer. We call qsort because it's supposed to be fast. + I think this looks bad. */ +INDEX_ELT ** +sort_index (index) + INDEX_ELT *index; +{ + INDEX_ELT *temp = index; + INDEX_ELT **array; + int count = 0; + + while (temp != (INDEX_ELT *) NULL) + { + count++; + temp = temp->next; + } + + /* We have the length. Make an array. */ + + array = (INDEX_ELT **) xmalloc ((count + 1) * sizeof (INDEX_ELT *)); + count = 0; + temp = index; + + while (temp != (INDEX_ELT *) NULL) + { + array[count++] = temp; + temp = temp->next; + } + array[count] = (INDEX_ELT *) NULL; /* terminate the array. */ + + /* Sort the array. */ + qsort (array, count, sizeof (INDEX_ELT *), index_element_compare); + + return (array); +} + +/* Non-zero means that we are in the middle of printing an index. */ +int printing_index = 0; + +/* Takes one arg, a short name of an index to print. + Outputs a menu of the sorted elements of the index. */ +cm_printindex () +{ + int item; + INDEX_ELT *index; + INDEX_ELT **array; + char *index_name; + int old_inhibitions = inhibit_paragraph_indentation; + int previous_filling_enabled_value = filling_enabled; + + close_paragraph (); + get_rest_of_line (&index_name); + + index = index_list (index_name); + if ((int) index == -1) + { + line_error ("Unknown index name `%s'", index_name); + free (index_name); + return; + } + else + free (index_name); + + array = sort_index (index); + + filling_enabled = 0; + inhibit_paragraph_indentation = 1; + close_paragraph (); + add_word ("* Menu:\n\n"); + + printing_index = 1; + for (item = 0; (index = array[item]); item++) + { + int real_line_number = line_number; + + /* Let errors generated while making the index entry point back + at the line which contains the entry. */ + line_number = index->defining_line; + + /* If this particular entry should be printed as a "code" index, + then wrap the entry with "@code{...}". */ + if (index->code) + execute_string ("* @code{%s}: ", index->entry); + else + execute_string ("* %s: ", index->entry); + + /* Pad the front of the destination nodename so that + the output looks nice. */ + if (fill_column > 40 && output_column < 40) + indent (40 - output_column); + + execute_string ("%s.\n", index->node); + + line_number = real_line_number; + flush_output (); + } + + printing_index = 0; + free (array); + close_single_paragraph (); + filling_enabled = previous_filling_enabled_value; + inhibit_paragraph_indentation = old_inhibitions; +} + + +/* **************************************************************** */ +/* */ +/* Making User Defined Commands */ +/* */ +/* **************************************************************** */ + +define_user_command (name, proc, needs_braces_p) + char *name; + FUNCTION *proc; + int needs_braces_p; +{ + int slot = user_command_array_len; + user_command_array_len++; + + if (!user_command_array) + user_command_array = (COMMAND **) xmalloc (1 * sizeof (COMMAND *)); + + user_command_array = (COMMAND **) xrealloc (user_command_array, + (1 + user_command_array_len) * + sizeof (COMMAND *)); + + user_command_array[slot] = (COMMAND *) xmalloc (sizeof (COMMAND)); + user_command_array[slot]->name = savestring (name); + user_command_array[slot]->proc = proc; + user_command_array[slot]->argument_in_braces = needs_braces_p; +} + +/* Make ALIAS run the named FUNCTION. Copies properties from FUNCTION. */ +define_alias (alias, function) + char *alias, *function; +{ +} + +/* Set the paragraph indentation variable to the value specified in STRING. + Values can be: + `asis': Don't change existing indentation. + `none': Remove existing indentation. + NUM: Indent NUM spaces at the starts of paragraphs. + Note that if NUM is zero, we assume `none'. + + Returns 0 if successful, or non-zero if STRING isn't one of the above. */ +int +set_paragraph_indent (string) + char *string; +{ + if (strcmp (string, "asis") == 0) + paragraph_start_indent = 0; + else if (strcmp (string, "none") == 0) + paragraph_start_indent = -1; + else + { + if (sscanf (string, "%d", ¶graph_start_indent) != 1) + return (-1); + else + { + if (paragraph_start_indent == 0) + paragraph_start_indent = -1; + } + } + return (0); +} + +cm_paragraphindent () +{ + char *arg; + + get_rest_of_line (&arg); + if (set_paragraph_indent (arg) != 0) + line_error ("Bad argument to @paragraphindent"); + + free (arg); +} + +/* Some support for footnotes. */ + +/* Footnotes are a new construct in Info. We don't know the best method + of implementing them for sure, so we present two possiblities. + + SeparateNode: + Make them look like followed references, with the reference + destinations in a makeinfo manufactured node or, + + EndNode: + Make them appear at the bottom of the node that they originally + appeared in. */ +#define SeparateNode 0 +#define EndNode 1 + +int footnote_style = EndNode; +int first_footnote_this_node = 1; +int footnote_count = 0; + +/* Set the footnote style based on he style identifier in STRING. */ +int +set_footnote_style (string) + char *string; +{ + if ((stricmp (string, "separate") == 0) || + (stricmp (string, "MN") == 0)) + footnote_style = SeparateNode; + else if ((stricmp (string, "end") == 0) || + (stricmp (string, "EN") == 0)) + footnote_style = EndNode; + else + return (-1); + + return (0); +} + +cm_footnotestyle () +{ + char *arg; + + get_rest_of_line (&arg); + + if (set_footnote_style (arg) != 0) + line_error ("Bad argument to @footnotestyle"); + + free (arg); +} + +typedef struct fn +{ + struct fn *next; + char *marker; + char *note; +} FN; + +FN *pending_notes = (FN *) NULL; + +/* A method for remembering footnotes. Note that this list gets output + at the end of the current node. */ +remember_note (marker, note) + char *marker, *note; +{ + FN *temp = (FN *) xmalloc (sizeof (FN)); + + temp->marker = savestring (marker); + temp->note = savestring (note); + temp->next = pending_notes; + pending_notes = temp; + footnote_count++; +} + +/* How to get rid of existing footnotes. */ +free_pending_notes () +{ + FN *temp; + + while ((temp = pending_notes) != (FN *) NULL) + { + free (temp->marker); + free (temp->note); + pending_notes = pending_notes->next; + free (temp); + } + first_footnote_this_node = 1; + footnote_count = 0; +} + +/* What to do when you see a @footnote construct. */ + + /* Handle a "footnote". + footnote *{this is a footnote} + where "*" is the marker character for this note. */ +cm_footnote () +{ + char *marker; + char *note; + + get_until ("{", &marker); + canon_white (marker); + + /* Read the argument in braces. */ + if (curchar () != '{') + { + line_error ("`@%s' expected more than just `%s'. It needs something in `{...}'", command, marker); + free (marker); + return; + } + else + { + int braces = 1; + int temp = ++input_text_offset; + int len; + + while (braces) + { + if (temp == size_of_input_text) + { + line_error ("No closing brace for footnote `%s'", marker); + return; + } + + if (input_text[temp] == '{') + braces++; + else if (input_text[temp] == '}') + braces--; + else if (input_text[temp] == '\n') + line_number ++; + + temp++; + } + + len = (temp - input_text_offset) - 1; + note = (char *)xmalloc (len + 1); + strncpy (note, &input_text[input_text_offset], len); + note[len] = '\0'; + input_text_offset = temp; + } + + if (!current_node || !*current_node) + { + line_error ("Footnote defined without parent node"); + free (marker); + free (note); + return; + } + + if (!*marker) + { + free (marker); + + if (number_footnotes) + { + marker = (char *)xmalloc (10); + sprintf (marker, "%d", current_footnote_number); + current_footnote_number++; + } + else + marker = savestring ("*"); + } + + remember_note (marker, note); + + /* Your method should at least insert MARKER. */ + switch (footnote_style) + { + case SeparateNode: + add_word_args ("(%s)", marker); + if (first_footnote_this_node) + { + char *temp_string; + + temp_string = (char *) + xmalloc ((strlen (current_node)) + (strlen ("-Footnotes")) + 1); + + add_word_args (" (*note %s-Footnotes::)", current_node); + strcpy (temp_string, current_node); + strcat (temp_string, "-Footnotes"); + remember_node_reference (temp_string, line_number, followed_reference); + free (temp_string); + first_footnote_this_node = 0; + } + break; + + case EndNode: + add_word_args ("(%s)", marker); + break; + + default: + break; + } + free (marker); + free (note); +} + +/* Non-zero means that we are currently in the process of outputting + footnotes. */ +int already_outputting_pending_notes = 0; + +/* Output the footnotes. We are at the end of the current node. */ +output_pending_notes () +{ + FN *footnote = pending_notes; + + if (!pending_notes) + return; + + switch (footnote_style) + { + + case SeparateNode: + { + char *old_current_node = current_node; + char *old_command = savestring (command); + + already_outputting_pending_notes++; + execute_string ("@node %s-Footnotes,,,%s\n", current_node, current_node); + already_outputting_pending_notes--; + current_node = old_current_node; + free (command); + command = old_command; + } + break; + + case EndNode: + close_paragraph (); + in_fixed_width_font++; + execute_string ("---------- Footnotes ----------\n\n"); + in_fixed_width_font--; + break; + } + + /* Handle the footnotes in reverse order. */ + { + FN **array = (FN **) xmalloc ((footnote_count + 1) * sizeof (FN *)); + + array[footnote_count] = (FN *) NULL; + + while (--footnote_count > -1) + { + array[footnote_count] = footnote; + footnote = footnote->next; + } + + filling_enabled = 1; + indented_fill = 1; + + while (footnote = array[++footnote_count]) + { + + switch (footnote_style) + { + case SeparateNode: + case EndNode: + execute_string ("(%s) %s", footnote->marker, footnote->note); + close_paragraph (); + break; + } + } + close_paragraph (); + free (array); + } +} + + +/* **************************************************************** */ +/* */ +/* User definable Macros (text substitution) */ +/* */ +/* **************************************************************** */ + +#if defined (HAVE_MACROS) + +/* Array of macros and definitions. */ +MACRO_DEF **macro_list = (MACRO_DEF **)NULL; + +int macro_list_len = 0; /* Number of elements. */ +int macro_list_size = 0; /* Number of slots in total. */ + +/* Return the macro definition of NAME or NULL if NAME is not defined. */ +MACRO_DEF * +find_macro (name) + char *name; +{ + register int i; + register MACRO_DEF *def; + + def = (MACRO_DEF *)NULL; + for (i = 0; macro_list && (def = macro_list[i]); i++) + if (strcmp (def->name, name) == 0) + break; + + return (def); +} + +/* Add the macro NAME with DEFINITION to macro_list. FILENAME is + the name of the file where this definition can be found, and + LINENO is the line number within that file. If a macro already + exists with NAME, then a warning is produced, and that previous + definition is overwritten. */ +void +add_macro (name, definition, filename, lineno) + char *name, *definition; + char *filename; + int lineno; +{ + register MACRO_DEF *def; + + def = find_macro (name); + + if (!def) + { + if (macro_list_len + 2 >= macro_list_size) + macro_list = (MACRO_DEF **)xrealloc + (macro_list, ((macro_list_size += 10) * sizeof (MACRO_DEF *))); + + macro_list[macro_list_len] = (MACRO_DEF *)xmalloc (sizeof (MACRO_DEF)); + macro_list[macro_list_len + 1] = (MACRO_DEF *)NULL; + + def = macro_list[macro_list_len]; + macro_list_len += 1; + def->name = savestring (name); + } + else + { + char *temp_filename = input_filename; + int temp_line = line_number; + + warning ("The macro `%s' is previously defined.", name); + + input_filename = def->filename; + line_number = def->lineno; + + warning ("Here is the previous definition of `%s'.", name); + + input_filename = temp_filename; + line_number = temp_line; + + free (def->filename); + free (def->definition); + } + + def->filename = savestring (filename); + def->lineno = lineno; + def->definition = savestring (definition); +} + + +/* Delete the macro with name NAME. The macro is deleted from the list, + but it is also returned. If there was no macro defined, NULL is + returned. */ +MACRO_DEF * +delete_macro (name) + char *name; +{ + register int i; + register MACRO_DEF *def; + + def = (MACRO_DEF *)NULL; + for (i = 0; macro_list && (def = macro_list[i]); i++) + if (strcmp (def->name, name) == 0) + { + memcpy (macro_list + i, macro_list + i + 1, + ((macro_list_len + 1) - i) * sizeof (MACRO_DEF *)); + break; + } + return (def); +} + +/* Execute the macro passed in DEF, a pointer to a MACRO_DEF. */ +void +execute_macro (def) + MACRO_DEF *def; +{ + + if (def != (MACRO_DEF *)NULL) + { + char *line, *string; + + get_until ("\n", &line); + + if (curchar () == '\n') /* as opposed to the end of the file... */ + { + line_number++; + input_text_offset++; + } + string = (char *)xmalloc (1 + strlen (def->definition) + strlen (line)); + strcpy (string, def->definition); + strcat (string, line); + free (line); + + execute_string ("%s\n", string); + free (string); + } +} + +int +cm_macro () +{ + register int i; + char *line, *name, *expansion; + + get_rest_of_line (&line); + canon_white (line); + + for (i = 0; line[i] && !whitespace (line[i]); i++); + name = (char *)xmalloc (i); + strncpy (name, line, i); + name[i] = '\0'; + + while (whitespace (line[i])) + i++; + + add_macro (name, line + i, input_filename, line_number - 1); + free (line); + free (name); +} + +int +cm_unmacro () +{ + register int i; + char *line, *name; + MACRO_DEF *def; + + get_rest_of_line (&line); + canon_white (line); + + for (i = 0; line[i] && !whitespace (line[i]); i++); + name = (char *)xmalloc (i); + strncpy (name, line, i); + name[i] = '\0'; + + def = delete_macro (name); + + if (def) + { + free (def->filename); + free (def->name); + free (def->definition); + free (def); + } + + free (line); + free (name); +} +#endif /* HAVE_MACROS */ + +/* **************************************************************** */ +/* */ +/* Looking For Include Files */ +/* */ +/* **************************************************************** */ + +/* Given a string containing units of information separated by colons, + return the next one pointed to by INDEX, or NULL if there are no more. + Advance INDEX to the character after the colon. */ +char * +extract_colon_unit (string, index) + char *string; + int *index; +{ + int i, start; + + i = *index; + + if (!string || (i >= strlen (string))) + return ((char *)NULL); + + /* Each call to this routine leaves the index pointing at a colon if + there is more to the path. If I is > 0, then increment past the + `:'. If I is 0, then the path has a leading colon. Trailing colons + are handled OK by the `else' part of the if statement; an empty + string is returned in that case. */ + if (i && string[i] == ':') + i++; + + start = i; + + while (string[i] && string[i] != ':') i++; + + *index = i; + + if (i == start) + { + if (string[i]) + (*index)++; + + /* Return "" in the case of a trailing `:'. */ + return (savestring ("")); + } + else + { + char *value; + + value = (char *)xmalloc (1 + (i - start)); + strncpy (value, &string[start], (i - start)); + value [i - start] = '\0'; + + return (value); + } +} + +/* Return the full pathname for FILENAME by searching along PATH. + When found, return the stat () info for FILENAME in FINFO. + If PATH is NULL, only the current directory is searched. + If the file could not be found, return a NULL pointer. */ +char * +get_file_info_in_path (filename, path, finfo) + char *filename, *path; + struct stat *finfo; +{ + char *dir; + int result, index = 0; + + if (path == (char *)NULL) + path = "."; + + /* Handle absolute pathnames. "./foo", "/foo", "../foo". */ + if (*filename == '/' || + (*filename == '.' && + (filename[1] == '/' || + (filename[1] == '.' && filename[2] == '/')))) + { + if (stat (filename, finfo) == 0) + return (savestring (filename)); + else + return ((char *)NULL); + } + + while (dir = extract_colon_unit (path, &index)) + { + char *fullpath; + + if (!*dir) + { + free (dir); + dir = savestring ("."); + } + + fullpath = (char *)xmalloc (2 + strlen (dir) + strlen (filename)); + sprintf (fullpath, "%s/%s", dir, filename); + free (dir); + + result = stat (fullpath, finfo); + + if (result == 0) + return (fullpath); + else + free (fullpath); + } + return ((char *)NULL); +} diff --git a/gnu/usr.bin/texinfo/misc/Makefile b/gnu/usr.bin/texinfo/misc/Makefile new file mode 100644 index 0000000..00cb486 --- /dev/null +++ b/gnu/usr.bin/texinfo/misc/Makefile @@ -0,0 +1,96 @@ +# Generated automatically from Makefile.in by configure. +# Makefile for GNU Texindex. +# Copyright (C) 1990, 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. + +#### Start of system configuration section. #### + +srcdir = . +VPATH = $(srcdir):$(common) + +common = $(srcdir)/../libtxi + +CC = gcc +INSTALL = /usr/bin/install -c +INSTALL_PROGRAM = $(INSTALL) +INSTALL_DATA = $(INSTALL) -m 644 + +LN = ln +RM = rm -f +TAR = tar +MKDIR = mkdir + +DEFS = -DSTDC_HEADERS=1 -DHAVE_UNISTD_H=1 -DHAVE_STRING_H=1 -DHAVE_VARARGS_H=1 -DHAVE_SYS_TIME_H=1 -DHAVE_SYS_FCNTL_H=1 -DHAVE_SETVBUF=1 -DHAVE_GETCWD=1 -DHAVE_BZERO=1 -DHAVE_RINDEX=1 -DHAVE_VFPRINTF=1 -DHAVE_VSPRINTF=1 +LIBS = -L../libtxi -ltxi +LOADLIBES = $(LIBS) + +SHELL = /bin/sh + +CFLAGS = -g +LDFLAGS = -g + +prefix = /usr/local +exec_prefix = $(prefix) +bindir = $(exec_prefix)/bin +# Prefix for each installed program, normally empty or `g'. +binprefix = +libdir = $(prefix)/lib +# Prefix for each installed man page, normally empty or `g'. +manprefix = +mandir = $(prefix)/man/man1 +manext = 1 +infodir = $(prefix)/info + +#### End of system configuration section. #### + +all: texindex +sub-all: all + +.c.o: + $(CC) -c $(CPPFLAGS) $(DEFS) -I. -I$(srcdir) -I$(common) $(CFLAGS) $< + + +install: all + $(INSTALL_PROGRAM) texindex $(bindir)/texindex + $(INSTALL_PROGRAM) $(srcdir)/texi2dvi $(bindir)/texi2dvi + +uninstall: + rm -f $(bindir)/texindex $(bindir)/texi2dvi + +Makefile: Makefile.in ../config.status + cd ..; sh config.status + +TAGS: + etags *.c *.h $(common)/getopt*.c $(common)/getopt.h + +clean: + rm -f *.o a.out core core.* texindex + +mostlyclean: clean + +distclean: clean + rm -f Makefile config.status + +realclean: distclean + rm -f TAGS + +texindex: texindex.o ../libtxi/libtxi.a + $(CC) $(LDFLAGS) -o texindex texindex.o $(LOADLIBES) + +texindex.o: texindex.c $(common)/getopt.h + +# Prevent GNU make v3 from overflowing arg limit on SysV. +.NOEXPORT: diff --git a/gnu/usr.bin/texinfo/misc/Makefile.in b/gnu/usr.bin/texinfo/misc/Makefile.in new file mode 100644 index 0000000..571b59bb --- /dev/null +++ b/gnu/usr.bin/texinfo/misc/Makefile.in @@ -0,0 +1,95 @@ +# Makefile for GNU Texindex. +# Copyright (C) 1990, 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. + +#### Start of system configuration section. #### + +srcdir = @srcdir@ +VPATH = $(srcdir):$(common) + +common = $(srcdir)/../libtxi + +CC = @CC@ +INSTALL = @INSTALL@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_DATA = @INSTALL_DATA@ + +LN = ln +RM = rm -f +TAR = tar +MKDIR = mkdir + +DEFS = @DEFS@ +LIBS = -L../libtxi -ltxi @LIBS@ +LOADLIBES = $(LIBS) + +SHELL = /bin/sh + +CFLAGS = -g +LDFLAGS = -g + +prefix = /usr/local +exec_prefix = $(prefix) +bindir = $(exec_prefix)/bin +# Prefix for each installed program, normally empty or `g'. +binprefix = +libdir = $(prefix)/lib +# Prefix for each installed man page, normally empty or `g'. +manprefix = +mandir = $(prefix)/man/man1 +manext = 1 +infodir = $(prefix)/info + +#### End of system configuration section. #### + +all: texindex +sub-all: all + +.c.o: + $(CC) -c $(CPPFLAGS) $(DEFS) -I. -I$(srcdir) -I$(common) $(CFLAGS) $< + + +install: all + $(INSTALL_PROGRAM) texindex $(bindir)/texindex + $(INSTALL_PROGRAM) $(srcdir)/texi2dvi $(bindir)/texi2dvi + +uninstall: + rm -f $(bindir)/texindex $(bindir)/texi2dvi + +Makefile: Makefile.in ../config.status + cd ..; sh config.status + +TAGS: + etags *.c *.h $(common)/getopt*.c $(common)/getopt.h + +clean: + rm -f *.o a.out core core.* texindex + +mostlyclean: clean + +distclean: clean + rm -f Makefile config.status + +realclean: distclean + rm -f TAGS + +texindex: texindex.o ../libtxi/libtxi.a + $(CC) $(LDFLAGS) -o texindex texindex.o $(LOADLIBES) + +texindex.o: texindex.c $(common)/getopt.h + +# Prevent GNU make v3 from overflowing arg limit on SysV. +.NOEXPORT: diff --git a/gnu/usr.bin/texinfo/misc/NEWS b/gnu/usr.bin/texinfo/misc/NEWS new file mode 100644 index 0000000..00de163 --- /dev/null +++ b/gnu/usr.bin/texinfo/misc/NEWS @@ -0,0 +1,171 @@ +This release of Info is version 2.8. Please read the file README. + +Changes since 2.5 beta: + +Note that versions 2.6 and 2.7 Beta were only released to a select group. + +* "info-" removed from the front of M-x commands. + +* Automatic footnote display. When you enter a node which contains + footnotes, and the variable "automatic-footnotes" is "On", Info pops + up a window containing the footnotes. Likewise, when you leave that + node, the window containing the footnotes goes away. + +* Cleaner built in documentation, and documentation functions. + + Use: + o `M-x describe-variable' to read a variable's documenation + o `M-x describe-key' to find out what a particular keystroke does. + o `M-x describe-function' to read a function's documentation. + o `M-x where-is' to find out what keys invoke a particular function. + +* Info can "tile" the displayed windows (via "M-x tile-windows"). If + the variable "automatic-tiling" is "On", then splitting a window or + deleting a window causes the remaining windows to be retiled. + +* You can save every keystroke you type in a "dribble file" by using the + `--dribble FILENAME' option. You can initially read keystrokes from an + alternate input stream with `--restore FILENAME', or by redirecting + input on the command line `info < old-dribble'. + +* New behaviour of menu items. If the label is the same as the + target node name, and the node couldn't be found in the current file, + treat the label as a file name. For example, a menu entry in "DIR" + might contain: + + * Emacs:: Cool text-editor. + + Info would not find the node "(dir)Emacs", so just plain "(emacs)" + would be tried. + +* New variable "ISO-Latin" allows you to use European machines with + 8-bit character sets. + +* Cleanups in echo area reading, and redisplay. Cleanups in handling the + window which shows possible completions. + +* Info can now read files that have been compressed. An array in filesys.c + maps extensions to programs that can decompress stdin, and write the results + to stdout. Currently, ".Z"/uncompress, ".z"/gunzip, and ".Y"/unyabba are + supported. The modeline for a compressed file shows "zz" in it. + +* There is a new variable "gc-compressed-files" which, if non-zero, says + it is okay to reclaim the file buffer space allocated to a file which + was compressed, if, and only if, that file's contents do not appear in + any history node. + +* New file `nodemenu.c' implements a few functions for manipulating + previously visited nodes. `C-x C-b' (list-visited-nodes) produces a + menu of the nodes that could be reached by info-history-node in some + window. `C-x b' (select-visited-node) is similar, but reads one of + the node names with completion. + +* Keystroke `M-r' (move_to_screen_line) allows the user to place the cursor at + the start of a specific screen line. Without a numeric argument, place the + cursor on the center line; with an arg, place the cursor on that line. + +* Interruptible display implemented. Basic display speedups and hacks. +* The message "*** Tags Out of Date ***" now means what it says. +* Index searching with `,' (info-index-next) has been improved. +* When scrolling with C-v, C-M-v, or M-v, only "Page Only" scrolling + will happen. + +* Continous scrolling (along with `]' (info-global-next) and `[' + (info-global-prev) works better. `]' and `[' accept numeric + arguments, moving that many nodes in that case. + +* `C-x w' (info-toggle-wrap) controls how lines wider than the width + of the screen are displayed. If a line is too long, a `$' is + displayed in the rightmost column of the window. + +* There are some new variables for controlling the behaviour of Info + interactively. The current list of variables is as follows: + + Variable Name Default Value Description + ------------- ------------- ----------- + `automatic-footnotes' On When "On", footnotes appear and + disappear automatically. + + `automatic-tiling' Off When "On", creating of deleting a + window resizes other windows. + + `visible-bell' Off If non-zero, try to use a visible bell. + + `errors-ring-bell' On If non-zero, errors cause a ring. + + `show-index-match' On If non-zero, the portion of the string + matched is highlighted by changing its + case. + + `scroll-behaviour' Continuous One of "Continuous", "Next Only", or + "Page Only". "Page Only" prevents you from + scrolling past the bottom or top of a node. + "Next Only" causes the Next or Prev node to + be selected when you scroll past the bottom + or top of a node. "Continous" moves + linearly through the files hierchichal + structure. + + `scroll-step' 0 Controls how scrolling is done for you when + the cursor moves out of the current window. + Non-zero means it is the number of lines + you would like the screen to shift. A + value of 0 means to center the line + containing the cursor in the window. + + `gc-compressed-files' Off If non-zero means it is okay to reclaim the + file buffer space allocated to a file which + was compressed, if, and only if, that + file's contents do not appear in the node + list of any window. + + `ISO-Latin' Off Non-zero means that you are using an ISO + Latin character set. By default, standard + ASCII characters are assumed. +________________________________________ +This release of Info is version 2.5 beta. + +Changes since 2.4 beta: + +* Index (i) and (,) commands fully implemented. +* "configure" script now shipped with Info. +* New function "set-variable" allows users to set various variables. +* User-settable behaviour on end or beginning of node scrolling. This + supercedes the SPC and DEL changes in 2.3 beta. + +________________________________________ +This release of Info is version 2.4 beta. + +Changes since 2.3 beta: + +* info-last-node now means move to the last node of this info file. +* info-history-node means move backwards through this window's node history. +* info-first-node moves to the first node in the Info file. This node is + not necessarily "Top"! +* SPC and DEL can select the Next or Prev node after printing an informative + message when pressed at the end/beg of a node. + +---------------------------------------- +This release of Info is version 2.3 beta. + +Changes since 2.2 beta: + +* M-x command lines if NAMED_COMMANDS is #defined. Variable in Makefile. +* Screen height changes made quite robust. +* Interactive function "set-screen-height" implements user height changes. +* Scrolling on some terminals is faster now. +* C-l with numeric arguement is fixed. + +---------------------------------------- +This release of Info is version 2.2 beta. + +Changes since 2.0: + +* C-g can now interrupt multi-file searches. +* Incremental search is fully implemented. +* Loading large tag tables is much faster now. +* makedoc.c replaces shell script, speeding incremental builds. +* Scrolling in redisplay is implemented. +* Recursive uses of the echo area made more robust. +* Garbage collection of unreferenced nodes. + diff --git a/gnu/usr.bin/texinfo/misc/README b/gnu/usr.bin/texinfo/misc/README new file mode 100644 index 0000000..12cfa62 --- /dev/null +++ b/gnu/usr.bin/texinfo/misc/README @@ -0,0 +1,54 @@ + Please Emacs, use -*- text -*- mode when editing this file. + + * The file RELEASE contains information about what has changed + since the last release. + + * The file INSTALL contains instructions on how to install Info. + (Type "./configure" and then "make".) + +This is the README file GNU Info version 2.8. This marks the first +non-beta release. + +Thu Jan 21 14:50:52 1993 + +---------------------------------------- +Version 2.7 beta, Wed Dec 30 02:02:38 1992 +Version 2.6 beta, Tue Dec 22 03:58:07 1992 +Version 2.5 beta, Tue Dec 8 14:50:35 1992 +Version 2.4 beta, Sat Nov 28 14:34:02 1992 +Version 2.3 beta, Fri Nov 27 01:04:13 1992 +Version 2.2 beta, Tue Nov 24 09:36:08 1992 +Version 2.1 beta, Tue Nov 17 23:29:36 1992 + +Info 2.0 is a complete rewrite of the original standalone Info I wrote +in 1987, the first program I wrote for rms. That program was +something like my second Unix program ever, and my die-hard machine +language coding habits tended to show through. I found the original +Info hard to read and maintain, and thus decided to write this one. + +The rewrite consists of about 12,000 lines of code written in about 12 +days. I believe this version of Info to be in much better shape than +the original Info, and the only reason it is in Beta test is because +of its short life span. + +Info 2.0 is substantially different from its original standalone +predecessor. It appears almost identical to the GNU Emacs version, +but has the advantages of smaller size, ease of portability, and a +built in library which can be used in other programs (to get or +display documentation from Info files, for example). + +I eagerly await responses to this newer version of Info; comments on +its portability, ease of use and user interface, code quality, and +general usefulness are all of interest to me, and I will appreciate +any comments that you would care to make. + +A full listing of the commands available in Info can be gotten by +typing `?' while within an Info window. This produces a node in a +window which can be viewed just like any Info node. + +So, please send your comments, bug reports, and suggestions to + + bfox@ai.mit.edu + +Thanks for beta testing this software. + diff --git a/gnu/usr.bin/texinfo/misc/deref.c b/gnu/usr.bin/texinfo/misc/deref.c new file mode 100644 index 0000000..c15bc1a --- /dev/null +++ b/gnu/usr.bin/texinfo/misc/deref.c @@ -0,0 +1,238 @@ +/* + * deref.c + + * compile command: gcc -g -o deref deref.c + + * execute command: deref filename.texi > newfile.texi + + * To: bob@gnu.ai.mit.edu + * Subject: another tool + * Date: 18 Dec 91 16:03:13 EST (Wed) + * From: gatech!skeeve!arnold@eddie.mit.edu (Arnold D. Robbins) + * + * Here is deref.c. It turns texinfo cross references back into the + * one argument form. It has the same limitations as fixref; one xref per + * line and can't cross lines. You can use it to find references that do + * cross a line boundary this way: + * + * deref < manual > /dev/null 2>errs + * + * (This assumes bash or /bin/sh.) The file errs will have list of lines + * where deref could not find matching braces. + * + * A gawk manual processed by deref goes through makeinfo without complaint. + * Compile with gcc and you should be set. + * + * Enjoy, + * + * Arnold + * ----------- + */ + +/* + * deref.c + * + * Make all texinfo references into the one argument form. + * + * Arnold Robbins + * arnold@skeeve.atl.ga.us + * December, 1991 + * + * Copyright, 1991, Arnold Robbins + */ + +/* + * LIMITATIONS: + * One texinfo cross reference per line. + * Cross references may not cross newlines. + * Use of fgets for input (to be fixed). + */ + +#include <stdio.h> +#include <ctype.h> +#include <errno.h> + +/* for gcc on the 3B1, delete if this gives you grief */ +extern int fclose (FILE * fp); +extern int fprintf (FILE * fp, const char *str,...); + +extern char *strerror (int errno); +extern char *strchr (char *cp, int ch); +extern int strncmp (const char *s1, const char *s2, int count); + +extern int errno; + +void process (FILE * fp); +void repair (char *line, char *ref, int toffset); + +int Errs = 0; +char *Name = "stdin"; +int Line = 0; +char *Me; + +/* main --- handle arguments, global vars for errors */ + +int +main (int argc, char **argv) +{ + FILE *fp; + + Me = argv[0]; + + if (argc == 1) + process (stdin); + else + for (argc--, argv++; *argv != NULL; argc--, argv++) + { + if (argv[0][0] == '-' && argv[0][1] == '\0') + { + Name = "stdin"; + Line = 0; + process (stdin); + } + else if ((fp = fopen (*argv, "r")) != NULL) + { + Name = *argv; + Line = 0; + process (fp); + fclose (fp); + } + else + { + fprintf (stderr, "%s: can not open: %s\n", + *argv, strerror (errno)); + Errs++; + } + } + return Errs != 0; +} + +/* isref --- decide if we've seen a texinfo cross reference */ + +int +isref (char *cp) +{ + if (strncmp (cp, "@ref{", 5) == 0) + return 5; + if (strncmp (cp, "@xref{", 6) == 0) + return 6; + if (strncmp (cp, "@pxref{", 7) == 0) + return 7; + return 0; +} + +/* process --- read files, look for references, fix them up */ + +void +process (FILE * fp) +{ + char buf[BUFSIZ]; + char *cp; + int count; + + while (fgets (buf, sizeof buf, fp) != NULL) + { + Line++; + cp = strchr (buf, '@'); + if (cp == NULL) + { + fputs (buf, stdout); + continue; + } + do + { + count = isref (cp); + if (count == 0) + { + cp++; + cp = strchr (cp, '@'); + if (cp == NULL) + { + fputs (buf, stdout); + goto next; + } + continue; + } + /* got one */ + repair (buf, cp, count); + break; + } + while (cp != NULL); + next:; + } +} + +/* repair --- turn all texinfo cross references into the one argument form */ + +void +repair (char *line, char *ref, int toffset) +{ + int braces = 1; /* have seen first left brace */ + char *cp; + + ref += toffset; + + /* output line up to and including left brace in reference */ + for (cp = line; cp <= ref; cp++) + putchar (*cp); + + /* output node name */ + for (; *cp && *cp != '}' && *cp != ',' && *cp != '\n'; cp++) + putchar (*cp); + + if (*cp != '}') + { /* could have been one arg xref */ + /* skip to matching right brace */ + for (; braces > 0; cp++) + { + switch (*cp) + { + case '@': + cp++; /* blindly skip next character */ + break; + case '{': + braces++; + break; + case '}': + braces--; + break; + case '\n': + case '\0': + Errs++; + fprintf (stderr, + "%s: %s: %d: mismatched braces\n", + Me, Name, Line); + goto out; + default: + break; + } + } + out: + ; + } + + putchar ('}'); + if (*cp == '}') + cp++; + + /* now the rest of the line */ + for (; *cp; cp++) + putchar (*cp); + return; +} + +/* strerror --- return error string, delete if in your library */ + +char * +strerror (int errno) +{ + static char buf[100]; + extern int sys_nerr; + extern char *sys_errlist[]; + + if (errno < sys_nerr && errno >= 0) + return sys_errlist[errno]; + + sprintf (buf, "unknown error %d", errno); + return buf; +} diff --git a/gnu/usr.bin/texinfo/misc/fixfonts b/gnu/usr.bin/texinfo/misc/fixfonts new file mode 100755 index 0000000..ee2ea71 --- /dev/null +++ b/gnu/usr.bin/texinfo/misc/fixfonts @@ -0,0 +1,84 @@ +#!/bin/sh +# Make links named `lcircle10' for all TFM and GF/PK files, if no +# lcircle10 files already exist. + +# Don't override definition of prefix and/or libdir if they are +# already defined in the environment. +if test "z${prefix}" = "z" ; then + prefix=/usr/local +else + # prefix may contain references to other variables, thanks to make. + eval prefix=\""${prefix}"\" +fi + +if test "z${libdir}" = "z" ; then + libdir="${prefix}/lib/tex" +else + # libdir may contain references to other variables, thanks to make. + eval libdir=\""${libdir}"\" +fi + +texlibdir="${libdir}" +texfontdir="${texlibdir}/fonts" + +# Directories for the different font formats, in case they're not all +# stored in one place. +textfmdir="${textfmdir-${texfontdir}}" +texpkdir="${texpkdir-${texfontdir}}" +texgfdir="${texgfdir-${texfontdir}}" + +test "z${TMPDIR}" = "z" && TMPDIR="/tmp" + +tempfile="${TMPDIR}/circ$$" +tempfile2="${TMPDIR}/circ2$$" + +# EXIT SIGHUP SIGINT SIGQUIT SIGTERM +#trap 'rm -f "${tempfile}" "${tempfile2}"' 0 1 2 3 15 + +# Find all the fonts with names that include `circle'. +(cd "${texfontdir}"; find . -name '*circle*' -print > "${tempfile}") + +# If they have lcircle10.tfm, assume everything is there, and quit. +if grep 'lcircle10\.tfm' "${tempfile}" > /dev/null 2>&1 ; then + echo "Found lcircle10.tfm." + exit 0 +fi + +# No TFM file for lcircle. Make a link to circle10.tfm if it exists, +# and then make a link to the bitmap files. +grep 'circle10\.tfm' "${tempfile}" > "${tempfile2}" \ + || { + echo "I can't find any circle fonts in ${texfontdir}. +If it isn't installed somewhere else, you need to get the Metafont sources +from somewhere, e.g., labrea.stanford.edu:pub/tex/latex/circle10.mf, and +run Metafont on them." + exit 1 + } + +# We have circle10.tfm. (If we have it more than once, take the first +# one.) Make the link. +tempfile2_line1="`sed -ne '1p;q' \"${tempfile2}\"`" +ln "${tempfile2_line1}" "${textfmdir}/lcircle10.tfm" +echo "Linked to ${tempfile2_line1}." + +# Now make a link for the PK files, if any. +(cd "${texpkdir}" + for f in `grep 'circle10.*pk' "${tempfile}"` ; do + set - `echo "$f" \ + | sed -ne '/\//!s/^/.\//;s/\(.*\)\/\([^\/][^\/]*\)$/\1 \2/;p'` + ln "$f" "${1}/l${2}" + echo "Linked to $f." + done +) + +# And finally for the GF files. +(cd "${texgfdir}" + for f in `grep 'circle10.*gf' "${tempfile}"` ; do + set - `echo "$f" \ + | sed -ne '/\//!s/^/.\//;s/\(.*\)\/\([^\/][^\/]*\)$/\1 \2/;p'` + ln "$f" "${1}/l${2}" + echo "Linked to $f." + done +) + +# eof diff --git a/gnu/usr.bin/texinfo/misc/mkinstalldirs b/gnu/usr.bin/texinfo/misc/mkinstalldirs new file mode 100755 index 0000000..0e29377 --- /dev/null +++ b/gnu/usr.bin/texinfo/misc/mkinstalldirs @@ -0,0 +1,35 @@ +#!/bin/sh +# Make directory hierarchy. +# Written by Noah Friedman <friedman@prep.ai.mit.edu> +# Public domain. + +defaultIFS=' +' +IFS="${IFS-${defaultIFS}}" + +errstatus=0 + +for file in ${1+"$@"} ; do + oIFS="${IFS}" + # Some sh's can't handle IFS=/ for some reason. + IFS='%' + set - `echo ${file} | sed -e 's@/@%@g' -e 's@^%@/@'` + IFS="${oIFS}" + + pathcomp='' + + for d in ${1+"$@"} ; do + pathcomp="${pathcomp}${d}" + + if test ! -d "${pathcomp}"; then + echo "mkdir $pathcomp" 1>&2 + mkdir "${pathcomp}" || errstatus=$? + fi + + pathcomp="${pathcomp}/" + done +done + +exit $errstatus + +# eof diff --git a/gnu/usr.bin/texinfo/misc/tex3patch b/gnu/usr.bin/texinfo/misc/tex3patch new file mode 100755 index 0000000..1708c75 --- /dev/null +++ b/gnu/usr.bin/texinfo/misc/tex3patch @@ -0,0 +1,71 @@ +#!/bin/sh +# Auxiliary script to work around TeX 3.0 bug. ---- tex3patch ---- +# patches texinfo.tex in current directory, or in directory given as arg. + +ANYVERSION=no + +for arg in $1 $2 +do + case $arg in + --dammit | -d ) ANYVERSION=yes ;; + + * ) dir=$arg + esac +done + +if [ -z "$dir" ]; then + dir='.' +fi + +if [ \( 2 -lt $# \) -o \ + \( ! -f $dir/texinfo.tex \) ]; then + echo "To patch texinfo.tex for peaceful coexistence with Unix TeX 3.0," + echo "run $0" + echo "with no arguments in the same directory as texinfo.tex; or run" + echo " $0 DIRECTORY" + echo "(where DIRECTORY is a path leading to texinfo.tex)." + exit +fi + +if [ -z "$TMPDIR" ]; then + TMPDIR=/tmp +fi + +echo "Checking for \`dummy.tfm'" + +( cd $TMPDIR; tex '\relax \batchmode \font\foo=dummy \bye' ) + +grep -s '3.0' $TMPDIR/texput.log +if [ 1 = "$?" -a "$ANYVERSION" != "yes" ]; then + echo "You probably do not need this patch," + echo "since your TeX does not seem to be version 3.0." + echo "If you insist on applying the patch, run $0" + echo "again with the option \`--dammit'" + exit +fi + +grep -s 'file not found' $TMPDIR/texput.log +if [ 0 = $? ]; then + echo "This patch requires the dummy font metric file \`dummy.tfm'," + echo "which does not seem to be part of your TeX installation." + echo "Please get your TeX maintainer to install \`dummy.tfm'," + echo "then run this script again." + exit +fi +rm $TMPDIR/texput.log + +echo "Patching $dir/texinfo.tex" + +sed -e 's/%%*\\font\\nullfont/\\font\\nullfont/' \ + $dir/texinfo.tex >$TMPDIR/texinfo.tex +mv $dir/texinfo.tex $dir/texinfo.tex-distrib; mv $TMPDIR/texinfo.tex $dir + +if [ 0 = $? ]; then + echo "Patched $dir/texinfo.tex to avoid TeX 3.0 bug." + echo "The original version is saved as $dir/texinfo.tex-distrib." +else + echo "Patch failed. Sorry." +fi +----------------------------------------tex3patch ends + + diff --git a/gnu/usr.bin/texinfo/misc/texi2dvi b/gnu/usr.bin/texinfo/misc/texi2dvi new file mode 100755 index 0000000..12281e5 --- /dev/null +++ b/gnu/usr.bin/texinfo/misc/texi2dvi @@ -0,0 +1,263 @@ +#!/bin/sh +# texi2dvi -- smartly produce DVI files from texinfo sources +# +# Copyright (C) 1992, 1993 Free Software Foundation. +# +# 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, you can either send email to this +# program's author (see below) or write to: +# +# Free Software Foundation, Inc. +# 675 Mass Ave. +# Cambridge, MA 02139, USA. +# +# Please send bug reports, etc. to bug-texinfo@prep.ai.mit.edu +# If possible, please send a copy of the output of the script called with +# the `--debug' option when making a bug report. +# +# Version 0.4 +# Last modified 26-Mar-93 +# + +# Please note that in the interest of general portability, some common +# bourne shell constructs were avoided because they weren't guaranteed to +# be available in some earlier implementations. I've tried to make this as +# portable as possible. +# +# Among the more interesting lossages I noticed with some bourne shells +# are: +# 1) Some don't have an `unset' builtin +# 2) In some implementations the `shift' builtin can't take a +# numerical argument. + +progname=`basename $0` + +usage="Usage: ${progname} {-D} {-h} [file1] {file2} {...} + {--debug} {--help} + + Options in braces are optional. Those in brackets are required. +" + +if test $# -eq 0 ; then + echo "${usage}" 1>&2; + exit 1 +fi + +backup_extension=".bak" +texindex="texindex" +tex="tex" +bq="\`" # To prevent hairy quoting and escaping later. +eq="'" +orig_pwd="`pwd`" + +if test "z${TEXINDEX}" != "z" ; then + texindex="${TEXINDEX}" +fi + +if test "z${TEX}" != "z" ; then + tex="${TEX}" +fi + +# Save this so we can construct a new TEXINPUTS path for each file to be +# processed. +TEXINPUTS_orig="${TEXINPUTS}" +export TEXINPUTS + +# Parse command line options + +# "unset" option variables to make sure they weren't accidentally +# exported +debug="" + +# If you add new commands be sure to change the wildcards below to make +# sure they are unambiguous (i.e. only match one possible long option) +# Be sure to show at least one instance of the full long option name to +# document what the long option is canonically called. +while test $# -gt 0 ; do + case z$1 in + z-D | z--debug | z--d* ) + debug="t" + shift + ;; + z-h | z--help | z--h* ) + echo "${usage}" 1>&2 + exit 1 + ;; + z-- ) + shift + break + ;; + z-* ) + echo "${progname}: ${bq}${1}${eq} is not a valid option." 1>&2 + echo "" 1>&2 + echo "${usage}" 1>&2 + exit 1 + ;; + * ) + break + ;; + esac +done + +# See if there are any command line args left (which will be interpreted as +# filename arguments) +if test $# -eq 0 ; then + echo "${progname}: at least one file name is required as an argument." 1>&2 + echo "" 1>&2 + echo "${usage}" 1>&2 + exit 1 +fi + +test "z${debug}" = "zt" && set -x + +# Texify files +for command_line_filename in ${1+"$@"} ; do + # Roughly equivalent to `dirname ...`, but more portable + directory="`echo ${command_line_filename} | sed 's/\/[^\/]*$//'`" + filename_texi="`basename ${command_line_filename}`" + # Strip off the last extension part (probably .texinfo or .texi) + filename_noext="`echo ${filename_texi} | sed 's/\.[^.]*$//'`" + + # If directory and file are the same, then it's probably because there's + # no pathname component. Set dirname to `.', the current directory. + if test "z${directory}" = "z${command_line_filename}" ; then + directory="." + fi + + # Source file might @include additional texinfo sources. Put `.' and + # directory where source file(s) reside in TEXINPUTS before anything + # else. `.' goes first to ensure that any old .aux, .cps, etc. files in + # ${directory} don't get used in preference to fresher files in `.'. + TEXINPUTS=".:${directory}:${TEXINPUTS_orig}" + + # "Unset" variables that might have values from previous iterations and + # which won't be completely reset later. + definite_index_files="" + + # See if file exists here. If it doesn't we're in trouble since, even + # though the user may be able to reenter a valid filename at the tex + # prompt (assuming they're attending the terminal), this script won't be + # able to find the right index files and so forth. + if test ! -r "${command_line_filename}" ; then + echo "${progname}: ${command_line_filename}: No such file or permission denied." 1>&2 + continue; + fi + + # Find all files having root filename with a two-letter extension, + # determine whether they're really index files, and save them. Foo.aux + # is actually the cross-references file, but we need to keep track of + # that too. + possible_index_files="`eval echo ${filename_noext}.?? ${filename_noext}.aux`" + for this_file in ${possible_index_files} ; do + # If file is empty, forget it. + if test ! -s "${this_file}" ; then + continue; + fi + + # Examine first character of file. If it's not a backslash or + # single quote, then it's definitely not an index or xref file. + first_character="`sed -n '1s/^\(.\).*$/\1/p;q' ${this_file}`" + if test "${first_character}" = "\\" -o "${first_character}" = "'" ; then + definite_index_files="${definite_index_files} ${this_file}" + fi + done + orig_index_files="${definite_index_files}" + orig_index_files_sans_aux="`echo ${definite_index_files} \ + | sed 's/'${filename_noext}'\.aux//; + s/^[ ]*//;s/[ ]*$//;'`" + + # Now save copies of original index files so we have some means of + # comparison later. + for index_file_to_save in ${orig_index_files} ; do + cp "${index_file_to_save}" "${index_file_to_save}${backup_extension}" + done + + # Run texindex on current index files. If they already exist, and + # after running TeX a first time the index files don't change, then + # there's no reason to run TeX again. But we won't know that if the + # index files are out of date or nonexistent. + if test "${orig_index_files_sans_aux}" ; then + ${texindex} ${orig_index_files_sans_aux} + fi + + if ${tex} ${command_line_filename} ; then # TeX run first time + definite_index_files="" + # Get list of new index files + possible_index_files="`eval echo ${filename_noext}.?? ${filename_noext}.aux`" + for this_file in ${possible_index_files} ; do + # If file is empty, forget it. + if test ! -s ${this_file} ; then + continue; + fi + + # Examine first character of file. If it's not a backslash or + # single quote, then it's definitely not an index or xref file. + first_character="`sed -n '1s/^\(.\).*$/\1/p;q' ${this_file}`" + if test "${first_character}" = "\\" -o "${first_character}" = "'" ; then + definite_index_files="${definite_index_files} ${this_file}" + fi + done + new_index_files="${definite_index_files}" + new_index_files_sans_aux="`echo ${definite_index_files} \ + | sed 's/'${filename_noext}'\.aux//; + s/^[ ]*//;s/[ ]*$//;'`" + + # If old and new list don't at least have the same file list, then one + # file or another has definitely changed. + if test "${orig_index_files}" != "${new_index_files}" ; then + index_files_changed_p=t + else + # File list is the same. We must compare each file until we find a + # difference. + index_files_changed_p="" + for this_file in ${new_index_files} ; do + # cmp -s will return nonzero exit status if files differ. + cmp -s "${this_file}" "${this_file}${backup_extension}" + if test $? -ne 0 ; then + # We only need to keep comparing until we find *one* that + # differs, because we'll have to run texindex & tex no + # matter what. + index_files_changed_p=t + break + fi + done + fi + + # If index files have changed since TeX has been run, or if the aux + # file wasn't present originally, run texindex and TeX again. + if test "${index_files_changed_p}" ; then + retval=0 + if test "${new_index_files_sans_aux}" ; then + ${texindex} ${new_index_files_sans_aux} + retval=$? + fi + if test ${retval} -eq 0 ; then + ${tex} "${command_line_filename}" + fi + fi + fi + + # Generate list of files to delete, then call rm once with the entire + # list. This is significantly faster than multiple executions of rm. + file_list="" + for file in ${orig_index_files} ; do + file_list="${file_list} ${file}${backup_extension}" + done + if test "${file_list}" ; then + rm -f ${file_list} + fi +done + +# +# eof +# diff --git a/gnu/usr.bin/texinfo/misc/texindex.c b/gnu/usr.bin/texinfo/misc/texindex.c new file mode 100644 index 0000000..a88d516 --- /dev/null +++ b/gnu/usr.bin/texinfo/misc/texindex.c @@ -0,0 +1,1700 @@ +/* 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 */ diff --git a/gnu/usr.bin/texinfo/texindex/Makefile b/gnu/usr.bin/texinfo/texindex/Makefile new file mode 100644 index 0000000..ef51fdf --- /dev/null +++ b/gnu/usr.bin/texinfo/texindex/Makefile @@ -0,0 +1,21 @@ +# +# Bmakefile for GNU info +# +# $id$ +# + +PROG= texindex + +SRCS+= texindex.c getopt1.c getopt.c +.PATH: ${.CURDIR}/../info + +CFLAGS+= -I${.CURDIR}/../info -I${.CURDIR} +CFLAGS+= -DNAMED_FUNCTIONS=1 -DSTDC_HEADERS=1 +CFLAGS+= -DHAVE_UNISTD_H=1 -DHAVE_STRING_H=1 -DHAVE_VARARGS_H=1 +CFLAGS+= -DHAVE_SYS_FCNTL_H=1 -DHAVE_SETVBUF=1 -DHAVE_GETCWD=1 -DHAVE_BZERO=1 +CFLAGS+= -DHAVE_RINDEX=1 -DHAVE_VFPRINTF=1 -DHAVE_VSPRINTF=1 +CFLAGS+= -DHAVE_SYS_TIME_H=1 -DDEFAULT_INFOPATH='"${INFODIR}"' + +.include "../../Makefile.inc" +.include <bsd.prog.mk> + diff --git a/gnu/usr.bin/texinfo/texindex/texindex.c b/gnu/usr.bin/texinfo/texindex/texindex.c new file mode 100644 index 0000000..f7b0aef --- /dev/null +++ b/gnu/usr.bin/texinfo/texindex/texindex.c @@ -0,0 +1,1700 @@ +/* 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 const char * const 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 */ |
