Mercurial > octave-nkf
changeset 2331:798a4d06ba7d
[project @ 1996-07-19 01:52:57 by jwe]
Initial revision
| author | jwe |
|---|---|
| date | Fri, 19 Jul 1996 01:57:38 +0000 |
| parents | 12ff450cbb1f |
| children | 98d0771f7484 |
| files | info/NEWS info/README info/info-stnd.texi info/info.1 info/info.texi info/mkinstalldirs info/userdoc.texi kpathsea/AUTHORS kpathsea/CONFIGURE kpathsea/HIER kpathsea/INSTALL kpathsea/MakeTeXPK.in kpathsea/NEWS kpathsea/README kpathsea/aclocal.m4 kpathsea/c-auto.h.in kpathsea/common.ac kpathsea/config.guess kpathsea/config.sub kpathsea/configure.in kpathsea/copying.texi kpathsea/freedom.texi kpathsea/install.texi kpathsea/kpathsea.texi kpathsea/maintain.texi kpathsea/make-stds.texi kpathsea/stamp-auto.in kpathsea/standards.texi kpathsea/texmf.cnf.in liboctave/OChangeLog liboctave/filemode.c make/README |
| diffstat | 31 files changed, 13947 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/info/NEWS Fri Jul 19 01:57:38 1996 +0000 @@ -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. +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/info/README Fri Jul 19 01:57:38 1996 +0000 @@ -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. +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/info/info-stnd.texi Fri Jul 19 01:57:38 1996 +0000 @@ -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
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/info/info.1 Fri Jul 19 01:57:38 1996 +0000 @@ -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
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/info/info.texi Fri Jul 19 01:57:38 1996 +0000 @@ -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 @* +59 Temple Place - Suite 330, @* +Boston, MA 02111-1307 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 +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/info/mkinstalldirs Fri Jul 19 01:57:38 1996 +0000 @@ -0,0 +1,36 @@ +#!/bin/sh +# mkinstalldirs --- make directory hierarchy +# Author: Noah Friedman <friedman@prep.ai.mit.edu> +# Created: 1993-05-16 +# Last modified: Wed Jan 25 09:35:21 1995 +# Public domain + +errstatus=0 + +dirmode=0755 + +for file in ${1+"$@"} ; do + set fnord `echo ":$file" | sed -ne 's/^:\//#/;s/^://;s/\// /g;s/^#/\//;p'` + shift + + pathcomp= + for d in ${1+"$@"} ; do + pathcomp="$pathcomp$d" + case "$pathcomp" in + -* ) pathcomp=./$pathcomp ;; + esac + + if test ! -d "$pathcomp"; then + echo "mkdir $pathcomp" 1>&2 + mkdir "$pathcomp" || errstatus=$? + echo "chmod $dirmode $pathcomp" 1>&2 + chmod $dirmode "$pathcomp" || errstatus=$? + fi + + pathcomp="$pathcomp/" + done +done + +exit $errstatus + +# mkinstalldirs ends here
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/info/userdoc.texi Fri Jul 19 01:57:38 1996 +0000 @@ -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
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kpathsea/AUTHORS Fri Jul 19 01:57:38 1996 +0000 @@ -0,0 +1,7 @@ +Karl Berry wrote all files not otherwise marked, with help from Kathryn +Hargreaves on some of the original versions. + +The implementation of the link trick in pathsrch.c is taken from GNU +find, implemented by David MacKenzie from Matthew Farwell's suggestion. + +Mike Haertel wrote the GNU malloc source.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kpathsea/CONFIGURE Fri Jul 19 01:57:38 1996 +0000 @@ -0,0 +1,179 @@ +Contents: + + Basic Installation + Compilers and Options + Using a Different Build Directory + Installation Names + Optional Features + Specifying the System Type + Sharing Defaults + Operation Controls + + +Basic Installation +================== + + These are generic installation instructions. + + The `configure' shell script attempts to guess correct values for +various system-dependent variables used during compilation. It uses +those values to create a `Makefile' in each directory of the package. +It may also create one or more `.h' files containing system-dependent +definitions. Finally, it creates a shell script `config.status' that +you can run in the future to recreate the current configuration, a file +`config.cache' that saves the results of its tests to speed up +reconfiguring, and a file `config.log' containing compiler output +(useful mainly for debugging `configure'). + + If you need to do unusual things to compile the package, please try +to figure out how `configure' could check whether to do them, and mail +diffs or instructions to the address given in the `README' so they can +be considered for the next release. If at some point `config.cache' +contains results you don't want to keep, you may remove or edit it. + + The file `configure.in' is used to create `configure' by a program +called `autoconf'. You only need `configure.in' if you want to change +it or regenerate `configure' using a newer version of `autoconf'. + +The simplest way to compile this package is: + + 1. `cd' to the directory containing the package's source code and type + `./configure' to configure the package for your system. If you're + using `csh' on an old version of System V, you might need to type + `sh ./configure' instead to prevent `csh' from trying to execute + `configure' itself. + + Running `configure' takes awhile. While running, it prints some + messages telling which features it is checking for. + + 2. Type `make' to compile the package. + + 3. Optionally, type `make check' to run any self-tests that come with + the package. + + 4. Type `make install' to install the programs and any data files and + documentation. + + 5. You can remove the program binaries and object files from the + source directory by typing `make clean'. To also remove the files + that `configure' created (so you can compile the package for a + different kind of computer), type `make distclean'. + +Compilers and Options +===================== + + Some systems require unusual options for compilation or linking that +the `configure' script does not know about. You can give `configure' +initial values for variables by setting them in the environment. Using +a Bourne-compatible shell, you can do that on the command line like +this: + CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure + +Or on systems that have the `env' program, you can do it like this: + env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure + +Using a Different Build Directory +================================= + + You can compile the package in a different directory from the one +containing the source code. Doing so allows you to compile it on more +than one kind of computer at the same time. To do this, you must use a +version of `make' that supports the `VPATH' variable, such as GNU +`make'. `cd' to the directory where you want the object files and +executables to go and run the `configure' script. `configure' +automatically checks for the source code in the directory that +`configure' is in and in `..'. + +Installation Names +================== + + By default, `make install' will install the package's files in +`/usr/local/bin', `/usr/local/man', etc. You can specify an +installation prefix other than `/usr/local' by giving `configure' the +option `--prefix=PATH'. + + You can specify separate installation prefixes for +architecture-specific files and architecture-independent files. If you +give `configure' the option `--exec-prefix=PATH', the package will use +PATH as the prefix for installing programs and libraries. +Documentation and other data files will still use the regular prefix. + + If the package supports it, you can cause programs to be installed +with an extra prefix or suffix on their names by giving `configure' the +option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'. + +Optional Features +================= + + Some packages pay attention to `--enable-FEATURE' options to +`configure', where FEATURE indicates an optional part of the package. +They may also pay attention to `--with-PACKAGE' options, where PACKAGE +is something like `gnu-as' or `x' (for the X Window System). The +`README' should mention any `--enable-' and `--with-' options that the +package recognizes. + + For packages that use the X Window System, `configure' can usually +find the X include and library files automatically, but if it doesn't, +you can use the `configure' options `--x-includes=DIR' and +`--x-libraries=DIR' to specify their locations. + +Specifying the System Type +========================== + + There may be some features `configure' can not figure out +automatically, but needs to determine by the type of host the package +will run on. Usually `configure' can figure that out, but if it prints +a message saying it can not guess the host type, give it the +`--host=TYPE' option. TYPE can either be a short name for the system +type, such as `sun4', or a canonical name with three fields: + CPU-COMPANY-SYSTEM + +See the file `config.sub' for the possible values of each field. If +`config.sub' isn't included in this package, then this package doesn't +need to know the host type. + + If you are building compiler tools for cross-compiling, you can also +use the `--target=TYPE' option to select the type of system they will +produce code for and the `--build=TYPE' option to select the type of +system on which you are compiling the package. + +Sharing Defaults +================ + + If you want to set default values for `configure' scripts to share, +you can create a site shell script called `config.site' that gives +default values for variables like `CC', `cache_file', and `prefix'. +`configure' looks for `PREFIX/share/config.site' if it exists, then +`PREFIX/etc/config.site' if it exists. Or, you can set the +`CONFIG_SITE' environment variable to the location of the site script. +A warning: not all `configure' scripts look for a site script. + +Operation Controls +================== + + `configure' recognizes the following options to control how it +operates. + +`--cache-file=FILE' + Save the results of the tests in FILE instead of `config.cache'. + Set FILE to `/dev/null' to disable caching, for debugging + `configure'. + +`--help' + Print a summary of the options to `configure', and exit. + +`--quiet' +`--silent' +`-q' + Do not print messages saying which checks are being made. + +`--srcdir=DIR' + Look for the package's source code in directory DIR. Usually + `configure' can determine that directory automatically. + +`--version' + Print the version of Autoconf used to generate the `configure' + script, and exit. + +`configure' also accepts some other, not widely useful, options. +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kpathsea/HIER Fri Jul 19 01:57:38 1996 +0000 @@ -0,0 +1,59 @@ +Here is the installed TeX & Metafont hierarchy (as of 4sep94) that +we have been working on. Please send comments to mackay@cs.washington.edu, +unixtex@u.washington.edu, and kb@cs.umb.edu. +(Especially if you try to actually install TeX like this!) + +First, pick a root directory for the library files: +TEXMF = /usr/local/lib/texmf + +(Or, in make variable terms: $(datadir)/texmf.) + +All the files are installed relative to $TEXMF. Top-level directories: +bibtex -- bib/*.bib, bst/*.bst +doc -- bibtex/, fontname/, eplain/, ... +fonts -- see below +tex -- see below +mf -- utility MF sources + ({plain, expr, null, io, slant, modes, ...}.mf) +ini -- .base, .fmt, .pool +dvips -- only if you have a PostScript printer, naturally + +In general, where possible, the same setup as ctan is clearly a win. + +Under dvips, have the .pro/.ps/psfonts.map files. + +Under tex, at least: +plain ({plain, manmac, null, plain, story, testfont, webmac}.tex, + perhaps also texinfo.tex, eplain.tex, other single-file sources) +latex (with subdirectories base/ for M&S's files, + misc/ for one-file styles, and other distributions by directory) +tugboat (tugboat.cmn, tugboat.sty, etc.) +mft (*.mft) + +Under fonts: +<source>/<typeface>/ + for <source> in public, adobe, ams, bitstream, urw, ... + for public/<typeface> in cm, concrete, punk, ... + for ams/<typeface> in euler, symbols, ... + for adobe/<typeface> in times, palatino, avantgar, ... + See the *.map files in fontname 2.0 for canonical directory names. + +Under .../<source>/<typeface>/ +src/*.mf +tfm/*.tfm +vf/*.vf +afm/*.afm +pk/$MAKETEX_MODE (including pseudo-modes for gsrenderfont, ps2pk, gsftopk) +type1/*.{pfa,pfb,gsf} +truetype/*.ttf + +See the TeX directory structure node in the manual for an additional +complication with MAKETEX_MODE. + +For example: +texmf/fonts/public/cm/pk/cx/cmr10.300pk +texmf/fonts/public/sauter/src/b-cmbx.mf +texmf/fonts/adobe/utopia/type1/putr.pfa + + +For default path values, see texmf.cnf[.in].
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kpathsea/INSTALL Fri Jul 19 01:57:38 1996 +0000 @@ -0,0 +1,410 @@ +Contents: + +Installation + Default paths + Common problems + Unable to find files + Slow path searching + `XtInherit' + `wchar_t' + `ShellWidgetClass' + Pointer combination warnings + Shared library + Reporting bugs + + +Installation +************ + + Here are the basic steps for configuration and installation: + + 1. Edit the file `make/paths.make' if you want to make changes to the + installation directories or paths that will have effect across + different runs of `configure'. Alternatively, override the Make + variables on the command line when you run Make. + + Exception: to reliably change the top-level `prefix', you must give + `configure' the option `-prefix=PREFIX', instead of changing the + value in `paths.make'. + + 2. Edit `kpathsea/texmf.cnf.in' to change the local paths to match + your local setup. *Note Default paths: (kpathsea)Default paths, + for more details on changing the paths. A copy is in + `kpathsea/INSTALL'. See `kpathsea/HIER' for an explanation of the + default setup. + + If the paths do not match where the files actually are, the + programs will probably start up Very, Very, Slowly, and/or not be + able to find the fonts or other input files. + + 3. `sh configure' (in the top-level directory). This makes + system-dependent `#define's' in `*/c-auto.h' (from the + corresponding `c-auto.h.in') and creates a `Makefile' (from the + corresponding `Makefile.in', by doing `@VAR@' and `ac_include' + substitutions). + + Perhaps the most common desire is to compile with optimization + instead of or as well as debugging. You can change the options + passed to the compiler by changing `CFLAGS', either for + `configure' or `make'. For example: + + prompt$ env CFLAGS="-g -O" configure + prompt$ make + or + prompt$ configure + prompt$ make CFLAGS="-g -O" + + *Note Running `configure' scripts: (autoconf)Invoking configure, + for detailed `configure' options. (A copy is in + `kpathsea/CONFIGURE'.) + + 4. `make' (still in the top-level directory). Barring configuration + and compiler bugs, this will compile all the programs. *Note + Common problems: (kpathsea)Common problems, for system-dependent + problems (this section is also in `kpathsea/INSTALL'). + + This also creates the `texmf.cnf' and `paths.h' files that define + the default search paths. + + 5. `make install'. This installs the library, header files, and + documentation. Or `make install-data' to just install the + architecture-independent files. Or `make install-exec' to just + install the (binary) archive library file. + + Since I only distribute Kpathsea as part of another package, you + will probably be doing the above in a top-level directory that + contains a `Makefile', `kpathsea', and the other package. But you + can do the installation in `kpathsea' itself, if you only want to + install the library, not the other package. + + 6. The first time you install any manual in Info, you have to add a + line (you choose where) to the `dir' file in your `$(infodir)' + directory. A sample line to add is given near the top of the + Texinfo source files (`kpathsea/kpathsea.texi' and + `dvipsk/dvips.texi'). + + 7. `make distclean'. This removes all files created by the build. + + + *Note Filename database::, for a description of an +externally-generated database that can help speed searches. + + *Note Debugging::, for runtime debugging support that may help track +down problems. + + Do not attempt to use any version of Kpathsea with any program except +the version that the program came with, unless you are a glutton for +punishment. + +Default paths +============= + + To summarize the chain of events that go into defining the default +paths: + + 1. `configure' creates a `Makefile' from each `Makefile.in'. + + 2. When Make runs in the `kpathsea' directory, it creates a file + `texmf.sed' that substitutes the Make value of `$(var)' for a + string `@var@'. The variables in question are the one that define + the installation directories. + + 3. `texmf.sed' (and a little extra magic--see `kpathsea/Makefile') is + applied to `texmf.cnf.in' to generate `texmf.cnf'. This is the + file that will eventually be installed and used by the programs to + look up programs. + + 4. The definitions in `texmf.cnf' are changed into the form of C + `#define''s, producing `paths.h'. These values will be the + compile-time defaults; they are not used unless no `texmf.cnf' file + can be found at runtime. + + (That's a partial lie: the compile-time defaults are what extra + `:''s in `texmf.cnf' expand into; but the paths as distributed + have no extra `:''s, and there's no particular reason for them to.) + + + The purpose of this elaborate sequence is to avoid having the same +information in more than one place. If you change the installation +directories or top-level prefix before running `configure', those +changes will propagate through the whole sequence. If you change the +default paths in `texmf.cnf.in', those changes are propagated to the +compile-time defaults. + + Alternatively, you can ignore the whole mess and edit `texmf.cnf' +after it is installed. Maybe even copying it into place beforehand so +you can complete the installation, if TeX or Metafont is having trouble +finding their input files. + + Unfortunately, editing `Makefile.in' *does not work* in one common +case--changing the `prefix' or `exec_prefix' variables. For these, you +must use the `-prefix' or `-exec-prefix' options to `configure'. *Note +Running `configure' scripts: (autoconf)Running configure Scripts. +(That's another partial lie: editing does work, as long as a program +named `tex' is not in your `PATH'.) + + *Note TeX directory structure: TeX directory structure, for a +description of some ways to arrange the TeX library files, and some +features of the distributed paths that may not be obvious. The file +`kpathsea/HIER' is a copy of that section. + + The Make definitions are all repeated in several `Makefile''s; but +changing the top-level `Makefile' should suffice, as it passes down all +the variable definitions, thus overriding the submakes. (The +definitions are repeated so you can potentially run Make in the +subdirectories.) + +Common problems +=============== + + Some common problems with compilation, linking, or execution are +described below. + +Unable to find files +-------------------- + + If a program complains it cannot find fonts (or other input files), +any of several things might be wrong: + + * You don't have the fonts (or whatever) installed. Nothing will + automatically generate TFM files or TeX and Metafont sources for + you (by default). *Note Obtaining Web2c: (web2c)Obtaining Web2c. + + You can, however, configure TeX and Metafont to run a script to + generate these input files, if you have (or write) such scripts. + *Note `MakeTeX'... invocation: (web2c)MakeTeX... invocation. + + * You have (perhaps unknowingly) told Kpathsea to use search paths + that don't reflect where the files actually are. One common cause + is having environment variables set, thus overriding what you + carefully set in `texmf.cnf'. *Note TeX environment variables: TeX + environment variables. + + * Your files reside in a directory that is only pointed to via a + symbolic link, in a leaf directory. + + Unfortunately, Kpathsea's subdirectory searching has a (congenital) + deficiency: If a directory D being searched for subdirectories + contains plain files and symbolic links to other directories, but + no true subdirectories, D will be considered a leaf directory, + i.e., the symbolic links will not be followed. *Note Subdirectory + expansion::, for an explanation of why this happens. + + You can work around this problem by creating an empty dummy + subdirectory in D. Then D will no longer be a leaf, and the + symlinks will be followed. + + The directory immediately followed by the `//' in the path + specification, however, is always searched for subdirectories, + even if it is a leaf. This is since presumably you would not have + asked for the directory to be searched for subdirectories if you + didn't want it to be. + + * There is a bug in the library. *Note Reporting bugs::. + + In any case, you may find the debugging options helpful in determining +precisely where the fonts (or whatever) are being looked for. See the +program's documentation for its debugging options, and also *note +Debugging::.. + +Slow path searching +------------------- + + If your program takes an excessively long time to find fonts or other +input files, but does eventually succeed, here are some possible +culprits: + + * Most likely, you just have a lot of directories to search, and that + takes a noticeable time. The solution is to create and maintain a + separate `ls-R' file that lists all the files in your main TeX + hierarchy. *Note Filename database::. (Kpathsea always uses `ls-R' + if it's present; there's no need to recompile or reinstall any of + the programs.) + + * Your recursively-searched directories (e.g., + `/usr/local/lib/tex/fonts//'), contain a mixture of files and + directories. This prevents Kpathsea from using a useful + optimization (*note Subdirectory expansion::.). + + It is best to have only directories (and perhaps a `README') in the + upper levels of the directory structure, and it's very important + to have *only* files, and no subdirectories, in the directories + where the dozens of TFM, PK, or whatever files reside. + + * Finally, one simple-to-fix (but unlikely) cause: If you recursively + search `$HOME' or `~', and you are running as `root', you will + search every directory on the system. This typically takes quite + some time! + + In any case, you may find the debugging options helpful in determining +precisely when the disk or network is being pounded. *Note Debugging::, +and also see the program's documentation. + +`XtInherit' +----------- + + On DEC OSF/1 1.x systems, the loader has a bug that manifests itself +in the following error (all on one line, but for the sake of the paper +width it's broken here): + + xdvik/xdvi: /sbin/loader: Fatal Error: search_for_undefineds: + symbol _XtInherit should not have any relocation entry + +According to Michael Rickabaugh `<mjr@quarry.enet.dec.com>': + + This is a bug fixed in DEC OSF/1 2.0. + + If you know how, installing `/sbin/loader' from a 2.0 system onto a + 1.3 system will work. Make sure that `/usr' is *not* mounted + when you do this. (If you forget about umounting `/usr', it is + possible most of your filesystems will become corrupted.) + + Otherwise, I suggest getting a hold of a 2.0 CD and running + `/usr/sbin/installupdate'. + + Alternatively, you may be able to use the freely available X11 +libraries that come with the MIT distribution (on `ftp.x.org', for +example). + + Linking statically, perhaps only with some of the X libraries, may +also work. (if you find the definitive workaround, please let me know.) + +`wchar_t' +--------- + + The upshot of all the following is that if you get error messages +regarding `wchar_t', try defining `NO_FOIL_X_WCHAR_T' (for Web2c) or +`FOIL_X_WCHAR_T' (for everything else). + + `wchar_t' has caused infinite trouble. None of my code ever uses +`wchar_t'; all I want to do is include X header files and various +system header files, possibly compiling with GCC. This seems an +impossible task! + + The X11 header `<Xlib.h>' and GCC's `<stddef.h>' have conflicting +definitions for wchar_t. + + The particulars: `<X11/Xlib.h>' from MIT X11R5 defines `wchar_t' if +`X_WCHAR' is defined, which is defined if `X_NOT_STDC_ENV' is defined, +and we define *that* if `STDC_HEADERS' is not defined (`configure' +decides if STDC_HEADERS gets defined). But when compiling with gcc on +SunOS 4.1.x, `STDC_HEADERS' is not defined (`string.h' doesn't declare +the `mem'* functions), so we do get X's `wchar_t'--and we also get +gcc's `wchar_t' from its `<stddef.h>'. Conflict. + + On the other hand, SunOS 4.1.1 with some other X configurations +actually needs GCC to define `wchar_t', and fails otherwise. + + My current theory is to define `wchar_t' to a nonsense symbol before +the X include files are read; that way its definition (if any) will be +ignored by other system include files. Going along with that, define +`X_WCHAR' to tell X not to use `<stddef.h>', that we've already +included, but instead to make its own definition. + + But this is not the end of the story. The X11 include files +distributed with DG/UX 5.4.2 for the Aviion have been modified to +include `<_int_wchar_t.h>' if `X_WCHAR', so our `#define' will not have +any typedef to change--but the uses of `wchar_t' in the X include files +will be changed to reference this undefined symbol. So there's nothing +to foil in this case. I don't know how to detect this automatically, so +it's up to you to define `NO_FOIL_X_WCHAR_T' yourself. + +`ShellWidgetClass' +------------------ + + This section is adapted from question 47 from the +`comp.sys.sun.admin' FAQ. + + If you are linking with Sun's OpenWindows libraries in SunOS 4.1.x, +you may get undefined symbols `_get_wmShellWidgetClass' and +`_get_applicationShellWidgetClass'. This problem does not arise with +the standard MIT libraries under SunOS. + + The cause is bugs in the `Xmu' shared library as shipped from Sun. +There are several fixes: + + * Get the Openwindows patches that apply to this problem. + + * Statically link the `Xmu' library into the executable. + + * Avoid using `Xmu' at all. For this last, if you are compiling + Metafont, *note Online Metafont graphics: (Web2c)Online Metafont + graphics.. If you are compiling Xdvi, see the `-DNOTOOL' option in + `xdvik/INSTALL'. + + * Ignore the errors. The binary runs fine regardless. + + Here is the information for getting the two patches: + + Patch ID: 100512-02 + Bug ID's: 1086793, 1086912, 1074766 + Description: 4.1.x OpenWindows 3.0 `libXt' jumbo patch + + Patch ID: 100573-03 + Bug ID: 1087332 + Description: 4.1.x OpenWindows 3.0 undefined symbols when using shared + `libXmu'. + + The way to statically link with `libXmu' depends on whether you are +using a Sun compiler (e.g., `cc') or `gcc'. If the format, alter the +`x_libs' make variable to include + + -Bstatic -lXmu -Bdynamic + + If you are using `gcc', include `-static' in `LDFLAGS'; this will +link all libraries statically. If you want to link only `Xmu' +statically and everything else dynamically, you have to do it by hand: +run `gcc -v', grab the `ld' line, and add the `-B''s given above around +`-lXmu'. + + The reason is that gcc moves all linker options to the front of the +`ld' command line. So you can't specify different options for +different libraries. When I reported this to the GCC maintainers, the +reply was that they would happily merge in the changes, but they didn't +want to take the time to do it themselves. + +Pointer combination warnings +---------------------------- + + When compiling with old C compilers, you may get some warnings about +"illegal pointer combinations". These are spurious; just ignore them. +I decline to clutter up the source with casts to get rid of them. + + In general, if you have trouble with a system C compiler, I advise +trying the GNU C compiler. (And vice versa, unfortunately; but in that +case I also recommend reporting a bug to the GCC bug list.) + +Shared library +============== + + You can compile Kpathsea as a shared library. The advantage in doing +this is that the different executables can then share the code, +decreasing memory usage. (The other advantage in general of shared +libraries is that it's possible to update the library and programs +independently. But since the Kpathsea interface is not and can not be +frozen, that doesn't apply here.) + + Under Solaris, use `-K pic -xstrconst' if you compile with a Sun +compiler, `-fpic' if you use GCC. Also add `-L$(LIBDIR) -R$(LIBDIR)' +to `LDFLAGS' when you link the binaries, so that the library can be +found, and users do not have set `LD_LIBRARY_PATH'. + + (If you know how to make Kpathsea shared on other systems, please +send a message to the bug address in the next section.) + +Reporting bugs +============== + + If you encounter problems, please report them to `tex-k@cs.umb.edu'. +Include the version number of the library, the system you are using, and +enough information to reproduce the bug in your report. To get on this +mailing list yourself, email `tex-k-request@cs.umb.edu' with a message +whose body contains a line + subscribe YOU@YOUR.PREFERRED.ADDRESS + + To avoid wasted effort and time (both mine and yours), I strongly +advise applying the principles given in the GNU C manual (*note +Reporting Bugs: (gcc)Bugs.) to your bug reports. + + Please also report bugs in this documentation--not only factual +errors, but unclear explanations, typos, wrong fonts, ...
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kpathsea/MakeTeXPK.in Fri Jul 19 01:57:38 1996 +0000 @@ -0,0 +1,276 @@ +#!/bin/sh +# original MakeTeXPK -- make a new PK font, because one wasn't found. +# Version of 12dec94. +# +# (If you change or delete the word `original' on the previous line, +# installation won't write this MakeTeXPK over yours.) +# +# This script must echo the name of the generated PK file (and nothing +# else) to standard output. Yes, this is different from the original dvips. +# +# Parameters: +# name dpi bdpi magnification [mode [destdir]] +# +# `name' is the base name of the font, such as `cmr10'. +# `dpi' is the resolution the font is needed at. +# `bdpi' is the base resolution, used to intuit the mode to use. +# `magnification' is a string to pass to MF as the value of `mag'. +# `mode', if supplied, is the mode to use. Unless it's `default', in +# which case we guess. (This is so people can specify a destdir +# without a mode.) +# `destdir', if supplied, is either the absolute directory name to use +# (if it starts with a /) or relative to the default DESTDIR (if not). + +# The root of where to put the new file. (Using the sh construct +# ${var=value} is the tersest construct that lets an environment +# variable `var' override the value given here.) +: ${DESTROOT=${MTPK_DESTROOT-@fontdir@}} + +# Define to `gsftopk' or `ps2pk' or whatever to make PK files for +# PostScript fonts. If this is defined, PSMAPFILE must also be defined to +# be your psfonts.map file or some equivalent. +: ${ps_to_pk=gsftopk} +: ${PSMAPFILE=@psheaderdir@/psfonts.map} + +# Location of the files that map font name parts to directory names. +: ${NAMEMAPDIR=@fontnamedir@} + +# This is needed only if all the font directories were not included in +# the compile-time path for gsftopk. +: ${DVIPSHEADERS=@datadir@/ghostscript/type1:} + +# If this directory doesn't exist, the DC fonts won't be attempted. +: ${dcfontdir=@dcfontdir@} + +# If this directory doesn't exist, the Sauter stuff won't be attempted. +: ${sauterdir=@sauterdir@} + +# If the true typeface directory cannot be determined from the fontname, +# the files are installed here, relative to $DESTROOT. +: ${default_namepart=tmp/pk} + +# TEMPDIR needs to be unique for each process because of the possibility +# of processes simultaneously running this script. +TEMPDIR=${TMPDIR-/tmp}/mtpk.$$ + +if test $# -lt 4; then + echo "Usage: $0 name dpi bdpi mag [mode [destdir]]." >&2 + exit 1 +fi + +NAME=$1 +DPI=$2 +BDPI=$3 +MAG=$4 +MODE=$5 + +# DESTDIR is harder. +case "$6" in + "") + # Nothing specified, so try to intuit the directory from the + # fontname. First the special cases: either $NAME matches an entire + # name in special.map, or it matches the abbreviation in + # special.map and ends with a numeral (for the pointsize). + # We (painfully) use only the minimal features in original awk. + if test -r $NAMEMAPDIR/special.map; then + namepart=`awk \ +'{if ($1 == NAME || (substr (NAME, 1, length ($1)) == $1 \ + && substr (NAME, length (NAME), 1) ~ /[0-9]/)) \ + { print $2 "/" $3; exit; }}' NAME=$NAME $NAMEMAPDIR/special.map` + + if test -z "$namepart"; then + # Try the normal case. Source first. + s_abbrev=`echo $NAME | cut -c 1-1` + sourcedir=`awk '{ if ($1 == s_abbrev) { print $2; exit; }}' \ + s_abbrev=$s_abbrev $NAMEMAPDIR/source.map` + + if test -n "$sourcedir"; then + # We found the source. Try for the typeface. + t_abbrev=`echo $NAME | cut -c 2-3` + typefacedir=`awk '{ if ($1 == t_abbrev) { print $2; exit; }}' \ + t_abbrev=$t_abbrev $NAMEMAPDIR/typeface.map` + + if test -n "$typefacedir"; then + # Found everything. + namepart=$sourcedir/$typefacedir + + else + echo "$0: Could not map typeface abbreviation $t_abbrev." >&2 + fi + else + echo "$0: Could not map source abbreviation $s_abbrev." >&2 + fi + fi + else + # No map files. + : + fi + if test -z "$namepart"; then + # If we failed for whatever reason, default to a generic subdir. + namepart=$default_namepart + else + # Otherwise, get the `pk' in before we append the mode. + namepart=$namepart/pk + fi + + # Finally, update the parent of the installation directory. + DESTROOT="$DESTROOT/$namepart" + ;; + /*) DESTDIR=$6;; # Absolute, explicit destdir => use it. + *) DESTDIR=$DESTROOT/$6;; # Relative destdir => append to the default. +esac + +GFNAME=$NAME.$DPI'gf' +PKNAME=$NAME.$DPI'pk' + +# Clean up on normal or abnormal exit. DESTDIR changes, hence the eval. +trap "cd /; eval rm -rf $TEMPDIR \$DESTDIR/pktmp.$$" 0 1 2 15 + +# Allow fonts to be read and written (especially in case we make +# directories) by everyone. +umask 0 + +# Possible local customizations? +test -r @web2cdir@/MakeTeXPK.site && . @web2cdir@/MakeTeXPK.site + +# Remember where we were for the paths. We'd most like to replace `.', +# wherever it is in the path, with $SAVEPWD, but we don't have access to the +# compile-time path. So we are conservative, and put this at the end. +SAVEPWD=`pwd` + +# Go to the unique working directory. +test -d $TEMPDIR || mkdir $TEMPDIR +cd $TEMPDIR || exit 1 + +# grep for the font in $PSMAPFILE, if some ps-to-pk is claimed to be supported. +# We have to figure out the name of the base font -- $NAME is probably +# something like pplr, but it's rpplr or pplr0 or pplr8r that's in psfonts.map. +pattern="^r?$NAME"'(0|8r)?([ ]|$)' +test -n "$ps_to_pk" && egrep "$pattern" $PSMAPFILE >psline +if test -s psline; then + # This is a PostScript font. + MODE=$ps_to_pk + case $ps_to_pk in + ps2pk*) special_part=`cat psline | sed -e 's/^.*"//' -e 's/".*$//'` + # .167 SlantFont + slant=`echo $special_part \ + | awk '{ if ($2 == SlantFont) print "-S" $1 }'` + extend=`echo $special_part \ + | awk '{ if ($2 == ExtendFont) print "-E" $1 }'` + cmd="$ps_to_pk -v -X$DPI $slant $extend $NAME";; + *) cmd="$ps_to_pk $NAME $DPI";; + esac + + # Update DESTDIR for new mode, and check if we were spuriously called. + test -z "$6" && DESTDIR="$DESTROOT/$MODE" + if test -r $DESTDIR/$PKNAME; then # sigh, this is repeated below + echo "$0: $DESTDIR/$PKNAME already exists." >&2 + echo $DESTDIR/$PKNAME + exit 0 + fi + + DVIPSHEADERS="$DVIPSHEADERS:$SAVEPWD" + export DVIPSHEADERS + echo "$0: Running $cmd" >&2 + $cmd >&2 || { echo "$0: $ps_to_pk failed." >&2; exit 1; } + +else + # Try Metafont. + MFINPUTS="$MFINPUTS:$SAVEPWD" + export MFINPUTS + + # If an explicit mode is not supplied, try to guess. You can get a + # list of extant modes from ftp.cs.umb.edu:pub/tex/modes.mf. + if test -z "$MODE" || test "$MODE" = default; then + case "$BDPI" in + 85) MODE=sun;; + 300) MODE=cx;; + 600) MODE=ljfour;; + 1270) MODE=linolo;; + *) echo "$0: Can't guess mode for $BDPI dpi devices." >&2 + echo "$0: Use a config file, or update me." >&2 + exit 1 + esac + fi + + # If no destination directory specified, install font in directory + # named for the mode. + test -z "$6" && DESTDIR="$DESTROOT/$MODE" + + if test -r $DESTDIR/$PKNAME; then # sigh, this is repeated above + echo "$0: $DESTDIR/$PKNAME already exists." >&2 + echo $DESTDIR/$PKNAME + exit 0 + fi + + # Run Metafont. Always use plain Metafont, since reading cmbase.mf + # does not noticeably slow things down. Separate the filename from the + # rest, since we have to use ./$NAME if we generate something. + cmd="mf \mode:=$MODE; mag:=$MAG; scrollmode; input" + echo "$0: Running $cmd $NAME" >&2 + if $cmd $NAME </dev/null >&2; then + : # Success already. + + else + # These other cases should really be part of MakeTeXMF. + # First have to figure out the real magnification, which means + # extracting the point size from the name -- a trailing number. + rootname=`echo $NAME | sed 's/[0-9]*$//'` + pointsize=`echo $NAME | sed "s/^$rootname//"` + case "$pointsize" in + 11) realsize=10.95444;; # \magstephalf + 14) realsize=14.4;; # \magstep2 + 17) realsize=17.28;; # \magstep3 + 20) realsize=20.74;; # \magstep4 + 25) realsize=24.88;; # \magstep5 + *) realsize=$pointsize;; + esac + mfname=$NAME.mf + rm -f $mfname # We are in $TEMPDIR, so this is safe. + + if test -z "$pointsize"; then + # No point size, so it can't be a DC or Sauter font. Give up. + : + + elif echo $NAME | grep '^dc' >/dev/null; then + echo "$0: Trying DC font." >&2 + echo "if unknown dxbase: input dxbase fi;" >$mfname + echo "gensize:=$realsize;" >>$mfname + echo "generate $rootname." >>$mfname + echo "$0: Running $cmd ./$NAME" >&2 + $cmd ./$mfname </dev/null >&2 + + elif test -d $sauterdir; then + echo "$0: Trying interpolated/extrapolated (Sauter) font." >&2 + echo "design_size:=$realsize;" >>$mfname + echo "input b-$rootname;" >>$mfname + echo "$0: Running $cmd ./$NAME" >&2 + $cmd ./$mfname </dev/null >&2 + # Result should go in the sauterdir, not the cm dir. + test -z "$6" && $DESTDIR=$sauterdir/pk/$MODE + fi # alternative mf sources + fi # first mf failed + + # If we couldn't make the font, quit. + test -r $GFNAME || \ + { echo "$0: Metafont failed to make $GFNAME." >&2; exit 1; } + + # Success. Make the PK file. + gftopk ./$GFNAME $PKNAME || exit 1 +fi + +# If we get here, we've succeeded; move the final font to $DESTDIR. +test -d $DESTDIR \ + || mkdir $DESTDIR \ + || { echo "$0: Could not mkdir $DESTDIR." >&2; exit 1; } + +# Install the PK file carefully, since others may be working simultaneously. +mv $PKNAME $DESTDIR/pktmp.$$ \ + || { echo "$0: Could not mv $PKNAME $DESTDIR/pktmp.$$." >&2; exit 1; } + +cd $DESTDIR || exit 1 +mv pktmp.$$ $PKNAME + +# If this line (or an equivalent) is not present, dvipsk/xdvik/dviljk +# will think MakeTeXPK failed. Any other output to stdout will also lose. +echo $DESTDIR/$PKNAME
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kpathsea/NEWS Fri Jul 19 01:57:38 1996 +0000 @@ -0,0 +1,124 @@ +This file records noteworthy changes. + +2.6 (9 January 1995) +* MakeTeXPK installed from kpathsea, instead of each driver. +* MakeTeXPK.site looked for in texmf/web2c, instead of texmf/dvips. +* texmf.cnf installed and looked for in texmf/web2c, instead of texmf. +* If a mode is not explicitly specified, search all subdirectories (this + was actually in a previous release). +* install-sh only looked for in the top-level directory. +* kpsewhich replaces and generalizes kpsexpand. + +2.5 (15 December 1994) +* Go back to calling db_insert after a successful MakeTeXPK, and check + for lack of an ls-R. +* Handle case of magstep -.5 for MakeTeXPK properly. + +2.4 (28 October 1994) +* Avoid calling db_insert, which caused a segmentation fault. + +2.3 (26 October 1994) +* Extra :'s in an envvar value, referring to the texmf.cnf value, work. +* Names like dpi600/cmr10.pk can be found in ls-R. +* KPATHSEA_DEBUG environment variable checked. +* Directories like pk/ljfour directly under $TEXMF/fonts are found. +* New standalone program, kpsexpand, optionally compiled and installed, + to do variable expansion (not path searching). +* Debugging output written to stderr instead of stdout. +* pxlNNN support removed; I never intended to support `pxl1500', and + pxl300 is never used. + +2.2 (14 October 1994) +* MakeTeXPK invoked for the any_glyph type; this is for xdvik. +* MakeTeXPK sources $(psheaderdir)/MakeTeXPK.site if it exists. +* pxlNNN/cmr10.pk searched for (as well as dpiNNN/cmr10.pk and cmr10.NNNpk) + +2.1 (12 September 1994) +* Manual goes through TeX, and .cps/.aux files are in the distribution. +* INSTALL* variables set at the top level. +* Dependency on GNU tr making paths.h and texmf.sed (->texmf.cnf) removed. +* texmf.cnf installed if it didn't previously exist. + +2.0 (8 September 1994) +* Runtime configuration file support; see the manual. +* Both dpi600/cmr10.pk and cmr10.600pk are searched for. +* ls-R matches $TEXMF//latex2e vs. $TEXMF//latex209. +* $TEXMFLOG, if set, specifies a filename for logging successful searches. +* All directory entries beginning with `.' are ignored, not just `.' and `..'. +* Default path for PK and GF fonts includes the mode name. +* ls-R is in $TEXMFROOT instead of hardwired at compile time. +* More debugging flags, and they can be set with client program options. +* If MakeTeX{PK,TFM} fail, or aren't invoked, a file missfont.log is + written with the requisite commands, as in dvips. +* More 328/329/330 fixes, maybe for the last time. +* The override font paths (XDVIFONTS etc.) apply only to glyph (PK/GF) + searches, not TFM or VF. +* -g is not the default when linking, to avoid unnecessarily large binaries + (due to static libraries) under Linux. +* configure checks for a smart putenv. +* Stat results are cached to speed up disk searches. + +1.8 (2 April 1994) +* New target install-info, so the documentation can be installed without + the headers. +* Existing but unreadable files are complained about, instead of just ignored. +* A leading %% in a path element forbids searching the disk for that + element; only a db will be searched (if it exists). +* The db is only used if it might be relevant to a given path element, + not searched first regardless. + +1.7 (1 March 1994) +* Searches can use an externally-built ls-R ``database'', for speed. +* `VPATH = .' lines removed from generated Makefile, for broken Sun make. +* A path foo//tfm finds foo/tfm as well as foo/*/tfm. + +1.6 (3 February 1994) +* Memory fault in copying long paths fixed. +* More variables passed down from the top-level Makefile. +* Mention SMART_PUTENV in the INSTALL file, and fix bug in xputenv.c + when one envvar is a proper prefix of another. +* More attempts at eliminating magstephalf annoyances. +* Directory name substitutions are done globally when creating paths.h. +* Various changes for DOS. + +1.5 (24 January 1994) +* Default paths changed. +* Defining GCC_WCHAR lets GCC define wchar_t. +* EXIT_FAILURE and EXIT_SUCCESS defined in all cases (if they're not already). +* str[r]chr never redefined (I hope). + +1.4 (3 November 1993) +* Check closest fallback font size. +* All default paths (including dvips') in paths.h.in, not the Makefile. +* Rearrange directory lists so that dirs in which a file is found + migrate to the top. +* Update for Autoconf 1.7. + +1.3 (6 October 1993) +* Fix free of non-malloced memory bug. +* Fix uninitialized gf path bug. +* mkdirchain invoked as an absolute filename. + +1.2 (27 September 1993) +* Running MakeTeXPK is tried before the fallback resolutions. +* The final bitmap name uses a variable spec, so DOS & OS/2 can get + dpi300/cmr10.pk. +* Document TeX-specific features. +* Dpi passed to MakeTeXPK via the envvar KPATHSEA_DPI instead of MAKETEX_DPI. + +1.1 (26 August 1993) +* Installation fixes. + +1.0 (5 August 1993) +* Routines to look up TeX font files, default path specifications, etc. +* Sort-of pattern matching: /foo//bar matches subdirectories + /foo/a/bar, /foo/b/bar, /foo/a1/a2/bar, etc. +* $var and ${var} expansion. +* Support for MakeTeX... scripts. +* Support for fallback resolutions and font. +* Lazy evaluation of path elements. +* Some runtime debugging support. + +0.2 (12 May 1993) + +First general release as a standalone library.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kpathsea/README Fri Jul 19 01:57:38 1996 +0000 @@ -0,0 +1,27 @@ +This directory contains the Kpathsea[rch] library, which implements +generic path searching, configuration, and TeX-specific file searching. + +See `Makefile.in' for the version number. +See `NEWS' for changes by release. +See `INSTALL' for installation instructions. +See `CONFIGURE' for details on running Autoconf-generated configure scripts. +See `PROJECTS' for future improvements. + +Please report bugs to tex-k@cs.umb.edu. +(Email tex-k-request@cs.umb.edu with a line containing + subscribe you@preferred.email.address +in the body of the message to join this mailing list.) + +Suggestions for improvements in either the library or the documentation, +no matter how small, are welcome. + +Installing this package will create the library and header files in +subdirectories of /usr/local (by default). Typically this library is not +installed, however; only the programs that use it are. + +This is free software. See the files COPYING* for copying permissions. +The top-level headers are `pathsearch.h' for the generic path searching +support, and `tex-{file,glyph}.h' for the TeX-specific support. + +kb@cs.umb.edu +Member of the League for Programming Freedom -- write lpf@uunet.uu.net.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kpathsea/aclocal.m4 Fri Jul 19 01:57:38 1996 +0000 @@ -0,0 +1,349 @@ +dnl Modifications for the latest version of Autoconf for kpathsea. +dnl These changes have all been sent back to the Autoconf maintainer. + +dnl This is a subroutine of AC_OUTPUT. It is called inside an unquoted +dnl here document whose contents are going into config.status. +dnl AC_OUTPUT_FILES(FILE...) +dnl I've added ac_include support --karl@cs.umb.edu. +undefine([AC_OUTPUT_FILES]) +define(AC_OUTPUT_FILES, +[# Protect against being on the right side of a sed subst in config.status. +changequote(, )dnl +sed 's/%@/@@/; s/@%/@@/; s/%g$/@g/; /@g$/s/[\\\\&%]/\\\\&/g; + s/@@/%@/; s/@@/@%/; s/@g$/%g/' > conftest.subs <<\CEOF +changequote([, ])dnl +dnl These here document variables are unquoted when configure runs +dnl but quoted when config.status runs, so variables are expanded once. +$ac_vpsub +dnl Shell code in configure.in might set extrasub. +$extrasub +dnl Insert the sed substitutions of variables. +undivert(AC_DIVERSION_SED) +CEOF +EOF +cat >> $CONFIG_STATUS <<EOF + +CONFIG_FILES=\${CONFIG_FILES-"$1"} +EOF +cat >> $CONFIG_STATUS <<\EOF +for ac_file in .. $CONFIG_FILES; do if test "x$ac_file" != x..; then +dnl Specifying an input file breaks the trap to clean up on interrupt, +dnl but that's not a huge problem. + # Support "outfile[:infile]", defaulting infile="outfile.in". + case "$ac_file" in + *:*) ac_file_in=`echo "$ac_file"|sed 's%.*:%%'` + ac_file=`echo "$ac_file"|sed 's%:.*%%'` ;; + *) ac_file_in="${ac_file}.in" ;; + esac + + # Adjust relative srcdir, etc. for subdirectories. + + # Remove last slash and all that follows it. Not all systems have dirname. +changequote(, )dnl + ac_dir=`echo $ac_file|sed 's%/[^/][^/]*$%%'` +changequote([, ])dnl + if test "$ac_dir" != "$ac_file" && test "$ac_dir" != .; then + # The file is in a subdirectory. + test ! -d "$ac_dir" && mkdir "$ac_dir" + ac_dir_suffix="/$ac_dir" + # A "../" for each directory in $ac_dir_suffix. +changequote(, )dnl + ac_dots=`echo $ac_dir_suffix|sed 's%/[^/]*%../%g'` +changequote([, ])dnl + else + ac_dir_suffix= ac_dots= + fi + + case "$ac_given_srcdir" in + .) srcdir=. + if test -z "$ac_dots"; then top_srcdir=. + else top_srcdir=`echo $ac_dots|sed 's%/$%%'`; fi ;; + /*) srcdir="$ac_given_srcdir$ac_dir_suffix"; top_srcdir="$ac_given_srcdir" ;; + *) # Relative path. + srcdir="$ac_dots$ac_given_srcdir$ac_dir_suffix" + top_srcdir="$ac_dots$ac_given_srcdir" ;; + esac + +ifdef([AC_PROVIDE_AC_PROG_INSTALL], +[ case "$ac_given_INSTALL" in +changequote(, )dnl + [/$]*) INSTALL="$ac_given_INSTALL" ;; +changequote([, ])dnl + *) INSTALL="$ac_dots$ac_given_INSTALL" ;; + esac +])dnl + echo creating "$ac_file" + rm -f "$ac_file" + configure_input="Generated automatically from `echo $ac_file_in|sed 's%.*/%%'` by configure." + case "$ac_file" in + *Makefile*) ac_comsub="1i\\ +# $configure_input" ;; + *) ac_comsub= ;; + esac + # Replace lines of the form ac_include foo with the contents of foo: + # first, from the ac_include lines construct a list of sed + # commands to remove them, and include the files; then run sed. + # Have to use sed because old (Ultrix, SunOS) awk does not support + # getline or system. (Anyway, configure scripts aren't supposed to use awk.) + # Use \@...@<cmd> form of sed address because the filename may contain /. + # Can't use only one -e and commands {dr foo} because foo has to be last. + # Use @e initially instead of -e because GNU echo has a -e option. + # USe `X' to mean a bunch of backslashes; this is for FreeBSD. + file_substs=`sed -n \ +changequote(,)dnl +"/^ac_include/s%ac_include[ ]*\(.*\)%@e 'X@^&@r \1' -e 'X@^&@d'%p" \ +changequote([,])dnl + $ac_given_srcdir/${ac_file}.in` + if test -n "$file_substs"; then + # Change @e back to -e and X@^ to \@^. + file_subst_cmd="sed `echo $file_substs \ + | sed -e 's/@e/-e/g' -e 's/X@^/\\\\\@^/g'`" + else + # If no substitutions and hence no sed commands, don't choke. + file_subst_cmd=cat + fi + # cd into the srcdir because the files being included more or less + # must be part of the distribution. I can't find any way to do + # variable substitution in the sed commands (so the user could have, + # e.g., $top_srcdir in their ac_include line). + (cd $ac_given_srcdir && eval $file_subst_cmd ${ac_file}.in) \ + | sed -e "$ac_comsub +s%@configure_input@%$configure_input%g +s%@srcdir@%$srcdir%g +s%@top_srcdir@%$top_srcdir%g +ifdef([AC_PROVIDE_AC_PROG_INSTALL], [s%@INSTALL@%$INSTALL%g +])dnl +" -f conftest.subs > $ac_file +fi; done +rm -f conftest.subs +]) + + +dnl +dnl Only change from Autoconf 2.1 is to check IceConnectionNumber, not +dnl ...Numbers. +dnl +dnl Find additional X libraries, magic flags, etc. +undefine([AC_PATH_XTRA]) +AC_DEFUN(AC_PATH_XTRA, +[AC_REQUIRE([AC_ISC_POSIX])dnl +AC_REQUIRE([AC_PATH_X])dnl +if test "$no_x" = yes; then + # Not all programs may use this symbol, but it does not hurt to define it. + X_CFLAGS="$X_CFLAGS -DX_DISPLAY_MISSING" +else + if test -n "$x_includes"; then + X_CFLAGS="$X_CFLAGS -I$x_includes" + fi + + # It would be nice to have a more robust check for the -R ld option than + # just checking for Solaris. + # It would also be nice to do this for all -L options, not just this one. + if test -n "$x_libraries"; then + X_LIBS="$X_LIBS -L$x_libraries" + if test "`(uname) 2>/dev/null`" = SunOS && + uname -r | grep '^5' >/dev/null; then + X_LIBS="$X_LIBS -R$x_libraries" + fi + fi + + # Check for libraries that X11R6 Xt/Xaw programs need. + + ac_save_LDFLAGS="$LDFLAGS" + LDFLAGS="$LDFLAGS -L$x_libraries" + # SM needs ICE to (dynamically) link under SunOS 4.x (so we have to + # check for ICE first), but we must link in the order -lSM -lICE or + # we get undefined symbols. So assume we have SM if we have ICE. + # These have to be linked with before -lX11, unlike the other + # libraries we check for below, so use a different variable. + # --interran@uluru.Stanford.EDU, kb@cs.umb.edu. + AC_CHECK_LIB(ICE, IceConnectionNumber, + [X_PRE_LIBS="$X_PRE_LIBS -lSM -lICE"]) + LDFLAGS="$ac_save_LDFLAGS" + + # Check for system-dependent libraries X programs must link with. + + if test "$ISC" = yes; then + X_EXTRA_LIBS="$X_EXTRA_LIBS -lnsl_s -linet" + else + # Martyn.Johnson@cl.cam.ac.uk says this is needed for Ultrix, if the X + # libraries were built with DECnet support. And karl@cs.umb.edu says + # the Alpha needs dnet_stub (dnet does not exist). + AC_CHECK_LIB(dnet, dnet_ntoa, [X_EXTRA_LIBS="$X_EXTRA_LIBS -ldnet"]) + if test $ac_cv_lib_dnet = no; then + AC_CHECK_LIB(dnet_stub, dnet_ntoa, + [X_EXTRA_LIBS="$X_EXTRA_LIBS -ldnet_stub"]) + fi + + # msh@cis.ufl.edu says -lnsl (and -lsocket) are needed for his 386/AT, + # to get the SysV transport functions. + # Not sure which flavor of 386 UNIX this is, but it seems harmless to + # check for it. + AC_CHECK_LIB(nsl, t_accept, [X_EXTRA_LIBS="$X_EXTRA_LIBS -lnsl"]) + + # lieder@skyler.mavd.honeywell.com says without -lsocket, + # socket/setsockopt and other routines are undefined under SCO ODT 2.0. + # But -lsocket is broken on IRIX, according to simon@lia.di.epfl.ch. + if test "`(uname) 2>/dev/null`" != IRIX; then + AC_CHECK_LIB(socket, socket, [X_EXTRA_LIBS="$X_EXTRA_LIBS -lsocket"]) + fi + fi +fi +AC_SUBST(X_CFLAGS)dnl +AC_SUBST(X_PRE_LIBS)dnl +AC_SUBST(X_LIBS)dnl +AC_SUBST(X_EXTRA_LIBS)dnl +]) + + +dnl +dnl Definition was buggy in Autoconf 2.1; parameters were incorrectly +dnl passed to AC_MSG_ERROR and AC_TRY_LINK. +dnl +dnl Check if lex declares yytext as a char * by default, not a char[]. +undefine([AC_DECL_YYTEXT]) +AC_DEFUN(AC_DECL_YYTEXT, +[AC_REQUIRE_CPP()dnl +AC_REQUIRE([AC_PROG_LEX])dnl +AC_CACHE_VAL(ac_cv_prog_lex_output_root, +[# The minimal lex program is just a single line: %%. But some broken lexes +# (Solaris, I think it was) want two %% lines, so accommodate them. +echo '%% +%%' | $LEX +if test -f lex.yy.c; then + ac_cv_prog_lex_output_root=lex.yy +elif test -f lexyy.c; then + ac_cv_prog_lex_output_root=lexyy +else + AC_MSG_ERROR([cannot find output from $LEX, giving up]) +fi])dnl +LEX_OUTPUT_ROOT=$ac_cv_prog_lex_output_root +AC_SUBST(LEX_OUTPUT_ROOT)dnl +AC_MSG_CHECKING(for yytext declaration) +AC_CACHE_VAL(ac_cv_prog_lex_yytext_pointer, +[# POSIX says lex can declare yytext either as a pointer or an array; the +# default is implementation-dependent. Figure out which it is, since +# not all implementations provide the %pointer and %array declarations. +ac_cv_prog_lex_yytext_pointer=no +echo 'extern char *yytext;' >>$LEX_OUTPUT_ROOT.c +ac_save_LIBS="$LIBS" +LIBS="$LIBS $LEXLIB" +AC_TRY_LINK(`cat $LEX_OUTPUT_ROOT.c`,, ac_cv_prog_lex_yytext_pointer=yes) +LIBS="$ac_save_LIBS" +rm -f "${LEX_OUTPUT_ROOT}.c"])dnl +AC_MSG_RESULT($ac_cv_prog_lex_yytext_pointer) +if test $ac_cv_prog_lex_yytext_pointer = yes; then + AC_DEFINE(YYTEXT_POINTER) +fi +]) + +dnl +dnl install-sh needs .. magic. +dnl +dnl AC_OUTPUT_SUBDIRS(DIRECTORY...) +undefine([AC_OUTPUT_SUBDIRS]) +define(AC_OUTPUT_SUBDIRS, +[ +if test "$no_recursion" != yes; then + + # Remove --cache-file and --srcdir arguments so they do not pile up. + ac_sub_configure_args= + ac_prev= + for ac_arg in $ac_configure_args; do + if test -n "$ac_prev"; then + ac_prev= + continue + fi + case "$ac_arg" in + -cache-file | --cache-file | --cache-fil | --cache-fi \ + | --cache-f | --cache- | --cache | --cach | --cac | --ca | --c) + ac_prev=cache_file ;; + -cache-file=* | --cache-file=* | --cache-fil=* | --cache-fi=* \ + | --cache-f=* | --cache-=* | --cache=* | --cach=* | --cac=* | --ca=* | --c=*) + ;; + -srcdir | --srcdir | --srcdi | --srcd | --src | --sr) + ac_prev=srcdir ;; + -srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*) + ;; + *) ac_sub_configure_args="$ac_sub_configure_args $ac_arg" ;; + esac + done + + for ac_config_dir in $1; do + + # Do not complain, so a configure script can configure whichever + # parts of a large source tree are present. + if test ! -d $srcdir/$ac_config_dir; then + continue + fi + + echo configuring in $ac_config_dir + + case "$srcdir" in + .) ;; + *) + if test -d ./$ac_config_dir || mkdir ./$ac_config_dir; then :; + else + AC_MSG_ERROR(can not create `pwd`/$ac_config_dir) + fi + ;; + esac + + ac_popdir=`pwd` + cd $ac_config_dir + + case "$srcdir" in + .) # No --srcdir option. We are building in place. + ac_sub_srcdir=$srcdir ;; + /*) # Absolute path. + ac_sub_srcdir=$srcdir/$ac_config_dir ;; + *) # Relative path. + ac_sub_srcdir=../$srcdir/$ac_config_dir ;; + esac + + # Check for guested configure; otherwise get Cygnus style configure. + if test -f $ac_sub_srcdir/configure; then + ac_sub_configure=$ac_sub_srcdir/configure + elif test -f $ac_sub_srcdir/configure.in; then + ac_sub_configure=$ac_configure + else + AC_MSG_WARN(no configuration information is in $ac_config_dir) + ac_sub_configure= + fi + + # The recursion is here. + if test -n "$ac_sub_configure"; then + + # Make the cache file name correct relative to the subdirectory. +changequote(, )dnl + # A "../" for each directory in /$ac_config_dir. + ac_dots=`echo /$ac_config_dir|sed 's%/[^/]*%../%g'` +changequote([, ])dnl + case "$cache_file" in + /*) ac_sub_cache_file=$cache_file ;; + *) # Relative path. + ac_sub_cache_file="$ac_dots$cache_file" ;; + esac + +ifdef([AC_PROVIDE_AC_PROG_INSTALL], + [ case "$ac_given_INSTALL" in +changequote(, )dnl + [/$]*) INSTALL="$ac_given_INSTALL" ;; +changequote([, ])dnl + *) INSTALL="$ac_dots$ac_given_INSTALL" ;; + esac +])dnl + + echo "[running ${CONFIG_SHELL-/bin/sh} $ac_sub_configure $ac_sub_configure_args --cache-file=$ac_sub_cache_file] --srcdir=$ac_sub_srcdir" + # The eval makes quoting arguments work. + if eval ${CONFIG_SHELL-/bin/sh} $ac_sub_configure $ac_sub_configure_args --cache-file=$ac_sub_cache_file --srcdir=$ac_sub_srcdir + then : + else + AC_MSG_ERROR($ac_sub_configure failed for $ac_config_dir) + fi + fi + + cd $ac_popdir + done +fi +])
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kpathsea/c-auto.h.in Fri Jul 19 01:57:38 1996 +0000 @@ -0,0 +1,71 @@ +/* c-auto.h.in. Generated automatically from configure.in by autoheader. */ + +/* Define if the closedir function returns void instead of int. */ +#undef CLOSEDIR_VOID + +/* Define to empty if the keyword does not work. */ +#undef const + +/* Define if you need to in order for stat and other things to work. */ +#undef _POSIX_SOURCE + +/* Define if you have the ANSI C header files. */ +#undef STDC_HEADERS + +/* Define if your putenv doesn't waste space when the same environment + variable is assigned more than once, with different (malloced) + values. This is true only on NetBSD/FreeBSD, as far as I know. See + xputenv.c. */ +#undef SMART_PUTENV + +/* Define if you are using GNU libc or otherwise have global variables + `program_invocation_name' and `program_invocation_short_name'. */ +#undef HAVE_PROGRAM_INVOCATION_NAME + +/* Define if you have the basename function. */ +#undef HAVE_BASENAME + +/* Define if you have the bcopy function. */ +#undef HAVE_BCOPY + +/* Define if you have the memmove function. */ +#undef HAVE_MEMMOVE + +/* Define if you have the putenv function. */ +#undef HAVE_PUTENV + +/* Define if you have the <assert.h> header file. */ +#undef HAVE_ASSERT_H + +/* Define if you have the <dirent.h> header file. */ +#undef HAVE_DIRENT_H + +/* Define if you have the <float.h> header file. */ +#undef HAVE_FLOAT_H + +/* Define if you have the <limits.h> header file. */ +#undef HAVE_LIMITS_H + +/* Define if you have the <memory.h> header file. */ +#undef HAVE_MEMORY_H + +/* Define if you have the <ndir.h> header file. */ +#undef HAVE_NDIR_H + +/* Define if you have the <pwd.h> header file. */ +#undef HAVE_PWD_H + +/* Define if you have the <stdlib.h> header file. */ +#undef HAVE_STDLIB_H + +/* Define if you have the <string.h> header file. */ +#undef HAVE_STRING_H + +/* Define if you have the <sys/dir.h> header file. */ +#undef HAVE_SYS_DIR_H + +/* Define if you have the <sys/ndir.h> header file. */ +#undef HAVE_SYS_NDIR_H + +/* Define if you have the <unistd.h> header file. */ +#undef HAVE_UNISTD_H
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kpathsea/common.ac Fri Jul 19 01:57:38 1996 +0000 @@ -0,0 +1,98 @@ +dnl Common Autoconf sinclude file for kpathsea-using programs. (Have to +dnl use the m4 `sinclude' builtin instead of `include', since Autoconf +dnl disables `include'.) + +dnl Write output here, instead of putting a zillion -D's on the command line. +AC_CONFIG_HEADER(c-auto.h) + +AC_PROG_MAKE_SET + +AC_PROG_CC +AC_PROG_INSTALL +AC_PROG_RANLIB + +AC_ISC_POSIX + +AC_HEADER_DIRENT +AC_HEADER_STDC +AC_FUNC_CLOSEDIR_VOID +AC_CHECK_HEADERS(assert.h float.h limits.h memory.h pwd.h stdlib.h \ + string.h unistd.h) + +AC_CHECK_FUNCS(basename bcopy memmove putenv) + +AC_C_CONST + + +# This is a GNU libc invention. +AC_MSG_CHECKING(whether program_invocation_name is predefined) +AC_CACHE_VAL(kb_cv_var_program_inv_name, +[AC_TRY_LINK(, [main() { program_invocation_name = "love"; }], + kb_cv_var_program_inv_name=yes, kb_cv_var_program_inv_name=no)])dnl +AC_MSG_RESULT($kb_cv_var_program_inv_name) +if test $kb_cv_var_program_inv_name = yes; then + AC_DEFINE(HAVE_PROGRAM_INVOCATION_NAME) +fi + + +# Some BSD putenv's, e.g., FreeBSD, do malloc/free's on the environment. +# This test program is due to Mike Hibler <mike@cs.utah.edu>. +# We don't actually need to run this if we don't have putenv, but it +# doesn't hurt. +AC_MSG_CHECKING(whether putenv uses malloc) +AC_CACHE_VAL(kb_cv_func_putenv_malloc, +[AC_TRY_RUN([ +#define VAR "YOW_VAR" +#define STRING1 "GabbaGabbaHey" +#define STRING2 "Yow!!" /* should be shorter than STRING1 */ +extern char *getenv (); /* in case char* and int don't mix gracefully */ +main () +{ + char *str1, *rstr1, *str2, *rstr2; + str1 = getenv (VAR); + if (str1) + exit (1); + str1 = malloc (strlen (VAR) + 1 + strlen (STRING1) + 1); + if (str1 == 0) + exit (2); + strcpy (str1, VAR); + strcat (str1, "="); + strcat (str1, STRING1); + if (putenv (str1) < 0) + exit (3); + rstr1 = getenv (VAR); + if (rstr1 == 0) + exit (4); + rstr1 -= strlen (VAR) + 1; + if (strncmp (rstr1, VAR, strlen (VAR))) + exit (5); + str2 = malloc (strlen (VAR) + 1 + strlen (STRING2) + 1); + if (str2 == 0 || str1 == str2) + exit (6); + strcpy (str2, VAR); + strcat (str2, "="); + strcat (str2, STRING2); + if (putenv (str2) < 0) + exit (7); + rstr2 = getenv (VAR); + if (rstr2 == 0) + exit (8); + rstr2 -= strlen (VAR) + 1; +#if 0 + printf ("rstr1=0x%x, rstr2=0x%x\n", rstr1, rstr2); + /* + * If string from first call was reused for the second call, + * you had better not do a free on the first string! + */ + if (rstr1 == rstr2) + printf ("#define SMART_PUTENV\n"); + else + printf ("#undef SMART_PUTENV\n"); +#endif + exit (rstr1 == rstr2 ? 0 : 1); +}], kb_cv_func_putenv_malloc=yes, kb_cv_func_putenv_malloc=no, + kb_cv_func_putenv_malloc=no)])dnl +AC_MSG_RESULT($kb_cv_func_putenv_malloc) +if test $kb_cv_func_putenv_malloc = yes; then + AC_DEFINE(SMART_PUTENV) +fi
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kpathsea/config.guess Fri Jul 19 01:57:38 1996 +0000 @@ -0,0 +1,568 @@ +#! /bin/sh +# Attempt to guess a canonical system name. +# Copyright (C) 1992, 1993, 1994, 1995 Free Software Foundation, Inc. +# +# This file 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 of the License, 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., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +# +# As a special exception to the GNU General Public License, if you +# distribute this file as part of a program that contains a +# configuration script generated by Autoconf, you may include it under +# the same distribution terms that you use for the rest of that program. + +# Written by Per Bothner <bothner@cygnus.com>. +# The master version of this file is at the FSF in /home/gd/gnu/lib. +# +# This script attempts to guess a canonical system name similar to +# config.sub. If it succeeds, it prints the system name on stdout, and +# exits with 0. Otherwise, it exits with 1. +# +# The plan is that this can be called by configure scripts if you +# don't specify an explicit system type (host/target name). +# +# Only a few systems have been added to this list; please add others +# (but try to keep the structure clean). +# + +# This is needed to find uname on a Pyramid OSx when run in the BSD universe. +# (ghazi@noc.rutgers.edu 8/24/94.) +if (test -f /.attbin/uname) >/dev/null 2>&1 ; then + PATH=$PATH:/.attbin ; export PATH +fi + +UNAME_MACHINE=`(uname -m) 2>/dev/null` || UNAME_MACHINE=unknown +UNAME_RELEASE=`(uname -r) 2>/dev/null` || UNAME_RELEASE=unknown +UNAME_SYSTEM=`(uname -s) 2>/dev/null` || UNAME_SYSTEM=unknown +UNAME_VERSION=`(uname -v) 2>/dev/null` || UNAME_VERSION=unknown + +trap 'rm -f dummy.c dummy.o dummy; exit 1' 1 2 15 + +# Note: order is significant - the case branches are not exclusive. + +case "${UNAME_MACHINE}:${UNAME_SYSTEM}:${UNAME_RELEASE}:${UNAME_VERSION}" in + alpha:OSF1:V*:*) + # After 1.2, OSF1 uses "V1.3" for uname -r. + echo alpha-dec-osf`echo ${UNAME_RELEASE} | sed -e 's/^V//'` + exit 0 ;; + alpha:OSF1:*:*) + # 1.2 uses "1.2" for uname -r. + echo alpha-dec-osf${UNAME_RELEASE} + exit 0 ;; + 21064:Windows_NT:50:3) + echo alpha-dec-winnt3.5 + exit 0 ;; + amiga:NetBSD:*:*) + echo m68k-cbm-netbsd${UNAME_RELEASE} + exit 0 ;; + arm:RISC*:1.[012]*:*|arm:riscix:1.[012]*:*) + echo arm-acorn-riscix${UNAME_RELEASE} + exit 0;; + Pyramid*:OSx*:*:*) + if test "`(/bin/universe) 2>/dev/null`" = att ; then + echo pyramid-pyramid-sysv3 + else + echo pyramid-pyramid-bsd + fi + exit 0 ;; + sun4*:SunOS:5.*:*) + echo sparc-sun-solaris2`echo ${UNAME_RELEASE}|sed -e 's/[^.]*//'` + exit 0 ;; + i86pc:SunOS:5.*:*) + echo i386-unknown-solaris2`echo ${UNAME_RELEASE}|sed -e 's/[^.]*//'` + exit 0 ;; + sun4*:SunOS:6*:*) + # According to config.sub, this is the proper way to canonicalize + # SunOS6. Hard to guess exactly what SunOS6 will be like, but + # it's likely to be more like Solaris than SunOS4. + echo sparc-sun-solaris3`echo ${UNAME_RELEASE}|sed -e 's/[^.]*//'` + exit 0 ;; + sun4*:SunOS:*:*) + case "`/usr/bin/arch -k`" in + Series*|S4*) + UNAME_RELEASE=`uname -v` + ;; + esac + # Japanese Language versions have a version number like `4.1.3-JL'. + echo sparc-sun-sunos`echo ${UNAME_RELEASE}|sed -e 's/-/_/'` + exit 0 ;; + sun3*:SunOS:*:*) + echo m68k-sun-sunos${UNAME_RELEASE} + exit 0 ;; + atari*:NetBSD:*:*) + echo m68k-atari-netbsd${UNAME_RELEASE} + exit 0 ;; + sun3*:NetBSD:*:*) + echo m68k-sun-netbsd${UNAME_RELEASE} + exit 0 ;; + mac68k:NetBSD:*:*) + echo m68k-apple-netbsd${UNAME_RELEASE} + exit 0 ;; + RISC*:ULTRIX:*:*) + echo mips-dec-ultrix${UNAME_RELEASE} + exit 0 ;; + VAX*:ULTRIX*:*:*) + echo vax-dec-ultrix${UNAME_RELEASE} + exit 0 ;; + mips:*:4*:UMIPS) + echo mips-mips-riscos4sysv + exit 0 ;; + mips:*:5*:RISCos) + echo mips-mips-riscos${UNAME_RELEASE} + exit 0 ;; + m88k:CX/UX:7*:*) + echo m88k-harris-cxux7 + exit 0 ;; + m88k:*:4*:R4*) + echo m88k-motorola-sysv4 + exit 0 ;; + m88k:*:3*:R3*) + echo m88k-motorola-sysv3 + exit 0 ;; + AViiON:dgux:*:*) + if [ ${TARGET_BINARY_INTERFACE}x = m88kdguxelfx \ + -o ${TARGET_BINARY_INTERFACE}x = x ] ; then + echo m88k-dg-dgux${UNAME_RELEASE} + else + echo m88k-dg-dguxbcs${UNAME_RELEASE} + fi + exit 0 ;; + M88*:DolphinOS:*:*) # DolphinOS (SVR3) + echo m88k-dolphin-sysv3 + exit 0 ;; + M88*:*:R3*:*) + # Delta 88k system running SVR3 + echo m88k-motorola-sysv3 + exit 0 ;; + XD88*:*:*:*) # Tektronix XD88 system running UTekV (SVR3) + echo m88k-tektronix-sysv3 + exit 0 ;; + Tek43[0-9][0-9]:UTek:*:*) # Tektronix 4300 system running UTek (BSD) + echo m68k-tektronix-bsd + exit 0 ;; + *:IRIX*:*:*) + echo mips-sgi-irix`echo ${UNAME_RELEASE}|sed -e 's/-/_/g'` + exit 0 ;; + ????????:AIX?:[12].1:2) # AIX 2.2.1 or AIX 2.1.1 is RT/PC AIX. + echo romp-ibm-aix # uname -m gives an 8 hex-code CPU id + exit 0 ;; # Note that: echo "'`uname -s`'" gives 'AIX ' + i[34]86:AIX:*:*) + echo i386-ibm-aix + exit 0 ;; + *:AIX:2:3) + if grep bos325 /usr/include/stdio.h >/dev/null 2>&1; then + sed 's/^ //' << EOF >dummy.c + #include <sys/systemcfg.h> + + main() + { + if (!__power_pc()) + exit(1); + puts("powerpc-ibm-aix3.2.5"); + exit(0); + } +EOF + ${CC-cc} dummy.c -o dummy && ./dummy && rm dummy.c dummy && exit 0 + rm -f dummy.c dummy + echo rs6000-ibm-aix3.2.5 + elif grep bos324 /usr/include/stdio.h >/dev/null 2>&1; then + echo rs6000-ibm-aix3.2.4 + else + echo rs6000-ibm-aix3.2 + fi + exit 0 ;; + *:AIX:*:4) + if /usr/sbin/lsattr -EHl proc0 | grep POWER >/dev/null 2>&1; then + IBM_ARCH=rs6000 + else + IBM_ARCH=powerpc + fi + if [ -x /usr/bin/oslevel ] ; then + IBM_REV=`/usr/bin/oslevel` + else + IBM_REV=4.${UNAME_RELEASE} + fi + echo ${IBM_ARCH}-ibm-aix${IBM_REV} + exit 0 ;; + *:AIX:*:*) + echo rs6000-ibm-aix + exit 0 ;; + ibmrt:4.4BSD:*|romp-ibm:BSD:*) + echo romp-ibm-bsd4.4 + exit 0 ;; + ibmrt:*BSD:*|romp-ibm:BSD:*) # covers RT/PC NetBSD and + echo romp-ibm-bsd${UNAME_RELEASE} # 4.3 with uname added to + exit 0 ;; # report: romp-ibm BSD 4.3 + *:BOSX:*:*) + echo rs6000-bull-bosx + exit 0 ;; + DPX/2?00:B.O.S.:*:*) + echo m68k-bull-sysv3 + exit 0 ;; + 9000/[34]??:4.3bsd:1.*:*) + echo m68k-hp-bsd + exit 0 ;; + hp300:4.4BSD:*:* | 9000/[34]??:4.3bsd:2.*:*) + echo m68k-hp-bsd4.4 + exit 0 ;; + 9000/[3478]??:HP-UX:*:*) + case "${UNAME_MACHINE}" in + 9000/31? ) HP_ARCH=m68000 ;; + 9000/[34]?? ) HP_ARCH=m68k ;; + 9000/7?? | 9000/8?7 ) HP_ARCH=hppa1.1 ;; + 9000/8?? ) HP_ARCH=hppa1.0 ;; + esac + HPUX_REV=`echo ${UNAME_RELEASE}|sed -e 's/[^.]*.[0B]*//'` + echo ${HP_ARCH}-hp-hpux${HPUX_REV} + exit 0 ;; + 3050*:HI-UX:*:*) + sed 's/^ //' << EOF >dummy.c + #include <unistd.h> + int + main () + { + long cpu = sysconf (_SC_CPU_VERSION); + /* The order matters, because CPU_IS_HP_MC68K erroneously returns + true for CPU_PA_RISC1_0. CPU_IS_PA_RISC returns correct + results, however. */ + if (CPU_IS_PA_RISC (cpu)) + { + switch (cpu) + { + case CPU_PA_RISC1_0: puts ("hppa1.0-hitachi-hiuxwe2"); break; + case CPU_PA_RISC1_1: puts ("hppa1.1-hitachi-hiuxwe2"); break; + case CPU_PA_RISC2_0: puts ("hppa2.0-hitachi-hiuxwe2"); break; + default: puts ("hppa-hitachi-hiuxwe2"); break; + } + } + else if (CPU_IS_HP_MC68K (cpu)) + puts ("m68k-hitachi-hiuxwe2"); + else puts ("unknown-hitachi-hiuxwe2"); + exit (0); + } +EOF + ${CC-cc} dummy.c -o dummy && ./dummy && rm dummy.c dummy && exit 0 + rm -f dummy.c dummy + echo unknown-hitachi-hiuxwe2 + exit 0 ;; + 9000/7??:4.3bsd:*:* | 9000/8?7:4.3bsd:*:* ) + echo hppa1.1-hp-bsd + exit 0 ;; + 9000/8??:4.3bsd:*:*) + echo hppa1.0-hp-bsd + exit 0 ;; + hp7??:OSF1:*:* | hp8?7:OSF1:*:* ) + echo hppa1.1-hp-osf + exit 0 ;; + hp8??:OSF1:*:*) + echo hppa1.0-hp-osf + exit 0 ;; + parisc*:Lites*:*:*) + echo hppa1.1-hp-lites + exit 0 ;; + C1*:ConvexOS:*:* | convex:ConvexOS:C1*:*) + echo c1-convex-bsd + exit 0 ;; + C2*:ConvexOS:*:* | convex:ConvexOS:C2*:*) + if getsysinfo -f scalar_acc + then echo c32-convex-bsd + else echo c2-convex-bsd + fi + exit 0 ;; + C34*:ConvexOS:*:* | convex:ConvexOS:C34*:*) + echo c34-convex-bsd + exit 0 ;; + C38*:ConvexOS:*:* | convex:ConvexOS:C38*:*) + echo c38-convex-bsd + exit 0 ;; + C4*:ConvexOS:*:* | convex:ConvexOS:C4*:*) + echo c4-convex-bsd + exit 0 ;; + CRAY*X-MP:*:*:*) + echo xmp-cray-unicos + exit 0 ;; + CRAY*Y-MP:*:*:*) + echo ymp-cray-unicos${UNAME_RELEASE} + exit 0 ;; + CRAY*C90:*:*:*) + echo c90-cray-unicos${UNAME_RELEASE} + exit 0 ;; + CRAY-2:*:*:*) + echo cray2-cray-unicos + exit 0 ;; + hp3[0-9][05]:NetBSD:*:*) + echo m68k-hp-netbsd${UNAME_RELEASE} + exit 0 ;; + i[34]86:BSD/386:*:* | *:BSD/OS:*:*) + echo ${UNAME_MACHINE}-unknown-bsdi${UNAME_RELEASE} + exit 0 ;; + *:FreeBSD:*:*) + echo ${UNAME_MACHINE}-unknown-freebsd`echo ${UNAME_RELEASE}|sed -e 's/[-(].*//'` + exit 0 ;; + *:NetBSD:*:*) + echo ${UNAME_MACHINE}-unknown-netbsd`echo ${UNAME_RELEASE}|sed -e 's/[-_].*/\./'` + exit 0 ;; + *:GNU:*:*) + echo `echo ${UNAME_MACHINE}|sed -e 's,/.*$,,'`-unknown-gnu`echo ${UNAME_RELEASE}|sed -e 's,/.*$,,'` + exit 0 ;; + *:Linux:*:*) + # The BFD linker knows what the default object file format is, so + # first see if it will tell us. + ld_help_string=`ld --help 2>&1` + if echo $ld_help_string | grep >/dev/null 2>&1 "supported emulations: elf_i[345]86"; then + echo "${UNAME_MACHINE}-unknown-linux" ; exit 0 + elif echo $ld_help_string | grep >/dev/null 2>&1 "supported emulations: i[345]86linux"; then + echo "${UNAME_MACHINE}-unknown-linuxaout" ; exit 0 + elif echo $ld_help_string | grep >/dev/null 2>&1 "supported emulations: i[345]86coff"; then + echo "${UNAME_MACHINE}-unknown-linuxcoff" ; exit 0 + elif test "${UNAME_MACHINE}" = "alpha" ; then + echo alpha-unknown-linux ; exit 0 + else + # Either a pre-BFD a.out linker (linuxoldld) or one that does not give us + # useful --help. Gcc wants to distinguish between linuxoldld and linuxaout. + test ! -d /usr/lib/ldscripts/. \ + && echo "${UNAME_MACHINE}-unknown-linuxoldld" && exit 0 + # Determine whether the default compiler is a.out or elf + cat >dummy.c <<EOF +main(argc, argv) +int argc; +char *argv[]; +{ +#ifdef __ELF__ + printf ("%s-unknown-linux\n", argv[1]); +#else + printf ("%s-unknown-linuxaout\n", argv[1]); +#endif + return 0; +} +EOF + ${CC-cc} dummy.c -o dummy 2>/dev/null && ./dummy "${UNAME_MACHINE}" && rm dummy.c dummy && exit 0 + rm -f dummy.c dummy + fi ;; +# ptx 4.0 does uname -s correctly, with DYNIX/ptx in there. earlier versions +# are messed up and put the nodename in both sysname and nodename. + i[34]86:DYNIX/ptx:4*:*) + echo i386-sequent-sysv4 + exit 0 ;; + i[34]86:*:4.*:* | i[34]86:SYSTEM_V:4.*:*) + if grep Novell /usr/include/link.h >/dev/null 2>/dev/null; then + echo ${UNAME_MACHINE}-univel-sysv${UNAME_RELEASE} + else + echo ${UNAME_MACHINE}-unknown-sysv${UNAME_RELEASE} + fi + exit 0 ;; + i[34]86:*:3.2:*) + if test -f /usr/options/cb.name; then + UNAME_REL=`sed -n 's/.*Version //p' </usr/options/cb.name` + echo ${UNAME_MACHINE}-unknown-isc$UNAME_REL + elif /bin/uname -X 2>/dev/null >/dev/null ; then + UNAME_REL=`(/bin/uname -X|egrep Release|sed -e 's/.*= //')` + (/bin/uname -X|egrep i80486 >/dev/null) && UNAME_MACHINE=i486 + echo ${UNAME_MACHINE}-unknown-sco$UNAME_REL + else + echo ${UNAME_MACHINE}-unknown-sysv32 + fi + exit 0 ;; + Intel:Mach:3*:*) + echo i386-unknown-mach3 + exit 0 ;; + paragon:*:*:*) + echo i860-intel-osf1 + exit 0 ;; + i860:*:4.*:*) # i860-SVR4 + if grep Stardent /usr/include/sys/uadmin.h >/dev/null 2>&1 ; then + echo i860-stardent-sysv${UNAME_RELEASE} # Stardent Vistra i860-SVR4 + else # Add other i860-SVR4 vendors below as they are discovered. + echo i860-unknown-sysv${UNAME_RELEASE} # Unknown i860-SVR4 + fi + exit 0 ;; + mini*:CTIX:SYS*5:*) + # "miniframe" + echo m68010-convergent-sysv + exit 0 ;; + M680[234]0:*:R3V[567]*:*) + test -r /sysV68 && echo 'm68k-motorola-sysv' && exit 0 ;; + 3[34]??:*:4.0:3.0 | 3[34]??,*:*:4.0:3.0) + uname -p 2>/dev/null | grep 86 >/dev/null \ + && echo i486-ncr-sysv4.3 && exit 0 ;; + 3[34]??:*:4.0:* | 3[34]??,*:*:4.0:*) + uname -p 2>/dev/null | grep 86 >/dev/null \ + && echo i486-ncr-sysv4 && exit 0 ;; + m680[234]0:LynxOS:2.[23]*:*) + echo m68k-lynx-lynxos${UNAME_RELEASE} + exit 0 ;; + mc68030:UNIX_System_V:4.*:*) + echo m68k-atari-sysv4 + exit 0 ;; + i[34]86:LynxOS:2.[23]*:*) + echo i386-lynx-lynxos${UNAME_RELEASE} + exit 0 ;; + TSUNAMI:LynxOS:2.[23]*:*) + echo sparc-lynx-lynxos${UNAME_RELEASE} + exit 0 ;; + rs6000:LynxOS:2.[23]*:*) + echo rs6000-lynx-lynxos${UNAME_RELEASE} + exit 0 ;; + Macintosh::*:*) + echo powerpc-apple-machten${UNAME_RELEASE} + exit 0 ;; + RM*:SINIX-*:*:*) + echo mips-sni-sysv4 + exit 0 ;; + *:SINIX-*:*:*) + if uname -p 2>/dev/null >/dev/null ; then + UNAME_MACHINE=`(uname -p) 2>/dev/null` + echo ${UNAME_MACHINE}-sni-sysv4 + else + echo ns32k-sni-sysv + fi + exit 0 ;; +esac + +#echo '(No uname command or uname output not recognized.)' 1>&2 +#echo "${UNAME_MACHINE}:${UNAME_SYSTEM}:${UNAME_RELEASE}:${UNAME_VERSION}" 1>&2 + +cat >dummy.c <<EOF +#ifdef _SEQUENT_ +# include <sys/types.h> +# include <sys/utsname.h> +#endif +main () +{ +#if defined (sony) +#if defined (MIPSEB) + /* BFD wants "bsd" instead of "newsos". Perhaps BFD should be changed, + I don't know.... */ + printf ("mips-sony-bsd\n"); exit (0); +#else +#include <sys/param.h> + printf ("m68k-sony-newsos%s\n", +#ifdef NEWSOS4 + "4" +#else + "" +#endif + ); exit (0); +#endif +#endif + +#if defined (__arm) && defined (__acorn) && defined (__unix) + printf ("arm-acorn-riscix"); exit (0); +#endif + +#if defined (hp300) && !defined (hpux) + printf ("m68k-hp-bsd\n"); exit (0); +#endif + +#if defined (NeXT) +#if !defined (__ARCHITECTURE__) +#define __ARCHITECTURE__ "m68k" +#endif + int version; + version=`(hostinfo | sed -n 's/.*NeXT Mach \([0-9]*\).*/\1/p') 2>/dev/null`; + printf ("%s-next-nextstep%s\n", __ARCHITECTURE__, version==2 ? "2" : "3"); + exit (0); +#endif + +#if defined (MULTIMAX) || defined (n16) +#if defined (UMAXV) + printf ("ns32k-encore-sysv\n"); exit (0); +#else +#if defined (CMU) + printf ("ns32k-encore-mach\n"); exit (0); +#else + printf ("ns32k-encore-bsd\n"); exit (0); +#endif +#endif +#endif + +#if defined (__386BSD__) + printf ("i386-unknown-bsd\n"); exit (0); +#endif + +#if defined (sequent) +#if defined (i386) + printf ("i386-sequent-dynix\n"); exit (0); +#endif +#if defined (ns32000) + printf ("ns32k-sequent-dynix\n"); exit (0); +#endif +#endif + +#if defined (_SEQUENT_) + struct utsname un; + + uname(&un); + + if (strncmp(un.version, "V2", 2) == 0) { + printf ("i386-sequent-ptx2\n"); exit (0); + } + if (strncmp(un.version, "V1", 2) == 0) { /* XXX is V1 correct? */ + printf ("i386-sequent-ptx1\n"); exit (0); + } + printf ("i386-sequent-ptx\n"); exit (0); + +#endif + +#if defined (vax) +#if !defined (ultrix) + printf ("vax-dec-bsd\n"); exit (0); +#else + printf ("vax-dec-ultrix\n"); exit (0); +#endif +#endif + +#if defined (alliant) && defined (i860) + printf ("i860-alliant-bsd\n"); exit (0); +#endif + + exit (1); +} +EOF + +${CC-cc} dummy.c -o dummy 2>/dev/null && ./dummy && rm dummy.c dummy && exit 0 +rm -f dummy.c dummy + +# Apollos put the system type in the environment. + +test -d /usr/apollo && { echo ${ISP}-apollo-${SYSTYPE}; exit 0; } + +# Convex versions that predate uname can use getsysinfo(1) + +if [ -x /usr/convex/getsysinfo ] +then + case `getsysinfo -f cpu_type` in + c1*) + echo c1-convex-bsd + exit 0 ;; + c2*) + if getsysinfo -f scalar_acc + then echo c32-convex-bsd + else echo c2-convex-bsd + fi + exit 0 ;; + c34*) + echo c34-convex-bsd + exit 0 ;; + c38*) + echo c38-convex-bsd + exit 0 ;; + c4*) + echo c4-convex-bsd + exit 0 ;; + esac +fi + +#echo '(Unable to guess system type)' 1>&2 + +exit 1
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kpathsea/config.sub Fri Jul 19 01:57:38 1996 +0000 @@ -0,0 +1,867 @@ +#! /bin/sh +# Configuration validation subroutine script, version 1.1. +# Copyright (C) 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc. +# This file is (in principle) common to ALL GNU software. +# The presence of a machine in this file suggests that SOME GNU software +# can handle that machine. It does not imply ALL GNU software can. +# +# This file 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 of the License, 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., 59 Temple Place - Suite 330, +# Boston, MA 02111-1307, USA. + +# As a special exception to the GNU General Public License, if you +# distribute this file as part of a program that contains a +# configuration script generated by Autoconf, you may include it under +# the same distribution terms that you use for the rest of that program. + +# Configuration subroutine to validate and canonicalize a configuration type. +# Supply the specified configuration type as an argument. +# If it is invalid, we print an error message on stderr and exit with code 1. +# Otherwise, we print the canonical config type on stdout and succeed. + +# This file is supposed to be the same for all GNU packages +# and recognize all the CPU types, system types and aliases +# that are meaningful with *any* GNU software. +# Each package is responsible for reporting which valid configurations +# it does not support. The user should be able to distinguish +# a failure to support a valid configuration from a meaningless +# configuration. + +# The goal of this file is to map all the various variations of a given +# machine specification into a single specification in the form: +# CPU_TYPE-MANUFACTURER-OPERATING_SYSTEM +# It is wrong to echo any other type of specification. + +if [ x$1 = x ] +then + echo Configuration name missing. 1>&2 + echo "Usage: $0 CPU-MFR-OPSYS" 1>&2 + echo "or $0 ALIAS" 1>&2 + echo where ALIAS is a recognized configuration type. 1>&2 + exit 1 +fi + +# First pass through any local machine types. +case $1 in + *local*) + echo $1 + exit 0 + ;; + *) + ;; +esac + +# Separate what the user gave into CPU-COMPANY and OS (if any). +basic_machine=`echo $1 | sed 's/-[^-]*$//'` +if [ $basic_machine != $1 ] +then os=`echo $1 | sed 's/.*-/-/'` +else os=; fi + +### Let's recognize common machines as not being operating systems so +### that things like config.sub decstation-3100 work. We also +### recognize some manufacturers as not being operating systems, so we +### can provide default operating systems below. +case $os in + -sun*os*) + # Prevent following clause from handling this invalid input. + ;; + -dec* | -mips* | -sequent* | -encore* | -pc532* | -sgi* | -sony* | \ + -att* | -7300* | -3300* | -delta* | -motorola* | -sun[234]* | \ + -unicom* | -ibm* | -next | -hp | -isi* | -apollo | -altos* | \ + -convergent* | -ncr* | -news | -32* | -3600* | -3100* | -hitachi* |\ + -c[123]* | -convex* | -sun | -crds | -omron* | -dg | -ultra | -tti* | \ + -harris | -dolphin | -highlevel | -gould | -cbm | -ns | -masscomp ) + os= + basic_machine=$1 + ;; + -hiux*) + os=-hiuxwe2 + ;; + -sco4) + os=-sco3.2v4 + basic_machine=`echo $1 | sed -e 's/86-.*/86-unknown/'` + ;; + -sco3.2.[4-9]*) + os=`echo $os | sed -e 's/sco3.2./sco3.2v/'` + basic_machine=`echo $1 | sed -e 's/86-.*/86-unknown/'` + ;; + -sco3.2v[4-9]*) + # Don't forget version if it is 3.2v4 or newer. + basic_machine=`echo $1 | sed -e 's/86-.*/86-unknown/'` + ;; + -sco*) + os=-sco3.2v2 + basic_machine=`echo $1 | sed -e 's/86-.*/86-unknown/'` + ;; + -isc) + os=-isc2.2 + basic_machine=`echo $1 | sed -e 's/86-.*/86-unknown/'` + ;; + -clix*) + basic_machine=clipper-intergraph + ;; + -isc*) + basic_machine=`echo $1 | sed -e 's/86-.*/86-unknown/'` + ;; + -lynx*) + os=-lynxos + ;; + -ptx*) + basic_machine=`echo $1 | sed -e 's/86-.*/86-sequent/'` + ;; + -windowsnt*) + os=`echo $os | sed -e 's/windowsnt/winnt/'` + ;; +esac + +# Decode aliases for certain CPU-COMPANY combinations. +case $basic_machine in + # Recognize the basic CPU types without company name. + # Some are omitted here because they have special meanings below. + tahoe | i[345]86 | i860 | m68k | m68000 | m88k | ns32k | arm \ + | arme[lb] | pyramid \ + | tron | a29k | 580 | i960 | h8300 | hppa1.0 | hppa1.1 \ + | alpha | we32k | ns16k | clipper | sparclite | i370 | sh \ + | powerpc | powerpcle | sparc64 | 1750a | dsp16xx | mips64 | mipsel \ + | pdp11 | mips64el | mips64orion | mips64orionel \ + | sparc) + basic_machine=$basic_machine-unknown + ;; + # Object if more than one company name word. + *-*-*) + echo Invalid configuration \`$1\': machine \`$basic_machine\' not recognized 1>&2 + exit 1 + ;; + # Recognize the basic CPU types with company name. + vax-* | tahoe-* | i[345]86-* | i860-* | m68k-* | m68000-* | m88k-* \ + | sparc-* | ns32k-* | fx80-* | arm-* | c[123]* \ + | mips-* | pyramid-* | tron-* | a29k-* | romp-* | rs6000-* | power-* \ + | none-* | 580-* | cray2-* | h8300-* | i960-* | xmp-* | ymp-* \ + | hppa1.0-* | hppa1.1-* | alpha-* | we32k-* | cydra-* | ns16k-* \ + | pn-* | np1-* | xps100-* | clipper-* | orion-* | sparclite-* \ + | pdp11-* | sh-* | powerpc-* | powerpcle-* | sparc64-* | mips64-* | mipsel-* \ + | mips64el-* | mips64orion-* | mips64orionel-*) + ;; + # Recognize the various machine names and aliases which stand + # for a CPU type and a company and sometimes even an OS. + 3b1 | 7300 | 7300-att | att-7300 | pc7300 | safari | unixpc) + basic_machine=m68000-att + ;; + 3b*) + basic_machine=we32k-att + ;; + alliant | fx80) + basic_machine=fx80-alliant + ;; + altos | altos3068) + basic_machine=m68k-altos + ;; + am29k) + basic_machine=a29k-none + os=-bsd + ;; + amdahl) + basic_machine=580-amdahl + os=-sysv + ;; + amiga | amiga-*) + basic_machine=m68k-cbm + ;; + amigados) + basic_machine=m68k-cbm + os=-amigados + ;; + amigaunix | amix) + basic_machine=m68k-cbm + os=-sysv4 + ;; + apollo68) + basic_machine=m68k-apollo + os=-sysv + ;; + balance) + basic_machine=ns32k-sequent + os=-dynix + ;; + convex-c1) + basic_machine=c1-convex + os=-bsd + ;; + convex-c2) + basic_machine=c2-convex + os=-bsd + ;; + convex-c32) + basic_machine=c32-convex + os=-bsd + ;; + convex-c34) + basic_machine=c34-convex + os=-bsd + ;; + convex-c38) + basic_machine=c38-convex + os=-bsd + ;; + cray | ymp) + basic_machine=ymp-cray + os=-unicos + ;; + cray2) + basic_machine=cray2-cray + os=-unicos + ;; + crds | unos) + basic_machine=m68k-crds + ;; + da30 | da30-*) + basic_machine=m68k-da30 + ;; + decstation | decstation-3100 | pmax | pmax-* | pmin | dec3100 | decstatn) + basic_machine=mips-dec + ;; + delta | 3300 | motorola-3300 | motorola-delta \ + | 3300-motorola | delta-motorola) + basic_machine=m68k-motorola + ;; + delta88) + basic_machine=m88k-motorola + os=-sysv3 + ;; + dpx20 | dpx20-*) + basic_machine=rs6000-bull + os=-bosx + ;; + dpx2* | dpx2*-bull) + basic_machine=m68k-bull + os=-sysv3 + ;; + ebmon29k) + basic_machine=a29k-amd + os=-ebmon + ;; + elxsi) + basic_machine=elxsi-elxsi + os=-bsd + ;; + encore | umax | mmax) + basic_machine=ns32k-encore + ;; + fx2800) + basic_machine=i860-alliant + ;; + genix) + basic_machine=ns32k-ns + ;; + gmicro) + basic_machine=tron-gmicro + os=-sysv + ;; + h3050r* | hiux*) + basic_machine=hppa1.1-hitachi + os=-hiuxwe2 + ;; + h8300hms) + basic_machine=h8300-hitachi + os=-hms + ;; + harris) + basic_machine=m88k-harris + os=-sysv3 + ;; + hp300-*) + basic_machine=m68k-hp + ;; + hp300bsd) + basic_machine=m68k-hp + os=-bsd + ;; + hp300hpux) + basic_machine=m68k-hp + os=-hpux + ;; + hp9k2[0-9][0-9] | hp9k31[0-9]) + basic_machine=m68000-hp + ;; + hp9k3[2-9][0-9]) + basic_machine=m68k-hp + ;; + hp9k7[0-9][0-9] | hp7[0-9][0-9] | hp9k8[0-9]7 | hp8[0-9]7) + basic_machine=hppa1.1-hp + ;; + hp9k8[0-9][0-9] | hp8[0-9][0-9]) + basic_machine=hppa1.0-hp + ;; + i370-ibm* | ibm*) + basic_machine=i370-ibm + os=-mvs + ;; +# I'm not sure what "Sysv32" means. Should this be sysv3.2? + i[345]86v32) + basic_machine=`echo $1 | sed -e 's/86.*/86-unknown/'` + os=-sysv32 + ;; + i[345]86v4*) + basic_machine=`echo $1 | sed -e 's/86.*/86-unknown/'` + os=-sysv4 + ;; + i[345]86v) + basic_machine=`echo $1 | sed -e 's/86.*/86-unknown/'` + os=-sysv + ;; + i[345]86sol2) + basic_machine=`echo $1 | sed -e 's/86.*/86-unknown/'` + os=-solaris2 + ;; + iris | iris4d) + basic_machine=mips-sgi + case $os in + -irix*) + ;; + *) + os=-irix4 + ;; + esac + ;; + isi68 | isi) + basic_machine=m68k-isi + os=-sysv + ;; + m88k-omron*) + basic_machine=m88k-omron + ;; + magnum | m3230) + basic_machine=mips-mips + os=-sysv + ;; + merlin) + basic_machine=ns32k-utek + os=-sysv + ;; + miniframe) + basic_machine=m68000-convergent + ;; + mips3*-*) + basic_machine=`echo $basic_machine | sed -e 's/mips3/mips64/'` + ;; + mips3*) + basic_machine=`echo $basic_machine | sed -e 's/mips3/mips64/'`-unknown + ;; + ncr3000) + basic_machine=i486-ncr + os=-sysv4 + ;; + news | news700 | news800 | news900) + basic_machine=m68k-sony + os=-newsos + ;; + news1000) + basic_machine=m68030-sony + os=-newsos + ;; + news-3600 | risc-news) + basic_machine=mips-sony + os=-newsos + ;; + next | m*-next ) + basic_machine=m68k-next + case $os in + -nextstep* ) + ;; + -ns2*) + os=-nextstep2 + ;; + *) + os=-nextstep3 + ;; + esac + ;; + nh3000) + basic_machine=m68k-harris + os=-cxux + ;; + nh[45]000) + basic_machine=m88k-harris + os=-cxux + ;; + nindy960) + basic_machine=i960-intel + os=-nindy + ;; + np1) + basic_machine=np1-gould + ;; + pa-hitachi) + basic_machine=hppa1.1-hitachi + os=-hiuxwe2 + ;; + paragon) + basic_machine=i860-intel + os=-osf + ;; + pbd) + basic_machine=sparc-tti + ;; + pbb) + basic_machine=m68k-tti + ;; + pc532 | pc532-*) + basic_machine=ns32k-pc532 + ;; + pentium | p5 | p6) + # We don't have specific support for the Intel Pentium (p6) followon yet, so just call it a Pentium + basic_machine=i586-intel + ;; + pentium-* | p5-* | p6-*) + # We don't have specific support for the Intel Pentium (p6) followon yet, so just call it a Pentium + basic_machine=i586-`echo $basic_machine | sed 's/^[^-]*-//'` + ;; + k5) + # We don't have specific support for AMD's K5 yet, so just call it a Pentium + basic_machine=i586-amd + ;; + nexen) + # We don't have specific support for Nexgen yet, so just call it a Pentium + basic_machine=i586-nexgen + ;; + pn) + basic_machine=pn-gould + ;; + power) basic_machine=rs6000-ibm + ;; + ppc) basic_machine=powerpc-unknown + ;; + ppc-*) basic_machine=powerpc-`echo $basic_machine | sed 's/^[^-]*-//'` + ;; + ppcle | powerpclittle | ppc-le | powerpc-little) + basic_machine=powerpcle-unknown + ;; + ppcle-* | powerpclittle-*) + basic_machine=powerpcle-`echo $basic_machine | sed 's/^[^-]*-//'` + ;; + ps2) + basic_machine=i386-ibm + ;; + rm[46]00) + basic_machine=mips-siemens + ;; + rtpc | rtpc-*) + basic_machine=romp-ibm + ;; + sequent) + basic_machine=i386-sequent + ;; + sh) + basic_machine=sh-hitachi + os=-hms + ;; + sps7) + basic_machine=m68k-bull + os=-sysv2 + ;; + spur) + basic_machine=spur-unknown + ;; + sun2) + basic_machine=m68000-sun + ;; + sun2os3) + basic_machine=m68000-sun + os=-sunos3 + ;; + sun2os4) + basic_machine=m68000-sun + os=-sunos4 + ;; + sun3os3) + basic_machine=m68k-sun + os=-sunos3 + ;; + sun3os4) + basic_machine=m68k-sun + os=-sunos4 + ;; + sun4os3) + basic_machine=sparc-sun + os=-sunos3 + ;; + sun4os4) + basic_machine=sparc-sun + os=-sunos4 + ;; + sun4sol2) + basic_machine=sparc-sun + os=-solaris2 + ;; + sun3 | sun3-*) + basic_machine=m68k-sun + ;; + sun4) + basic_machine=sparc-sun + ;; + sun386 | sun386i | roadrunner) + basic_machine=i386-sun + ;; + symmetry) + basic_machine=i386-sequent + os=-dynix + ;; + tower | tower-32) + basic_machine=m68k-ncr + ;; + udi29k) + basic_machine=a29k-amd + os=-udi + ;; + ultra3) + basic_machine=a29k-nyu + os=-sym1 + ;; + vaxv) + basic_machine=vax-dec + os=-sysv + ;; + vms) + basic_machine=vax-dec + os=-vms + ;; + vxworks960) + basic_machine=i960-wrs + os=-vxworks + ;; + vxworks68) + basic_machine=m68k-wrs + os=-vxworks + ;; + vxworks29k) + basic_machine=a29k-wrs + os=-vxworks + ;; + xmp) + basic_machine=xmp-cray + os=-unicos + ;; + xps | xps100) + basic_machine=xps100-honeywell + ;; + none) + basic_machine=none-none + os=-none + ;; + +# Here we handle the default manufacturer of certain CPU types. It is in +# some cases the only manufacturer, in others, it is the most popular. + mips) + basic_machine=mips-mips + ;; + romp) + basic_machine=romp-ibm + ;; + rs6000) + basic_machine=rs6000-ibm + ;; + vax) + basic_machine=vax-dec + ;; + pdp11) + basic_machine=pdp11-dec + ;; + we32k) + basic_machine=we32k-att + ;; + sparc) + basic_machine=sparc-sun + ;; + cydra) + basic_machine=cydra-cydrome + ;; + orion) + basic_machine=orion-highlevel + ;; + orion105) + basic_machine=clipper-highlevel + ;; + *) + echo Invalid configuration \`$1\': machine \`$basic_machine\' not recognized 1>&2 + exit 1 + ;; +esac + +# Here we canonicalize certain aliases for manufacturers. +case $basic_machine in + *-digital*) + basic_machine=`echo $basic_machine | sed 's/digital.*/dec/'` + ;; + *-commodore*) + basic_machine=`echo $basic_machine | sed 's/commodore.*/cbm/'` + ;; + *) + ;; +esac + +# Decode manufacturer-specific aliases for certain operating systems. + +if [ x"$os" != x"" ] +then +case $os in + # -solaris* is a basic system type, with this one exception. + -solaris1 | -solaris1.*) + os=`echo $os | sed -e 's|solaris1|sunos4|'` + ;; + -solaris) + os=-solaris2 + ;; + -unixware* | svr4*) + os=-sysv4 + ;; + -gnu/linux*) + os=`echo $os | sed -e 's|gnu/linux|linux|'` + ;; + # First accept the basic system types. + # The portable systems comes first. + # Each alternative MUST END IN A *, to match a version number. + # -sysv* is not here because it comes later, after sysvr4. + -gnu* | -bsd* | -mach* | -minix* | -genix* | -ultrix* | -irix* \ + | -vms* | -sco* | -esix* | -isc* | -aix* | -sunos | -sunos[345]* \ + | -hpux* | -unos* | -osf* | -luna* | -dgux* | -solaris* | -sym* \ + | -amigados* | -msdos* | -newsos* | -unicos* | -aos* \ + | -nindy* | -vxworks* | -ebmon* | -hms* | -mvs* | -clix* \ + | -riscos* | -linux* | -uniplus* | -iris* | -rtu* | -xenix* \ + | -hiux* | -386bsd* | -netbsd* | -freebsd* | -riscix* \ + | -lynxos* | -bosx* | -nextstep* | -cxux* | -aout* | -elf* \ + | -ptx* | -coff* | -ecoff* | -winnt* | -domain* | -vsta* \ + | -udi* | -eabi* | -lites* ) + # Remember, each alternative MUST END IN *, to match a version number. + ;; + -sunos5*) + os=`echo $os | sed -e 's|sunos5|solaris2|'` + ;; + -sunos6*) + os=`echo $os | sed -e 's|sunos6|solaris3|'` + ;; + -osfrose*) + os=-osfrose + ;; + -osf*) + os=-osf + ;; + -utek*) + os=-bsd + ;; + -dynix*) + os=-bsd + ;; + -acis*) + os=-aos + ;; + -ctix* | -uts*) + os=-sysv + ;; + # Preserve the version number of sinix5. + -sinix5.*) + os=`echo $os | sed -e 's|sinix|sysv|'` + ;; + -sinix*) + os=-sysv4 + ;; + -triton*) + os=-sysv3 + ;; + -oss*) + os=-sysv3 + ;; + -svr4) + os=-sysv4 + ;; + -svr3) + os=-sysv3 + ;; + -sysvr4) + os=-sysv4 + ;; + # This must come after -sysvr4. + -sysv*) + ;; + -xenix) + os=-xenix + ;; + -none) + ;; + *) + # Get rid of the `-' at the beginning of $os. + os=`echo $os | sed 's/[^-]*-//'` + echo Invalid configuration \`$1\': system \`$os\' not recognized 1>&2 + exit 1 + ;; +esac +else + +# Here we handle the default operating systems that come with various machines. +# The value should be what the vendor currently ships out the door with their +# machine or put another way, the most popular os provided with the machine. + +# Note that if you're going to try to match "-MANUFACTURER" here (say, +# "-sun"), then you have to tell the case statement up towards the top +# that MANUFACTURER isn't an operating system. Otherwise, code above +# will signal an error saying that MANUFACTURER isn't an operating +# system, and we'll never get to this point. + +case $basic_machine in + *-acorn) + os=-riscix1.2 + ;; + arm*-semi) + os=-aout + ;; + pdp11-*) + os=-none + ;; + *-dec | vax-*) + os=-ultrix4.2 + ;; + m68*-apollo) + os=-domain + ;; + i386-sun) + os=-sunos4.0.2 + ;; + m68000-sun) + os=-sunos3 + # This also exists in the configure program, but was not the + # default. + # os=-sunos4 + ;; + *-tti) # must be before sparc entry or we get the wrong os. + os=-sysv3 + ;; + sparc-* | *-sun) + os=-sunos4.1.1 + ;; + *-ibm) + os=-aix + ;; + *-hp) + os=-hpux + ;; + *-hitachi) + os=-hiux + ;; + i860-* | *-att | *-ncr | *-altos | *-motorola | *-convergent) + os=-sysv + ;; + *-cbm) + os=-amigados + ;; + *-dg) + os=-dgux + ;; + *-dolphin) + os=-sysv3 + ;; + m68k-ccur) + os=-rtu + ;; + m88k-omron*) + os=-luna + ;; + *-sequent) + os=-ptx + ;; + *-crds) + os=-unos + ;; + *-ns) + os=-genix + ;; + i370-*) + os=-mvs + ;; + *-next) + os=-nextstep3 + ;; + *-gould) + os=-sysv + ;; + *-highlevel) + os=-bsd + ;; + *-encore) + os=-bsd + ;; + *-sgi) + os=-irix + ;; + *-siemens) + os=-sysv4 + ;; + *-masscomp) + os=-rtu + ;; + *) + os=-none + ;; +esac +fi + +# Here we handle the case where we know the os, and the CPU type, but not the +# manufacturer. We pick the logical manufacturer. +vendor=unknown +case $basic_machine in + *-unknown) + case $os in + -riscix*) + vendor=acorn + ;; + -sunos*) + vendor=sun + ;; + -lynxos*) + vendor=lynx + ;; + -aix*) + vendor=ibm + ;; + -hpux*) + vendor=hp + ;; + -hiux*) + vendor=hitachi + ;; + -unos*) + vendor=crds + ;; + -dgux*) + vendor=dg + ;; + -luna*) + vendor=omron + ;; + -genix*) + vendor=ns + ;; + -mvs*) + vendor=ibm + ;; + -ptx*) + vendor=sequent + ;; + -vxworks*) + vendor=wrs + ;; + esac + basic_machine=`echo $basic_machine | sed "s/unknown/$vendor/"` + ;; +esac + +echo $basic_machine$os
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kpathsea/configure.in Fri Jul 19 01:57:38 1996 +0000 @@ -0,0 +1,45 @@ +dnl Process this file with autoconf to produce a configure script. +AC_INIT(pathsearch.c) + +AC_CANONICAL_HOST +if test -z "$host"; then + host=unknown +fi +target_host_type=$host +canonical_host_type=$host + +### Enable creation of shared libraries. Currently only works with +### gcc on some systems. + +AC_ARG_ENABLE(shared, + [ --shared create shared libraries (not all systems)], + [if test $enableval = no; then SHARED_LIBS=false; else SHARED_LIBS=true; fi], + SHARED_LIBS=false) +AC_SUBST(SHARED_LIBS) + +if $SHARED_LIBS; then + CPICFLAG=-fPIC + SHLEXT=so + case "$canonical_host_type" in + alpha-dec-osf*) + CPICFLAG= + ;; + rs6000-ibm-aix*) + CPICFLAG= + ;; + hppa*-hp-hpux*) + SHLEXT=sl + ;; + esac +else + CPICFLAG= + SHLEXT= +fi +AC_MSG_RESULT([defining CPICFLAG to be $CPICFLAG]) +AC_MSG_RESULT([defining SHLEXT to be $SHLEXT]) +AC_SUBST(CPICFLAG) +AC_SUBST(SHLEXT) + +sinclude(common.ac) + +AC_OUTPUT(Makefile)
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kpathsea/copying.texi Fri Jul 19 01:57:38 1996 +0000 @@ -0,0 +1,390 @@ +@node Copying +@appendix GNU GENERAL PUBLIC LICENSE +@center Version 2, June 1991 + +@display +Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. +59 Temple Place - Suite 330, Boston, MA 02111-1307, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@unnumberedsec Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software---to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed 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. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, 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 show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + +@iftex +@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end iftex +@ifinfo +@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end ifinfo + +@enumerate +@item +This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The ``Program'', below, +refers to any such program or work, and a ``work based on the Program'' +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term ``modification''.) Each licensee is addressed as ``you''. + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + +@item +You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + +@item +You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + +@enumerate a +@item +You must cause the modified files to carry prominent notices +stating that you changed the files and the date of any change. + +@item +You must cause any work that you distribute or publish, that in +whole or in part contains or is derived from the Program or any +part thereof, to be licensed as a whole at no charge to all third +parties under the terms of this License. + +@item +If the modified program normally reads commands interactively +when run, you must cause it, when started running for such +interactive use in the most ordinary way, to print or display an +announcement including an appropriate copyright notice and a +notice that there is no warranty (or else, saying that you provide +a warranty) and that users may redistribute the program under +these conditions, and telling the user how to view a copy of this +License. (Exception: if the Program itself is interactive but +does not normally print such an announcement, your work based on +the Program is not required to print an announcement.) +@end enumerate + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + +@item +You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + +@enumerate a +@item +Accompany it with the complete corresponding machine-readable +source code, which must be distributed under the terms of Sections +1 and 2 above on a medium customarily used for software interchange; or, + +@item +Accompany it with a written offer, valid for at least three +years, to give any third party, for a charge no more than your +cost of physically performing source distribution, a complete +machine-readable copy of the corresponding source code, to be +distributed under the terms of Sections 1 and 2 above on a medium +customarily used for software interchange; or, + +@item +Accompany it with the information you received as to the offer +to distribute corresponding source code. (This alternative is +allowed only for noncommercial distribution and only if you +received the program in object code or executable form with such +an offer, in accord with Subsection b above.) +@end enumerate + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + +@item +You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + +@item +You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + +@item +Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + +@item +If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + +@item +If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + +@item +The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and ``any +later version'', you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + +@item +If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + +@iftex +@heading NO WARRANTY +@end iftex +@ifinfo +@center NO WARRANTY +@end ifinfo + +@item +BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + +@item +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. +@end enumerate + +@iftex +@heading END OF TERMS AND CONDITIONS +@end iftex +@ifinfo +@center END OF TERMS AND CONDITIONS +@end ifinfo + +@page +@unnumberedsec Appendix: How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the ``copyright'' line and a pointer to where the full notice is found. + +@smallexample +@var{one line to give the program's name and a brief idea of what it does.} +Copyright (C) 19@var{yy} @var{name of author} + +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 of the License, 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., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +@end smallexample + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + +@smallexample +Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} +Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. +This is free software, and you are welcome to redistribute it +under certain conditions; type `show c' for details. +@end smallexample + +The hypothetical commands @samp{show w} and @samp{show c} should show +the appropriate parts of the General Public License. Of course, the +commands you use may be called something other than @samp{show w} and +@samp{show c}; they could even be mouse-clicks or menu items---whatever +suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a ``copyright disclaimer'' for the program, if +necessary. Here is a sample; alter the names: + +@example +Yoyodyne, Inc., hereby disclaims all copyright interest in the program +`Gnomovision' (which makes passes at compilers) written by James Hacker. + +@var{signature of Ty Coon}, 1 April 1989 +Ty Coon, President of Vice +@end example + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kpathsea/freedom.texi Fri Jul 19 01:57:38 1996 +0000 @@ -0,0 +1,268 @@ +@c Copyright (C) 1992 Karl Berry. +@c For copying conditions, see the file copying.texi. + +@node Freedom +@appendix Regain your programming freedom + +@cindex freedom, programming +Until a few years ago, programmers in the United States could write any +program they wished. This freedom has now been taken away by two +developments: software patents, which grant the patent holder an +absolute monopoly on some programming technique, and user interface +copyright, which forbid compatible implementations of an existing user +interface. + +In Europe, especially through the GATT treaty, things are rapidly +approaching the same pass. + +@menu +* Software patents:: Algorithm monopolies. +* User interface copyright:: Forbidding upward-compatibility. +* What to do?:: What to do? +@end menu + + +@node Software patents, User interface copyright, , Freedom +@section Software patents + +@cindex patents, software +@cindex software patents + +The U.S. Patent and Trademark Office has granted numerous software +patents on software techniques. Patents are an absolute +monopoly---independent reinvention is precluded. This monopoly lasts +for seventeen years, i.e., forever (with respect to computer science). + +One patent relevant to @TeX{} is patent 4,956,809, issued to the Mark +Williams company on September 11, 1990, applied for in 1982, which +covers (among other things) +@quotation +representing in a standardized order +consisting of a standard binary structure file stored on auxiliary +memory or transported on a communications means, said standardized +order being different from a different order used on at least one +of the different computers; + +Converting in each of the different computers binary data read from an +auxiliary data storage or communications means from the standardized +order to the natural order of the respective host computer after said +binary data are read from said auxiliary data storage or +communications means and before said binary data are used by the +respective host computer; and + +Converting in each of the different computers binary data written into +auxiliary data storage or communications means from the natural order +of the respective host computer to the standardized order prior to +said writing. +@end quotation + +@noindent @dots{} in other words, storing data on disk in +a machine-independent order, as the DVI, TFM, GF, and PK file formats +specify. Even though @TeX{} is ``prior art'' in this respect, the +patent was granted (the patent examiners not being computer scientists, +even less computer typographers). Since there is a strong presumption +in the courts of a patent's validity once it has been granted, there is +a good chance that users or implementors of @TeX{} could be successfully +sued on the issue. + +As another example, the X window system, which was intended to be able +to be used freely by everyone, is now being threatened by two patents: +4,197,590 on the use of exclusive-or to redraw cursors, held by Cadtrak, +a litigation company (this has been upheld twice in court); and +4,555,775, held by AT&T, on the use of backing store to redraw windows +quickly. + +Here is one excerpt from a recent mailing by the League for Programming +Freedom (@pxref{What to do?}) which I feel sums up the situation rather +well. It comes from an article in @cite{Think} magazine, issue #5, +1990. The comments after the quote were written by Richard Stallman. + +@quotation + ``You get value from patents in two ways,'' says Roger Smith, IBM + Assistant General Counsel, intellectual property law. ``Through fees, + and through licensing negotiations that give IBM access to other + patents. + + ``The IBM patent portfolio gains us the freedom to do what we need to + do through cross-licensing---it gives us access to the inventions of + others that are the key to rapid innovation. Access is far more + valuable to IBM than the fees it receives from its 9,000 active + patents. There's no direct calculation of this value, but it's many + times larger than the fee income, perhaps an order of magnitude + larger.'' +@end quotation + +This information should dispel the belief that the patent system will +``protect'' a small software developer from competition from IBM. IBM +can always find patents in its collection which the small developer is +infringing, and thus obtain a cross-license. + +However, the patent system does cause trouble for the smaller +companies which, like IBM, need access to patented techniques in order +to do useful work in software. Unlike IBM, the smaller companies do +not have 9,000 patents and cannot usually get a cross-license. No +matter how hard they try, they cannot have enough patents to do this. + +Only the elimination of patents from the software field can enable +most software developers to continue with their work. + +The value IBM gets from cross-licensing is a measure of the amount of +harm that the patent system would do to IBM if IBM could not avoid it. +IBM's estimate is that the trouble could easily be ten times the good +one can expect from one's own patents---even for a company with 9,000 +of them. + + +@node User interface copyright, What to do?, Software patents, Freedom +@section User interface copyright + +@cindex rms +@cindex user interface copyright +@cindex interface copyright +(This section is copied from the GCC manual, by Richard Stallman.) + +@quotation +@i{This section is a political message from the League for Programming +Freedom to the users of the GNU font utilities. It is included here as +an expression of support for the League on my part.} +@end quotation + +Apple, Lotus and Xerox are trying to create a new form of +legal monopoly: a copyright on a class of user interfaces. These +monopolies would cause serious problems for users and developers of +computer software and systems. + +Until a few years ago, the law seemed clear: no one could restrict +others from using a user interface; programmers were free to implement +any interface they chose. Imitating interfaces, sometimes with changes, +was standard practice in the computer field. The interfaces we know +evolved gradually in this way; for example, the Macintosh user interface +drew ideas from the Xerox interface, which in turn drew on work done at +Stanford and SRI. 1-2-3 imitated VisiCalc, and dBase imitated a +database program from JPL. + +Most computer companies, and nearly all computer users, were happy with +this state of affairs. The companies that are suing say it does not +offer ``enough incentive'' to develop their products, but they must have +considered it ``enough'' when they made their decision to do so. It +seems they are not satisfied with the opportunity to continue to compete +in the marketplace---not even with a head start. + +If Xerox, Lotus, and Apple are permitted to make law through +the courts, the precedent will hobble the software industry: + +@itemize @bullet +@item +Gratuitous incompatibilities will burden users. Imagine if each +car manufacturer had to arrange the pedals in a different order. + +@item +Software will become and remain more expensive. Users will be +``locked in'' to proprietary interfaces, for which there is no real +competition. + +@item +Large companies have an unfair advantage wherever lawsuits become +commonplace. Since they can easily afford to sue, they can intimidate +small companies with threats even when they don't really have a case. + +@item +User interface improvements will come slower, since incremental +evolution through creative imitation will no longer be permitted. + +@item +Even Apple, etc., will find it harder to make improvements if +they can no longer adapt the good ideas that others introduce, for +fear of weakening their own legal positions. Some users suggest that +this stagnation may already have started. + +@item +If you use GNU software, you might find it of some concern that user +interface copyright will make it hard for the Free Software Foundation +to develop programs compatible with the interfaces that you already +know. +@end itemize + + +@node What to do?, , User interface copyright, Freedom +@section What to do? + +(This section is copied from the GCC manual, by Richard Stallman.) + +To protect our freedom from lawsuits like these, a group of programmers +and users have formed a new grass-roots political organization, the +League for Programming Freedom. + +The purpose of the League is to oppose new monopolistic practices such +as user-interface copyright and software patents; it calls for a return +to the legal policies of the recent past, in which these practices were +not allowed. The League is not concerned with free software as an +issue, and not affiliated with the Free Software Foundation. + +The League's membership rolls include John McCarthy, inventor of Lisp, +Marvin Minsky, founder of the Artificial Intelligence lab, Guy L. +Steele, Jr., author of well-known books on Lisp and C, as well as +Richard Stallman, the developer of GNU CC. Please join and add your +name to the list. Membership dues in the League are $42 per year for +programmers, managers and professionals; $10.50 for students; $21 for +others. + +The League needs both activist members and members who only pay their +dues. + +To join, or for more information, phone (617) 492-0023 or write to: + +@display +League for Programming Freedom +1 Kendall Square #143 +P.O. Box 9171 +Boston, MA 02111-1307 +@end display + +You can also send electronic mail to @code{league@@prep.ai.mit.edu}. + +Here are some suggestions from the League for things you can do to +protect your freedom to write programs: + +@itemize @bullet +@item +Don't buy from Xerox, Lotus or Apple. Buy from their competitors or +from the defendants they are suing. + +@item +Don't develop software to work with the systems made by these companies. + +@item +Port your existing software to competing systems, so that you encourage +users to switch. + +@item +Write letters to company presidents to let them know their conduct +is unacceptable. + +@item +Tell your friends and colleagues about this issue and how it threatens +to ruin the computer industry. + +@item +Above all, don't work for the look-and-feel plaintiffs, and don't +accept contracts from them. + +@item +Write to Congress to explain the importance of this issue. + +@display +House Subcommittee on Intellectual Property +2137 Rayburn Bldg +Washington, DC 20515 + +Senate Subcommittee on Patents, Trademarks and Copyrights +United States Senate +Washington, DC 20510 +@end display + +(These committees have received lots of mail already; let's give them +even more.) +@end itemize + +Express your opinion! You can make a difference.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kpathsea/install.texi Fri Jul 19 01:57:38 1996 +0000 @@ -0,0 +1,67 @@ +@c install.texi -- this file is the installation items common to +@c kpathsea-using programs. It's included by kpathsea.texi and dvips.texi. + +@item +@vindex CFLAGS +@flindex paths.make@r{, editing} +Edit the file @file{make/paths.make} if you want to make changes to the +installation directories or paths that will have effect across different +runs of @code{configure}. Alternatively, override the Make variables on +the command line when you run Make. + +@cindex installation directories, changing +Exception: to reliably change the top-level @samp{prefix}, you must give +@samp{configure} the option @samp{-prefix=@var{prefix}}, instead of +changing the value in @file{paths.make}. + +@item +@cindex paths, changing default +Edit @file{kpathsea/texmf.cnf.in} to change the local paths to match your +local setup. @xref{Default paths, , , kpathsea, Kpathsea}, for more +details on changing the paths. A copy is in @file{kpathsea/INSTALL}. +See @file{kpathsea/HIER} for an explanation of the default setup. + +If the paths do not match where the files actually are, the programs +will probably start up Very, Very, Slowly, and/or not be able to find +the fonts or other input files. + +@item +@flindex configure@r{, running} +@flindex CONFIG +@flindex kpathsea/CONFIG +@flindex c-auto.h.in +@flindex Makefile.in +@findex ac_include +@cindex @@@var{var}@@ substitutions +@cindex system dependencies +@code{sh configure} (in the top-level directory). This makes +system-dependent @samp{#define's} in @file{*/c-auto.h} (from the +corresponding @file{c-auto.h.in}) and creates a @file{Makefile} (from +the corresponding @file{Makefile.in}, by doing @samp{@@@var{var}@@} and +@samp{ac_include} substitutions). + +Perhaps the most common desire is to compile with optimization instead +of or as well as debugging. You can change the options passed to the +compiler by changing @samp{CFLAGS}, either for @code{configure} or +@code{make}. For example: + +@example +prompt$ env CFLAGS="-g -O" configure +prompt$ make +@exdent @r{or} +prompt$ configure +prompt$ make CFLAGS="-g -O" +@end example + +@noindent @xref{Invoking configure, , Running @code{configure} scripts, +autoconf, Autoconf}, for detailed @code{configure} options. (A copy is +in @file{kpathsea/CONFIGURE}.) + +@item +@code{make} (still in the top-level directory). Barring configuration +and compiler bugs, this will compile all the programs. @xref{Common +problems, , Common problems, kpathsea, Kpathsea}, for system-dependent +problems (this section is also in @file{kpathsea/INSTALL}). + +This also creates the @file{texmf.cnf} and @file{paths.h} files that +define the default search paths.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kpathsea/kpathsea.texi Fri Jul 19 01:57:38 1996 +0000 @@ -0,0 +1,2088 @@ +\input texinfo +@setfilename kpathsea.info +@settitle Kpathsea: A library for path searching + +@set version 2.6 +@set month-year January 1995 + +@c Define new indices for commands, filenames, and options. +@defcodeindex cm +@defcodeindex fl +@defcodeindex op + +@c Put everything in one index (arbitrarily chosen to be the concept index). +@syncodeindex cm cp +@syncodeindex fl cp +@syncodeindex fn cp +@syncodeindex ky cp +@syncodeindex op cp +@syncodeindex pg cp +@syncodeindex tp cp +@syncodeindex vr cp + +@ifinfo +@format +START-INFO-DIR-ENTRY +* Kpathsea: (kpathsea). File lookup along search paths. +END-INFO-DIR-ENTRY +@end format + +This file documents the Kpathsea library for path searching. + +Copyright (C) 1993, 94, 95 Karl Berry. + +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 ``Freedom'' 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 the sections entitled ``Freedom'' and ``GNU General Public +License'' may be included in a translation approved by the Free Software +Foundation instead of in the original English. +@end ifinfo + + +@titlepage + +@title Kpathsea library +@subtitle for version @value{version} +@subtitle @value{month-year} +@author Karl Berry + +@page + +@vskip 0pt plus 1filll +Copyright @copyright{} 1993, 94 Karl Berry. + +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 ``Regain your programming freedom'' 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 the sections entitled ``Regain your programming freedom'' +and ``GNU General Public License'' may be included in a translation +approved by the Free Software Foundation instead of in the original English. + +@end titlepage + + +@ifinfo +@node Top +@top Kpathsea library + +This manual documents how to install and use the Kpathsea library for +filename lookup. It corresponds to version @value{version} +(released in @value{month-year}). + +@menu +* Introduction:: Overview. +* Installation:: Compilation, installation, and bug reporting. +* Debugging:: Analyzing runtime problems. + +* Path searching:: How filename lookups work. +* TeX searching:: Special support for TeX lookups. + +* TeX directory structure:: Ways to manage the many input files. + +* Programming:: How to use the library in your program. + +* Copying:: Conditions for copying, modifying and sharing. +* Freedom:: Regain your programming freedom. +* Index:: General index. +@end menu +@end ifinfo + + +@node Introduction +@chapter Introduction + +@cindex introduction +@cindex fundamental purpose + +This manual corresponds to version @value{version} of the Kpathsea +library, released in @value{month-year}. + +The library's fundamental purpose is to look up a file in a list of +directories specified by the user, similar to what shells do when +looking up program names to execute. + +@cindex programs using the library +The following software, all of which I maintain, uses this library: + +@itemize @bullet +@item Dviljk +@item Dvipsk (@pxref{Top, , Introduction, dvipsk, Dvips: A DVI driver}) +@item GNU font utilities (@pxref{Top, , Introduction, fontu, GNU font +utilities}) +@item Web2c (@pxref{Top, , Introduction, web2c, Web2c: A @TeX{} +implementation}) +@item Xdvik +@end itemize + +@cindex interface, not frozen +The library is still under development (and probably always will be, +despite my hopes). I do not promise to keep the interface unchanged. If +you have comments or suggestions, please send them to me +(@pxref{Reporting bugs}). + +@cindex conditions for use +@cindex license for using the library +@cindex GNU General Public License +Currently, I distribute the library under the GNU General Public License +(@pxref{Copying}). In short, this means if you write a program using +the library, you must (offer to) distribute the source, and allow anyone +to modify the source and distribute their modifications. + +@cindex GNU Library General Public License +If you have a problem with this, contact me. I would consider putting +the library under the GNU Library General Public License, which would +permit you to distribute the source only to the library, not to your +program using it. But I will only do this if someone actually says they +will not use the library under the GPL conditions, and would use it +under the LGPL. + +@cindex @TeX{} Users Group +If you know enough about @TeX{} to be reading this manual, then you (or +perhaps your institution) should consider joining the @TeX{} Users Group +(if you're already a member, great!). TUG produces a periodical called +@cite{TUGboat}, sponsors an annual meeting (the proceedings of which are +published in @cite{TUGboat}), and arranges courses on @TeX{} for all levels +of users. Given sufficient funding (which your joining will help) TUG +could sponsor more projects that will benefit the @TeX{} community, such as +a successor to @TeX{} +@iftex +$\pi$ +@end iftex +@ifinfo +pi +@end ifinfo +. Anyway, here is the address: + +@flindex tug@@tug.org +@display +@TeX{} Users Group +P.O. Box 869 +Santa Barbara, CA 93102 USA +phone: (805) 899-4673 +email: @samp{tug@@tug.org} +@end display + +@menu +* History:: +@end menu + +@node History +@section History + +@cindex history of Kpathsea + +@cindex Knuth, Donald E. +(This section is for those people who are curious about how this came about.) +(If you like to read historical accounts of software, I urge you to seek +out the GNU Autoconf manual and, even more fun, the ``Errors of +@TeX{}'' paper that Don Knuth published in @cite{Software---Practice and +Experience}.) + +@cindex Morgan, Tim +@cindex Rokicki, Tom +My first ChangeLog entry for Web2c seems to be February 1990, but I may +have done some stuff before then. In any case, Tim Morgan and I were +sort of jointly maintaining it for a time. (I should say that Tim had +made Web2c into a real distribution long before I had ever used it or +even heard of it, and Tom Rokicki did the original implementation.) + +It must have been later in 1990 and 1991 that I started working on +@cite{TeX for the Impatient} and Dvips, Xdvi, Web2c, and the GNU +fontutils (which I was also writing at the time) using different +environment variables, and, even more importantly, having different bugs +in their path searching became extremely painful. I also desperately +wanted to implement subdirectory searching, since I couldn't stand +putting everything in one big directory, and also couldn't stand having +to explicitly specify @file{pandora}, @file{cm} in a path. + +@cindex Vojta, Paul +In the first incarnation, I just hacked separately on each program--- +that was the original subdirectory searching code in both Xdvi and +Dvips, though I think Paul Vojta has completely rewritten Xdvi's support +by now. That is, I tried to go with the flow in each program, rather +than changing the program's calling sequences to conform to common +routines. + +Then, as bugs inevitably appeared, I found I was fixing the same thing +in each of three (Web2c and fontutils were always sharing code, since I +maintained those---there was no Dvipsk or Xdvik or Dviljk at this +point). After a while, I finally started sharing source files. They +weren't a library, though. I just kept things up to date with shell +scripts. (I was developing on a 386 running ISC 2.2 at the time, and so +didn't have symbolic links. An awful experience.) + +Things kept on like this for quite a while. The @file{ChangeLog}s for +Xdvik and Dvipsk record initial releases of those distributions in May +and June 1992. I think it was because I was tired of the different +configuration strategies of each program, not so much because of the +path searching. (Autoconf was being developed by David MacKenzie and +others, and I was adapting it to @TeX{} and friends.) + +@cindex zuhn, david +I starting to make it a separate library that other programs could link +with on my birthday in April 1993, according to the ChangeLog. I don't +remember exactly why I finally took the time to make it a separate +library; I think it was a conversation with david zuhn that led to doing +it. Just seemed like it was time. + +@cindex Walsh, Norman +@cindex Neumann, Gustaf +Dviljk got started in March 1994 after I bought a Laserjet 4. (Kpathsea +work got suspended while Norm Walsh and I, with Gustaf Neumann's help, +implemented a way for @TeX{} to get at all those neat builtin LJ4 fonts +... such a treat to have something to typeset in besides Palatino!) + +At this point (October 1994), I've implemented just about all the +path-searching features in Kpathsea that I ever intended to (and some I +didn't intend @dots{}). After the next stable release of Web2c, I figure +I'll be able to stop development, and turn most of my attention back to +making fonts for GNU. (Always assuming Microsoft hasn't completely +obliterated Unix by then, or that software patents haven't stopped +software development by anybody smaller than a company with a +million-dollar-a-year legal budget. Which is actually what I think is +likely to happen, but that's another story@dots{}) + + +@node Installation +@chapter Installation + +@cindex installation +@cindex configuration +@cindex compilation + +Here are the basic steps for configuration and installation: + +@enumerate + +@include install.texi + +@item +@code{make install}. This installs the library, header files, and +documentation. Or @code{make install-data} to just install the +architecture-independent files. Or @code{make install-exec} to just +install the (binary) archive library file. + +Since I only distribute Kpathsea as part of another package, you will +probably be doing the above in a top-level directory that contains a +@samp{Makefile}, @samp{kpathsea}, and the other package. But you can do +the installation in @samp{kpathsea} itself, if you only want to install +the library, not the other package. + +@item +The first time you install any manual in Info, you have to add a line +(you choose where) to the @file{dir} file in your @samp{$(infodir)} +directory. A sample line to add is given near the top of the Texinfo +source files (@file{kpathsea/kpathsea.texi} and +@file{dvipsk/dvips.texi}). + +@item +@code{make distclean}. This removes all files created by the build. + +@end enumerate + +@xref{Filename database}, for a description of an externally-generated +database that can help speed searches. + +@xref{Debugging}, for runtime debugging support that may help track down +problems. + +Do not attempt to use any version of Kpathsea with any program except +the version that the program came with, unless you are a glutton for +punishment. + +@menu +* Default paths:: Changing default installation directories and paths. +* Common problems:: When things go wrong. +* Shared library:: Making Kpathsea a shared library. +* Reporting bugs:: Where and how to report bugs. +@end menu + + +@node Default paths +@section Default paths + +@cindex default paths, changing +@cindex paths, changing default +@cindex installation directories, changing default +@cindex directories, changing default installation + +@cindex default paths, how they're made +To summarize the chain of events that go into defining the default paths: + +@enumerate + +@item +@samp{configure} creates a @file{Makefile} from each @file{Makefile.in}. + +@item +@flindex texmf.sed +When Make runs in the @file{kpathsea} directory, it creates +a file @file{texmf.sed} that substitutes the Make value of @code{$(var)} +for a string @code{@@var@@}. The variables in question are the one that +define the installation directories. + +@item +@flindex texmf.cnf.in +@flindex texmf.cnf@r{, generated} +@file{texmf.sed} (and a little extra magic---see +@file{kpathsea/Makefile}) is applied to @file{texmf.cnf.in} to generate +@file{texmf.cnf}. This is the file that will eventually be installed and +used by the programs to look up programs. + +@item +@flindex paths.h +The definitions in @file{texmf.cnf} are changed into the form of C +@samp{#define}'s, producing @file{paths.h}. These values will be the +compile-time defaults; they are not used unless no @file{texmf.cnf} file +can be found at runtime. + +(That's a partial lie: the compile-time defaults are what extra +@samp{:}'s in @file{texmf.cnf} expand into; but the paths as distributed +have no extra @samp{:}'s, and there's no particular reason for them to.) + +@end enumerate + +The purpose of this elaborate sequence is to avoid having the same +information in more than one place. If you change the installation +directories or top-level prefix before running @samp{configure}, those +changes will propagate through the whole sequence. If you change the +default paths in @file{texmf.cnf.in}, those changes are propagated to +the compile-time defaults. + +Alternatively, you can ignore the whole mess and edit @file{texmf.cnf} +after it is installed. Maybe even copying it into place beforehand so +you can complete the installation, if @TeX{} or Metafont is having +trouble finding their input files. + +@vindex prefix@r{, changing} +@vindex exec_prefix@r{, changing} +Unfortunately, editing @file{Makefile.in} @emph{does not work} in one +common case---changing the @code{prefix} or @code{exec_prefix} +variables. For these, you must use the @samp{-prefix} or +@samp{-exec-prefix} options to @code{configure}. @xref{Running +configure Scripts, , Running @code{configure} scripts, autoconf, +Autoconf}. (That's another partial lie: editing does work, as long as a +program named @code{tex} is not in your @code{PATH}.) + +@flindex HIER +@flindex kpathsea/HIER +@xref{TeX directory structure, @TeX{} directory structure}, for a +description of some ways to arrange the @TeX{} library files, and some +features of the distributed paths that may not be obvious. The file +@file{kpathsea/HIER} is a copy of that section. + +The Make definitions are all repeated in several @file{Makefile}'s; but +changing the top-level @file{Makefile} should suffice, as it passes down +all the variable definitions, thus overriding the submakes. (The +definitions are repeated so you can potentially run Make in the +subdirectories.) + + +@node Common problems +@section Common problems + +Some common problems with compilation, linking, or execution are +described below. + +@menu +* Unable to find files:: If your program can't find fonts or anything else. +* Slow path searching:: If it takes forever to find anything. + +* XtInherit:: For XtInherit link problems on OSF/1 1.x. +* wchar_t:: For wchar_t difficulties. +* ShellWidgetClass:: For dynamic linking with Sun's openwin libraries. +* Pointer combination warnings:: For old compilers that don't grok char *. +@end menu + + +@node Unable to find files +@subsection Unable to find files + +@cindex unable to find files +@cindex files, unable to find + +If a program complains it cannot find fonts (or other input files), +any of several things might be wrong: + +@itemize @bullet + +@item +You don't have the fonts (or whatever) installed. Nothing will +automatically generate TFM files or @TeX{} and Metafont sources for you +(by default). @xref{Obtaining Web2c, , , web2c, Web2c}. + +You can, however, configure @TeX{} and Metafont to run a script to +generate these input files, if you have (or write) such +scripts. @xref{MakeTeX... invocation, , @samp{MakeTeX}@dots{} +invocation, web2c, Web2c}. + +@item +You have (perhaps unknowingly) told Kpathsea to use search paths that +don't reflect where the files actually are. One common cause is having +environment variables set, thus overriding what you carefully set in +@file{texmf.cnf}. @xref{TeX environment variables, @TeX{} environment +variables}. + +@item +@cindex symbolic links not found +@cindex leaf directories wrongly guessed +Your files reside in a directory that is only pointed to via a symbolic +link, in a leaf directory. + +Unfortunately, Kpathsea's subdirectory searching has a (congenital) +deficiency: If a directory @var{d} being searched for subdirectories +contains plain files and symbolic links to other directories, but no +true subdirectories, @var{d} will be considered a leaf directory, i.e., +the symbolic links will not be followed. @xref{Subdirectory expansion}, +for an explanation of why this happens. + +You can work around this problem by creating an empty dummy subdirectory +in @var{d}. Then @var{d} will no longer be a leaf, and the symlinks will +be followed. + +The directory immediately followed by the @samp{//} in the path +specification, however, is always searched for subdirectories, even if +it is a leaf. This is since presumably you would not have asked for the +directory to be searched for subdirectories if you didn't want it to be. + +@item +There is a bug in the library. @xref{Reporting bugs}. + +@end itemize + +In any case, you may find the debugging options helpful in determining +precisely where the fonts (or whatever) are being looked for. See the +program's documentation for its debugging options, and also +@pxref{Debugging}. + + +@node Slow path searching +@subsection Slow path searching + +@cindex excessive startup time +@cindex slow startup time +@cindex startup time, excessive + +If your program takes an excessively long time to find fonts or other +input files, but does eventually succeed, here are some possible culprits: + +@itemize @bullet + +@item +Most likely, you just have a lot of directories to search, and that +takes a noticeable time. The solution is to create and maintain a +separate @file{ls-R} file that lists all the files in your main @TeX{} +hierarchy. @xref{Filename database}. (Kpathsea always uses @file{ls-R} +if it's present; there's no need to recompile or reinstall any of the +programs.) + +@item +Your recursively-searched directories (e.g., +@file{/usr/local/lib/tex/fonts//}), contain a mixture of files and +directories. This prevents Kpathsea from using a useful optimization +(@pxref{Subdirectory expansion}). + +It is best to have only directories (and perhaps a @file{README}) in the +upper levels of the directory structure, and it's very important to have +@emph{only} files, and no subdirectories, in the directories where the +dozens of TFM, PK, or whatever files reside. + +@item +@cindex recursion from @file{/} +@cindex @samp{~} searching caveat +@cindex @samp{$HOME} searching caveat +@cindex @samp{root} searching peculiarities +Finally, one simple-to-fix (but unlikely) cause: If you recursively +search @samp{$HOME} or @samp{~}, and you are running as @samp{root}, you +will search every directory on the system. This typically takes quite +some time! + +@end itemize + +In any case, you may find the debugging options helpful in determining +precisely when the disk or network is being pounded. @xref{Debugging}, +and also see the program's documentation. + + +@node XtInherit +@subsection @code{XtInherit} + +@findex XtInherit @r{bug on OSF/1} +@cindex OSF/1 loader bug and @code{XtInherit} +@cindex Alpha OSF/1 loader bug and @code{XtInherit} + +On DEC OSF/1 1.x systems, the loader has a bug that manifests itself in +the following error (all on one line, but for the sake of the paper +width it's broken here): + +@example +xdvik/xdvi: /sbin/loader: Fatal Error: search_for_undefineds: + symbol _XtInherit should not have any relocation entry +@end example + +@noindent According to Michael Rickabaugh @samp{<mjr@@quarry.enet.dec.com>}: + +@display +This is a bug fixed in DEC OSF/1 2.0. + +If you know how, installing @file{/sbin/loader} from a 2.0 system onto a +1.3 system will work. Make sure that @file{/usr} is @emph{not} mounted +when you do this. (If you forget about umounting @code{/usr}, it is +possible most of your filesystems will become corrupted.) + +Otherwise, I suggest getting a hold of a 2.0 CD and running +@file{/usr/sbin/installupdate}. +@end display + +Alternatively, you may be able to use the freely available X11 libraries +that come with the MIT distribution (on @file{ftp.x.org}, for example). + +Linking statically, perhaps only with some of the X libraries, may also +work. (if you find the definitive workaround, please let me know.) + + +@node wchar_t +@subsection @code{wchar_t} + +@vindex FOIL_X_WCHAR_T +@tindex wchar_t + +The upshot of all the following is that if you get error messages +regarding @code{wchar_t}, try defining @code{NO_FOIL_X_WCHAR_T} (for +Web2c) or @code{FOIL_X_WCHAR_T} (for everything else). + +@code{wchar_t} has caused infinite trouble. None of my code ever uses +@code{wchar_t}; all I want to do is include X header files and various +system header files, possibly compiling with GCC. This seems an +impossible task! + +@flindex Xlib.h +The X11 header @file{<Xlib.h>} and GCC's @file{<stddef.h>} have +conflicting definitions for wchar_t. + +The particulars: @file{<X11/Xlib.h>} from MIT X11R5 defines +@code{wchar_t} if @code{X_WCHAR} is defined, which is defined if +@code{X_NOT_STDC_ENV} is defined, and we define @emph{that} if +@code{STDC_HEADERS} is not defined (@samp{configure} decides if +STDC_HEADERS gets defined). But when compiling with gcc on SunOS 4.1.x, +@code{STDC_HEADERS} is not defined (@file{string.h} doesn't declare the +@samp{mem}* functions), so we do get X's @code{wchar_t}---and we also +get gcc's @code{wchar_t} from its @file{<stddef.h>}. Conflict. + +On the other hand, SunOS 4.1.1 with some other X configurations actually +needs GCC to define @code{wchar_t}, and fails otherwise. + +My current theory is to define @code{wchar_t} to a nonsense symbol +before the X include files are read; that way its definition (if any) +will be ignored by other system include files. Going along with that, +define @code{X_WCHAR} to tell X not to use @file{<stddef.h>}, that we've +already included, but instead to make its own definition. + +But this is not the end of the story. The X11 include files distributed +with DG/UX 5.4.2 for the Aviion have been modified to include +@file{<_int_wchar_t.h>} if @code{X_WCHAR}, so our @code{#define} will +not have any typedef to change---but the uses of @code{wchar_t} in the X +include files will be changed to reference this undefined symbol. So +there's nothing to foil in this case. I don't know how to detect this +automatically, so it's up to you to define @code{NO_FOIL_X_WCHAR_T} +yourself. + + +@node ShellWidgetClass +@subsection @code{ShellWidgetClass} + +@cindex dynamic linking problems with openwin libraries +@cindex openwin libraries, dynamic linking problems +@findex get_wmShellWidgetClass +@findex get_applicationShellWidgetClass + +@flindex comp.sys.sun.admin @r{FAQ} +@cindex FAQ, @samp{comp.sys.sun.admin} +This section is adapted from question 47 from the +@samp{comp.sys.sun.admin} FAQ. + +If you are linking with Sun's OpenWindows libraries in SunOS 4.1.x, you +may get undefined symbols @code{_get_wmShellWidgetClass} and +@code{_get_applicationShellWidgetClass}. This problem does not arise +with the standard MIT libraries under SunOS. + +@findex Xmu @r{library problems} +The cause is bugs in the @code{Xmu} shared library as shipped from Sun. +There are several fixes: + +@itemize @bullet + +@item Get the Openwindows patches that apply to this problem. + +@item Statically link the @code{Xmu} library into the executable. + +@item Avoid using @code{Xmu} at all. For this last, if you are compiling +Metafont, @pxref{Online Metafont graphics, , , Web2c, web2c}. If you are +compiling Xdvi, see the @code{-DNOTOOL} option in @file{xdvik/INSTALL}. + +@item Ignore the errors. The binary runs fine regardless. + +@end itemize + +@cindex Sun openwin patches +Here is the information for getting the two patches: + +@display +Patch ID: 100512-02 +Bug ID's: 1086793, 1086912, 1074766 +Description: 4.1.x OpenWindows 3.0 @code{libXt} jumbo patch + +Patch ID: 100573-03 +Bug ID: 1087332 +Description: 4.1.x OpenWindows 3.0 undefined symbols when using shared +@code{libXmu}. +@end display + +@cindex static linking +The way to statically link with @code{libXmu} depends on whether you are +using a Sun compiler (e.g., @code{cc}) or @code{gcc}. If the format, +alter the @code{x_libs} make variable to include + +@example +-Bstatic -lXmu -Bdynamic +@end example + +@opindex -static +If you are using @code{gcc}, include @samp{-static} in @samp{LDFLAGS}; +this will link all libraries statically. If you want to link only +@code{Xmu} statically and everything else dynamically, you have to do it +by hand: run @code{gcc -v}, grab the @code{ld} line, and add the +@samp{-B}'s given above around @code{-lXmu}. + +The reason is that gcc moves all linker options to the front of the +@code{ld} command line. So you can't specify different options for +different libraries. When I reported this to the GCC maintainers, the +reply was that they would happily merge in the changes, but they didn't +want to take the time to do it themselves. + + +@node Pointer combination warnings +@subsection Pointer combination warnings + +@cindex warnings, pointer combinations +@cindex pointer combination warnings +@cindex illegal pointer combination warnings +@pindex cc @r{warnings} +When compiling with old C compilers, you may get some warnings about +``illegal pointer combinations''. These are spurious; just ignore them. +I decline to clutter up the source with casts to get rid of them. + +In general, if you have trouble with a system C compiler, I advise +trying the GNU C compiler. (And vice versa, unfortunately; but in that +case I also recommend reporting a bug to the GCC bug list.) + + +@node Shared library +@section Shared library + +@cindex shared library, making +You can compile Kpathsea as a shared library. The advantage in doing +this is that the different executables can then share the code, +decreasing memory usage. (The other advantage in general of shared +libraries is that it's possible to update the library and programs +independently. But since the Kpathsea interface is not and can not be +frozen, that doesn't apply here.) + +Under Solaris, use @samp{-K pic -xstrconst} if you compile with a Sun +compiler, @samp{-fpic} if you use GCC. Also add @samp{-L@var{$(libdir)} +-R@var{$(libdir)}} to @samp{LDFLAGS} when you link the binaries, so that +the library can be found, and users do not have set @samp{LD_LIBRARY_PATH}. + +(If you know how to make Kpathsea shared on other systems, please send a +message to the bug address in the next section.) + + +@node Reporting bugs +@section Reporting bugs + +@cindex reporting bugs +@cindex bugs, reporting + +@flindex tex-k@@cs.umb.edu @r{(bug address)} +@cindex bug address +If you encounter problems, please report them to @samp{tex-k@@cs.umb.edu}. +Include the version number of the library, the system you are using, and +enough information to reproduce the bug in your report. To get on this +mailing list yourself, email @samp{tex-k-request@@cs.umb.edu} with a +message whose body contains a line +@example +subscribe @var{you}@@@var{your.preferred.address} +@end example + +To avoid wasted effort and time (both mine and yours), I strongly advise +applying the principles given in the GNU C manual (@pxref{Bugs, , +Reporting Bugs, gcc, The GNU CC manual}) to your bug reports. + +Please also report bugs in this documentation---not only factual errors, +but unclear explanations, typos, wrong fonts, @dots{} + + +@node Debugging +@chapter Debugging + +@cindex debugging +@cindex runtime debugging +@cindex options for debugging + +@vindex kpathsea_debug +@flindex debug.h +Kpathsea provides a number of runtime debugging options, detailed below +by their names (and corresponding numeric values). You can set these +with some runtime argument (e.g., @samp{-d}) to the program; in that +case, you should use the numeric values described in the program's +documentation (which, except for Dviljk, are different from those +below). + +@vindex KPATHSEA_DEBUG +You can also set the environment variable @code{KPATHSEA_DEBUG}. In +this case, you should use the numbers below. Also use the numbers below +if you run the program under a debugger and set the the variable +@samp{kpathsea_debug} yourself. + +In any case, you can @emph{not} use the @emph{names} below; you must +always use somebody's numbers. (Sorry.) And to set more than option, +just sum the corresponding numbers. + +@vtable @code + +@item KPSE_DEBUG_STAT +(1). Reports @samp{stat}(2) calls. This is useful for verifying that +your directory structure is not forcing Kpathsea to do many additional +file tests (@pxref{Slow path searching} and @pxref{Subdirectory +expansion}). If you are using an up-to-date @file{ls-R} database +(@pxref{Filename database}), this should produce no output unless a +nonexistent file is searched for. + +@item KPSE_DEBUG_HASH +(2). Reports lookups in all hash tables, including @file{ls-R} +(@pxref{Filename database}), font aliases (@pxref{Fontmap}), and config +file values (@pxref{Config files}). Useful when expected values are not +being found, e.g.., file searches are looking at the disk instead of +using @file{ls-R}. + +@item KPSE_DEBUG_FOPEN +(4). Reports file openings and closings. Especially useful when your +system's file table is full, for seeing if some files have been opened +but never closed. In case you want to set breakpoints: this works by +redefining @samp{fopen} (@samp{fclose}) to be @samp{kpse_fopen_trace} +(@samp{kpse_fclose_trace}). + +@item KPSE_DEBUG_PATHS +(8). Reports general path information for each file type Kpathsea is +asked to search. This is useful when you are trying to track down how a +particular path got defined---from @file{texmf.cnf}, @file{config.ps}, +the compile-time default, an environment variable, etc. This is the +contents of a structure defined in @file{tex-file.h}. + +@item KPSE_DEBUG_EXPAND +(16). Reports the directory list corresponding to each path element +Kpathsea searches in. This is only relevant when Kpathsea is searching +the disk, since @file{ls-R} searches don't look through directory lists +in this way (they go straight to the file using the hash table). + +@item KPSE_DEBUG_SEARCH +(32). Reports on each file search Kpathsea attempts: the name of the +file searched for, the path searched in, whether or not the file must +exist (when drivers search for @file{cmr10.vf}, it need not exist), and +whether or not we are collecting all occurrences of the file in the +path (as with, e.g., @file{texmf.cnf} and @file{texfonts.map}), or just +the first (as with most lookups). This can help you correlate what +Kpathsea is doing with what is in your input file. + +@end vtable + +@cindex @samp{kdebug:} +Debugging output from Kpathsea is always written to standard error, and +begins with @samp{kdebug:}. (Except for hash table buckets, which just +start with the number.) + +@menu +* Logging:: Recording successful searches. +@end menu + + +@node Logging +@section Logging + +@cindex log file + +@cindex recording successful searches +Kpathsea can record the time and filename found for each successful +search. This may be useful in finding good candidates for deletion when +your disk is full. + +@vindex TEXMFLOG +To do this, define the environment or config file variable +@code{TEXMFLOG}. The value is the name of the file to append the +information to. The file is created if it doesn't exist. + +@cindex epoch +@findex time +Each successful search turns into one line in the log file, with two +words separated by a space. The first word is the time of the search, as +the integer number of seconds since ``the epoch'', i.e., UTC midnight 1 +January 1970 (more precisely, the result of the @code{time} system +call). The second word is the filename. + +For example, after @code{setenv TEXMFLOG /tmp/log}, running Dvips on +@file{story.dvi} appends the following lines: + +@example +774455887 /usr/local/lib/texmf/dvips/config.ps +774455887 /usr/local/lib/texmf/dvips/psfonts.map +774455888 /usr/local/lib/texmf/dvips/texc.pro +774455888 /usr/local/lib/texmf/fonts/public/cm/pk/ljfour/cmbx10.600pk +774455889 /usr/local/lib/texmf/fonts/public/cm/pk/ljfour/cmsl10.600pk +774455889 /usr/local/lib/texmf/fonts/public/cm/pk/ljfour/cmr10.600pk +774455889 /usr/local/lib/texmf/dvips/texc.pro +@end example + +@noindent Only filenames that are absolute are recorded, to preserve +some semblance of privacy. + + +@node Path searching +@chapter Path searching + +@cindex path searching + +This chapter describes the generic path searching mechanism Kpathsea +provides. For information about searching for particular file types +(e.g., @TeX{} fonts), see the next chapter. + +@menu +* Searching overview:: Basic scheme for searching. +* Path sources:: Constructing the search path. + +* Default expansion:: a: or :a or a::b expands to a default. +* Variable expansion:: $foo and $@{foo@} expand to environment values. +* Tilde expansion:: ~ and ~user expand to home directories. +* Subdirectory expansion:: a// and a//b recursively expand to subdirs. + +* Filename database:: Using an externally-built list to search. +@end menu + + +@node Searching overview +@section Searching overview + +@cindex path searching, overview +@cindex searching overview +@cindex overview of path searching + +@cindex search path, defined +A @dfn{search path} is a colon-separated list of path elements, which +are directory names with some extra frills. A search path can come from +(a combination of) many sources; see below. To look up a file +@samp{foo} along a path @samp{.:/dir}, Kpathsea checks each element of +the path in turn: first @file{./foo}, then @file{/dir/foo}, (typically) +returning the first one that exists. + +@cindex magic characters +@kindex : @r{may not be :} +@kindex / @r{may not be /} +The ``colon'' and ``slash'' mentioned here aren't necessarily @samp{:} +and @samp{/} on non-Unix systems. Kpathsea tries to adapt to other +operating systems' conventions. + +@cindex database search +@cindex searching the database +To check a path element @var{e}, Kpathsea first sees if a prebuilt +database (see below) applies to @var{e}, i.e., if the database is in a +directory that is a prefix of @var{e}. If so, the path specification is +matched against the contents of the database. + +@cindex floating directories +@cindex filesystem search +@cindex disk search +@cindex searching the disk +If the database does not exist, or does not apply to this path element, +contains no matches, the filesystem is searched. Kpathsea constructs the +list of directories that correspond to this path element, and then +checks in them for the file being searched for. (To help speed future +lookups of files in the same directory, the directory in which a file is +found is floated to the top of the directory list.) + +Each path element is checked in turn: first the database, then the +disk. Once a match is found, the searching stops and the result is +returned. This avoids possibly-expensive processing of path +specifications that are never needed on a particular run. + +@cindex expansion of path elements +Although the simplest and most common path element is a directory name, +Kpathsea supports additional features in search paths: layers of default +values, environment variable names, config file values, users' home +directories, and recursive subdirectory searching. Thus, we say that +Kpathsea @dfn{expands} a path element, meaning getting rid of all the +magic specifications and getting down to the basic directory name or +names. This process is described in the sections below. It happens in +the same order as the sections. + +@cindex absolute filenames +@cindex relative filenames +@cindex explicitly relative filenames +@cindex filenames, absolute or explicitly relative +Exception to the above: If the filename being searched for is absolute +or explicitly relative, i.e., starts with @samp{/} or @samp{./} or +@samp{../}, Kpathsea simply checks if that file exists; it is not looked +for along any paths. + + +@node Path sources +@section Path sources + +@cindex path sources +@cindex sources for search paths + +A search path can come from many sources. In priority order (meaning +Kpathsea will use whichever it finds first): + +@enumerate + +@item +@cindex environment variable, source for path +A user-set environment variable, e.g., @samp{TEXINPUTS}. + +@item +A program-specific configuration file, e.g., an @samp{S /a:/b} line in +Dvips' @file{config.ps}. + +@item +@cindex configuration file, source for path +@cindex Kpathsea config file, source for path +@flindex texmf.cnf@r{, source for path} +A line in a Kpathsea configuration file @file{texmf.cnf}, e.g., +@samp{TEXINPUTS=/c:/d}. See section below. + +@item +@cindex compilation value, source for path +The compile-time default (specified in @file{kpathsea/paths.h}). + +@end enumerate + +@noindent In any case, once the path specification to use is determined, its +evaluation is independent of its source. These sources may also be +combined via default expansion. See the next section. + +You can see each of these values for a given search path by using the +debugging options of Kpathsea or your program. @xref{Debugging}. + +@menu +* Config files:: Kpathsea's runtime config files (texmf.cnf). +@end menu + + +@node Config files +@subsection Config files + +@cindex config files +@flindex texmf.cnf @r{definition} + +@cindex runtime configuration files +As mentioned above, Kpathsea reads @dfn{runtime configuration files} +named @file{texmf.cnf} for search path definitions. The path used to +search for them is constructed in the usual way, as described above +(except that configuration files cannot be used to define the path, +naturally; also, an @file{ls-R} database is not used to search for them, +for technical reasons). + +@vindex TEXMFCNF +The environment variable used is @samp{TEXMFCNF}. + +Kpathsea reads @emph{all} @file{texmf.cnf} files in the search path, not +just the first one found; it uses the first definition of each variable +encountered. Thus, with the (default) search path of @samp{.:$TEXMF}, +values from @file{./texmf.cnf} override those from +@file{$TEXMF/texmf.cnf}. + +Here is the format for @file{texmf.cnf} files: + +@itemize @bullet + +@cindex comments, in @file{texmf.cnf} +@item Anything after a @samp{%} or @samp{#} is ignored; this is for comments. + +@item Blank lines are ignored. + +@item Each remaining nonblank line must look like + +@example +@var{variable} @r{[}. @var{progname}@r{]} @r{[}=@r{]} @var{value} +@end example + +@noindent where the @samp{=} and surrounding whitespace is optional. + +@item The @var{variable} name may contain any characters except +whitespace, @samp{=}, or @samp{.} characters, but sticking to +@samp{A-Za-z_} is safest. + +@item If the @samp{.@var{progname}} is present, the definition only +applies if the program that is running is named (i.e., the last +component of @code{argv[0]}) @var{progname}. This allows (for example) +different flavors of @TeX{} to have different search paths. + +@item The @var{value} may contain any characters except whitespace, +@samp{%}, and @samp{@@}. (These restrictions are necessary because of +the various @code{sed} and other processing done on @file{texmf.cnf} at +build time.) + +@item All definitions are read before anything is expanded, so you can +use variables before they are defined (like @code{make}, unlike most +everything else). + +@end itemize + +@noindent Here is the fragment from the distributed file illustrating +most of these points: + +@example +% TeX input files -- i.e., anything to be found by \input or \openin [...] +latex209_inputs = .:$TEXMF/tex/latex209//:$TEXMF/tex// +latex2e_inputs = .:$TEXMF/tex/latex2e//:$TEXMF/tex// +TEXINPUTS = .:$TEXMF/tex// +TEXINPUTS.latex209 = $latex209_inputs +TEXINPUTS.latex2e = $latex2e_inputs +TEXINPUTS.latex = $latex2e_inputs +@end example + +@cindex shell scripts as configuration files +@cindex configuration files as shell scripts. +Although this format has obvious similarities to Bourne shell +scripts---change the comment character to @code{#}, disallow spaces +around the @code{=}, and get rid of the @code{.@var{program}} +convention, and it could be run through the shell. But there seemed +little advantage to doing this, since all the information would have to +passed back (with @code{echo}'s, presumably) to Kpathsea and parsed +there anyway, since the @code{sh} process couldn't affect its parent's +environment. + +@flindex cnf.c +The implementation of all this is in @file{kpathsea/cnf.c}. + + +@node Default expansion +@section Default expansion + +@kindex :: +@cindex doubled colons +@cindex leading colons +@cindex trailing colons +@cindex extra colons +@cindex default expansion +@cindex expansion, default + +If the highest-priority search path (in the list in the previous +section) contains an @dfn{extra colon} (i.e., leading, trailing, or +doubled), Kpathsea inserts the next-highest-priority search path that is +set at that point. If that search path has an extra colon, the same +happens with the next-highest. (An extra colon in the compile-time +default value has unpredictable results, and may cause the program to +crash, so installers beware.) + +For example, given + +@example +setenv TEXINPUTS /home/karl: +@end example + +@noindent and a @samp{TEXINPUTS} value from @file{texmf.cnf} of + +@example +.:$TEXMF//tex +@end example + +@noindent then the final value used for searching will be: + +@example +/home/karl:.:$TEXMF//tex +@end example + +@noindent You can trace this by debugging ``paths'' (@pxref{Debugging}). + +Minor technical point: Since it would be useless to insert the default +value in more than one place, Kpathsea changes only one extra @samp{:} +and leaves any others in place (where they will eventually be +effectively equivalent to @samp{.}, i.e., the current directory). It +checks first for a leading @samp{:}, then a trailing @samp{:}, then a +doubled @samp{:}. + + +@node Variable expansion +@section Variable expansion + +@kindex $ +@cindex environment variables in paths +@cindex variable expansion +@cindex expansion, variable +@flindex texmf.cnf@r{, and variable expansion} + +@samp{$foo} or @samp{$@{foo@}} in a path element is replaced by (1) the +value of an environment variable @samp{foo} (if it is set); (2) the +value of @samp{foo} from @file{texmf.cnf} (if any such exists); (3) the +empty string. + +If the character after the @samp{$} is alphanumeric or @samp{_}, the +variable name consists of all consecutive such characters. If the +character after the @samp{$} is a @samp{@{}, the variable name consists +of everything up to the next @samp{@}} (braces are not balanced!). +Otherwise, Kpathsea gives a warning and ignores the @samp{$} and its +following character. + +@cindex quoting variable values +Remember to quote the @samp{$}'s and braces as necessary for your shell. + +@cindex shell variables +@emph{Shell} variable values cannot be seen by Kpathsea. + +For example, given + +@example +setenv TEXMF /home/tex +setenv TEXINPUTS .:$TEXMF:$@{TEXMF@}new +@end example + +@noindent the final @samp{TEXINPUTS} path is the three directories: + +@example +.:/home/tex:/home/texnew +@end example + +@noindent You can trace this by debugging ``paths'' (@pxref{Debugging}). + + +@node Tilde expansion +@section Tilde expansion + +@kindex ~ +@cindex home directories in paths +@cindex tilde expansion +@cindex expansion, tilde + +A leading @samp{~} or @samp{~@var{user}} in a path element is replaced +by the current or @var{user}'s home directory, respectively. + +If @var{user} is invalid, or the home directory cannot be determined, +Kpathsea uses @file{.} instead. + +For example, + +@example +setenv TEXINPUTS ~/mymacros: +@end example + +@noindent will prepend a directory @file{mymacros} in your home +directory to the default path. + + +@node Subdirectory expansion +@section Subdirectory expansion + +@kindex // +@cindex subdirectory searching +@cindex expansion, subdirectory + +A @samp{//} in a path element following a directory @var{d} is replaced +by all subdirectories of @var{d}: first those subdirectories directly +under @var{d}, then the subsubdirectories under those, and so on. At +each level, the order in which the directories are searched is +unspecified. (It's ``directory order'', and definitely not +alphabetical.) + +If you specify any filename components after the @samp{//}, only +subdirectories which contain those components are included. For example, +@samp{/a//b} would expand into directories @file{/a/1/b}, @file{/a/2/b}, +@file{/a/1/1/b}, and so on, but not @file{/a/b/c} or @file{/a/1}. + +@cindex trick for detecting leaf directories +@cindex leaf directory trick +I should mention one related implementation trick, which I stole from +GNU find. Matthew Farwell @samp{<dylan@@ibmpcug.co.uk>} suggested it, +and David MacKenzie @samp{<djm@@gnu.ai.mit.edu>} implemented it (as far +as I know). + +@vindex st_nlink +The trick is that in every real Unix implementation (as opposed to the +POSIX specification), a directory which contains no subdirectories will +have exactly two links (namely, one for @file{.} and one for @file{..}). +That is to say, the @code{st_nlink} field in the @samp{stat} structure +will be two. Thus, we don't have to stat everything in the bottom-level +(leaf) directories---we can just check @code{st_nlink}, notice it's two, +and do no more work. + +But if you have a directory that contains @emph{one} subdirectory and +five hundred files, @code{st_nlink} will be 3, and Kpathsea has to stat +every one of those 501 entries. Therein lies slowness. + +@vindex UNIX_ST_LINK +You can disable the trick by undefining @code{UNIX_ST_LINK} in +@file{kpathsea/config.h}. (It is undefined by default except under Unix.) + +@flindex elt-dirs.c +Unfortunately, in some cases files in leaf directories are +@code{stat}'d: if the path specification is, say, +@samp{$TEXMF/fonts//pk//}, then files in a subdirectory +@samp{@dots{}/pk}, even if it is a leaf, are checked. The reason cannot +be explained without reference to the implementation, so read +@file{kpathsea/elt-dirs.c} (search for @samp{may descend}) if you are +curious. (And if you can find a way to @emph{solve} the problem, please +let me know.) + + +@node Filename database +@section Filename database (@code{ls-R}) + +@cindex filename database +@cindex database for filename searches +@cindex externally-built filename database + +Kpathsea goes to some lengths to minimize disk accesses for searches +(@pxref{Subdirectory expansion}). Nevertheless, at installations with +enough directories, doing a linear search of each possible directory for +a given file can take an excessively long time (``excessive'' depending +on the speed of the disk, whether it's NFS-mounted, how patient you are, +etc.). In practice, the union of font directories from the Dvips(k) and +Dviljk distributions is large enough for searching to be noticeably slow +on typical machines these days. + +@flindex ls-R @r{database file} +Therefore, Kpathsea can use an externally-built ``database'' that maps +files to directories, thus avoiding the need to exhaustively search the +disk. By fiat, you must name the file @file{ls-R}, and put it at the +root of the @TeX{} installation hierarchy (@samp{$TEXMF} by +default). Kpathsea does variable expansion on the @samp{$TEXMF}, +naturally, so you can use different @file{ls-R}'s for different trees, +if you are testing new ones. However, one and only one @file{ls-R} is +read; it is not searched for along any paths. + +@pindex cron @r{and @file{ls-R}} +You can build @file{ls-R} with the command +@example +ls -R @var{/your/root/dir} >ls-R +@end example +@noindent if your @code{ls} produces the right output +format (see the section below). GNU @code{ls}, for example, outputs in +this format. It is probably best to do this via @code{cron}, so changes +in the installed files will be automatically reflected (albeit with some +delay) in the database. + +@cindex symbolic links, and @file{ls-R} +@opindex -L @r{option to @code{ls}} +If your system uses symbolic links, the command @code{ls -LR} will be +more reliable than plain @code{ls -R}. The former follows the symbolic +links to the real files, which is what Kpathsea needs. + +@cindex warning about unusable @file{ls-R} +Kpathsea warns you if it finds an @file{ls-R} file, but the file does +not contain any usable entries. The usual culprit is using just @code{ls +-R} to generate the @file{ls-R} file instead of @code{ls -R +@var{/your/dir}}. Kpathsea looks for lines starting with @samp{/}, to +improve reliability with unusual filenames (specifically, those ending +with a @samp{:}). + +@kindex !! @r{in path specifications} +Because the database may be out-of-date for a particular run (e.g., if a +font was just built with @code{MakeTeXPK}), if a file is not found in +the database, by default Kpathsea goes ahead and searches the disk. If a +particular path element begins with @samp{!!}, however, @emph{only} the +database will be searched for that element, never the disk. If the +database does not exist, nothing will be searched. Because this can +greatly surprise users (``I see the font @file{foo.tfm} when I do an +@code{ls}; why can't Dvips find it?''), I do not recommend using this +feature. + +@menu +* Database format:: Syntax details of the database file. +@end menu + + +@node Database format +@subsection Database format + +@cindex format of external database +@cindex database, format of + +The ``database'' read by Kpathsea is a line-oriented file of plain +text. The format is that generated by GNU (and perhaps other) @code{ls} +programs given the @samp{-R} option, as follows. + +@itemize @bullet + +@item +Blank lines are ignored. + +@item +If a line begins with @samp{/} and ends with a colon, it's the name of a +directory. + +@item +All other lines name entries in the most recently seen directory. +@samp{/}'s in such lines will produce possibly-strange results. + +@item +Files with no preceding directory line are ignored. + +@end itemize + + +For example, here's the first few lines of @file{ls-R} on my system: + +@example +bibtex +dvips +fonts +ini +ls-R +mf +tex + +/usr/local/lib/texmf/bibtex: +bib +bst +doc + +/usr/local/lib/texmf/bibtex/bib: +asi.bib +bibshare +btxdoc.bib +@end example + +@noindent On my system, @file{ls-R} is about 30K bytes. + + +@node TeX searching +@chapter @TeX{} searching + +@cindex @TeX{} searching + +Although the basic features in Kpathsea can be used for any type of path +searching, it came about (like all libraries) with a specific +application in mind: I wrote Kpathsea specifically for @TeX{} system +programs. I had been struggling with the programs I was using (Dvips, +Xdvi, and @TeX{} itself) having slightly different notions of how to +specify paths; and debugging was painful, since no code was shared. + +Therefore, Kpathsea provides some @TeX{}-specific features. Indeed, +many of the supposedly generic path searching features were provided +because they seemed useful in that con@TeX{}t (font lookup, particularly). + +@menu +* Envvars: TeX environment variables. Overriding compiled-in paths. +* Glyph lookup:: Searching for bitmap fonts. +@end menu + + +@node TeX environment variables +@section @TeX{} environment variables + +@cindex environment variables for @TeX{} +@cindex @TeX{} environment variables + +Kpathsea defines a sequence of environment variables to search for each +file type it supports. This makes it easy for different programs to +check the same environment variables, in the same order. + +The following table lists the environment variables searched for each +file type in the order they are searched (and a brief description of the +file type). That is, only if the first variable is unset is the second +variable checked, and so on. If none are set, various other things are +checked; @pxref{Path sources}. + +@table @samp + +@item .base +@flindex .base +@vindex MFBASES +(Metafont memory dump) +@samp{MFBASES} + +@item .bib +@flindex .bib +@vindex BIBINPUTS +(Bib@TeX{} bibliography source) +@samp{BIBINPUTS} + +@item .bst +@flindex .bst +@vindex BSTINPUTS +@vindex TEXINPUTS +(Bib@TeX{} style file) +@samp{BSTINPUTS}, @samp{TEXINPUTS} + +@item .cnf +@flindex .cnf +@vindex TEXMFCNF +(Kpathsea runtime configuration files) +@samp{TEXMFCNF} + +@item .eps +@flindex .eps +@vindex TEXPICTS +@vindex TEXINPUTS +(Encapsulated PostScript figures) +@samp{TEXPICTS}, @samp{TEXINPUTS} + +@item .fmt +@flindex .fmt +@vindex TEXFORMATS +(@TeX{} memory dump) +@samp{TEXFORMATS} + +@item gf +@flindex .gf +@vindex GFFONTS +@vindex GLYPHFONTS +@vindex TEXFONTS +(generic font bitmap) +@samp{@var{program}FONTS}, @samp{GFFONTS}, @samp{GLYPHFONTS}, @samp{TEXFONTS} + +@item .mf +@flindex .mf +@vindex MFINPUTS +(Metafont source) +@samp{MFINPUTS} + +@item mf.pool +@flindex .pool +@vindex MFPOOL +(Metafont program strings) +@samp{MFPOOL} + +@item .pict +@flindex .pict +(Other kinds of figures) +Same as @file{.eps}. + +@item pk +@flindex .pk +@vindex PKFONTS +@vindex TEXPKS +@vindex GLYPHFONTS +@vindex TEXFONTS +(packed bitmap font) +@samp{@var{program}FONTS}, @samp{PKFONTS}, @samp{TEXPKS}, +@samp{GLYPHFONTS}, @samp{TEXFONTS} + +@item .tex +@flindex .tex +@vindex TEXINPUTS +(@TeX{} source) +@samp{TEXINPUTS} + +@item tex.pool +@flindex .pool +@vindex TEXPOOL +(@TeX{} program strings) +@samp{TEXPOOL} + +@item .tfm +@flindex .tfm +@vindex TFMFONTS +@vindex TEXFONTS +(@TeX{} font metrics) +@samp{TFMFONTS}, @samp{TEXFONTS} + +@item .vf +@flindex .vf +@vindex VFFONTS +@vindex TEXFONTS +(virtual font) +@samp{VFFONTS}, @samp{TEXFONTS} + +@end table + +For the font variables, the intent is that: + +@enumerate + +@item +@samp{TEXFONTS} is the default for everything. + +@item +@samp{GLYPHFONTS} is the default for bitmap (or, more precisely, +non-metric) files. + +@item +Each format has its own variable. + +@item +@vindex XDVIFONTS +@vindex DVIPSFONTS +Each program can and should have its own font override path as well; +e.g., @samp{DVIPSFONTS} for Dvipsk. Again, this is for bitmaps, not metrics. + +@end enumerate + +If these environment variables are set, the corresponding +@file{texmf.cnf} definition won't be looked at (unless, as usual, the +environment variable has an extra @samp{:}). @xref{Default expansion}. + + +@node Glyph lookup +@section Glyph lookup + +@cindex glyph lookup +@cindex searching for glyphs +@cindex @TeX{} glyph lookup + +@flindex tex-glyph.c +@findex kpse_find_glyph_format +Kpathsea provides a routine (@code{kpse_find_glyph_format} in +@file{kpathsea/tex-glyph.c}) which searches for a bitmap font in GF or +PK format (or either) given a font name (e.g., @samp{cmr10}) and a +resolution (e.g., 300). + +The search is based solely on filenames, not file contents---if a PK +file is named @file{cmr10.300gf}, it will be found as a GF file. + +Here is an outline of the search strategy (details in the sections +below) for a file @var{name} at resolution @var{dpi}. The search stops +at the first successful lookup. + +@enumerate + +@item Look for an existing file @var{name}.@var{dpi} in the specified +format(s). + +@item If @var{name} is an alias for a file @var{f} in the fontmap +file @file{texfonts.map}, look for @var{f}.@var{dpi}. + +@item Run an external script (typically named @code{MakeTeXPK}) to +generate the font. + +@item Look for @var{fallback}.@var{dpi}, where @var{fallback} is some +last-resort font (typically @samp{cmr10}). + +@end enumerate + +@menu +* Basic glyph lookup:: Features common to all glyph lookups. +* Fontmap:: Aliases for fonts. +* MakeTeX... scripts:: Creating files on the fly. +* Fallback font:: Resolutions and fonts of last resort. +@end menu + + +@node Basic glyph lookup +@subsection Basic glyph lookup + +@cindex basic glyph lookup +@cindex common features in glyph lookup + +When Kpathsea looks for a bitmap font @var{name} at resolution @var{dpi} +in a format @var{format}, it first checks each directory in the search +path for a file @samp{@var{name}.@var{dpi}@var{format}}; for example, +@samp{cmr10.300pk}. Kpathsea looks for a PK file first, then a GF file. + +If that fails, Kpathsea looks for +@samp{dpi@var{dpi}/@var{name}.@var{format}}; for example, +@samp{dpi300/cmr10.pk}. This is how fonts are typically stored on +filesystems (like DOS's) that permit only three-character extensions. + +@cindex tolerance for glyph lookup +@cindex glyph lookup bitmap tolerance +@findex KPSE_BITMAP_TOLERANCE +If that fails, Kpathsea looks for a font with a close-enough @var{dpi}. +``Close enough'' is defined (by the macro @code{KPSE_BITMAP_TOLERANCE} +in @file{kpathsea/tex-glyph.h}) to be @code{@var{dpi} / 500 + 1}, which +is slightly more than the 0.2% allowed by the DVI standard. + + +@node Fontmap +@subsection Fontmap + +@cindex fontmap files +@cindex font alias files +@cindex aliases for fonts +@flindex texfonts.map + +If a bitmap font is not found with the original name (see the previous +section), Kpathsea looks through any @dfn{fontmap} files for an +@dfn{alias} for the original font name. These files are named +@file{texfonts.map} and are searched for along the usual glyph path. + +This feature is intended to help in two respects: + +@enumerate + +@item +@cindex fontnames, unlimited length +An alias name is limited in length only by available memory, not by your +filesystem. Therefore, if you want to ask for +@file{Adobe-Lucida-Bold-Sans=Typewriter} instead of @file{plcbst}, you +can. + +@item +@cindex circle fonts +@flindex lcircle10 +A few fonts have historically had multiple names: specifically, +La@TeX{}'s ``circle font'' has variously been known as @file{circle10}, +@file{lcircle10}, and @file{lcirc10}. Aliases can make all the names +equivalent, so that it no longer matters what the name of the installed +file is; @TeX{} documents will find their favorite name. + +@end enumerate + +The format of fontmap files is straightforward: the first word on each +line is the true filename; the second word is the alias; subsequent +words are ignored. A @dfn{word} is a sequence of non-whitespace +characters. Blank lines are ignored; +comments start with @samp{%} and continue to end-of-line. + +If an alias has an extension, it matches only those files with +that extension; otherwise, it matches anything with the same root, +regardless of extension. For example, an alias @samp{foo.tfm} matches only +when exactly @file{foo.tfm} is being searched for; but an alias +@samp{foo} matches @file{foo.vf}, @file{foo.300pk}, etc. + +As an example, here are the fontmap entries that make the circle fonts +equivalent. These are in the distributed @file{texfonts.map} in the +Web2C distribution. + +@example +circle10 lcircle10 +circle10 lcirc10 +lcircle10 circle10 +lcircle10 lcirc10 +lcirc10 circle10 +lcirc10 lcircle10 +@end example + + +@node MakeTeX... scripts +@subsection @file{MakeTeX}@dots{} scripts + +@cindex @file{MakeTeX}@dots{} scripts +@cindex scripts for file creation + +If Kpathsea cannot find a bitmap font, by either its original name or a +fontmap alias, it can be configured to invoke an external program to +create it. The same mechanism can be used for other nonexistent files. + +The script is passed the name of the file to create and possibly other +arguments, as explained below. It must echo the full pathname of the +file it created (and nothing else) to standard output; it can write +diagnostics to standard error. + +@menu +* MakeTeX... script names:: +* MakeTeX... script arguments:: +@end menu + + +@node MakeTeX... script names +@subsubsection @file{MakeTeX}@dots{} script names + +@cindex @file{MakeTeX}@dots{} script names +@cindex names for @file{MakeTeX}@dots{} scripts + +@flindex tex-make.c +@vindex kpse_make_specs +The following table shows the default name of the script for each +possible file types. (The source is the variable @code{kpse_make_specs} +in @file{kpathsea/tex-make.c}.) + +@table @file + +@item MakeTeXPK +@pindex MakeTeXPK +Glyph fonts. + +@item MakeTeXTeX +@pindex MakeTeXTeX +@TeX{} input files. + +@item MakeTeXMF +@pindex MakeTeXMF +Metafont input files. + +@item MakeTeXTFM +@pindex MakeTeXTFM +TFM files. + +@end table + +@vindex DVIPSMAKEPK +@vindex XDVIMAKEPK +@vindex DVILJMAKEPK +@noindent These names are overridden by an environment variable specific +to the program---for example, @samp{DVIPSMAKEPK} for Dvipsk. + +@flindex missfont.log +@cindex failed @code{MakeTeX@dots{}} +@vindex TEXMFOUTPUT +If a @code{MakeTeX@dots{}} script fails, the invocation is appended to a +file @file{missfont.log} in the current directory. If the current +directory is not writable and the environment variable +@samp{TEXMFOUTPUT} is set, its value is used. Otherwise, nothing is +written. + + +@node MakeTeX... script arguments +@subsubsection @file{MakeTeX}@dots{} script arguments + +@cindex arguments to @file{MakeTeX}@dots{} + +The first argument to a @file{MakeTeX}@dots{} script is always the name +of the file to be created. + +For @file{MakeTeXPK}, three or four additional arguments are also +passed, via corresponding environment variables: + +@enumerate + +@item +@vindex KPATHSEA_DPI +The dpi to make the font at (@samp{KPATHSEA_DPI}). + +@item +@vindex MAKETEX_BASE_DPI +@cindex base dpi +The ``base dpi'' the program is operating at (@samp{MAKETEX_BASE_DPI}), +i.e., the assumed resolution of the output device. + +@item +@vindex MAKETEX_MAG +@vindex mag @r{Metafont variable} +@cindex magstep for @code{MakeTeXPK} +A ``magstep'' string suitable for the Metafont @code{mag} variable +(@samp{MAKETEX_MAG}). + +@item +@vindex MAKETEX_MODE +@vindex mode @r{Metafont variable} +@cindex Metafont mode name for @code{MakeTeXPK} +Optionally, a Metafont mode name to assign to the Metafont @code{mode} +variable (@samp{MAKETEX_MODE}). Otherwise, (the default) +@code{MakeTeXPK} guesses the mode from the resolution. @xref{TeX +directory structure, @TeX{} directory structure}. + +@item +@vindex mtp_destdir +@cindex destination directory for @code{MakeTeXPK} +Optionally, a directory name. If the directory is absolute, it is used +as-is. Otherwise, it is appended to the root destination directory set +in the script (from environment variables @code{DESTDIR} or +@code{MTP_DESTDIR} or a compile-time default). If this argument is not +supplied, the mode name is appended to the root destination directory. + +@end enumerate + +@noindent Kpathsea sets @samp{KPATHSEA_DPI} appropriately for each +attempt at building a font. It's up to the program using Kpathsea to +set the others. (@xref{Calling sequence}.) + +@vindex MAKETEXPK @r{environment variable} +@cindex specification for @code{MakeTeXPK} +You can change the specification for the arguments passed to the +external script by setting the environment variable named as the script +name, but all capitals---@samp{MAKETEXPK}, for example. If you've +changed the script name by setting (say) @samp{DVIPSMAKEPK} to +@samp{foo}, then the spec is taken from the environment variable @samp{FOO}. + +The spec can contain any variable references, to the above variables or +any others you might have set. As an example, the default spec for +@code{MakeTeXPK} is: + +@example +$KPATHSEA_DPI $MAKETEX_BASE_DPI $MAKETEX_MAG $MAKETEX_MODE +@end example + +@noindent The convention of passing the name of the file to be created +as the first argument cannot be changed. + + +@node Fallback font +@subsection Fallback font + +@cindex fallback font +@cindex fallback resolutions +@cindex font of last resort +@cindex resolutions, last-resort +@cindex last-resort font + +@vindex DVIPSSIZES +@vindex XDVISIZES +@vindex DVILJSIZES +@vindex TEXSIZES +@vindex default_texsizes +If a bitmap font cannot be found or created at the requested size, +Kpathsea looks for the font at a set of @dfn{fallback resolutions}. You +specify these resolutions as a colon-separated list (like search paths). +Kpathsea looks first for a program-specific environment variable (e.g., +@code{DVIPSSIZES} for Dvipsk), then the environment variable +@samp{TEXSIZES}, then a default specified at compilation time (the Make +variable @code{default_texsizes}). You can set this list to be empty if +you prefer to find fonts at their stated size or not at all. + +@flindex cmr10 +@vindex kpse_fallback_font +Finally, if the font cannot be found even at the fallback resolutions, +Kpathsea looks for a fallback font, typically @file{cmr10}. Programs +must enable this feature by assigning to the global variable +@code{kpse_fallback_font} or calling @code{kpse_init_prog} +(@pxref{Calling sequence}); the default is no such fallback font. + + +@node TeX directory structure +@chapter @TeX{} directory structure + +(This section obviously not really written yet; sorry. See +@file{kpathsea/HIER}.) + +@vindex TEXMF + +@vindex MAKETEX_MODE +@cindex paths, device name included in +By default, the bitmap font paths end with @code{$MAKETEX_MODE}, thus +including the device name (i.e., the Metafont mode) in the path. This +is to make it possible to distinguish two different devices with the +same resolution---write/white and write/black 300dpi printers, for +example. + +@findex kpse_init_prog +@flindex proginit.c +@flindex kpathsea/proginit.c +However, since most sites don't have this complication, Kpathsea +(specifically, @code{kpse_init_prog} in @file{kpathsea/proginit.c}) has +a special case: if the mode has not been explicitly set by the user (or +in a configuration file), it sets @samp{MAKETEX_MODE} to @code{/}. This +makes the default PK path, for example, expand into @code{@dots{}/pk//}, +so fonts will be found even if there is no subdirectory for the mode. +(If your site has only one printer, for example.) + +To make the paths independent of the mode, simply edit +@file{texmf.cnf.in} before installation, or the installed +@file{texmf.cnf}. @xref{Default paths}. + +@xref{MakeTeX... script arguments, @file{MakeTeX}@dots{} script +arguments}, for how this interacts with @code{MakeTeXPK}. + + +@node Programming +@chapter Programming + +This chapter is for programmers who wish to use +Kpathsea. @xref{Introduction}, for the conditions under which you may do +so. (If you do this, I'd appreciate a note, just to satisfy my +curiousity.) + +@menu +* Overview: Programming overview: Introduction. +* Calling sequence:: Specifics of what to call. +* Config: Programming with config files: Getting info from texmf.cnf. +@end menu + + +@node Programming overview +@section Programming overview + +@cindex programming overview +@cindex overview of programming with Kpathsea + +Aside from this manual, your best source of information is the source to +the programs I've modified to use Kpathsea (also listed in the +introduction). Of those, Dviljk is probably the simplest, and hence a +good place to start. Xdvik adds VF support and the complication of X +resources. Dvipsk adds the complication of its own config files. + +@flindex pathsearch.h +@flindex tex-file.h +@flindex tex-glyph.h +Beyond these of examples of use, the @file{.h} files in the Kpathsea +source describe the interfaces and functionality (and of course the +@file{.c} files define the actual routines, which are the ultimate +documentation). @file{pathsearch.h} declares the basic searching +routine. @file{tex-file.h} and @file{tex-glyph.h} define the interfaces +for looking up particular kinds of files. + +The library provides no way for an external program to register new file +types: @file{tex-file.[ch]} must be modified to do this. For example, +Kpathsea has support for looking up Dvips config files, even though +obviously no program other than Dvips will ever want to do so. I felt +this was acceptable, since along with new file types should also come +new defaults in @file{texmf.cnf} (and its descendant @file{paths.h}), +since it's best for users if they can modify one configuration file for +all kinds of paths. + +Kpathsea does not open any files or parse any formats itself. Its +purpose is only to return filenames. The GNU font utilities source does +contain libraries to read TFM, GF, and PK files. + + +@node Calling sequence +@section Calling sequence + +@cindex programming with Kpathsea +@cindex calling sequence + +The typical way to use Kpathsea in your program goes something like this: + +@enumerate + +@item +@findex kpse_set_progname +@vindex argv[0] +Call @code{kpse_set_progname} with @code{argv[0]}; This is the only +initialization that is mandatory to take full advantage of +Kpathsea---specifically, for the @code{.@var{program}} feature of config +files (@pxref{Config files}). + +@vindex program_invocation_name +@vindex program_invocation_short_name +@vindex KPATHSEA_DEBUG +@code{kpse_set_progname} sets the global variables +@code{program_invocation_name} and @code{program_invocation_short_name}. +It also initializes debugging flags based on the environment variable +@code{KPATHSEA_DEBUG}, if that is set. set. + +@cindex GNU C library +The GNU C library provides these two global variables itself; in this +case, the call to @code{kpse_set_program} does nothing. But you (as a +software author) most likely do not want to force people installing your +program to have glibc. + +@item +@vindex kpathsea_debug +@cindex debugging flags, in kpathsea-using program +Set debugging options. @xref{Debugging}. If your program doesn't have a +debugging flag already, you can define one and set @samp{kpathsea_debug} +to the number that the user supplies (see Dviljk), or you can just omit +this altogether (people can always set @samp{KPATHSEA_DEBUG}). If you +do have runtime debugging already, you need to merge Kpathsea's options +with yours (see Dvipsk and Xdvik). + +@item +@vindex client_path @r{in @code{kpse_format_info}} +@vindex kpse_format_info +@flindex resident.c +@cindex config files, for kpathsea-using program +If your program has its own configuration files that can define search +paths, you should assign those paths to the @code{client_path} member in +the appropriate element of the @file{kpse_format_info} array. (This array +is indexed by file type; see @file{tex-file.h}.) See @file{resident.c} +in Dvipsk for an example. + +@item +@findex kpse_init_prog +@flindex proginit.h +Call @code{kpse_init_prog} (see @file{proginit.c}). It's useful for the +DVI drivers, at least, but for other programs it may be simpler to +extract the parts of it that actually apply. This does not initialize +any paths, it just looks for (and sets) certain environment variables +and other random information. (A search path is always initialized at +the first call to find a file of that type; this eliminates much useless +work, e.g., initializing the Bib@TeX{} search paths in a DVI driver.) + +@item +@findex kpse_find_* +The routine to actually find a file of type @var{format} is +@code{kpse_find_@var{format}}, defined in @file{tex-file.h}. These are +macros that expand to a call to @file{kpse_find_file}. You can call, +say, @code{kpse_find_tfm} after doing only the first of the +initialization steps above---Kpathsea will read the generic config file +@file{texmf.cmf}, look for environment variables, and do the expansions +at the first lookup. + +@item +To find PK and/or GF bitmap fonts, the routines are @file{kpse_find_pk}, +@file{kpse_find_gf} and @file{kpse_find_glyph}, defined in +@file{tex-glyph.h}. These return a structure in addition to the +resultant filename, because fonts can be found in so many ways. See the +documentation in the source. + +@end enumerate + +@cindex hash table routines +@cindex memory allocation routines +@cindex string routines +@cindex reading unlimited-length lines +@cindex input lines, reading +@cindex lines, reading unlimited-length +Kpathsea also provides many utility routines. Some are generic: hash +tables, memory allocation, string concatenation and copying, string +lists, reading input lines of unlimited length, etc. Others are +filename-related: default path, tilde, and variable expansion, +@code{stat} calls, etc. (Perhaps someday I'll move the former to a +separate library.) + +@flindex c-*.h +The @file{c-*.h} header files can also help your program adapt to many +different systems. You will almost certainly want to use Autoconf for +configuring your software if you use Kpathsea; I strongly recommend +using Autoconf regardless. You can get it by ftp from +@samp{prep.ai.mit.edu} in @file{pub/gnu/autoconf-*.tar.gz}, or from any +of its mirrors. + + +@node Programming with config files +@section Programming with config files + +@cindex programming with config files +@cindex config files, programming with + +You can use the same @code{texmf.cnf} configuration file as Kpathsea for +your program. This will help installers do all configuration in one place. + +@findex kpse_var_expand +@flindex variable.h +To retrieve a value @var{var}, the best way is to call +@code{kpse_var_expand} on the string @code{$@var{var}}. This will look +first for an environment variable @var{var}, then a config file +value. The result will be the value found, or the empty string. This +function is declared in @file{kpathsea/variable.h}. + +@findex kpse_cnf_get +@flindex cnf.h +If for some reason you want to retrieve a value @emph{only} from a +config file, not automatically looking for a corresponding environment +variable, call @code{kpse_cnf_get} (declared in @file{kpathsea/cnf.h}) +with the string @var{var}. + +No initialization calls are needed. + + +@include copying.texi +@include freedom.texi + + +@node Index +@unnumbered Index + +@printindex cp + +@contents + +@bye
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kpathsea/maintain.texi Fri Jul 19 01:57:38 1996 +0000 @@ -0,0 +1,500 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename maintain.info +@settitle Information For Maintainers of GNU Software +@c For double-sided printing, uncomment: +@c @setchapternewpage odd +@c UPDATE THIS DATE WHENEVER YOU MAKE CHANGES! +@set lastupdate 08 November 1994 +@c %**end of header + +@ifinfo +@format +START-INFO-DIR-ENTRY +* Maintaining: (maintain). Maintaining GNU software. +END-INFO-DIR-ENTRY +@end format +@end ifinfo + +@setchapternewpage off + +@ifinfo +Information for maintainers of GNU software. +Copyright (C) 1992, 1993, 1994 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 Information For Maintainers of GNU Software +@author Richard Stallman +@author last updated @value{lastupdate} +@page + +@vskip 0pt plus 1filll +Copyright @copyright{} 1992, 1993, 1994 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, Preface, (dir), (dir) +@top Version + +Last updated @value{lastupdate}. +@end ifinfo + +@menu +* Preface:: +* Legal Matters:: +* Clean Ups:: +* Mail:: +* Old Versions:: +* Archives:: +* Distributions:: +@end menu + +@node Preface +@chapter About This Document + +This file contains guidelines and advice for someone who is the +maintainer of a GNU program on behalf of the GNU project. Anyone +can change GNU software, but there's no need to pay attention to +these guidelines unless you are maintaining a version for +widespread distribution. + +Corrections or suggestions regarding this document should be sent to +@code{gnu@@prep.ai.mit.edu}. If you make a suggestion, please include a +suggested new wording for it; our time is limited. We prefer a context +diff to the @file{maintain.texi} file, but if you don't have that file, +please mail your suggestion anyway. + +This release of the GNU Maintenance Instructions was last updated +@value{lastupdate}. + +@node Legal Matters +@chapter Legal Matters + +When incorporating changes from other people, make sure to follow the +correct procedures. Doing this ensures that the FSF has the legal right +to distribute and defend GNU software. + +@menu +* Copyrights:: +* Recording Changes:: +@end menu + +@node Copyrights +@section Copyrights + +For the sake of registering the copyright on later versions of the +software, you need to keep track of each person who makes significant +changes. A change of ten lines or so, or a few such changes, in a +large program is not significant. + +@strong{Before} incorporating significant changes, make sure that the +person has signed copyright papers and that the Foundation has +received and signed them. + +You can tell the person what papers to sign by email. For large +changes, ask for an assignment. Send the person a copy of +@file{/gd/gnuorg/assign.changes}, but first, go to the second page +and insert the person's name and the name of the program involved in +place of @samp{NAME OF PERSON} and @samp{NAME OF PROGRAM}. Do this +before sending, because otherwise the person might sign without +noticing them. Then the papers would be useless. + +For medium to small changes, ask for a disclaimer. Use the file +@file{/gd/gnuorg/disclaim.changes}. + +To check whether papers have been received, look in +@file{/gd/gnuorg/copyright.list}. If you can't look there directly, +@code{fsf-records@@prep.ai.mit.edu} can check for you, and can also +check for papers that are waiting to be entered and inform you +when expected papers arrive. + +You can also send the person @file{/gd/gnuorg/conditions.text}, which +explains his options (assign vs. disclaim) and their consequences. + +@node Recording Changes +@section Recording Changes + +@strong{Keep records of which portions were written by whom.} + +These records don't need to be as detailed as a change log. They don't +need to distinguish work done at different times, only different people. + +They should say which files or functions were written by each person, +and which files or functions were revised by each person. They don't +need to say what the purpose of the change was. The Register of +Copyrights doesn't care what the program does. + +For example, this would describe an early version of GAS: + +@display +Dean Elsner first version of all files except gdb-lines.c and m68k.c. +Jay Fenlason entire files gdb-lines.c and m68k.c, most of app.c, + extensive changes in messages.c, input-file.c, write.c, + revisions elsewhere. +@end display + +Please keep these records in a file named @file{AUTHORS} in the source +directory for the program itself. + +@node Clean Ups +@chapter Cleaning Up Changes + +If someone sends you changes which are ugly and will make the program +harder to understand and maintain in the future, such as a port to +another operating system containing ad hoc conditionals, don't +hesitate to ask the person to clean up his changes before you merge +them. + +Since the amount of work we do is constant in any case, the more work +we get other people to do, the faster GNU will advance. + +If the person will not or can not make the changes clean enough, then +say that you can't afford to merge them. Invite him to distribute +his changes himself, or to find other people who can make them clean +enough for us to maintain. + +The only reason to do these cleanups yourself is if (1) it is easy +enough that it is less work than telling the author what to clean up, +or (2) users will greatly appreciate the improvement, and you would +almost write it yourself if you had time. + +The GNU Coding Standards are a good thing to send people who have to +clean up C programs (@pxref{Top, , Contents, standards, GNU Coding +Standards}). The Emacs Lisp manual contains an appendix that gives +coding standards for Emacs Lisp programs; it is good to urge authors to +read it (@pxref{Tips, , Tips and Standards, elisp, The GNU Emacs Lisp +Reference Manual}). + +@node Mail +@chapter Dealing With Mail + +Once a program is in use, you will start getting bug reports. Some +GNU programs have their own special lists for sending bug reports. +For miscellaneous programs that don't have their own lists, we use a +catch-all list, @code{bug-gnu-utils@@prep.ai.mit.edu}. Talk with +@code{gnu@@prep.ai.mit.edu} to arrange to be added to the proper list +for your program. + +When you receive bug reports, keep in mind that the main purpose of +the bug reports is to enable you to improve the next version of the +program. Helping individuals is only secondary. So you don't +need to give a substantial response unless you have a reason to +(for example, to ask for more information, or to ask the user to +test a fix). But it is good to respond to the rest of the bug +reports with just ``Thanks.'' That is quick and tells the user that +the bug report was useful. + +As a practical matter, any time you spend helping individuals beyond +what is necessary for you, takes time away from maintaining the program. +While this may seem ``friendly'' and ``helpful,'' actually it is +counterproductive. If you help one person when you could instead have +helped thousands, the world is worse off. + +@node Old Versions +@chapter Recording Old Versions + +It is very important to keep backup files of all source files of GNU. +You can do this using RCS if you like. The easiest way to use RCS is +via the Version Control library in Emacs; @ref{Concepts of VC, , +Concepts of Version Control, emacs, The GNU Emacs Manual}. + +Alternatively, you can keep backup files. + +@menu +* Backup Files:: +* Deleting Backup Files:: +@end menu + +@node Backup Files +@section Backup Files + +Emacs makes a backup file by renaming the old source file to a new +name. This means that if the file is also pointed to by a +distribution directory, the distribution directory continues to point +to the same version it always did---the right thing. + +We want to keep more than one backup for all GNU sources. So, if you +are going to edit GNU sources, @emph{make certain} to put +@example +(setq version-control t) +@end example +@noindent +into your @file{.emacs} file, so that Emacs always creates numbered +backup files. + +Using Emacs backup files works as long as people always make changes +with Emacs. If you change the file in some other way, and use +@code{cp}, @code{ftp}, or @code{tar} to install it, you will +@emph{overwrite} the old version and fail to make a backup. Don't do +that! + +If you want to make a change to a source file with something other +than Emacs, you can write the changed file to another name, and use +@kbd{C-x C-w} in Emacs to write it under the real name. This makes the +backup file properly. + +You can use GNU @code{cp} or @code{mv} to install changed files if you +give them the @samp{--backup} (or, equivalently, @samp{-b}) option; then +they make backup copies the same way that Emacs does. You should also +use the @samp{--version-control=t} option, or, alternately, first +@example +export VERSION_CONTROL=t +@end example +@noindent +(or the @code{csh} equivalent); this makes GNU @code{cp} and @code{mv} +create numbered backup files instead of a single backup file with a +@samp{~} appended to the filename. For installing many changed files, +you can use shell wildcards and also give GNU @code{cp} or @code{mv} the +@samp{--update} (@samp{-u}) option, which only copies (or moves) files +that have been modified more recently than the existing destination +files, and the @samp{--verbose} (@samp{-v}) option, which prints the +names of the files that are actually copied (or moved). + +Before you use @code{mv} or @code{cp} in this way, @emph{make sure it is +the GNU version}. Do @samp{which mv} (in @code{csh}) or @samp{type mv} +(in @code{bash}) to verify you are not getting @file{/bin/mv} (or +likewise for @code{cp}). Or just type @samp{cp} or @samp{mv} and look +at the usage message. + +@node Deleting Backup Files +@section Deleting Backup Files + +Always answer no when Emacs offers to delete backup files automatically. +The way to delete them is by hand, using @kbd{M-x dired}. + +When you decide which backup files to delete, it is good to keep one +every couple of weeks or so, going back about 2 months. + +If there is a long gap between versions, because that file did not change +during a long period of time, then keep the version before the gap +even if it is 2 months old. Pretend it is just 2 weeks older than the +next kept version, so delete it when the next version is >= 6 weeks old. + +If the changes in a program have been simple, then you don't need to +keep as many backup files. Just one a month for 2 months is enough. + +If you have made big changes, keep the versions before and after the +big change, until they are old enough. + +If you made several changes the same day, usually the last version written +that day is best to keep. + +It is almost always right to keep the most recent backup version. + +@node Archives +@chapter Archives + +For each program, you should keep a special magtape or cartridge as an +archive. Each time you release a new version, @code{dd} the tar file onto +the end of the tape. Keep a list of versions on the tape's paper +label, and add to it each time you add to the tape. + +For cartridges, you can type +@example +mt -f /dev/nrst8 eom +@end example +@noindent +to go straight to the end of the data on the tape. + +For reel-to-reel tapes, there is no automated way to go to the end of +the data on the tape. You have to count the number of files (based +on the written label), and space forward over them with @samp{mt fsf}. + +To be safe, it is important to check your count. If the count is @var{n}, +then do: +@example +mt -f /dev/nrmt8 fsf @var{n}-1 +@end example +@noindent +This puts you at the beginning of the last existing tar file. + +Then do +@example +tar tf /dev/nrmt8 +@end example +@noindent +to list that tar file. If the version number appears in a directory +name, which is a good idea, you can use this to verify that you have +reached the tar file you wanted to reach. + +@kbd{C-c} the @code{tar} before it finishes; then do +@example +mt -f /dev/nrmt8 fsf +@end example +@noindent +to skip past it and its end-of-file marker. + +To copy the new distribution file onto cartridge tape, do: +@example +dd if=@var{tar-file-name} of=/dev/nrst8 bs=102400 +@end example +@noindent +(This specifies a blocking factor of 200.) + +For reel-to-reel tape, do: +@example +dd if=@var{tar-file-name} of=/dev/nrmt8 bs=10240 +@end example +@noindent +(This specifies a blocking factor of 20.) + +When the tape gets full, put it aside permanently and start writing +another. + +@node Distributions +@chapter Distributions + +It is important to follow the GNU conventions when making GNU software +distributions. + +@menu +* Distribution tar Files:: +* Distribution Patches:: +* Distribution on prep:: +* Test Releases:: +@end menu + +@node Distribution tar Files +@section Distribution tar Files + +The tar file for version @var{m}.@var{n} of program @code{foo} should be +named @file{foo-@var{m}.@var{n}.tar}. It should unpack into a +subdirectory named @file{foo-@var{m}.@var{n}}. Tar files should not +unpack into files in the current directory, because this is inconvenient +if the user happens to unpack into a directory with other files in it. + +Here is how the @file{Makefile} for Bison creates the tar file. +This method is good for other programs. + +@example +dist: bison.info + echo bison-`sed -e '/version_string/!d' \ + -e 's/[^0-9.]*\([0-9.]*\).*/\1/' -e q version.c` > .fname + -rm -rf `cat .fname` + mkdir `cat .fname` + dst=`cat .fname`; for f in $(DISTFILES); do \ + ln $(srcdir)/$$f $$dst/$$f || @{ echo copying $$f; \ + cp -p $(srcdir)/$$f $$dst/$$f ; @} \ + done + tar --gzip -chf `cat .fname`.tar.gz `cat .fname` + -rm -rf `cat .fname` .fname +@end example + +Source files that are symbolic links to other file systems cannot be +installed in the temporary directory using @code{ln}, so use @code{cp} +if @code{ln} fails. + +@node Distribution Patches +@section Distribution Patches + +If the program is large, it is useful to make a set of diffs for each +release, against the previous important release. + +At the front of the set of diffs, put a short explanation of which +version this is for and which previous version it is relative to. +Also explain what else people need to do to update the sources +properly (for example, delete or rename certain files before +installing the diffs). + +The purpose of having diffs is that they are small. To keep them +small, exclude files that the user can easily update. For example, +exclude info files, DVI files, tags tables, output files of Bison or +Flex. In Emacs diffs, we exclude compiled Lisp files, leaving it up +to the installer to recompile the patched sources. + +When you make the diffs, each version should be in a directory suitably +named---for example, @file{gcc-2.3.2} and @file{gcc-2.3.3}. This way, +it will be very clear from the diffs themselves which version is which. + +If you use GNU @code{diff} to make the patch, use the options +@samp{-rc2P}. That will put any new files into the output as ``entirely +different.'' + +If the distribution has subdirectories in it, then the diffs probably +include some files in the subdirectories. To help users install such +patches reliably, give them precise directions for how to run patch. +For example, say this: + +@display +To apply these patches, cd to the main directory of the program +and then use `patch -p1'. `-p1' avoids guesswork in choosing +which subdirectory to find each file in. +@end display + +It's wise to test your patch by applying it to a copy of the old +version, and checking that the result exactly matches the new version. + +@node Distribution on prep +@section Distribution on @code{prep} + +Only the latest version of any program needs to be on @code{prep}. Being an +archive of old versions is not the function of @code{prep}. + +Diffs are another matter. Since they are much smaller than +distribution files, it is good to keep the diffs around for quite a +while. + +@node Test Releases +@section Test Releases + +When you release a greatly changed new major version of a program, +you might want to do so as a beta test release. + +Once a program gets to be widely used and people expect it to work +solidly, it is a good idea to do pretest releases before each ``real'' +release. This means that you make a tar file, but send it only to a +group of volunteers that you have recruited. (Use a suitable GNU +mailing list/newsgroup to recruit them.) + +One thing that you should never do is to release a distribution which +is considered a pretest or beta test but which contains the version +number for the planned real release. Many people will look only at +the version number (in the tar file name, in the directory name that +it unpacks into, or wherever they can find it) to determine whether a +tar file is the latest version. People might look at the test release +in this way and mistake it for the real release. Therefore, always +change the number when you make a new tar file. + +If you are about to release version 4.6 but you want to do a pretest +or beta test first, call it 4.5.90. If you need a second pretest, +call it 4.5.91, and so on. + +@contents + +@bye
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kpathsea/make-stds.texi Fri Jul 19 01:57:38 1996 +0000 @@ -0,0 +1,628 @@ +@comment This file is included by both standards.texi and make.texinfo. +@comment It was broken out of standards.texi on 1/6/93 by roland. + +@node Makefile Conventions +@chapter Makefile Conventions +@comment standards.texi does not print an index, but make.texinfo does. +@cindex makefile, conventions for +@cindex conventions for makefiles +@cindex standards for makefiles + +This chapter describes conventions for writing the Makefiles for GNU programs. + +@menu +* Makefile Basics:: +* Utilities in Makefiles:: +* Standard Targets:: +* Command Variables:: +* Directory Variables:: +@end menu + +@node Makefile Basics +@section General Conventions for Makefiles + +Every Makefile should contain this line: + +@example +SHELL = /bin/sh +@end example + +@noindent +to avoid trouble on systems where the @code{SHELL} variable might be +inherited from the environment. (This is never a problem with GNU +@code{make}.) + +Different @code{make} programs have incompatible suffix lists and +implicit rules, and this sometimes creates confusion or misbehavior. So +it is a good idea to set the suffix list explicitly using only the +suffixes you need in the particular Makefile, like this: + +@example +.SUFFIXES: +.SUFFIXES: .c .o +@end example + +@noindent +The first line clears out the suffix list, the second introduces all +suffixes which may be subject to implicit rules in this Makefile. + +Don't assume that @file{.} is in the path for command execution. When +you need to run programs that are a part of your package during the +make, please make sure that it uses @file{./} if the program is built as +part of the make or @file{$(srcdir)/} if the file is an unchanging part +of the source code. Without one of these prefixes, the current search +path is used. + +The distinction between @file{./} and @file{$(srcdir)/} is important +when using the @samp{--srcdir} option to @file{configure}. A rule of +the form: + +@smallexample +foo.1 : foo.man sedscript + sed -e sedscript foo.man > foo.1 +@end smallexample + +@noindent +will fail when the current directory is not the source directory, +because @file{foo.man} and @file{sedscript} are not in the current +directory. + +When using GNU @code{make}, relying on @samp{VPATH} to find the source +file will work in the case where there is a single dependency file, +since the @file{make} automatic variable @samp{$<} will represent the +source file wherever it is. (Many versions of @code{make} set @samp{$<} +only in implicit rules.) A makefile target like + +@smallexample +foo.o : bar.c + $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o +@end smallexample + +@noindent +should instead be written as + +@smallexample +foo.o : bar.c + $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@@ +@end smallexample + +@noindent +in order to allow @samp{VPATH} to work correctly. When the target has +multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest +way to make the rule work well. For example, the target above for +@file{foo.1} is best written as: + +@smallexample +foo.1 : foo.man sedscript + sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@@ +@end smallexample + +@node Utilities in Makefiles +@section Utilities in Makefiles + +Write the Makefile commands (and any shell scripts, such as +@code{configure}) to run in @code{sh}, not in @code{csh}. Don't use any +special features of @code{ksh} or @code{bash}. + +The @code{configure} script and the Makefile rules for building and +installation should not use any utilities directly except these: + +@example +cat cmp cp echo egrep expr grep +ln mkdir mv pwd rm rmdir sed test touch +@end example + +Stick to the generally supported options for these programs. For +example, don't use @samp{mkdir -p}, convenient as it may be, because +most systems don't support it. + +The Makefile rules for building and installation can also use compilers +and related programs, but should do so via @code{make} variables so that the +user can substitute alternatives. Here are some of the programs we +mean: + +@example +ar bison cc flex install ld lex +make makeinfo ranlib texi2dvi yacc +@end example + +Use the following @code{make} variables: + +@example +$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LEX) +$(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC) +@end example + +When you use @code{ranlib}, you should make sure nothing bad happens if +the system does not have @code{ranlib}. Arrange to ignore an error +from that command, and print a message before the command to tell the +user that failure of the @code{ranlib} command does not mean a problem. + +If you use symbolic links, you should implement a fallback for systems +that don't have symbolic links. + +It is ok to use other utilities in Makefile portions (or scripts) +intended only for particular systems where you know those utilities to +exist. + +@node Standard Targets +@section Standard Targets for Users + +All GNU programs should have the following targets in their Makefiles: + +@table @samp +@item all +Compile the entire program. This should be the default target. This +target need not rebuild any documentation files; Info files should +normally be included in the distribution, and DVI files should be made +only when explicitly asked for. + +@item install +Compile the program and copy the executables, libraries, and so on to +the file names where they should reside for actual use. If there is a +simple test to verify that a program is properly installed, this target +should run that test. + +The commands should create all the directories in which files are to be +installed, if they don't already exist. This includes the directories +specified as the values of the variables @code{prefix} and +@code{exec_prefix}, as well as all subdirectories that are needed. +One way to do this is by means of an @code{installdirs} target +as described below. + +Use @samp{-} before any command for installing a man page, so that +@code{make} will ignore any errors. This is in case there are systems +that don't have the Unix man page documentation system installed. + +The way to install Info files is to copy them into @file{$(infodir)} +with @code{$(INSTALL_DATA)} (@pxref{Command Variables}), and then run +the @code{install-info} program if it is present. @code{install-info} +is a script that edits the Info @file{dir} file to add or update the +menu entry for the given Info file; it will be part of the Texinfo package. +Here is a sample rule to install an Info file: + +@comment This example has been carefully formatted for the Make manual. +@comment Please do not reformat it without talking to roland@gnu.ai.mit.edu. +@smallexample +$(infodir)/foo.info: foo.info +# There may be a newer info file in . than in srcdir. + -if test -f foo.info; then d=.; \ + else d=$(srcdir); fi; \ + $(INSTALL_DATA) $$d/foo.info $@@; \ +# Run install-info only if it exists. +# Use `if' instead of just prepending `-' to the +# line so we notice real errors from install-info. +# We use `$(SHELL) -c' because some shells do not +# fail gracefully when there is an unknown command. + if $(SHELL) -c 'install-info --version' \ + >/dev/null 2>&1; then \ + install-info --infodir=$(infodir) $$d/foo.info; \ + else true; fi +@end smallexample + +@item uninstall +Delete all the installed files that the @samp{install} target would +create (but not the noninstalled files such as @samp{make all} would +create). + +@comment The gratuitous blank line here is to make the table look better +@comment in the printed Make manual. Please leave it in. +@item clean + +Delete all files from the current directory that are normally created by +building the program. Don't delete the files that record the +configuration. Also preserve files that could be made by building, but +normally aren't because the distribution comes with them. + +Delete @file{.dvi} files here if they are not part of the distribution. + +@item distclean +Delete all files from the current directory that are created by +configuring or building the program. If you have unpacked the source +and built the program without creating any other files, @samp{make +distclean} should leave only the files that were in the distribution. + +@item mostlyclean +Like @samp{clean}, but may refrain from deleting a few files that people +normally don't want to recompile. For example, the @samp{mostlyclean} +target for GCC does not delete @file{libgcc.a}, because recompiling it +is rarely necessary and takes a lot of time. + +@item realclean +Delete everything from the current directory that can be reconstructed +with this Makefile. This typically includes everything deleted by +@code{distclean}, plus more: C source files produced by Bison, tags tables, +Info files, and so on. + +One exception, however: @samp{make realclean} should not delete +@file{configure} even if @file{configure} can be remade using a rule in +the Makefile. More generally, @samp{make realclean} should not delete +anything that needs to exist in order to run @file{configure} +and then begin to build the program. + +@item TAGS +Update a tags table for this program. + +@item info +Generate any Info files needed. The best way to write the rules is as +follows: + +@smallexample +info: foo.info + +foo.info: foo.texi chap1.texi chap2.texi + $(MAKEINFO) $(srcdir)/foo.texi +@end smallexample + +@noindent +You must define the variable @code{MAKEINFO} in the Makefile. It should +run the @code{makeinfo} program, which is part of the Texinfo +distribution. + +@item dvi +Generate DVI files for all TeXinfo documentation. +For example: + +@smallexample +dvi: foo.dvi + +foo.dvi: foo.texi chap1.texi chap2.texi + $(TEXI2DVI) $(srcdir)/foo.texi +@end smallexample + +@noindent +You must define the variable @code{TEXI2DVI} in the Makefile. It should +run the program @code{texi2dvi}, which is part of the Texinfo +distribution. Alternatively, write just the dependencies, and allow GNU +Make to provide the command. + +@item dist +Create a distribution tar file for this program. The tar file should be +set up so that the file names in the tar file start with a subdirectory +name which is the name of the package it is a distribution for. This +name can include the version number. + +For example, the distribution tar file of GCC version 1.40 unpacks into +a subdirectory named @file{gcc-1.40}. + +The easiest way to do this is to create a subdirectory appropriately +named, use @code{ln} or @code{cp} to install the proper files in it, and +then @code{tar} that subdirectory. + +The @code{dist} target should explicitly depend on all non-source files +that are in the distribution, to make sure they are up to date in the +distribution. +@xref{Releases, , Making Releases, standards, GNU Coding Standards}. + +@item check +Perform self-tests (if any). The user must build the program before +running the tests, but need not install the program; you should write +the self-tests so that they work when the program is built but not +installed. +@end table + +The following targets are suggested as conventional names, for programs +in which they are useful. + +@table @code +@item installcheck +Perform installation tests (if any). The user must build and install +the program before running the tests. You should not assume that +@file{$(bindir)} is in the search path. + +@item installdirs +It's useful to add a target named @samp{installdirs} to create the +directories where files are installed, and their parent directories. +There is a script called @file{mkinstalldirs} which is convenient for +this; find it in the Texinfo package.@c It's in /gd/gnu/lib/mkinstalldirs. +You can use a rule like this: + +@comment This has been carefully formatted to look decent in the Make manual. +@comment Please be sure not to make it extend any further to the right.--roland +@smallexample +# Make sure all installation directories (e.g. $(bindir)) +# actually exist by making them if necessary. +installdirs: mkinstalldirs + $(srcdir)/mkinstalldirs $(bindir) $(datadir) \ + $(libdir) $(infodir) \ + $(mandir) +@end smallexample +@end table + +@node Command Variables +@section Variables for Specifying Commands + +Makefiles should provide variables for overriding certain commands, options, +and so on. + +In particular, you should run most utility programs via variables. +Thus, if you use Bison, have a variable named @code{BISON} whose default +value is set with @samp{BISON = bison}, and refer to it with +@code{$(BISON)} whenever you need to use Bison. + +File management utilities such as @code{ln}, @code{rm}, @code{mv}, and +so on, need not be referred to through variables in this way, since users +don't need to replace them with other programs. + +Each program-name variable should come with an options variable that is +used to supply options to the program. Append @samp{FLAGS} to the +program-name variable name to get the options variable name---for +example, @code{BISONFLAGS}. (The name @code{CFLAGS} is an exception to +this rule, but we keep it because it is standard.) Use @code{CPPFLAGS} +in any compilation command that runs the preprocessor, and use +@code{LDFLAGS} in any compilation command that does linking as well as +in any direct use of @code{ld}. + +If there are C compiler options that @emph{must} be used for proper +compilation of certain files, do not include them in @code{CFLAGS}. +Users expect to be able to specify @code{CFLAGS} freely themselves. +Instead, arrange to pass the necessary options to the C compiler +independently of @code{CFLAGS}, by writing them explicitly in the +compilation commands or by defining an implicit rule, like this: + +@smallexample +CFLAGS = -g +ALL_CFLAGS = -I. $(CFLAGS) +.c.o: + $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $< +@end smallexample + +Do include the @samp{-g} option in @code{CFLAGS}, because that is not +@emph{required} for proper compilation. You can consider it a default +that is only recommended. If the package is set up so that it is +compiled with GCC by default, then you might as well include @samp{-O} +in the default value of @code{CFLAGS} as well. + +Put @code{CFLAGS} last in the compilation command, after other variables +containing compiler options, so the user can use @code{CFLAGS} to +override the others. + +Every Makefile should define the variable @code{INSTALL}, which is the +basic command for installing a file into the system. + +Every Makefile should also define the variables @code{INSTALL_PROGRAM} +and @code{INSTALL_DATA}. (The default for each of these should be +@code{$(INSTALL)}.) Then it should use those variables as the commands +for actual installation, for executables and nonexecutables +respectively. Use these variables as follows: + +@example +$(INSTALL_PROGRAM) foo $(bindir)/foo +$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a +@end example + +@noindent +Always use a file name, not a directory name, as the second argument of +the installation commands. Use a separate command for each file to be +installed. + +@node Directory Variables +@section Variables for Installation Directories + +Installation directories should always be named by variables, so it is +easy to install in a nonstandard place. The standard names for these +variables are described below. They are based on a standard filesystem +layout; variants of it are used in SVR4, 4.4BSD, Linux, Ultrix v4, and +other modern operating systems. + +These two variables set the root for the installation. All the other +installation directories should be subdirectories of one of these two, +and nothing should be directly installed into these two directories. + +@table @samp +@item prefix +A prefix used in constructing the default values of the variables listed +below. The default value of @code{prefix} should be @file{/usr/local} +When building the complete GNU system, the prefix will be empty and +@file{/usr} will be a symbolic link to @file{/}. + +@item exec_prefix +A prefix used in constructing the default values of some of the +variables listed below. The default value of @code{exec_prefix} should +be @code{$(prefix)}. + +Generally, @code{$(exec_prefix)} is used for directories that contain +machine-specific files (such as executables and subroutine libraries), +while @code{$(prefix)} is used directly for other directories. +@end table + +Executable programs are installed in one of the following directories. + +@table @samp +@item bindir +The directory for installing executable programs that users can run. +This should normally be @file{/usr/local/bin}, but write it as +@file{$(exec_prefix)/bin}. + +@item sbindir +The directory for installing executable programs that can be run from +the shell, but are only generally useful to system administrators. This +should normally be @file{/usr/local/sbin}, but write it as +@file{$(exec_prefix)/sbin}. + +@item libexecdir +@comment This paragraph adjusted to avoid overfull hbox --roland 5jul94 +The directory for installing executable programs to be run by other +programs rather than by users. This directory should normally be +@file{/usr/local/libexec}, but write it as @file{$(exec_prefix)/libexec}. +@end table + +Data files used by the program during its execution are divided into +categories in two ways. + +@itemize @bullet +@item +Some files are normally modified by programs; others are never normally +modified (though users may edit some of these). + +@item +Some files are architecture-independent and can be shared by all +machines at a site; some are architecture-dependent and can be shared +only by machines of the same kind and operating system; others may never +be shared between two machines. +@end itemize + +This makes for six different possibilities. However, we want to +discourage the use of architecture-dependent files, aside from of object +files and libraries. It is much cleaner to make other data files +architecture-independent, and it is generally not hard. + +Therefore, here are the variables makefiles should use to specify +directories: + +@table @samp +@item datadir +The directory for installing read-only architecture independent data +files. This should normally be @file{/usr/local/share}, but write it as +@file{$(prefix)/share}. As a special exception, see @file{$(infodir)} +and @file{$(includedir)} below. + +@item sysconfdir +The directory for installing read-only data files that pertain to a +single machine--that is to say, files for configuring a host. Mailer +and network configuration files, @file{/etc/passwd}, and so forth belong +here. All the files in this directory should be ordinary ASCII text +files. This directory should normally be @file{/usr/local/etc}, but +write it as @file{$(prefix)/etc}. + +@c rewritten to avoid overfull hbox --tower +Do not install executables +@c here +in this directory (they probably +belong in @file{$(libexecdir)} or @file{$(sbindir))}. Also do not +install files that are modified in the normal course of their use +(programs whose purpose is to change the configuration of the system +excluded). Those probably belong in @file{$(localstatedir)}. + +@item sharedstatedir +The directory for installing architecture-independent data files which +the programs modify while they run. This should normally be +@file{/usr/local/com}, but write it as @file{$(prefix)/com}. + +@item localstatedir +The directory for installing data files which the programs modify while +they run, and that pertain to one specific machine. Users should never +need to modify files in this directory to configure the package's +operation; put such configuration information in separate files that go +in @file{datadir} or @file{$(sysconfdir)}. @file{$(localstatedir)} +should normally be @file{/usr/local/var}, but write it as +@file{$(prefix)/var}. + +@item libdir +The directory for object files and libraries of object code. Do not +install executables here, they probably belong in @file{$(libexecdir)} +instead. The value of @code{libdir} should normally be +@file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}. + +@item infodir +The directory for installing the Info files for this package. By +default, it should be @file{/usr/local/info}, but it should be written +as @file{$(prefix)/info}. + +@item includedir +@c rewritten to avoid overfull hbox --roland +The directory for installing header files to be included by user +programs with the C @samp{#include} preprocessor directive. This +should normally be @file{/usr/local/include}, but write it as +@file{$(prefix)/include}. + +Most compilers other than GCC do not look for header files in +@file{/usr/local/include}. So installing the header files this way is +only useful with GCC. Sometimes this is not a problem because some +libraries are only really intended to work with GCC. But some libraries +are intended to work with other compilers. They should install their +header files in two places, one specified by @code{includedir} and one +specified by @code{oldincludedir}. + +@item oldincludedir +The directory for installing @samp{#include} header files for use with +compilers other than GCC. This should normally be @file{/usr/include}. + +The Makefile commands should check whether the value of +@code{oldincludedir} is empty. If it is, they should not try to use +it; they should cancel the second installation of the header files. + +A package should not replace an existing header in this directory unless +the header came from the same package. Thus, if your Foo package +provides a header file @file{foo.h}, then it should install the header +file in the @code{oldincludedir} directory if either (1) there is no +@file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo +package. + +To tell whether @file{foo.h} came from the Foo package, put a magic +string in the file---part of a comment---and grep for that string. +@end table + +Unix-style man pages are installed in one of the following: + +@table @samp +@item mandir +The directory for installing the man pages (if any) for this package. +It should include the suffix for the proper section of the +manual---usually @samp{1} for a utility. It will normally be +@file{/usr/local/man/man1}, but you should write it as +@file{$(prefix)/man/man1}. + +@item man1dir +The directory for installing section 1 man pages. +@item man2dir +The directory for installing section 2 man pages. +@item @dots{} +Use these names instead of @samp{mandir} if the package needs to install man +pages in more than one section of the manual. + +@strong{Don't make the primary documentation for any GNU software be a +man page. Write a manual in Texinfo instead. Man pages are just for +the sake of people running GNU software on Unix, which is a secondary +application only.} + +@item manext +The file name extension for the installed man page. This should contain +a period followed by the appropriate digit; it should normally be @samp{.1}. + +@item man1ext +The file name extension for installed section 1 man pages. +@item man2ext +The file name extension for installed section 2 man pages. +@item @dots{} +Use these names instead of @samp{manext} if the package needs to install man +pages in more than one section of the manual. +@end table + +And finally, you should set the following variable: + +@table @samp +@item srcdir +The directory for the sources being compiled. The value of this +variable is normally inserted by the @code{configure} shell script. +@end table + +For example: + +@smallexample +@c I have changed some of the comments here slightly to fix an overfull +@c hbox, so the make manual can format correctly. --roland +# Common prefix for installation directories. +# NOTE: This directory must exist when you start the install. +prefix = /usr/local +exec_prefix = $(prefix) +# Where to put the executable for the command `gcc'. +bindir = $(exec_prefix)/bin +# Where to put the directories used by the compiler. +libexecdir = $(exec_prefix)/libexec +# Where to put the Info files. +infodir = $(prefix)/info +@end smallexample + +If your program installs a large number of files into one of the +standard user-specified directories, it might be useful to group them +into a subdirectory particular to that program. If you do this, you +should write the @code{install} rule to create these subdirectories. + +Do not expect the user to include the subdirectory name in the value of +any of the variables listed above. The idea of having a uniform set of +variable names for installation directories is to enable the user to +specify the exact same values for several different GNU packages. In +order for this to be useful, all the packages must be designed so that +they will work sensibly when the user does so. +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kpathsea/standards.texi Fri Jul 19 01:57:38 1996 +0000 @@ -0,0 +1,2451 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename standards.info +@settitle GNU Coding Standards +@c UPDATE THIS DATE WHENEVER YOU MAKE CHANGES! +@set lastupdate 17 November 1994 +@c %**end of header + +@ifinfo +@format +START-INFO-DIR-ENTRY +* Standards: (standards). GNU coding standards. +END-INFO-DIR-ENTRY +@end format +@end ifinfo + +@setchapternewpage off + +@ifinfo +GNU Coding Standards +Copyright (C) 1992, 1993, 1994 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 GNU Coding Standards +@author Richard Stallman +@author last updated @value{lastupdate} +@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, Preface, (dir), (dir) +@top Version + +Last updated @value{lastupdate}. +@end ifinfo + +@menu +* Preface:: About the GNU Coding Standards +* Reading Non-Free Code:: Referring to Proprietary Programs +* Contributions:: Accepting Contributions +* Change Logs:: Recording Changes +* Compatibility:: Compatibility with Other Implementations +* Makefile Conventions:: Makefile Conventions +* Configuration:: How Configuration Should Work +* Source Language:: Using Languages Other Than C +* Formatting:: Formatting Your Source Code +* Comments:: Commenting Your Work +* Syntactic Conventions:: Clean Use of C Constructs +* Names:: Naming Variables and Functions +* Using Extensions:: Using Non-standard Features +* System Functions:: Portability and ``standard'' library functions +* Semantics:: Program Behavior for All Programs +* Errors:: Formatting Error Messages +* Libraries:: Library Behavior +* Portability:: Portability As It Applies to GNU +* User Interfaces:: Standards for Command Line Interfaces +* Documentation:: Documenting Programs +* Releases:: Making Releases +@end menu + +@node Preface +@chapter About the GNU Coding Standards + +The GNU Coding Standards were written by Richard Stallman and other GNU +Project volunteers. Their purpose is to make the GNU system clean, +consistent, and easy to install. This document can also be read as a +guide to write portable, robust and reliable programs. It focuses on +programs written in C, but many of the rules and principles are useful +even if you write in another programming language. The rules often +state reasons for writing in a certain way. + +Corrections or suggestions regarding this document should be sent to +@code{gnu@@prep.ai.mit.edu}. If you make a suggestion, please include a +suggested new wording for it; our time is limited. We prefer a context +diff to the @file{standards.texi} or @file{make-stds.texi} files, but if +you don't have those files, please mail your suggestion anyway. + +This release of the GNU Coding Standards was last updated +@value{lastupdate}. + +@node Reading Non-Free Code +@chapter Referring to Proprietary Programs + +Don't in any circumstances refer to Unix source code for or during +your work on GNU! (Or to any other proprietary programs.) + +If you have a vague recollection of the internals of a Unix program, +this does not absolutely mean you can't write an imitation of it, but +do try to organize the imitation internally along different lines, +because this is likely to make the details of the Unix version +irrelevant and dissimilar to your results. + +For example, Unix utilities were generally optimized to minimize +memory use; if you go for speed instead, your program will be very +different. You could keep the entire input file in core and scan it +there instead of using stdio. Use a smarter algorithm discovered more +recently than the Unix program. Eliminate use of temporary files. Do +it in one pass instead of two (we did this in the assembler). + +Or, on the contrary, emphasize simplicity instead of speed. For some +applications, the speed of today's computers makes simpler algorithms +adequate. + +Or go for generality. For example, Unix programs often have static +tables or fixed-size strings, which make for arbitrary limits; use +dynamic allocation instead. Make sure your program handles NULs and +other funny characters in the input files. Add a programming language +for extensibility and write part of the program in that language. + +Or turn some parts of the program into independently usable libraries. +Or use a simple garbage collector instead of tracking precisely when +to free memory, or use a new GNU facility such as obstacks. + + +@node Contributions +@chapter Accepting Contributions + +If someone else sends you a piece of code to add to the program you are +working on, we need legal papers to use it---the same sort of legal +papers we will need to get from you. @emph{Each} significant +contributor to a program must sign some sort of legal papers in order +for us to have clear title to the program. The main author alone is not +enough. + +So, before adding in any contributions from other people, tell us +so we can arrange to get the papers. Then wait until we tell you +that we have received the signed papers, before you actually use the +contribution. + +This applies both before you release the program and afterward. If +you receive diffs to fix a bug, and they make significant change, we +need legal papers for it. + +You don't need papers for changes of a few lines here or there, since +they are not significant for copyright purposes. Also, you don't need +papers if all you get from the suggestion is some ideas, not actual code +which you use. For example, if you write a different solution to the +problem, you don't need to get papers. + +I know this is frustrating; it's frustrating for us as well. But if +you don't wait, you are going out on a limb---for example, what if the +contributor's employer won't sign a disclaimer? You might have to take +that code out again! + +The very worst thing is if you forget to tell us about the other +contributor. We could be very embarrassed in court some day as a +result. + +@node Change Logs +@chapter Change Logs + +Keep a change log for each directory, describing the changes made to +source files in that directory. The purpose of this is so that people +investigating bugs in the future will know about the changes that +might have introduced the bug. Often a new bug can be found by +looking at what was recently changed. More importantly, change logs +can help eliminate conceptual inconsistencies between different parts +of a program; they can give you a history of how the conflicting +concepts arose. + +Use the Emacs command @kbd{M-x add-change-log-entry} to start a new +entry in the +change log. An entry should have an asterisk, the name of the changed +file, and then in parentheses the name of the changed functions, +variables or whatever, followed by a colon. Then describe the changes +you made to that function or variable. + +Separate unrelated entries with blank lines. When two entries +represent parts of the same change, so that they work together, then +don't put blank lines between them. Then you can omit the file name +and the asterisk when successive entries are in the same file. + +Here are some examples: + +@example +* register.el (insert-register): Return nil. +(jump-to-register): Likewise. + +* sort.el (sort-subr): Return nil. + +* tex-mode.el (tex-bibtex-file, tex-file, tex-region): +Restart the tex shell if process is gone or stopped. +(tex-shell-running): New function. + +* expr.c (store_one_arg): Round size up for move_block_to_reg. +(expand_call): Round up when emitting USE insns. +* stmt.c (assign_parms): Round size up for move_block_from_reg. +@end example + +It's important to name the changed function or variable in full. Don't +abbreviate them; don't combine them. Subsequent maintainers will often +search for a function name to find all the change log entries that +pertain to it; if you abbreviate the name, they won't find it when they +search. For example, some people are tempted to abbreviate groups of +function names by writing @samp{* register.el +(@{insert,jump-to@}-register)}; this is not a good idea, since searching +for @code{jump-to-register} or @code{insert-register} would not find the +entry. + +There's no need to describe the full purpose of the changes or how they +work together. It is better to put such explanations in comments in the +code. That's why just ``New function'' is enough; there is a comment +with the function in the source to explain what it does. + +However, sometimes it is useful to write one line to describe the +overall purpose of a large batch of changes. + +You can think of the change log as a conceptual ``undo list'' which +explains how earlier versions were different from the current version. +People can see the current version; they don't need the change log +to tell them what is in it. What they want from a change log is a +clear explanation of how the earlier version differed. + +When you change the calling sequence of a function in a simple +fashion, and you change all the callers of the function, there is no +need to make individual entries for all the callers. Just write in +the entry for the function being called, ``All callers changed.'' + +When you change just comments or doc strings, it is enough to write an +entry for the file, without mentioning the functions. Write just, +``Doc fix.'' There's no need to keep a change log for documentation +files. This is because documentation is not susceptible to bugs that +are hard to fix. Documentation does not consist of parts that must +interact in a precisely engineered fashion; to correct an error, you +need not know the history of the erroneous passage. + + +@node Compatibility +@chapter Compatibility with Other Implementations + +With certain exceptions, utility programs and libraries for GNU should +be upward compatible with those in Berkeley Unix, and upward compatible +with @sc{ANSI} C if @sc{ANSI} C specifies their behavior, and upward +compatible with @sc{POSIX} if @sc{POSIX} specifies their behavior. + +When these standards conflict, it is useful to offer compatibility +modes for each of them. + +@sc{ANSI} C and @sc{POSIX} prohibit many kinds of extensions. Feel +free to make the extensions anyway, and include a @samp{--ansi} or +@samp{--compatible} option to turn them off. However, if the extension +has a significant chance of breaking any real programs or scripts, +then it is not really upward compatible. Try to redesign its +interface. + +Many GNU programs suppress extensions that conflict with POSIX if the +environment variable @code{POSIXLY_CORRECT} is defined (even if it is +defined with a null value). Please make your program recognize this +variable if appropriate. + +When a feature is used only by users (not by programs or command +files), and it is done poorly in Unix, feel free to replace it +completely with something totally different and better. (For example, +vi is replaced with Emacs.) But it is nice to offer a compatible +feature as well. (There is a free vi clone, so we offer it.) + +Additional useful features not in Berkeley Unix are welcome. +Additional programs with no counterpart in Unix may be useful, +but our first priority is usually to duplicate what Unix already +has. + +@comment The makefile standards are in a separate file that is also +@comment included by make.texinfo. Done by roland@gnu.ai.mit.edu on 1/6/93. +@include make-stds.texi + +@node Configuration +@chapter How Configuration Should Work + +Each GNU distribution should come with a shell script named +@code{configure}. This script is given arguments which describe the +kind of machine and system you want to compile the program for. + +The @code{configure} script must record the configuration options so +that they affect compilation. + +One way to do this is to make a link from a standard name such as +@file{config.h} to the proper configuration file for the chosen system. +If you use this technique, the distribution should @emph{not} contain a +file named @file{config.h}. This is so that people won't be able to +build the program without configuring it first. + +Another thing that @code{configure} can do is to edit the Makefile. If +you do this, the distribution should @emph{not} contain a file named +@file{Makefile}. Instead, include a file @file{Makefile.in} which +contains the input used for editing. Once again, this is so that people +won't be able to build the program without configuring it first. + +If @code{configure} does write the @file{Makefile}, then @file{Makefile} +should have a target named @file{Makefile} which causes @code{configure} +to be rerun, setting up the same configuration that was set up last +time. The files that @code{configure} reads should be listed as +dependencies of @file{Makefile}. + +All the files which are output from the @code{configure} script should +have comments at the beginning explaining that they were generated +automatically using @code{configure}. This is so that users won't think +of trying to edit them by hand. + +The @code{configure} script should write a file named @file{config.status} +which describes which configuration options were specified when the +program was last configured. This file should be a shell script which, +if run, will recreate the same configuration. + +The @code{configure} script should accept an option of the form +@samp{--srcdir=@var{dirname}} to specify the directory where sources are found +(if it is not the current directory). This makes it possible to build +the program in a separate directory, so that the actual source directory +is not modified. + +If the user does not specify @samp{--srcdir}, then @code{configure} should +check both @file{.} and @file{..} to see if it can find the sources. If +it finds the sources in one of these places, it should use them from +there. Otherwise, it should report that it cannot find the sources, and +should exit with nonzero status. + +Usually the easy way to support @samp{--srcdir} is by editing a +definition of @code{VPATH} into the Makefile. Some rules may need to +refer explicitly to the specified source directory. To make this +possible, @code{configure} can add to the Makefile a variable named +@code{srcdir} whose value is precisely the specified directory. + +The @code{configure} script should also take an argument which specifies the +type of system to build the program for. This argument should look like +this: + +@example +@var{cpu}-@var{company}-@var{system} +@end example + +For example, a Sun 3 might be @samp{m68k-sun-sunos4.1}. + +The @code{configure} script needs to be able to decode all plausible +alternatives for how to describe a machine. Thus, @samp{sun3-sunos4.1} +would be a valid alias. For many programs, @samp{vax-dec-ultrix} would +be an alias for @samp{vax-dec-bsd}, simply because the differences +between Ultrix and @sc{BSD} are rarely noticeable, but a few programs +might need to distinguish them. +@c Real 4.4BSD now runs on some Suns. + +There is a shell script called @file{config.sub} that you can use +as a subroutine to validate system types and canonicalize aliases. + +Other options are permitted to specify in more detail the software +or hardware present on the machine, and include or exclude optional +parts of the package: + +@table @samp +@item --enable-@var{feature}@r{[}=@var{parameter}@r{]} +Configure the package to build and install an optional user-level +facility called @var{feature}. This allows users to choose which +optional features to include. Giving an optional @var{parameter} of +@samp{no} should omit @var{feature}, if it is built by default. + +No @samp{--enable} option should @strong{ever} cause one feature to +replace another. No @samp{--enable} option should ever substitute one +useful behavior for another useful behavior. The only proper use for +@samp{--enable} is for questions of whether to build part of the program +or exclude it. + +@item --with-@var{package} +@c @r{[}=@var{parameter}@r{]} +The package @var{package} will be installed, so configure this package +to work with @var{package}. + +@c Giving an optional @var{parameter} of +@c @samp{no} should omit @var{package}, if it is used by default. + +Possible values of @var{package} include @samp{x}, @samp{x-toolkit}, +@samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc}, and +@samp{gdb}. + +Do not use a @samp{--with} option to specify the file name to use to +find certain files. That is outside the scope of what @samp{--with} +options are for. + +@item --nfp +The target machine has no floating point processor. + +@item --gas +The target machine assembler is GAS, the GNU assembler. +This is obsolete; users should use @samp{--with-gnu-as} instead. + +@item --x +The target machine has the X Window System installed. +This is obsolete; users should use @samp{--with-x} instead. +@end table + +All @code{configure} scripts should accept all of these ``detail'' +options, whether or not they make any difference to the particular +package at hand. In particular, they should accept any option that +starts with @samp{--with-} or @samp{--enable-}. This is so users will +be able to configure an entire GNU source tree at once with a single set +of options. + +You will note that the categories @samp{--with-} and @samp{--enable-} +are narrow: they @strong{do not} provide a place for any sort of option +you might think of. That is deliberate. We want to limit the possible +configuration options in GNU software. We do not want GNU programs to +have idiosyncratic configuration options. + +Packages that perform part of compilation may support cross-compilation. +In such a case, the host and target machines for the program may be +different. The @code{configure} script should normally treat the +specified type of system as both the host and the target, thus producing +a program which works for the same type of machine that it runs on. + +The way to build a cross-compiler, cross-assembler, or what have you, is +to specify the option @samp{--host=@var{hosttype}} when running +@code{configure}. This specifies the host system without changing the +type of target system. The syntax for @var{hosttype} is the same as +described above. + +Bootstrapping a cross-compiler requires compiling it on a machine other +than the host it will run on. Compilation packages accept a +configuration option @samp{--build=@var{hosttype}} for specifying the +configuration on which you will compile them, in case that is different +from the host. + +Programs for which cross-operation is not meaningful need not accept the +@samp{--host} option, because configuring an entire operating system for +cross-operation is not a meaningful thing. + +Some programs have ways of configuring themselves automatically. If +your program is set up to do this, your @code{configure} script can simply +ignore most of its arguments. + +@node Source Language +@chapter Using Languages Other Than C + +Using a language other than C is like using a non-standard feature: it +will cause trouble for users. Even if GCC supports the other language, +users may find it inconvenient to have to install the compiler for that +other language in order to build your program. So please write in C. + +There are three exceptions for this rule: + +@itemize @bullet +@item +It is okay to use a special language if the same program contains an +interpreter for that language. + +Thus, it is not a problem that GNU Emacs contains code written in Emacs +Lisp, because it comes with a Lisp interpreter. + +@item +It is okay to use another language in a tool specifically intended for +use with that language. + +This is okay because the only people who want to build the tool will be +those who have installed the other language anyway. + +@item +If an application is not of extremely widespread interest, then perhaps +it's not important if the application is inconvenient to install. +@end itemize + +@node Formatting +@chapter Formatting Your Source Code + +It is important to put the open-brace that starts the body of a C +function in column zero, and avoid putting any other open-brace or +open-parenthesis or open-bracket in column zero. Several tools look +for open-braces in column zero to find the beginnings of C functions. +These tools will not work on code not formatted that way. + +It is also important for function definitions to start the name of the +function in column zero. This helps people to search for function +definitions, and may also help certain tools recognize them. Thus, +the proper format is this: + +@example +static char * +concat (s1, s2) /* Name starts in column zero here */ + char *s1, *s2; +@{ /* Open brace in column zero here */ + @dots{} +@} +@end example + +@noindent +or, if you want to use @sc{ANSI} C, format the definition like this: + +@example +static char * +concat (char *s1, char *s2) +@{ + @dots{} +@} +@end example + +In @sc{ANSI} C, if the arguments don't fit nicely on one line, +split it like this: + +@example +int +lots_of_args (int an_integer, long a_long, short a_short, + double a_double, float a_float) +@dots{} +@end example + +For the body of the function, we prefer code formatted like this: + +@example +if (x < foo (y, z)) + haha = bar[4] + 5; +else + @{ + while (z) + @{ + haha += foo (z, z); + z--; + @} + return ++x + bar (); + @} +@end example + +We find it easier to read a program when it has spaces before the +open-parentheses and after the commas. Especially after the commas. + +When you split an expression into multiple lines, split it +before an operator, not after one. Here is the right way: + +@example +if (foo_this_is_long && bar > win (x, y, z) + && remaining_condition) +@end example + +Try to avoid having two operators of different precedence at the same +level of indentation. For example, don't write this: + +@example +mode = (inmode[j] == VOIDmode + || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]) + ? outmode[j] : inmode[j]); +@end example + +Instead, use extra parentheses so that the indentation shows the nesting: + +@example +mode = ((inmode[j] == VOIDmode + || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]))) + ? outmode[j] : inmode[j]); +@end example + +Insert extra parentheses so that Emacs will indent the code properly. +For example, the following indentation looks nice if you do it by hand, +but Emacs would mess it up: + +@example +v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 + + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000; +@end example + +But adding a set of parentheses solves the problem: + +@example +v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 + + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000); +@end example + +Format do-while statements like this: + +@example +do + @{ + a = foo (a); + @} +while (a > 0); +@end example + +Please use formfeed characters (control-L) to divide the program into +pages at logical places (but not within a function). It does not matter +just how long the pages are, since they do not have to fit on a printed +page. The formfeeds should appear alone on lines by themselves. + + +@node Comments +@chapter Commenting Your Work + +Every program should start with a comment saying briefly what it is for. +Example: @samp{fmt - filter for simple filling of text}. + +Please put a comment on each function saying what the function does, +what sorts of arguments it gets, and what the possible values of +arguments mean and are used for. It is not necessary to duplicate in +words the meaning of the C argument declarations, if a C type is being +used in its customary fashion. If there is anything nonstandard about +its use (such as an argument of type @code{char *} which is really the +address of the second character of a string, not the first), or any +possible values that would not work the way one would expect (such as, +that strings containing newlines are not guaranteed to work), be sure +to say so. + +Also explain the significance of the return value, if there is one. + +Please put two spaces after the end of a sentence in your comments, so +that the Emacs sentence commands will work. Also, please write +complete sentences and capitalize the first word. If a lower-case +identifer comes at the beginning of a sentence, don't capitalize it! +Changing the spelling makes it a different identifier. If you don't +like starting a sentence with a lower case letter, write the sentence +differently (e.g., ``The identifier lower-case is @dots{}''). + +The comment on a function is much clearer if you use the argument +names to speak about the argument values. The variable name itself +should be lower case, but write it in upper case when you are speaking +about the value rather than the variable itself. Thus, ``the inode +number NODE_NUM'' rather than ``an inode''. + +There is usually no purpose in restating the name of the function in +the comment before it, because the reader can see that for himself. +There might be an exception when the comment is so long that the function +itself would be off the bottom of the screen. + +There should be a comment on each static variable as well, like this: + +@example +/* Nonzero means truncate lines in the display; + zero means continue them. */ +int truncate_lines; +@end example + +Every @samp{#endif} should have a comment, except in the case of short +conditionals (just a few lines) that are not nested. The comment should +state the condition of the conditional that is ending, @emph{including +its sense}. @samp{#else} should have a comment describing the condition +@emph{and sense} of the code that follows. For example: + +@example +#ifdef foo + @dots{} +#else /* not foo */ + @dots{} +#endif /* not foo */ +@end example + +@noindent +but, by contrast, write the comments this way for a @samp{#ifndef}: + +@example +#ifndef foo + @dots{} +#else /* foo */ + @dots{} +#endif /* foo */ +@end example + + +@node Syntactic Conventions +@chapter Clean Use of C Constructs + +Please explicitly declare all arguments to functions. +Don't omit them just because they are @code{int}s. + +Declarations of external functions and functions to appear later in the +source file should all go in one place near the beginning of the file +(somewhere before the first function definition in the file), or else +should go in a header file. Don't put @code{extern} declarations inside +functions. + +It used to be common practice to use the same local variables (with +names like @code{tem}) over and over for different values within one +function. Instead of doing this, it is better declare a separate local +variable for each distinct purpose, and give it a name which is +meaningful. This not only makes programs easier to understand, it also +facilitates optimization by good compilers. You can also move the +declaration of each local variable into the smallest scope that includes +all its uses. This makes the program even cleaner. + +Don't use local variables or parameters that shadow global identifiers. + +Don't declare multiple variables in one declaration that spans lines. +Start a new declaration on each line, instead. For example, instead +of this: + +@example +int foo, + bar; +@end example + +@noindent +write either this: + +@example +int foo, bar; +@end example + +@noindent +or this: + +@example +int foo; +int bar; +@end example + +@noindent +(If they are global variables, each should have a comment preceding it +anyway.) + +When you have an @code{if}-@code{else} statement nested in another +@code{if} statement, always put braces around the @code{if}-@code{else}. +Thus, never write like this: + +@example +if (foo) + if (bar) + win (); + else + lose (); +@end example + +@noindent +always like this: + +@example +if (foo) + @{ + if (bar) + win (); + else + lose (); + @} +@end example + +If you have an @code{if} statement nested inside of an @code{else} +statement, either write @code{else if} on one line, like this, + +@example +if (foo) + @dots{} +else if (bar) + @dots{} +@end example + +@noindent +with its @code{then}-part indented like the preceding @code{then}-part, +or write the nested @code{if} within braces like this: + +@example +if (foo) + @dots{} +else + @{ + if (bar) + @dots{} + @} +@end example + +Don't declare both a structure tag and variables or typedefs in the +same declaration. Instead, declare the structure tag separately +and then use it to declare the variables or typedefs. + +Try to avoid assignments inside @code{if}-conditions. For example, +don't write this: + +@example +if ((foo = (char *) malloc (sizeof *foo)) == 0) + fatal ("virtual memory exhausted"); +@end example + +@noindent +instead, write this: + +@example +foo = (char *) malloc (sizeof *foo); +if (foo == 0) + fatal ("virtual memory exhausted"); +@end example + +Don't make the program ugly to placate @code{lint}. Please don't insert any +casts to @code{void}. Zero without a cast is perfectly fine as a null +pointer constant. + +@node Names +@chapter Naming Variables and Functions + +Please use underscores to separate words in a name, so that the Emacs +word commands can be useful within them. Stick to lower case; reserve +upper case for macros and @code{enum} constants, and for name-prefixes +that follow a uniform convention. + +For example, you should use names like @code{ignore_space_change_flag}; +don't use names like @code{iCantReadThis}. + +Variables that indicate whether command-line options have been +specified should be named after the meaning of the option, not after +the option-letter. A comment should state both the exact meaning of +the option and its letter. For example, + +@example +/* Ignore changes in horizontal whitespace (-b). */ +int ignore_space_change_flag; +@end example + +When you want to define names with constant integer values, use +@code{enum} rather than @samp{#define}. GDB knows about enumeration +constants. + +Use file names of 14 characters or less, to avoid creating gratuitous +problems on System V. You can use the program @code{doschk} to test for +this. @code{doschk} also tests for potential name conflicts if the +files were loaded onto an MS-DOS file system---something you may or may +not care about. + + +@node Using Extensions +@chapter Using Non-standard Features + +Many GNU facilities that already exist support a number of convenient +extensions over the comparable Unix facilities. Whether to use these +extensions in implementing your program is a difficult question. + +On the one hand, using the extensions can make a cleaner program. +On the other hand, people will not be able to build the program +unless the other GNU tools are available. This might cause the +program to work on fewer kinds of machines. + +With some extensions, it might be easy to provide both alternatives. +For example, you can define functions with a ``keyword'' @code{INLINE} +and define that as a macro to expand into either @code{inline} or +nothing, depending on the compiler. + +In general, perhaps it is best not to use the extensions if you can +straightforwardly do without them, but to use the extensions if they +are a big improvement. + +An exception to this rule are the large, established programs (such as +Emacs) which run on a great variety of systems. Such programs would +be broken by use of GNU extensions. + +Another exception is for programs that are used as part of +compilation: anything that must be compiled with other compilers in +order to bootstrap the GNU compilation facilities. If these require +the GNU compiler, then no one can compile them without having them +installed already. That would be no good. + +Since most computer systems do not yet implement @sc{ANSI} C, using the +@sc{ANSI} C features is effectively using a GNU extension, so the +same considerations apply. (Except for @sc{ANSI} features that we +discourage, such as trigraphs---don't ever use them.) + + +@node System Functions +@chapter Calling System Functions + +C implementations differ substantially. ANSI C reduces but does not +eliminate the incompatibilities; meanwhile, many users wish to compile +GNU software with pre-ANSI compilers. This chapter gives +recommendations for how to use the more or less standard C library +functions to avoid unnecessary loss of portability. + +@itemize @bullet +@item +Don't use the value of @code{sprintf}. It returns the number of +characters written on some systems, but not on all systems. + +@item +Don't declare system functions explicitly. + +Almost any declaration for a system function is wrong on some system. +To minimize conflicts, leave it to the system header files to declare +system functions. If the headers don't declare a function, let it +remain undeclared. + +While it may seem unclean to use a function without declaring it, in +practice this works fine for most system library functions on the +systems where this really happens. The problem is only theoretical. By +contrast, actual declarations have frequently caused actual conflicts. + +@item +If you must declare a system function, don't specify the argument types. +Use an old-style declaration, not an ANSI prototype. The more you +specify about the function, the more likely a conflict. + +@item +In particular, don't unconditionally declare @code{malloc} or +@code{realloc}. + +Most GNU programs use those functions just once, in functions +conventionally named @code{xmalloc} and @code{xrealloc}. These +functions call @code{malloc} and @code{realloc}, respectively, and +check the results. + +Because @code{xmalloc} and @code{xrealloc} are defined in your program, +you can declare them in other files without any risk of type conflict. + +On most systems, @code{int} is the same length as a pointer; thus, the +calls to @code{malloc} and @code{realloc} work fine. For the few +exceptional systems (mostly 64-bit machines), you can use +@strong{conditionalized} declarations of @code{malloc} and +@code{realloc}---or put these declarations in configuration files +specific to those systems. + +@item +The string functions require special treatment. Some Unix systems have +a header file @file{string.h}; other have @file{strings.h}. Neither +file name is portable. There are two things you can do: use Autoconf to +figure out which file to include, or don't include either file. + +@item +If you don't include either strings file, you can't get declarations for +the string functions from the header file in the usual way. + +That causes less of a problem than you might think. The newer ANSI +string functions are off-limits anyway because many systems still don't +support them. The string functions you can use are these: + +@example +strcpy strncpy strcat strncat +strlen strcmp strncmp +strchr strrchr +@end example + +The copy and concatenate functions work fine without a declaration as +long as you don't use their values. Using their values without a +declaration fails on systems where the width of a pointer differs from +the width of @code{int}, and perhaps in other cases. It is trivial to +avoid using their values, so do that. + +The compare functions and @code{strlen} work fine without a declaration +on most systems, possibly all the ones that GNU software runs on. +You may find it necessary to declare them @strong{conditionally} on a +few systems. + +The search functions must be declared to return @code{char *}. Luckily, +there is no variation in the data type they return. But there is +variation in their names. Some systems give these functions the names +@code{index} and @code{rindex}; other systems use the names +@code{strchr} and @code{strrchr}. Some systems support both pairs of +names, but neither pair works on all systems. + +You should pick a single pair of names and use it throughout your +program. (Nowadays, it is better to choose @code{strchr} and +@code{strrchr}.) Declare both of those names as functions returning +@code{char *}. On systems which don't support those names, define them +as macros in terms of the other pair. For example, here is what to put +at the beginning of your file (or in a header) if you want to use the +names @code{strchr} and @code{strrchr} throughout: + +@example +#ifndef HAVE_STRCHR +#define strchr index +#endif +#ifndef HAVE_STRRCHR +#define strrchr rindex +#endif + +char *strchr (); +char *strrchr (); +@end example +@end itemize + +Here we assume that @code{HAVE_STRCHR} and @code{HAVE_STRRCHR} are +macros defined in systems where the corresponding functions exist. +One way to get them properly defined is to use Autoconf. + +@node Semantics +@chapter Program Behavior for All Programs + +Avoid arbitrary limits on the length or number of @emph{any} data +structure, including filenames, lines, files, and symbols, by allocating +all data structures dynamically. In most Unix utilities, ``long lines +are silently truncated''. This is not acceptable in a GNU utility. + +Utilities reading files should not drop NUL characters, or any other +nonprinting characters @emph{including those with codes above 0177}. The +only sensible exceptions would be utilities specifically intended for +interface to certain types of printers that can't handle those characters. + +Check every system call for an error return, unless you know you wish to +ignore errors. Include the system error text (from @code{perror} or +equivalent) in @emph{every} error message resulting from a failing +system call, as well as the name of the file if any and the name of the +utility. Just ``cannot open foo.c'' or ``stat failed'' is not +sufficient. + +Check every call to @code{malloc} or @code{realloc} to see if it +returned zero. Check @code{realloc} even if you are making the block +smaller; in a system that rounds block sizes to a power of 2, +@code{realloc} may get a different block if you ask for less space. + +In Unix, @code{realloc} can destroy the storage block if it returns +zero. GNU @code{realloc} does not have this bug: if it fails, the +original block is unchanged. Feel free to assume the bug is fixed. If +you wish to run your program on Unix, and wish to avoid lossage in this +case, you can use the GNU @code{malloc}. + +You must expect @code{free} to alter the contents of the block that was +freed. Anything you want to fetch from the block, you must fetch before +calling @code{free}. + +If @code{malloc} fails in a noninteractive program, make that a fatal +error. In an interactive program (one that reads commands from the +user), it is better to abort the command and return to the command +reader loop. This allows the user to kill other processes to free up +virtual memory, and then try the command again. + +Use @code{getopt_long} to decode arguments, unless the argument syntax +makes this unreasonable. + +When static storage is to be written in during program execution, use +explicit C code to initialize it. Reserve C initialized declarations +for data that will not be changed. + +Try to avoid low-level interfaces to obscure Unix data structures (such +as file directories, utmp, or the layout of kernel memory), since these +are less likely to work compatibly. If you need to find all the files +in a directory, use @code{readdir} or some other high-level interface. +These will be supported compatibly by GNU. + +By default, the GNU system will provide the signal handling functions of +@sc{BSD} and of @sc{POSIX}. So GNU software should be written to use +these. + +In error checks that detect ``impossible'' conditions, just abort. +There is usually no point in printing any message. These checks +indicate the existence of bugs. Whoever wants to fix the bugs will have +to read the source code and run a debugger. So explain the problem with +comments in the source. The relevant data will be in variables, which +are easy to examine with the debugger, so there is no point moving them +elsewhere. + + +@node Errors +@chapter Formatting Error Messages + +Error messages from compilers should look like this: + +@example +@var{source-file-name}:@var{lineno}: @var{message} +@end example + +Error messages from other noninteractive programs should look like this: + +@example +@var{program}:@var{source-file-name}:@var{lineno}: @var{message} +@end example + +@noindent +when there is an appropriate source file, or like this: + +@example +@var{program}: @var{message} +@end example + +@noindent +when there is no relevant source file. + +In an interactive program (one that is reading commands from a +terminal), it is better not to include the program name in an error +message. The place to indicate which program is running is in the +prompt or with the screen layout. (When the same program runs with +input from a source other than a terminal, it is not interactive and +would do best to print error messages using the noninteractive style.) + +The string @var{message} should not begin with a capital letter when +it follows a program name and/or filename. Also, it should not end +with a period. + +Error messages from interactive programs, and other messages such as +usage messages, should start with a capital letter. But they should not +end with a period. + + +@node Libraries +@chapter Library Behavior + +Try to make library functions reentrant. If they need to do dynamic +storage allocation, at least try to avoid any nonreentrancy aside from +that of @code{malloc} itself. + +Here are certain name conventions for libraries, to avoid name +conflicts. + +Choose a name prefix for the library, more than two characters long. +All external function and variable names should start with this +prefix. In addition, there should only be one of these in any given +library member. This usually means putting each one in a separate +source file. + +An exception can be made when two external symbols are always used +together, so that no reasonable program could use one without the +other; then they can both go in the same file. + +External symbols that are not documented entry points for the user +should have names beginning with @samp{_}. They should also contain +the chosen name prefix for the library, to prevent collisions with +other libraries. These can go in the same files with user entry +points if you like. + +Static functions and variables can be used as you like and need not +fit any naming convention. + + +@node Portability +@chapter Portability As It Applies to GNU + +Much of what is called ``portability'' in the Unix world refers to +porting to different Unix versions. This is a secondary consideration +for GNU software, because its primary purpose is to run on top of one +and only one kernel, the GNU kernel, compiled with one and only one C +compiler, the GNU C compiler. The amount and kinds of variation among +GNU systems on different cpu's will be like the variation among Berkeley +4.3 systems on different cpu's. + +All users today run GNU software on non-GNU systems. So supporting a +variety of non-GNU systems is desirable; simply not paramount. +The easiest way to achieve portability to a reasonable range of systems +is to use Autoconf. It's unlikely that your program needs to know more +information about the host machine than Autoconf can provide, simply +because most of the programs that need such knowledge have already been +written. + +It is difficult to be sure exactly what facilities the GNU kernel +will provide, since it isn't finished yet. Therefore, assume you can +use anything in 4.3; just avoid using the format of semi-internal data +bases (e.g., directories) when there is a higher-level alternative +(@code{readdir}). + +You can freely assume any reasonably standard facilities in the C +language, libraries or kernel, because we will find it necessary to +support these facilities in the full GNU system, whether or not we +have already done so. The fact that there may exist kernels or C +compilers that lack these facilities is irrelevant as long as the GNU +kernel and C compiler support them. + +It remains necessary to worry about differences among cpu types, such +as the difference in byte ordering and alignment restrictions. It's +unlikely that 16-bit machines will ever be supported by GNU, so there +is no point in spending any time to consider the possibility that an +int will be less than 32 bits. + +You can assume that all pointers have the same format, regardless +of the type they point to, and that this is really an integer. +There are some weird machines where this isn't true, but they aren't +important; don't waste time catering to them. Besides, eventually +we will put function prototypes into all GNU programs, and that will +probably make your program work even on weird machines. + +Since some important machines (including the 68000) are big-endian, +it is important not to assume that the address of an @code{int} object +is also the address of its least-significant byte. Thus, don't +make the following mistake: + +@example +int c; +@dots{} +while ((c = getchar()) != EOF) + write(file_descriptor, &c, 1); +@end example + +You can assume that it is reasonable to use a meg of memory. Don't +strain to reduce memory usage unless it can get to that level. If +your program creates complicated data structures, just make them in +core and give a fatal error if malloc returns zero. + +If a program works by lines and could be applied to arbitrary +user-supplied input files, it should keep only a line in memory, because +this is not very hard and users will want to be able to operate on input +files that are bigger than will fit in core all at once. + + +@node User Interfaces +@chapter Standards for Command Line Interfaces + +Please don't make the behavior of a utility depend on the name used +to invoke it. It is useful sometimes to make a link to a utility +with a different name, and that should not change what it does. + +Instead, use a run time option or a compilation switch or both +to select among the alternate behaviors. + +Likewise, please don't make the behavior of the program depend on the +type of output device it is used with. Device independence is an +important principle of the system's design; do not compromise it +merely to save someone from typing an option now and then. + +If you think one behavior is most useful when the output is to a +terminal, and another is most useful when the output is a file or a +pipe, then it is usually best to make the default behavior the one that +is useful with output to a terminal, and have an option for the other +behavior. + +Compatibility requires certain programs to depend on the type of output +device. It would be disastrous if @code{ls} or @code{sh} did not do so +in the way all users expect. In some of these cases, we supplement the +program with a preferred alternate version that does not depend on the +output device type. For example, we provide a @code{dir} program much +like @code{ls} except that its default output format is always +multi-column format. + +It is a good idea to follow the @sc{POSIX} guidelines for the +command-line options of a program. The easiest way to do this is to use +@code{getopt} to parse them. Note that the GNU version of @code{getopt} +will normally permit options anywhere among the arguments unless the +special argument @samp{--} is used. This is not what @sc{POSIX} +specifies; it is a GNU extension. + +Please define long-named options that are equivalent to the +single-letter Unix-style options. We hope to make GNU more user +friendly this way. This is easy to do with the GNU function +@code{getopt_long}. + +One of the advantages of long-named options is that they can be +consistent from program to program. For example, users should be able +to expect the ``verbose'' option of any GNU program which has one, to be +spelled precisely @samp{--verbose}. To achieve this uniformity, look at +the table of common long-option names when you choose the option names +for your program. The table appears below. + +If you use names not already in the table, please send +@samp{gnu@@prep.ai.mit.edu} a list of them, with their meanings, so we +can update the table. + +It is usually a good idea for file names given as ordinary arguments +to be input files only; any output files would be specified using +options (preferably @samp{-o}). Even if you allow an output file name +as an ordinary argument for compatibility, try to provide a suitable +option as well. This will lead to more consistency among GNU +utilities, so that there are fewer idiosyncracies for users to +remember. + +Programs should support an option @samp{--version} which prints the +program's version number on standard output and exits successfully, and +an option @samp{--help} which prints option usage information on +standard output and exits successfully. These options should inhibit +the normal function of the command; they should do nothing except print +the requested information. + +@c Please leave newlines between items in this table; it's much easier +@c to update when it isn't completely squashed together and unreadable. +@c When there is more than one short option for a long option name, put +@c a semicolon between the lists of the programs that use them, not a +@c period. --friedman + +@table @samp + +@item after-date +@samp{-N} in @code{tar}. + +@item all +@samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname}, +and @code{unexpand}. + +@item all-text +@samp{-a} in @code{diff}. + +@item almost-all +@samp{-A} in @code{ls}. + +@item append +@samp{-a} in @code{etags}, @code{tee}, @code{time}; +@samp{-r} in @code{tar}. + +@item archive +@samp{-a} in @code{cp}. + +@item archive-name +@samp{-n} in @code{shar}. + +@item arglength +@samp{-l} in @code{m4}. + +@item ascii +@samp{-a} in @code{diff}. + +@item assume-new +@samp{-W} in Make. + +@item assume-old +@samp{-o} in Make. + +@item auto-check +@samp{-a} in @code{recode}. + +@item auto-pager +@samp{-a} in @code{wdiff}. + +@item auto-reference +@samp{-A} in @code{ptx}. + +@item avoid-wraps +@samp{-n} in @code{wdiff}. + +@item backward-search +@samp{-B} in @code{ctags}. + +@item basename +@samp{-f} in @code{shar}. + +@item batch +Used in GDB. + +@item baud +Used in GDB. + +@item before +@samp{-b} in @code{tac}. + +@item binary +@samp{-b} in @code{cpio} and @code{diff}. + +@item bits-per-code +@samp{-b} in @code{shar}. + +@item block-size +Used in @code{cpio} and @code{tar}. + +@item blocks +@samp{-b} in @code{head} and @code{tail}. + +@item break-file +@samp{-b} in @code{ptx}. + +@item brief +Used in various programs to make output shorter. + +@item bytes +@samp{-c} in @code{head}, @code{split}, and @code{tail}. + +@item c@t{++} +@samp{-C} in @code{etags}. + +@item catenate +@samp{-A} in @code{tar}. + +@item cd +Used in various programs to specify the directory to use. + +@item changes +@samp{-c} in @code{chgrp} and @code{chown}. + +@item classify +@samp{-F} in @code{ls}. + +@item colons +@samp{-c} in @code{recode}. + +@item command +@samp{-c} in @code{su}; +@samp{-x} in GDB. + +@item compare +@samp{-d} in @code{tar}. + +@item compress +@samp{-Z} in @code{tar} and @code{shar}. + +@item concatenate +@samp{-A} in @code{tar}. + +@item confirmation +@samp{-w} in @code{tar}. + +@item context +Used in @code{diff}. + +@item copyright +@samp{-C} in @code{ptx}, @code{recode}, and @code{wdiff}. + +@item core +Used in GDB. + +@item count +@samp{-q} in @code{who}. + +@item count-links +@samp{-l} in @code{du}. + +@item create +Used in @code{tar} and @code{cpio}. + +@item cut-mark +@samp{-c} in @code{shar}. + +@item cxref +@samp{-x} in @code{ctags}. + +@item date +@samp{-d} in @code{touch}. + +@item debug +@samp{-d} in Make and @code{m4}; +@samp{-t} in Bison. + +@item define +@samp{-D} in @code{m4}. + +@item defines +@samp{-d} in Bison and @code{ctags}. + +@item delete +@samp{-D} in @code{tar}. + +@item dereference +@samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du}, +@code{ls}, and @code{tar}. + +@item dereference-args +@samp{-D} in @code{du}. + +@item diacritics +@samp{-d} in @code{recode}. + +@item dictionary-order +@samp{-d} in @code{look}. + +@item diff +@samp{-d} in @code{tar}. + +@item digits +@samp{-n} in @code{csplit}. + +@item directory +Specify the directory to use, in various programs. In @code{ls}, it +means to show directories themselves rather than their contents. In +@code{rm} and @code{ln}, it means to not treat links to directories +specially. + +@item discard-all +@samp{-x} in @code{strip}. + +@item discard-locals +@samp{-X} in @code{strip}. + +@item dry-run +@samp{-n} in Make. + +@item ed +@samp{-e} in @code{diff}. + +@item elide-empty-files +@samp{-z} in @code{csplit}. + +@item end-delete +@samp{-x} in @code{wdiff}. + +@item end-insert +@samp{-z} in @code{wdiff}. + +@item entire-new-file +@samp{-N} in @code{diff}. + +@item environment-overrides +@samp{-e} in Make. + +@item eof +@samp{-e} in @code{xargs}. + +@item epoch +Used in GDB. + +@item error-limit +Used in Makeinfo. + +@item error-output +@samp{-o} in @code{m4}. + +@item escape +@samp{-b} in @code{ls}. + +@item exclude-from +@samp{-X} in @code{tar}. + +@item exec +Used in GDB. + +@item exit +@samp{-x} in @code{xargs}. + +@item exit-0 +@samp{-e} in @code{unshar}. + +@item expand-tabs +@samp{-t} in @code{diff}. + +@item expression +@samp{-e} in @code{sed}. + +@item extern-only +@samp{-g} in @code{nm}. + +@item extract +@samp{-i} in @code{cpio}; +@samp{-x} in @code{tar}. + +@item faces +@samp{-f} in @code{finger}. + +@item fast +@samp{-f} in @code{su}. + +@item fatal-warnings +@samp{-E} in @code{m4}. + +@item file +@samp{-f} in @code{info}, Make, @code{mt}, and @code{tar}; +@samp{-n} in @code{sed}; +@samp{-r} in @code{touch}. + +@item file-prefix +@samp{-b} in Bison. + +@item file-type +@samp{-F} in @code{ls}. + +@item files-from +@samp{-T} in @code{tar}. + +@item fill-column +Used in Makeinfo. + +@item flag-truncation +@samp{-F} in @code{ptx}. + +@item fixed-output-files +@samp{-y} in Bison. + +@item follow +@samp{-f} in @code{tail}. + +@item footnote-style +Used in Makeinfo. + +@item force +@samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}. + +@item force-prefix +@samp{-F} in @code{shar}. + +@item format +Used in @code{ls}, @code{time}, and @code{ptx}. + +@item freeze-state +@samp{-F} in @code{m4}. + +@item fullname +Used in GDB. + +@item gap-size +@samp{-g} in @code{ptx}. + +@item get +@samp{-x} in @code{tar}. + +@item graphic +@samp{-i} in @code{ul}. + +@item graphics +@samp{-g} in @code{recode}. + +@item group +@samp{-g} in @code{install}. + +@item gzip +@samp{-z} in @code{tar} and @code{shar}. + +@item hashsize +@samp{-H} in @code{m4}. + +@item header +@samp{-h} in @code{objdump} and @code{recode} + +@item heading +@samp{-H} in @code{who}. + +@item help +Used to ask for brief usage information. + +@item here-delimiter +@samp{-d} in @code{shar}. + +@item hide-control-chars +@samp{-q} in @code{ls}. + +@item idle +@samp{-u} in @code{who}. + +@item ifdef +@samp{-D} in @code{diff}. + +@item ignore +@samp{-I} in @code{ls}; +@samp{-x} in @code{recode}. + +@item ignore-all-space +@samp{-w} in @code{diff}. + +@item ignore-backups +@samp{-B} in @code{ls}. + +@item ignore-blank-lines +@samp{-B} in @code{diff}. + +@item ignore-case +@samp{-f} in @code{look} and @code{ptx}; +@samp{-i} in @code{diff} and @code{wdiff}. + +@item ignore-errors +@samp{-i} in Make. + +@item ignore-file +@samp{-i} in @code{ptx}. + +@item ignore-indentation +@samp{-S} in @code{etags}. + +@item ignore-init-file +@samp{-f} in Oleo. + +@item ignore-interrupts +@samp{-i} in @code{tee}. + +@item ignore-matching-lines +@samp{-I} in @code{diff}. + +@item ignore-space-change +@samp{-b} in @code{diff}. + +@item ignore-zeros +@samp{-i} in @code{tar}. + +@item include +@samp{-i} in @code{etags}; +@samp{-I} in @code{m4}. + +@item include-dir +@samp{-I} in Make. + +@item incremental +@samp{-G} in @code{tar}. + +@item info +@samp{-i}, @samp{-l}, and @samp{-m} in Finger. + +@item initial +@samp{-i} in @code{expand}. + +@item initial-tab +@samp{-T} in @code{diff}. + +@item inode +@samp{-i} in @code{ls}. + +@item interactive +@samp{-i} in @code{cp}, @code{ln}, @code{mv}, @code{rm}; +@samp{-e} in @code{m4}; +@samp{-p} in @code{xargs}; +@samp{-w} in @code{tar}. + +@item intermix-type +@samp{-p} in @code{shar}. + +@item jobs +@samp{-j} in Make. + +@item just-print +@samp{-n} in Make. + +@item keep-going +@samp{-k} in Make. + +@item keep-files +@samp{-k} in @code{csplit}. + +@item kilobytes +@samp{-k} in @code{du} and @code{ls}. + +@item language +@samp{-l} in @code{etags}. + +@item less-mode +@samp{-l} in @code{wdiff}. + +@item level-for-gzip +@samp{-g} in @code{shar}. + +@item line-bytes +@samp{-C} in @code{split}. + +@item lines +Used in @code{split}, @code{head}, and @code{tail}. + +@item link +@samp{-l} in @code{cpio}. + +@item list +@samp{-t} in @code{cpio}; +@samp{-l} in @code{recode}. + +@item list +@samp{-t} in @code{tar}. + +@item literal +@samp{-N} in @code{ls}. + +@item load-average +@samp{-l} in Make. + +@item login +Used in @code{su}. + +@item machine +No listing of which programs already use this; +someone should check to +see if any actually do and tell @code{gnu@@prep.ai.mit.edu}. + +@item macro-name +@samp{-M} in @code{ptx}. + +@item mail +@samp{-m} in @code{hello} and @code{uname}. + +@item make-directories +@samp{-d} in @code{cpio}. + +@item makefile +@samp{-f} in Make. + +@item mapped +Used in GDB. + +@item max-args +@samp{-n} in @code{xargs}. + +@item max-chars +@samp{-n} in @code{xargs}. + +@item max-lines +@samp{-l} in @code{xargs}. + +@item max-load +@samp{-l} in Make. + +@item max-procs +@samp{-P} in @code{xargs}. + +@item mesg +@samp{-T} in @code{who}. + +@item message +@samp{-T} in @code{who}. + +@item minimal +@samp{-d} in @code{diff}. + +@item mixed-uuencode +@samp{-M} in @code{shar}. + +@item mode +@samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}. + +@item modification-time +@samp{-m} in @code{tar}. + +@item multi-volume +@samp{-M} in @code{tar}. + +@item name-prefix +@samp{-a} in Bison. + +@item nesting-limit +@samp{-L} in @code{m4}. + +@item net-headers +@samp{-a} in @code{shar}. + +@item new-file +@samp{-W} in Make. + +@item no-builtin-rules +@samp{-r} in Make. + +@item no-character-count +@samp{-w} in @code{shar}. + +@item no-check-existing +@samp{-x} in @code{shar}. + +@item no-common +@samp{-3} in @code{wdiff}. + +@item no-create +@samp{-c} in @code{touch}. + +@item no-defines +@samp{-D} in @code{etags}. + +@item no-deleted +@samp{-1} in @code{wdiff}. + +@item no-dereference +@samp{-d} in @code{cp}. + +@item no-inserted +@samp{-2} in @code{wdiff}. + +@item no-keep-going +@samp{-S} in Make. + +@item no-lines +@samp{-l} in Bison. + +@item no-piping +@samp{-P} in @code{shar}. + +@item no-prof +@samp{-e} in @code{gprof}. + +@item no-regex +@samp{-R} in @code{etags}. + +@item no-sort +@samp{-p} in @code{nm}. + +@item no-split +Used in Makeinfo. + +@item no-static +@samp{-a} in @code{gprof}. + +@item no-time +@samp{-E} in @code{gprof}. + +@item no-timestamp +@samp{-m} in @code{shar}. + +@item no-validate +Used in Makeinfo. + +@item no-warn +Used in various programs to inhibit warnings. + +@item node +@samp{-n} in @code{info}. + +@item nodename +@samp{-n} in @code{uname}. + +@item nonmatching +@samp{-f} in @code{cpio}. + +@item nstuff +@samp{-n} in @code{objdump}. + +@item null +@samp{-0} in @code{xargs}. + +@item number +@samp{-n} in @code{cat}. + +@item number-nonblank +@samp{-b} in @code{cat}. + +@item numeric-sort +@samp{-n} in @code{nm}. + +@item numeric-uid-gid +@samp{-n} in @code{cpio} and @code{ls}. + +@item nx +Used in GDB. + +@item old-archive +@samp{-o} in @code{tar}. + +@item old-file +@samp{-o} in Make. + +@item one-file-system +@samp{-l} in @code{tar}, @code{cp}, and @code{du}. + +@item only-file +@samp{-o} in @code{ptx}. + +@item only-prof +@samp{-f} in @code{gprof}. + +@item only-time +@samp{-F} in @code{gprof}. + +@item output +In various programs, specify the output file name. + +@item output-prefix +@samp{-o} in @code{shar}. + +@item override +@samp{-o} in @code{rm}. + +@item overwrite +@samp{-c} in @code{unshar}. + +@item owner +@samp{-o} in @code{install}. + +@item paginate +@samp{-l} in @code{diff}. + +@item paragraph-indent +Used in Makeinfo. + +@item parents +@samp{-p} in @code{mkdir} and @code{rmdir}. + +@item pass-all +@samp{-p} in @code{ul}. + +@item pass-through +@samp{-p} in @code{cpio}. + +@item port +@samp{-P} in @code{finger}. + +@item portability +@samp{-c} in @code{cpio} and @code{tar}. + +@item prefix-builtins +@samp{-P} in @code{m4}. + +@item prefix +@samp{-f} in @code{csplit}. + +@item preserve +Used in @code{tar} and @code{cp}. + +@item preserve-environment +@samp{-p} in @code{su}. + +@item preserve-modification-time +@samp{-m} in @code{cpio}. + +@item preserve-order +@samp{-s} in @code{tar}. + +@item preserve-permissions +@samp{-p} in @code{tar}. + +@item print +@samp{-l} in @code{diff}. + +@item print-chars +@samp{-L} in @code{cmp}. + +@item print-data-base +@samp{-p} in Make. + +@item print-directory +@samp{-w} in Make. + +@item print-file-name +@samp{-o} in @code{nm}. + +@item print-symdefs +@samp{-s} in @code{nm}. + +@item printer +@samp{-p} in @code{wdiff}. + +@item query-user +@samp{-X} in @code{shar}. + +@item question +@samp{-q} in Make. + +@item quiet +Used in many programs to inhibit the usual output. @strong{Note:} every +program accepting @samp{--quiet} should accept @samp{--silent} as a +synonym. + +@item quiet-unshar +@samp{-Q} in @code{shar} + +@item quote-name +@samp{-Q} in @code{ls}. + +@item rcs +@samp{-n} in @code{diff}. + +@item read-full-blocks +@samp{-B} in @code{tar}. + +@item readnow +Used in GDB. + +@item recon +@samp{-n} in Make. + +@item record-number +@samp{-R} in @code{tar}. + +@item recursive +Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff}, +and @code{rm}. + +@item reference-limit +Used in Makeinfo. + +@item references +@samp{-r} in @code{ptx}. + +@item regex +@samp{-r} in @code{tac} and @code{etags}. + +@item release +@samp{-r} in @code{uname}. + +@item reload-state +@samp{-R} in @code{m4}. + +@item relocation +@samp{-r} in @code{objdump}. + +@item rename +@samp{-r} in @code{cpio}. + +@item replace +@samp{-i} in @code{xargs}. + +@item report-identical-files +@samp{-s} in @code{diff}. + +@item reset-access-time +@samp{-a} in @code{cpio}. + +@item reverse +@samp{-r} in @code{ls} and @code{nm}. + +@item reversed-ed +@samp{-f} in @code{diff}. + +@item right-side-defs +@samp{-R} in @code{ptx}. + +@item same-order +@samp{-s} in @code{tar}. + +@item same-permissions +@samp{-p} in @code{tar}. + +@item save +@samp{-g} in @code{stty}. + +@item se +Used in GDB. + +@item sentence-regexp +@samp{-S} in @code{ptx}. + +@item separate-dirs +@samp{-S} in @code{du}. + +@item separator +@samp{-s} in @code{tac}. + +@item sequence +Used by @code{recode} to chose files or pipes for sequencing passes. + +@item shell +@samp{-s} in @code{su}. + +@item show-all +@samp{-A} in @code{cat}. + +@item show-c-function +@samp{-p} in @code{diff}. + +@item show-ends +@samp{-E} in @code{cat}. + +@item show-function-line +@samp{-F} in @code{diff}. + +@item show-tabs +@samp{-T} in @code{cat}. + +@item silent +Used in many programs to inhibit the usual output. +@strong{Note:} every program accepting +@samp{--silent} should accept @samp{--quiet} as a synonym. + +@item size +@samp{-s} in @code{ls}. + +@item sort +Used in @code{ls}. + +@item sparse +@samp{-S} in @code{tar}. + +@item speed-large-files +@samp{-H} in @code{diff}. + +@item split-at +@samp{-E} in @code{unshar}. + +@item split-size-limit +@samp{-L} in @code{shar}. + +@item squeeze-blank +@samp{-s} in @code{cat}. + +@item start-delete +@samp{-w} in @code{wdiff}. + +@item start-insert +@samp{-y} in @code{wdiff}. + +@item starting-file +Used in @code{tar} and @code{diff} to specify which file within +a directory to start processing with. + +@item statistics +@samp{-s} in @code{wdiff}. + +@item stdin-file-list +@samp{-S} in @code{shar}. + +@item stop +@samp{-S} in Make. + +@item strict +@samp{-s} in @code{recode}. + +@item strip +@samp{-s} in @code{install}. + +@item strip-all +@samp{-s} in @code{strip}. + +@item strip-debug +@samp{-S} in @code{strip}. + +@item submitter +@samp{-s} in @code{shar}. + +@item suffix +@samp{-S} in @code{cp}, @code{ln}, @code{mv}. + +@item suffix-format +@samp{-b} in @code{csplit}. + +@item sum +@samp{-s} in @code{gprof}. + +@item summarize +@samp{-s} in @code{du}. + +@item symbolic +@samp{-s} in @code{ln}. + +@item symbols +Used in GDB and @code{objdump}. + +@item synclines +@samp{-s} in @code{m4}. + +@item sysname +@samp{-s} in @code{uname}. + +@item tabs +@samp{-t} in @code{expand} and @code{unexpand}. + +@item tabsize +@samp{-T} in @code{ls}. + +@item terminal +@samp{-T} in @code{tput} and @code{ul}. +@samp{-t} in @code{wdiff}. + +@item text +@samp{-a} in @code{diff}. + +@item text-files +@samp{-T} in @code{shar}. + +@item time +Used in @code{ls} and @code{touch}. + +@item to-stdout +@samp{-O} in @code{tar}. + +@item total +@samp{-c} in @code{du}. + +@item touch +@samp{-t} in Make, @code{ranlib}, and @code{recode}. + +@item trace +@samp{-t} in @code{m4}. + +@item traditional +@samp{-t} in @code{hello}; +@samp{-G} in @code{m4} and @code{ptx}. + +@item tty +Used in GDB. + +@item typedefs +@samp{-t} in @code{ctags}. + +@item typedefs-and-c++ +@samp{-T} in @code{ctags}. + +@item typeset-mode +@samp{-t} in @code{ptx}. + +@item uncompress +@samp{-z} in @code{tar}. + +@item unconditional +@samp{-u} in @code{cpio}. + +@item undefine +@samp{-U} in @code{m4}. + +@item undefined-only +@samp{-u} in @code{nm}. + +@item update +@samp{-u} in @code{cp}, @code{ctags}, @code{mv}, @code{tar}. + +@item uuencode +@samp{-B} in @code{shar}. + +@item vanilla-operation +@samp{-V} in @code{shar}. + +@item verbose +Print more information about progress. Many programs support this. + +@item verify +@samp{-W} in @code{tar}. + +@item version +Print the version number. + +@item version-control +@samp{-V} in @code{cp}, @code{ln}, @code{mv}. + +@item vgrind +@samp{-v} in @code{ctags}. + +@item volume +@samp{-V} in @code{tar}. + +@item what-if +@samp{-W} in Make. + +@item whole-size-limit +@samp{-l} in @code{shar}. + +@item width +@samp{-w} in @code{ls} and @code{ptx}. + +@item word-regexp +@samp{-W} in @code{ptx}. + +@item writable +@samp{-T} in @code{who}. + +@item zeros +@samp{-z} in @code{gprof}. + +@end table + +@node Documentation +@chapter Documenting Programs + +Please use Texinfo for documenting GNU programs. See the Texinfo +manual, either the hardcopy or the version in the GNU Emacs Info +subsystem (@kbd{C-h i}). See existing GNU Texinfo files (e.g., those +under the @file{man/} directory in the GNU Emacs distribution) for +examples. + +The title page of the manual should state the version of the program +which the manual applies to. The Top node of the manual should also +contain this information. If the manual is changing more frequently +than or independent of the program, also state a version number for +the manual in both of these places. + +The manual should document all command-line arguments and all +commands. It should give examples of their use. But don't organize +the manual as a list of features. Instead, organize it by the +concepts a user will have before reaching that point in the manual. +Address the goals that a user will have in mind, and explain how to +accomplish them. Don't use Unix man pages as a model for how to +write GNU documentation; they are a bad example to follow. + +The manual should have a node named @samp{@var{program} Invocation} or +@samp{Invoking @var{program}}, where @var{program} stands for the name +of the program being described, as you would type it in the shell to run +the program. This node (together with its subnodes, if any) should +describe the program's command line arguments and how to run it (the +sort of information people would look in a man page for). Start with an +@samp{@@example} containing a template for all the options and arguments +that the program uses. + +Alternatively, put a menu item in some menu whose item name fits one of +the above patterns. This identifies the node which that item points to +as the node for this purpose, regardless of the node's actual name. + +There will be automatic features for specifying a program name and +quickly reading just this part of its manual. + +If one manual describes several programs, it should have such a node for +each program described. + +In addition to its manual, the package should have a file named +@file{NEWS} which contains a list of user-visible changes worth +mentioning. In each new release, add items to the front of the file and +identify the version they pertain to. Don't discard old items; leave +them in the file after the newer items. This way, a user upgrading from +any previous version can see what is new. + +If the @file{NEWS} file gets very long, move some of the older items +into a file named @file{ONEWS} and put a note at the end referring the +user to that file. + +Please do not use the term ``pathname'' that is used in Unix +documentation; use ``file name'' (two words) instead. We use the term +``path'' only for search paths, which are lists of file names. + +It is ok to supply a man page for the program as well as a Texinfo +manual if you wish to. But keep in mind that supporting a man page +requires continual effort, each time the program is changed. Any time +you spend on the man page is time taken away from more useful things you +could contribute. + +Thus, even if a user volunteers to donate a man page, you may find this +gift costly to accept. Unless you have time on your hands, it may be +better to refuse the man page unless the same volunteer agrees to take +full responsibility for maintaining it---so that you can wash your hands +of it entirely. If the volunteer ceases to do the job, then don't feel +obliged to pick it up yourself; it may be better to withdraw the man +page until another volunteer offers to carry on with it. + +Alternatively, if you expect the discrepancies to be small enough that +the man page remains useful, put a prominent note near the beginning of +the man page explaining that you don't maintain it and that the Texinfo +manual is more authoritative, and describing how to access the Texinfo +documentation. + +@node Releases +@chapter Making Releases + +Package the distribution of Foo version 69.96 in a gzipped tar file +named @file{foo-69.96.tar.gz}. It should unpack into a subdirectory +named @file{foo-69.96}. + +Building and installing the program should never modify any of the files +contained in the distribution. This means that all the files that form +part of the program in any way must be classified into @dfn{source +files} and @dfn{non-source files}. Source files are written by humans +and never changed automatically; non-source files are produced from +source files by programs under the control of the Makefile. + +Naturally, all the source files must be in the distribution. It is okay +to include non-source files in the distribution, provided they are +up-to-date and machine-independent, so that building the distribution +normally will never modify them. We commonly include non-source files +produced by Bison, Lex, @TeX{}, and Makeinfo; this helps avoid +unnecessary dependencies between our distributions, so that users can +install whichever packages they want to install. + +Non-source files that might actually be modified by building and +installing the program should @strong{never} be included in the +distribution. So if you do distribute non-source files, always make +sure they are up to date when you make a new distribution. + +Make sure that the directory into which the distribution unpacks (as +well as any subdirectories) are all world-writable (octal mode 777). +This is so that old versions of @code{tar} which preserve the +ownership and permissions of the files from the tar archive will be +able to extract all the files even if the user is unprivileged. + +Make sure that all the files in the distribution are world-readable. + +Make sure that no file name in the distribution is more than 14 +characters long. Likewise, no file created by building the program +should have a name longer than 14 characters. The reason for this is +that some systems adhere to a foolish interpretation of the POSIX +standard, and refuse to open a longer name, rather than truncating as +they did in the past. + +Don't include any symbolic links in the distribution itself. If the tar +file contains symbolic links, then people cannot even unpack it on +systems that don't support symbolic links. Also, don't use multiple +names for one file in different directories, because certain file +systems cannot handle this and that prevents unpacking the +distribution. + +Try to make sure that all the file names will be unique on MS-DOG. A +name on MS-DOG consists of up to 8 characters, optionally followed by a +period and up to three characters. MS-DOG will truncate extra +characters both before and after the period. Thus, +@file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they +are truncated to @file{foobarha.c} and @file{foobarha.o}, which are +distinct. + +Include in your distribution a copy of the @file{texinfo.tex} you used +to test print any @file{*.texinfo} files. + +Likewise, if your program uses small GNU software packages like regex, +getopt, obstack, or termcap, include them in the distribution file. +Leaving them out would make the distribution file a little smaller at +the expense of possible inconvenience to a user who doesn't know what +other files to get. + +@contents + +@bye
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kpathsea/texmf.cnf.in Fri Jul 19 01:57:38 1996 +0000 @@ -0,0 +1,107 @@ +% original texmf.cnf -- runtime path configuration file for kpathsea. +% +% (If you change or delete `original' on the previous line, the +% distribution won't install its version over yours.) +% +% What follows is a super-summary of what this .cnf file can +% contain. Please read the Kpathsea manual for more information. +% +% texmf.cnf is generated from texmf.cnf.in, by replacing @var@ with the +% value of the Make variable `var', via a sed file texmf.sed, generated +% (once) by kpathsea/Makefile (itself generated from +% kpathsea/Makefile.in by configure). +% +% Any identifier (sticking to A-Za-z_ for names is safest) can be assigned. +% The `=' (and surrounding spaces) is optional. +% No space, %, or @ in variable values, for the sake of autogeneration. +% An environment variable foo overrides a definition of foo here. +% $foo (or ${foo}) in a value expands to the envvar or cnf value of foo. +% +% All definitions are read before anything is expanded, so you can use +% variables before they are defined. +% +% If a variable is qualified with `.<program>', it is ignored unless the +% current executable (last component of argv[0]) is named <program>. +% +% Which file formats use which paths for searches is described in the +% various programs' and the kpathsea documentation. +% +% // means to search subdirectories (recursively). +% A leading !! means to look only in the ls-R db, never on the disk. +% A leading/trailing/doubled : in the paths will be expanded into the +% compile-time default. Probably not what you want. + + +% Where the wild files are. You can set an environment variable to +% override this if you're testing a new TeX tree, without changing +% anything else. +TEXMF = @texmf@ + +% TeX input files -- i.e., anything to be found by \input or \openin, +% including .sty, .eps, etc. Things are confused by the many variants +% of LaTeX, which all have the same filenames. The current +% recommendation is to make `latex' be latex2e, and if you also want to +% support latex 2.09, call it latex209. If you do the reverse, the +% definitions below will need adjusting. +% +latex209_inputs = .:@texinputdir@/latex209//:@texinputdir@// +latex2e_inputs = .:@texinputdir@/latex2e//:@texinputdir@// +TEXINPUTS.latex209 = $latex209_inputs +TEXINPUTS.latex2e = $latex2e_inputs +TEXINPUTS.latex = $latex2e_inputs +% Earlier entries override later ones, so put this last. +TEXINPUTS = .:@texinputdir@// + +% Ditto for MF. +MFINPUTS = .:@mfinputdir@//:@fontdir@//src// + +% Predigested formats and string pools for initex/inimf. +TEXFORMATS = .:@fmtdir@ +MFBASES = .:@basedir@ +TEXPOOL = @texpooldir@ +MFPOOL = @mfpooldir@ + +% Device-independent font metric files. +VFFONTS = .:@fontdir@//vf +TFMFONTS = .:@fontdir@//tfm + +% Just an abbreviation. +pkdir = @fontdir@//pk + +% The $MAKETEX_MODE below means the drivers will not use a cx font when +% the mode is ricoh. If no mode is explicitly specified, kpse_prog_init +% sets MAKETEX_MODE to /, so all subdirectories are searched. See the manual. + +% xdvi needs to find bitmaps for PostScript fonts, which can be +% generated by standalone programs gsftopk and ps2pk (ps2mf needs no +% special treatment). See xdvik/INSTALL for more info. +PKFONTS.xdvi = .:$pkdir/$MAKETEX_MODE:$pkdir/gsftopk:$pkdir/ps2pk +% Again, the standard definition must come after the program-specific one. +% Don't use $pkdir since we can't do general variable expansion making paths.h. +PKFONTS = .:@fontdir@//pk/$MAKETEX_MODE + +% Similarly for the GF format, which only remains in existence because +% Metafont outputs it (and MF isn't going to change). +GFFONTS = .:@fontdir@//gf/$MAKETEX_MODE + +% Used to find texfonts.map; also a backup for PKFONTS and GFFONTS, +% but normally that is irrelevant, so don't bother with all subdirectories. +GLYPHFONTS = .:@fontdir@ + +% BibTeX bibliographies and style files. +BIBINPUTS = .:@texmf@/bibtex/bib +BSTINPUTS = .:@texmf@/bibtex/bst + +% Dvips' config.* files. +TEXCONFIG = .:~:@psheaderdir@ + +% Dvips' PostScript prologues (.pro) and .pfa/.pfb files. +DVIPSHEADERS = .:@psheaderdir@:@fontdir@//type1 + +% Enable this (or set the environment variable) if you want kpathsea to +% log names and times for all files found. +% TEXMFLOG = @texmf@/kpathsea.log + +% This definition isn't used from this .cnf file itself (that would be +% paradoxical), but the compile-time default in paths.h is built from it. +TEXMFCNF = .:@web2cdir@
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/liboctave/OChangeLog Fri Jul 19 01:57:38 1996 +0000 @@ -0,0 +1,137 @@ +Fri Jan 31 01:12:25 1992 John W. Eaton (jwe at andy.che.utexas.edu) + + Changes for GCC2: + ----------------- + + * Most .hP and .ccP files: Remove unnecessary `auto' keyword (this + cruft was added to allow earlier versions of g++ to compile + certain function definitions). + * Remove `inline' qualifiers for functions in .ccP files. + * Pass and return all class objects by reference. + +Wed Dec 18 11:08:15 1991 John W. Eaton (jwe at andy.che.utexas.edu) + + * Pass vector and matrix objects by reference to avoid (I think) a + g++-1.40 bug and get the NLP class working again. I didn't + understand reference types very well when I first wrote this, so + there were lots of problems... I'm sure there are more places + this needs fixing -- for example, the ODE, DAE and SDAE classes + probably need similar changes. + +Mon Aug 19 03:54:59 1991 John W. Eaton (jwe at andy.che.utexas.edu) + + * SDAE.ccP, SDAE.hP: New files that define an ODE + sensitivity + analysis class based on DDASAC. Needs work to have full + functionality. + + * SDAEFunc.ccP SDAEFunc.hP: New files that define a class of + functions to be used by the SDAE class. + +Wed Jul 24 04:01:49 1991 John W. Eaton (jwe at andy.che.utexas.edu) + + * FEGrid.ccP, FEGrid.hP: New files that define a finite element + grid class -- boundaries must be in ascending order and must have + nonzero width, etc. + +Tue Jul 23 01:20:27 1991 John W. Eaton (jwe at andy.che.utexas.edu) + + * Matrix.ccP, Matrix.hP: (rowset, colset) New member functions. + + * DAE.ccP, DAE.hP, DAEFunc.ccP, DAEFunc.hP: New files, analogous + to the ODE files, that define a DAE class. Maybe working. + + * ODE.ccP, ODE.hP: Modify to use new ODEFunc class. + + * ODEFunc.hP, ODEFunc.ccP: New files that define a function class + for the ODE object. + +Mon Jul 22 00:06:36 1991 John W. Eaton (jwe at andy.che.utexas.edu) + + * convert bounds, linear constraint, nonlinear constraint, + objective function, nlp, ode, and collocation weight classes to + generic style of libg++. + + * NLEqn.hP, NLEqn.ccP: New files that define a class for + solving square systems of nonlinear equations. Maybe working. + + * NLFunc.hP, NLFunc.ccP: New files that define a class for + nonlinear functions returning vectors. Modified nl_const class to + use NLFunc objects instead of handling functions with jacobians + directly. Modifed nlp class to use the new definition of nl_const + constructors. + +Sun Jul 21 06:31:39 1991 John W. Eaton (jwe at andy.che.utexas.edu) + + * LinEqn.hP, LinEqn.ccP: New files that define a class for + solving sets of linear equations. Maybe working. + +Thu Jul 18 00:40:59 1991 John W. Eaton (jwe at andy.che.utexas.edu) + + * SVD.hP, SVD.ccP: New files that define an SVD class. Maybe + working. + +Wed Jul 17 05:15:41 1991 John W. Eaton (jwe at andy.che.utexas.edu) + + * Matrix.{h,cc}P: New methods: inverse (a), a.inverse (), + a.determinant (), a.condition_number (). Based on linpack + routines. + + * *.h *.cc Matrix.hP Matrix.ccP: Removed extraneous this-> + references which aren't needed and look ugly. + + * colloc.cc: New private data member `initialized'. Only compute + values for r, q, A, and B when needed and then only if initialized + is false. Set initialized = false when any size/constant data + changes. Reset it to true before returning from init(). + + * Change type of most void foo::bar_set() methods to be of type + foo& and return *this so that they can be chained together: + a.foo().bar().baz(); + + * *.h, but not *.hP: Moved all definitions of functions into .cc + files. Hoping to speed up compilation somewhat. + +Tue Jul 16 08:33:01 1991 John W. Eaton (jwe at andy.che.utexas.edu) + + * *.h: make sure that include files are only included once by + using #ifndef _foo_h / #define _foo_h / ... / #endif _foo_h. + + * nlp.cc: appears to work for user supplied gradient and jacobian + functions. Linear constraints appear to work. + + * Add stream output operators for the <T>Matrix and <T>Vec + classes. + + * Updated the nlp class to handle new definition of the objective + function, bounds, and constraints. + + * New test programs: bounds-test, lin_const-test, and nl_const-test. + + * New classes: + + objective: instead of specifying the objective function + directly, you provide the nlp class with an objective function + object. The user has the option of specifying a gradient + function. + + bounds, lin_const, nl_const: these replace the constraint + object. nl_const allows the user the option of specifying a + jacobian function. + + The nl_const and objective objects should probably both know + how to compute gradient information whether the user supplies + a function or not. + + colloc: collocation object. The test program for this still + needs to be written. + +Sun Jul 14 22:50:51 1991 John W. Eaton (jwe at andy.che.utexas.edu) + + * Have very minimal but mostly working classes for simple matrix + operations (uses some BLAS routines), ordinary differential + equations (based on LSODE), nonlinear programming (based on + NPSOL), and constraint sets (for NLP). + + * About time to start this, since I seem to actually be making + progress on this stuff now. +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/liboctave/filemode.c Fri Jul 19 01:57:38 1996 +0000 @@ -0,0 +1,255 @@ +/* filemode.c -- make a string describing file modes + Copyright (C) 1985, 1990, 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. */ + +#ifdef HAVE_CONFIG_H +#include <config.h> +#endif + +#include <sys/types.h> +#include <sys/stat.h> + +#if !S_IRUSR +# if S_IREAD +# define S_IRUSR S_IREAD +# else +# define S_IRUSR 00400 +# endif +#endif + +#if !S_IWUSR +# if S_IWRITE +# define S_IWUSR S_IWRITE +# else +# define S_IWUSR 00200 +# endif +#endif + +#if !S_IXUSR +# if S_IEXEC +# define S_IXUSR S_IEXEC +# else +# define S_IXUSR 00100 +# endif +#endif + +#ifdef STAT_MACROS_BROKEN +#undef S_ISBLK +#undef S_ISCHR +#undef S_ISDIR +#undef S_ISFIFO +#undef S_ISLNK +#undef S_ISMPB +#undef S_ISMPC +#undef S_ISNWK +#undef S_ISREG +#undef S_ISSOCK +#endif /* STAT_MACROS_BROKEN. */ + +#if !defined(S_ISBLK) && defined(S_IFBLK) +#define S_ISBLK(m) (((m) & S_IFMT) == S_IFBLK) +#endif +#if !defined(S_ISCHR) && defined(S_IFCHR) +#define S_ISCHR(m) (((m) & S_IFMT) == S_IFCHR) +#endif +#if !defined(S_ISDIR) && defined(S_IFDIR) +#define S_ISDIR(m) (((m) & S_IFMT) == S_IFDIR) +#endif +#if !defined(S_ISREG) && defined(S_IFREG) +#define S_ISREG(m) (((m) & S_IFMT) == S_IFREG) +#endif +#if !defined(S_ISFIFO) && defined(S_IFIFO) +#define S_ISFIFO(m) (((m) & S_IFMT) == S_IFIFO) +#endif +#if !defined(S_ISLNK) && defined(S_IFLNK) +#define S_ISLNK(m) (((m) & S_IFMT) == S_IFLNK) +#endif +#if !defined(S_ISSOCK) && defined(S_IFSOCK) +#define S_ISSOCK(m) (((m) & S_IFMT) == S_IFSOCK) +#endif +#if !defined(S_ISMPB) && defined(S_IFMPB) /* V7 */ +#define S_ISMPB(m) (((m) & S_IFMT) == S_IFMPB) +#define S_ISMPC(m) (((m) & S_IFMT) == S_IFMPC) +#endif +#if !defined(S_ISNWK) && defined(S_IFNWK) /* HP/UX */ +#define S_ISNWK(m) (((m) & S_IFMT) == S_IFNWK) +#endif + +void mode_string (); +static char ftypelet (); +static void rwx (); +static void setst (); + +/* filemodestring - fill in string STR with an ls-style ASCII + representation of the st_mode field of file stats block STATP. + 10 characters are stored in STR; no terminating null is added. + The characters stored in STR are: + + 0 File type. 'd' for directory, 'c' for character + special, 'b' for block special, 'm' for multiplex, + 'l' for symbolic link, 's' for socket, 'p' for fifo, + '-' for regular, '?' for any other file type + + 1 'r' if the owner may read, '-' otherwise. + + 2 'w' if the owner may write, '-' otherwise. + + 3 'x' if the owner may execute, 's' if the file is + set-user-id, '-' otherwise. + 'S' if the file is set-user-id, but the execute + bit isn't set. + + 4 'r' if group members may read, '-' otherwise. + + 5 'w' if group members may write, '-' otherwise. + + 6 'x' if group members may execute, 's' if the file is + set-group-id, '-' otherwise. + 'S' if it is set-group-id but not executable. + + 7 'r' if any user may read, '-' otherwise. + + 8 'w' if any user may write, '-' otherwise. + + 9 'x' if any user may execute, 't' if the file is "sticky" + (will be retained in swap space after execution), '-' + otherwise. + 'T' if the file is sticky but not executable. */ + +void +filemodestring (statp, str) + struct stat *statp; + char *str; +{ + mode_string (statp->st_mode, str); +} + +/* Like filemodestring, but only the relevant part of the `struct stat' + is given as an argument. */ + +void +mode_string (mode, str) + unsigned short mode; + char *str; +{ + str[0] = ftypelet ((long) mode); + rwx ((mode & 0700) << 0, &str[1]); + rwx ((mode & 0070) << 3, &str[4]); + rwx ((mode & 0007) << 6, &str[7]); + setst (mode, str); +} + +/* Return a character indicating the type of file described by + file mode BITS: + 'd' for directories + 'b' for block special files + 'c' for character special files + 'm' for multiplexor files + 'l' for symbolic links + 's' for sockets + 'p' for fifos + '-' for regular files + '?' for any other file type. */ + +static char +ftypelet (bits) + long bits; +{ +#ifdef S_ISBLK + if (S_ISBLK (bits)) + return 'b'; +#endif + if (S_ISCHR (bits)) + return 'c'; + if (S_ISDIR (bits)) + return 'd'; + if (S_ISREG (bits)) + return '-'; +#ifdef S_ISFIFO + if (S_ISFIFO (bits)) + return 'p'; +#endif +#ifdef S_ISLNK + if (S_ISLNK (bits)) + return 'l'; +#endif +#ifdef S_ISSOCK + if (S_ISSOCK (bits)) + return 's'; +#endif +#ifdef S_ISMPC + if (S_ISMPC (bits)) + return 'm'; +#endif +#ifdef S_ISNWK + if (S_ISNWK (bits)) + return 'n'; +#endif + return '?'; +} + +/* Look at read, write, and execute bits in BITS and set + flags in CHARS accordingly. */ + +static void +rwx (bits, chars) + unsigned short bits; + char *chars; +{ + chars[0] = (bits & S_IRUSR) ? 'r' : '-'; + chars[1] = (bits & S_IWUSR) ? 'w' : '-'; + chars[2] = (bits & S_IXUSR) ? 'x' : '-'; +} + +/* Set the 's' and 't' flags in file attributes string CHARS, + according to the file mode BITS. */ + +static void +setst (bits, chars) + unsigned short bits; + char *chars; +{ +#ifdef S_ISUID + if (bits & S_ISUID) + { + if (chars[3] != 'x') + /* Set-uid, but not executable by owner. */ + chars[3] = 'S'; + else + chars[3] = 's'; + } +#endif +#ifdef S_ISGID + if (bits & S_ISGID) + { + if (chars[6] != 'x') + /* Set-gid, but not executable by group. */ + chars[6] = 'S'; + else + chars[6] = 's'; + } +#endif +#ifdef S_ISVTX + if (bits & S_ISVTX) + { + if (chars[9] != 'x') + /* Sticky, but not executable by others. */ + chars[9] = 'T'; + else + chars[9] = 't'; + } +#endif +}