.














                              Cook

                    A File Construction Tool





                        Reference Manual







                          Peter Miller

                    [4mmillerp@canb.auug.org.au[0m
































.












This document describes Cook version 2.21
and was prepared 1 April 2015.






This document describing the Cook program, and the Cook program
itself, are
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
1996, 1997, 1998, 1999, 2000, 2001, 2002 Peter Miller; All rights
reserved.

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,
Read Me(Cook)                                                    Read Me(Cook)



USA.

[1mNAME[0m
       cook - a file construction tool

[1mDESCRIPTION[0m
       The [4mcook[24m program is a tool for constructing files, and maintaining
       referential integrity between files.  It is given a set of files to
       create, and recipes of how to create and maintain them.  In any non-
       trivial program there will be prerequisites to performing the actions
       necessary to creating any file, such as include files.  The [4mcook[0m
       program provides a mechanism to define these.

       When a program is being developed or maintained, the programmer will
       typically change one file of several which comprise the program.  The
       [4mcook[24m program examines the last-modified times of the files to see when
       the prerequisites of a file have changed, implying that the file needs
       to be recreated as it is logically out of date.

       The [4mcook[24m program also provides a facility for implicit recipes,
       allowing users to specify how to form a file with a given suffix from a
       file with a different suffix.  For example, to create [4mfilename[24m.o from
       [4mfilename[24m.c

       * Cook is a replacement for   * There is a [4mmake2cook[0m
       the traditional [4mmake[24m(1)       utility included in the
       tool.                         distribution to help
       * Cook is more powerful       convert makefiles into
       than the traditional [4mmake[24m     cookbooks.
       tool.
       * Cook has true variables,    * Cook has a simple but
       not simple macros.            powerful string-based
       * Cook has user defined       description language with
       functions.                    many built-in functions.
                                     This allows sophisticated
                                     filename specification and
                                     manipulation without loss
                                     of readability or
                                     performance.
       * Cook can build in           * Cook is able to build
       parallel.                     your project with multiple
       * Cook can distribute         parallel threads, with
       builds across your LAN.       support for rules which
                                     must be single threaded.
                                     It is possible to
                                     distribute parallel builds
                                     over your LAN, allowing you
                                     to turn your network into a
                                     virtual parallel build
                                     engine.
       * Cook is able to use         * Cook can be configured
       fingerprints to supplement    with an explicit list of
       file modification times.      primary source files.  This
       This allows build             allow the dependency graph
       optimization without          to be constructed faster by
       contorted rules.              not going down dead ends,
       * In addition to walking      and also allows better
       the dependency graph, Cook    error messages when the
       can turn the input rules      graph can't be constructed.
       into a shell script, or a     This requires an accurate
       web page.                     source file manifest.
       * Cook runs on almost any     * Cook has special [4mcascade[0m
       flavor of UNIX.  The source   dependencies, allowing
       distribution is self          powerful include dependency
       configuring using a GNU       specification, amongst
       Autoconf generated            other things.
       configure script.

       If you are putting together a source-code distribution and planning to
       write a makefile, consider writing a cookbook instead.  Although Cook
       takes a day or two to learn, it is much more powerful and a bit more
       intuitave than the traditional [4mmake[24m(1) tool.  And Cook doesn't
       interpret tab differently to 8 space characters!

[1mARCHIVE SITE[0m
       The latest version of [4mcook[24m is available on the Web from:

           URL:    http://www.canb.auug.org.au/~millerp/cook/
           File:   cook-2.21.README     # the README from the tar file
           File:   cook-2.21.lsm        # LSM format description
           File:   cook-2.21.spec       # RedHat package specification
           File:   cook-2.21.rm.ps.gz   # PostScript of the Reference Manual
           File:   cook-2.21.ug.ps.gz   # PostScript of the User Guide
           File:   cook-2.21.tar.gz     # the complete source

       This Web page also contains a few other pieces of software written by
       me.  Please have a look if you are interested.

       Cook is also carried by sunsite.unc.edu in its Linux archives.  You
       will be able to find Cook on any of its mirrors.

           URL:    ftp://sunsite.unc.edu/pub/Linux/devel/make/
           File:   cook-2.21.README     # the README from the tar file
           File:   cook-2.21.lsm        # LSM format description
           File:   cook-2.21.spec       # RedHat package specification
           File:   cook-2.21.rm.ps.gz   # PostScript of the Reference Manual
           File:   cook-2.21.ug.ps.gz   # PostScript of the User Guide
           File:   cook-2.21.tar.gz     # the complete source
       This site is extensively mirrored around the world, so look for a copy
       near you (you will get much better response).

[1mMAILING LIST[0m
       A mailing list has been created so that users of [4mcook[24m may exchange
       ideas about how to use the [4mcook[24m program.  Discussion may include, but
       is not limited to: bugs, enhancements, and applications.  The list is
       not moderated.

       The address of the mailing list is
              cook-users@canb.auug.org.au
       Please DO NOT send subscribe requests to this address.

       To subscribe to this mailing list, send an email message to
       majordomo@canb.auug.org.au with a message body containing the single
       line
              subscribe cook-users
       If you have an email address which is not readily derived from your
       mail headers (majordomo is only a Perl program, after all) you will
       need to use a message of the form:
              subscribe cook-users [4maddress[0m
       where [4maddress[24m is the email address to which you want messages sent.

       The software which handles this mailing list CANNOT send you a copy of
       the [4mcook[24m program.

[1mBUILDING COOK[0m
       Full instructions for building the [4mcook[24m program may be found in the
       [4mBUILDING[24m file included in this distribution.

[1mCOPYRIGHT[0m
       [4mcook[24m version 2.21
       Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
       1997, 1998, 1999, 2000, 2001, 2002 Peter Miller; All rights reserved.

       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, USA.

       It should be in the [4mLICENSE[24m file included with this distribution.

[1mAUTHOR[0m
       Peter Miller   E-Mail:   millerp@canb.auug.org.au
       /\/\*          WWW:      http://www.canb.auug.org.au/~millerp/

[1mNEW IN THIS RELEASE[0m
       A number of features have been added to [4mcook[24m with this release.  The
       following list is only a summary; for excruciating detail, and also
       acknowlegements of those who generously sent me feedback, please see
       the [4metc/CHANGES.*[24m files included in this distribution.

   [1mVersion 2.21[0m
       * The [4mc_incl[24m(1) command now accepts the -stripdot and -nostripdot
       options.  These may be used to control the removal of redundant leading
       dot directories.

       * A bug has been fixed where cascade recipes failed to heed the
       stripdot setting.

       * There is a new [stripdot] function, so that you can strip leading dot
       directories from file names within functions.

       * A bug has been fixed in how the builtin functions which manipulate
       build graphs were called.  This fixed a problem with freeing a string
       which had already been freed.

   [1mVersion 2.20[0m
       * There is a fix for the build problems caused by recent GNU Gettext
       releases.

       * The fingerprint handling is now more robust, particularly when faced
       with files that move backwards in time.

       * There is a fix for the build problems caused by recent Bison
       releases.

   [1mVersion 2.19[0m
       * Some introduced with recent versions of GNU Bison have been fixed.
       Bison's include file insulation didn't use YY in the insulating symbol
       (just to be completely inconsistent) and in another case a namespace
       clash occurred for a function name.

       * The generated Makefile has been improved, along with other small
       build and install improvements.

       * A top-level [4mfail[24m statement how halts the parse as soon as it is
       executed.  This will make it more useful for checking build
       environments.

       * Documentation about [4mcook_rsh[24m(1) has been added to the Parallel
       chapter of the User Guide.

   [1mVersion 2.18[0m
       * A bug has been fixed in the [4mingredients-fingerprint[24m recipe attribute.
       It was failing to save the fingerprint cache file in some cases, and
       thus came to incorrect conclusions on following runs.

       * The [4m(exists)[24m ingredients attribute has been fixed so that it no
       longer implies behavious rimilar to [4mset[24m [4mshallow[24m.

       * There is a new [4mcook_rsh[24m(1) program, for use with the [4mhost-binding[0m
       recipe attribute, which allows you to load balance builds across
       classes of hosts.  See [4mcook_rsh[24m(1) and the Parallel chapter of the User
       Guide for more information.

       * Some build problems have been fixed on various platforms.

       * More keywords are now understood for M4 include directives.

   [1mVersion 2.17[0m
       * When using file fingerprints, the way the [4m.cook.fp[24m file is written
       has been changed, so that the timestamp of the containing directory is
       modified much less often.  This is useul in combination with the
       [4mcook_bom[24m(1) utility.

       * A bug has been fixed under Cygwin, where archive members were not
       being fingerprinted correctly.

       * A bug has been fixed in the [quote] function.  It now quotes all
       [4msh[24m(1), [4mcsh[24m(1) and [4mbash[24m(1) special characters correctly.

       * A bug has been fixed in the [uptodate] function.  It now works as
       advertised.

       * There is a new [4mingredients-fingerprint[24m recipe flag.  This means that
       you can now cause a recipe to re-trigger when the ingredients list
       changes.  This is especially useful when a library has a file removed.

       * The dependency graph can now have the edge types specified.  The
       ``weak'' edge type if useful for managing links, and the ``exists''
       edge type is useful for managing version stamps.  See the User Guide
       for more information.

   [1mVersion 2.16[0m
       * The [4mstringset[24m function now accepts a `+' operator.  While union is
       implicit, the apparrently redundant `+' operator is useful for
       cancelling the other operators.

       * The ``reason and fingerprint bug'' has been fixed.  This caused a
       mysterious error message to appear sometimes when using the -reson
       option incombination with fingerprints.

       * The % and %[4mn[24m patterns are now allowed to match the empty string,
       provided they aren't the first thing in the pattern (otherwise
       undesirable absolute path problems can occur).

       * The [4mc_incl[24m(1) command now accepts `-' as a file name on the command
       line, meaning standard input.

       * Some improvements have been made to the Cygwin support, extending the
       ``.exe'' automatic executable suffix coverage to a couple more places.

       * A bug in the ``c'' cookbook has been fixed, which was getting .h
       dependency files wrong.

   [1mVersion 2.15[0m
       * The [4mC_incl[24m(1) problem with absolute paths has been fixed.

       * A bug has been fixed which caused problems on Solaris and SGI, where
       Cook would report a No child processes error.

   [1mVersion 2.12[0m
       * The [4mc_incl[24m program now has a [1m-quote-filenames [22moption, which means
       that you can have filenames with spaces and special characters in them.

       * A bug in the [4mc_incl[24m program's path flattening has been fixed.

       * A small Y2K bug has been fixed in the date parsing used by the
       [4mcooktime[24m(1) command.

       * A bug which caused the -parallel option to lose track of processes
       when you used [execute] in a recipe body has been fixed.

       * The restrictions on the placement of the placement of %0 in a pattern
       have been dropped; too many people didn't like it.  This does [4mnot[24m break
       any cookbooks.

       * Cook now copes with the absence of the HOME environment variable.
       This was a problem for CGI scripts.

   [1mVersion 2.11[0m
       * Numerous portability problems have been fixed in the configure and
       build.

       * A bug has been fixed which prevented Cook from working correctly when
       run by some versions of [4mcron[24m(8) and [4mat[24m(1).

       * There is a new [4mcook_bom[24m [4m--ignore[24m option, allowing you to nominate
       file patterns that you don't want in the file lists.

       * There is a new [__FUNCTION__] variable, which contains the name of
       the executing function, which suppliments the existing [__FILE__] and
       [__LINE__] variables.

       * Functions now have local variables, just put the word local on the
       left-hand-side of the first assignment.  Local variables are reentrant
       and thread-safe.

   [1mVersion 2.10[0m
       * The [4m[print][24m and [4m[write][24m functions now work more sensably with the
       [1m-SCript [22moption.

       * The fingerprint code has been improved.  It now does considerably
       fewer redundant fingeprint calculations, resulting is some very welcome
       speed improvements.

       * The behaviour of the remote shell invocation to cope with rshd at the
       remote end failing to spawn a shell, and it copes with the default
       shell at the remote end not being the Bourne shell.

       * The [1m-PARallel [22mbehaviour has been improved, so that it now looks for
       child process who have finished [4mmore[24m [4mthan[24m it looks for recipes to run.
       This doesn't change the semantics any, but it matches user expectations
       far better (and results in shorter-lived zombie processes).

       * The [4mset[24m [4mmeter[24m recipe flag works once more.  (It stopped working when
       the parallel modifications were made, and mysteriously forgotten until
       now.)

       * There are some changes made to the fingerprinting code to detect when
       files under ClearCase move backwards in time (because the underlying
       file version is ``uncovered'') meaning that the derived (object) files
       need to be rebuilt.

       * There is a new [mtime-seconds] function, similar to the [mtime]
       function, except that it returns seconds since the epoch, rather than a
       human readable date.  More useful to handing to [expr].

       * A bug has been fixed on SGI IRIX which failed to cope with not being
       able to create directories because they already exist.

       * Ingredient recipes (ones with no body) may now have a double colon
       rather than a single colon, even when there is more than on target
       specified.  Some users may find this a more natural syntax for
       ingredients recipes.

       * The [expr] function now reports an error when given a number too big
       to represent, rather than quietly returning wrong answers.  The range
       of representable values depends on your system.

       * Cook now works with GNU Regex correctly on Windows-NT.

   [1mVersion 2.9[0m
       * There is a new ``for each'' style looping construct.  See the User
       Guide for more information.

       * It is now possible to use regular expression patterns, instead of
       Cook's native patterns.  You can set this for a whole cookbook or
       individual recipes.  The default is to use Cook's native patterns.  See
       the [4mFile[24m [4mName[24m [4mPatterns[24m chapter of the User Guide for more information.

       * A bug which caused [4mhost-binding[24m and [4msingle-thread[24m to core dump has
       been fixed.

       * All text file input now copes with CRLF sequences, so mixing NT and
       Unix builds on the one file server no longer creates problems.

       * Fingerprints are now cached per-directory, rather than one huge file
       for an entire directory tree.  This is more useful in recursive build
       and [search_list] situations.

       * The [cando], [cook] and [uptodate] functions now return lists of
       successful files, rather than a simple true/false result.

       * The [in] and [matches] functions now return the list index (1 based)
       of the matching word.  See the User Guide for more information.

       * There is a new [4mcook[24m [4m-web[24m option, to print a HTML web page on the
       standard output, representing the dependency graph.  This is useful in
       documenting the build process, or debugging cookbooks.

       * There is a new [4mcook[24m [4m--fingerprint-update[24m option which scans the
       directory tree below the current directory and updates the file
       fingerprints.  This helps when you use another tool (such as RCS or
       ClearCase) which alters the file but preserves the file's modification
       time.

       * There is a new [write] function for writing text files.  This is
       useful for coping with Windows-NT's absurdly short command lines.

   [1mVersion 2.8[0m
       * The remote [4mhost-binding[24m code has been improved to cope with
       staggeringly long commands (which tended to make [4mrsh[24m(1) barf), and also
       wierd and wonderfull $SHELL settings.

       * The #include directive now accepts more than one file, to be more
       symmetric with the #include-cooked directive.

       * A bug has been fixed where cooktime gave an incorrect error message
       if setting the file's utimes failed.

       * The configure script has been improved for use on non-UNIX systems.

       * There is a new builtin [cook] function, a natural companion for the
       [cando] and [uptodate] functions.  See the Cook User Guide for more
       information.

   [1mVersion 2.7[0m
       * There is a new [4mcook_bom[24m(1) command (Bill Of Materials).  This may be
       used to efficiently scan a directory tree for files, so that
       ingredients lists may be produced automatically.  See [4mcook_bom[24m(1) for
       more information.

       * There is a new assign-append statement, so you can now use += to
       append to the value of a variable.  See the User Guide for more
       information.

       * There is a new [4mgate-first[24m recipe flag, which causes the recipe gate
       to be evaluated before the ingredients are derived, rather than after.

       * The [4mc_incl[24m(1) command has a new --interior-files option, so you can
       tell it about include files that don't exist yet.  This is helpful when
       they are generated, [4mi.e.[24m they are interior files of the dependency
       graph, hence the option name.

       * There is a new [interior-files] function, which returns the files
       interior to the dependency graph (constructed by a recipe), and a
       complementatry [leaf-files] function, which returns the leaf files of
       the dependency graph (not constructed by any recipe).

       * There is a new ``no-include-cooked-warning'' flag, if you want to
       suppress the warnings about derived file dependencies in include-cooked
       files.

       * There is a new [4mrelative_dirname[24m built-in function, similar to the
       existing [4mdirname[24m function, but it returns ``.'' for files with no
       directory part, rather than the absolute path of the current directory.

   [1mVersion 2.6[0m
       * Cook has been ported to Windows-NT using CygWin32.  See the BUILDING
       file for details.

       * There are two new functions ([4mdos-path[24m and [4mun-dos-path[24m) for use when
       invoking non-CygWin32 WindowsNT programs.  See the Cook User Guide for
       more information.

       * Fingerprints now work meaningfully with directories.

       * A bug has been fixed in the pattern matching code.  It would
       sometimes cause core dumps.

       * A bug involving fingerprints in combination with the search_list has
       been fixed.  Cook would occasionally conclude that a shallow target was
       up-to-date when a shallow ingredient was edited to be the same as a
       deeper ingredient.

       * A bug has been fixed in cooktime.  It would use an inappropriate
       timezone offset on some systems.

   [1mRelease 2.5[0m
       * A problem which caused some tests to fail on Solaris' tmpfs now has a
       work-around.

       * The ``setenv'' statement has finally been documented.  It's been in
       the code tfor years, but I could never figure out why folks weren't
       using it!

       * A number of build problems on various systems have been fixed.

   [1mRelease 2.4[0m
       * There is a new form of dependencies.  Known as cascaded dependencies,
       they allow the user to associate additional dependencies with an
       ingredient.  For example, a C source file can be associated with
       cascaded include dependencies.  This means that all files which depend
       on the C source file, also depend on the included files.  The Cook
       Reference Manual has been updated to include this new functionality.

       * There is a new section of the Cook Reference Manual giving
       suggestions and a template for building large projects.

       * There is a new [expr] function, to calculate simple arithmetic
       expressions.  See the User Guide for more information.

       * There is a new c_incl -no-recursion option, to prevent scanning
       nested includes.  This is of most use when combined with the new
       cascade dependencies.

       * There is a new [exists-symlink] function, which may be used to test
       for the existence of symlinks.  The [exists] function follows symbolic
       links, and is not useful when manipulating the links themselves.

   [1mRelease 2.3[0m
       * There are 6 new special variables: graph_leaf_file,
       graph_leaf_pattern, graph_interior_file, graph_interior_pattern,
       graph_exterior_file and graph_exterior_pattern.  These variables may be
       used to define the leaves of the derivation graph (the [4maccept[24m forms),
       and non-leave of the graph (the [4mreject[24m forms).  This can make the graph
       derivation faster, and greatly improves some error messages.  This
       functionality is of most use when you have an exact source file
       manifest, [4me.g.[24m from a software configuration management system.  See
       the User Guide for more information.

       * The %0 pattern element has been extended to permit the matching of
       absolute paths.

   [1mRelease 2.2.2[0m
       * There is a new statement type, allowing functions to be invoked as
       subroutines in any place where a command may be invoked.  See the User
       Guide for more information.

       * A number of problems with installing Cook have been fixed.  This
       includes changing -mgm to -mm for the documnetation formatting, and
       missing include dependencies and missing rules for installing the man
       pages.

       * There is a new ``print'' builtin function.  When combined with the
       new function call statement, this provides a way of printing
       information without invoking ``echo''.  See the User Guide for more
       information.

       * Cook now defaults the language to ``en'' internally if neoither the
       LANG nor LANGUAGE environment variable was set.  This gives better
       error messages.

   [1mRelease 2.2.1[0m
       * A bug was fixed where a recipe would fail to trigger if some, but not
       all, of its targets were not present, but the existing targets were up-
       to-date.  This bug was introduced in the inference engine re-write.

   [1mRelease 2.2[0m
       * The [4mc_incl[24m utility has had two new languages added.  It now
       understands M4, and also has an ``optimistic'' language which can scan
       many assemblers and even some high-level languages.  See [4mc_incl[24m(1) for
       more information.

       * The [4mc_incl[24m utility also has a new --no-absolute-path option, to
       supress scanning and reporting of such files.  See [4mc_incl[24m(1) for more
       information.

       * There is a new warning added for dependencies on derived ingredients
       when this information resides solely in derived cookbooks included
       using the #include-cooked facility.  This assists in detecting problems
       which may preclude a successful ``clean'' build.

       * This release adds a number of cookbook functions to the distrubuted
       cookbooks.  These may be used by adding a
           #include "functions"
       line to your cookbook.  See the Cook User Guide for more information.

       * This release fixes a bug where the graph walking phase ignored
       interrupts until something went wrong.

       * This release fixes a bug where [4mmake2cook[24m did not correctly translate
       ``%'' into sematicly equivalent Cook constructs.

   [1mRelease 2.1[0m
       * It is possible to specify that a command is to be executed on a
       specific machine or machines.  This can be useful for restrictively
       licensed third party software tools.

       * The parallel functionality has been extended to implement a virtual
       parallel machine on a LAN.

       * Fingerprinting has been enhanced to be more informative, and to
       adjust file modification times so that subsequest fingerprint-less runs
       will not find too much to do.

       * The #line directive is now available, for better diagnostics of
       generated cookbooks.  The __FILE__ and __LINE__ variable are also
       available.

       * There is now a thread-id variable, to obtain a thread-unique value
       for use in generating temporary file names or variable names, [4metc[24m,
       which are unique to a thread.

       * Added the wordlist function and the command-line-goals variable for
       compatibility with GNU Make.  Updated [4mmake2cook[24m to understand them.

   [1mRelease 2.0.1[0m
       * An install problem in the generated Makefile, to do with the the
       manuals, has been fixed.

   [1mRelease 2.0[0m
       Development of this release was generously supported by Endocardial
       Solutions, Inc.

       * Parallel execution is now supported.  If you have a multi-processor
       machine, you can specify the number of parallel processing threads with
       the -PARallel command line option, or via the [4m[parallel_jobs][24m variable.
       By using the [4m[os[24m [4mnode][24m function, the [4m[parallel_jobs][24m variable can be
       set appropriately for the host machine automatically by the cookbook.
       There is a new single-thread keyword to support single threading
       recipes which cannot be paralleized.

       * The dependency graph is now constructed differently.  This gives
       exactly the same results, but the order of evaluation of recipes is a
       little more random.  This different graph construction is able to give
       better error messages, better -Reason information, and allows the
       introduction of parallel recipe evaluation if you have a multi-
       processor computer.

       * Recipes which use [4mc_incl[24m(1) to calculate their dependencies in the
       ingredients section will need a small modification - they will need to
       use the --Absent-Program-Ignore option.  See the User Guide for more
       information.

       * You can now print pair-wise file dependencies by using the -PAirs
       option.

       * You can now print a shell script which approximates the actions cook
       would take when building the targets by using the -SCript option.

       * There is a new ``shallow'' recipe flag, allowing you to specify that
       the targets of a recipe are required to be in the top-level directory,
       not further down the search_list path.

       * You may now define user-written functions in the cookbook to
       supplement the built-in functions.  Your functions will be called in
       the same manner as built-in functions.  There are new function and
       return keywords to support definition of functions.

       * The progress indicators produced by the -STar option now have more
       detail: [1m+ [22mmeans that the cook book is being read, [1m* [22mmeans that the
       graph is being constructed, and [1m# [22mmeans that the graph is being walked.

   [1mRelease 1.11[0m
       * Fixed a bug in the pattern matching which caused %0 (when not at the
       start of the pattern) to fail to match the empty string.

       * The install locations have been changed slightly to conform better to
       the GNU filesystem standards, and to take advantage of the additional
       install location options of the configure scripts generated by GNU
       Autoconf.

   [1mRelease 1.10[0m
       * Error messages have been internationalized.  It is now possible to
       get error messages in your native language, if it is supported.

       * The cook command now accepts a -no-include-cooked option, to disable
       any cooking of the #include-cooked files.

       * The cook -TRace option has been renamed -Reason.  This is thought to
       more accurately reflect what it does.

       * The cook -Reason output has been changed to cite cookbook file names
       and line numbers, in order to be more useful.  In addition, more reason
       messages carry location information.

   [1mRelease 1.9[0m
       * There are new ``f77'' and ``g77'' cookbooks, to allow Fortran
       sources, in addition to C sources.

       * There is a new [options] function, which expands to the current
       settings of the command line options.  This is useful for recursive
       cook directory structures.  See the Reference Manual for more
       information.

       * There is a new ``recursive'' cookbook, to assist in constructing
       recursive cook structures.

       * The [4mfind_libs[24m program now understands about shared libraries.

       * A bug which made the builtin [glob] function far to generous has been
       corrected.

       * A bug which caused some expression evaluation errors to be ignored
       has been corrected.

       * The ``set update'' flag has been re-named the ``set time-adjust''
       flag, to more closely describe what it does.  The old name will
       continue to work indefinitely.

       * There is a new ``set time-adjust-back'' flag, which sets recipe
       target times to be exactly one (1) second younger than the youngest
       ingredient.  This is usually an adjustment into the recent past.

   [1mRelease 1.8[0m
       * The fingerprint code has been improved to work better with the
       search_list functionality.

       * The diagnostics have been improved when cook ``don't know how''.  A
       list of attempted ingredients is included in the error message.

       * There is a new [4mmkdir[24m recipe flag.  This creates recipe target
       directories before the recipe body is run.  See the Reference Manual
       for more information.

       * There is a new [4munlink[24m recipe flag.  This unlinks recipe targets
       before the recipe body is run.  See the Reference Manual for more
       information.

       * There is a new [4mrecurse[24m recipe flag.  This overrides the infinite loop
       recipe heuristic, allowing recipes to recuse upon themselves if one of
       their ingredients matches one of their targets.  See the Reference
       Manual for more information.

   [1mRelease 1.7[0m
       * The AIX code to handle archive files has been fixed.

       * The fingerprint code now works on 64-bit systems.

   [1mRelease 1.6[0m
       * Fixed a bug in the leading-dot removal code, and added an option to
       make it user-settable.  Fixed a bug in the search_path depth code.

   [1mRelease 1.5[0m
       * The [4mc_incl[24m program now correctly prints the names of absent include
       files, causing them to be cooked correctly in a greater number of
       cases.

       * Recipes with no ingredients are now only applied if the target is
       absent.  To still use the previous behaviour, use the "set force"
       clause on the recipe.

       * It is now possible to supplement the last-modified time with a
       fingerprint, so cook does even fewer unnecesary recompilations than
       before.  Put the statement
              set fingerprint;
       somewhere near the top of your [4mHowto.cook[24m file for this to be the
       default for your project.

       * There is a new form of include directive:
              #include-cooked [4mfilename[24m...
       When files are included in this way, [4mcook[24m will check to make sure they
       are up-to-date.  If not, they will be cooked, and then [4mcook[24m will start
       again and re-read the cookbook.  This is most often used for
       maintaining include-dependency files.

       * [1mCook [22mnow configured using a program called [4mconfigure[24m, distributed
       with the package.  The [4mconfigure[24m program is generated by GNU Autoconf.
       See the [4mBUILDING[24m file for more details.

       * The semantics of [4msearch_list[24m have been improved.  It is now
       guaranteed that when ingredients change they result in targets earlier
       in the [4msearch_list[24m being updated.

       * There is now a [4mmake2cook[24m translator, to translate [4mMakefile[24m files into
       [4mHowto.cook[24m files.  Most of the GNU Make extensions are understood.
       There is no exact semantic mapping between [4mmake[24m and [4mcook,[24m so manual
       editing is sometimes required.  See [4mmake2cook[24m(1) for more information.

       * [4mCook[24m now understands archive member references, in the same format as
       used by [4mmake[24m, et al.  Archive member references benefit from stat
       caching and fingerprinting, just as normal files do.

   [1mRelease 1.4[0m
       * The [4mcook[24m program is now known to work on more systems.  Most changes
       were aimed at improving portability, or avoiding problems specific to
       some systems.

       * The GNU long option name convention is now understood.  Option names
       for [4mcook[24m were always long, so this mostly consists of ignoring the
       extra leading '-'.  The "--foo=bar" convention is also understood for
       options with arguments.

       * Tests which fail now tell you what it was they were testing for.
       This will give the user some idea of what is happening.



Build(Cook)                                                        Build(Cook)



[1mNAME[0m
        cook - a file construction tool

[1mSPACE REQUIREMENTS[0m
        You will need about 5MB to unpack and build the [4mCook[24m package.  Your
        milage may vary.

[1mBEFORE YOU START[0m
        There are a few pieces of software you may want to fetch and install
        before you proceed with your installation of Cook.

        Please note: if you install these packages into [4m/usr/local[24m (for
        example) you must ensure that the [4m./configure[24m script is told to also
        look in [4m/usr/local/include[24m for include files (CFLAGS), and
        [4m/usr/local/lib[24m for library files (LDFLAGS).  Otherwise the [4m./configure[0m
        script will incorrecly conclude that they have not been installed.

        GNU Gettext
                The [4mCook[24m package has been internationalized.  It can now print
                error messages in any of the supported languages.  In order to
                do this, the GNU Gettext package must be installed [4mbefore[24m you
                run the configure script as detailed in the next section.
                This is because the configure script looks for it.  On systems
                which use the GNU C library, version 2.0 or later, there is no
                need to explictly do this as GNU Gettext is included.
                Remember to use the GNU Gettext configure [4m--with-gnu-gettext[0m
                option if your system has native gettext tools.

        GNU rx
                Cook needs regular expressions to operate correctly.  Get a
                copy from your nearest GNU mirror.  On systems which use the
                GNU C library, version 2.0 or later, there is no need to
                explictly do this as GNU rx is included.

        GNU Groff
                The documentation for the [4mCook[24m package was prepared using the
                GNU Groff package.  This distribution includes full
                documentation, which may be processed into PostScript or DVI
                files at install time - if GNU Groff has been installed.  You
                must use GNU Groff version 1.15 or later.

        Bison   If your operating system does not have a native [4myacc[24m(1) you
                will need to fetch and install GNU Bison in order to build the
                [4mCook[24m package.

        GCC     You may also want to consider fetching and installing the GNU
                C Compiler if you have not done so already.  This is not
                essential.

        The GNU FTP archives may be found at ftp.gnu.org, and are mirrored
        around the world.

[1mSITE CONFIGURATION[0m
        The [1mCook [22mpackage is configured using the [4mconfigure[24m program included in
        this distribution.

        The [4mconfigure[24m shell script attempts to guess correct values for
        various system-dependent variables used during compilation, and
        creates the [4mMakefile[24m and [4mcommon/config.h[24m files.  It also creates a
        shell script [4mconfig.status[24m that you can run in the future to recreate
        the current configuration.

        Normally, you just [4mcd[24m to the directory containing [4mCook[24m's source code
        and type
                [1m% [22m./configure
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1m%[0m
        If you're using [4mcsh[24m on an old version of System V, you might need to
        type
                [1m% [22msh configure
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1m%[0m
        instead to prevent [4mcsh[24m from trying to execute [4mconfigure[24m itself.

        Running [4mconfigure[24m takes a minute or two.  While it is running, it
        prints some messages that tell what it is doing.  If you don't want to
        see the messages, run [4mconfigure[24m using the quiet option; for example,
                [1m% [22m./configure --quiet
                %

        There is a known problem with GCC 2.8.3 and HP/UX.  You will need to
        set CFLAGS = -O in the generated Makefile.  (The configure script sets
        it to CFLAGS = -O2.)  This is because the code optimization breaks the
        fingerprints.  If test 46 fails (see below) this is probably the
        reason.

        To compile the [1mCook [22mpackage in a different directory from the one
        containing the source code, you must use a version of [4mmake[24m that
        supports the [4mVPATH[24m [4mvariable,[24m such as [4mGNU[24m [4mmake[24m.  [4mcd[24m to the directory
        where you want the object files and executables to go and run the
        [4mconfigure[24m script.  [4mconfigure[24m automatically checks for the source code
        in the directory that [4mconfigure[24m is in and in [4m..[24m  (the parent
        directory).  If for some reason [4mconfigure[24m is not in the source code
        directory that you are configuring, then it will report that it can't
        find the source code.  In that case, run [4mconfigure[24m with the option
        --srcdir=[4mDIR[24m, where [4mDIR[24m is the directory that contains the source
        code.

        By default, [4mconfigure[24m will arrange for the [4mmake[24m [4minstall[24m command to
        install the [1mCook [22mpackage's files in [4m/usr/local/bin[24m, [4m/usr/local/lib[24m,
        [4m/usr/local/share[24m and [4m/usr/local/man[24m.  There are a number of options
        which allow you to control the placement of these files.

        --prefix=[4mPATH[0m
                This specifies the path prefix to be used in the installation.
                Defaults to [4m/usr/local[24m unless otherwise specified.

        --exec-prefix=[4mPATH[0m
                You can specify separate installation prefixes for
                architecture-specific files files.  Defaults to [4m${prefix}[0m
                unless otherwise specified.

        --bindir=[4mPATH[0m
                This directory contains executable programs.  On a network,
                this directory may be shared between machines with identical
                hardware and operating systems; it may be mounted read-only.
                Defaults to [4m${exec_prefix}/bin[24m unless otherwise specified.

        --datadir=[4mPATH[0m
                This directory contains installed data, such as the
                documentation and cookbooks distributed with Cook.  On a
                network, this directory may be shared between all machines; it
                may be mounted read-only.  Defaults to [4m${prefix}/share/cook[0m
                unless otherwise specified.  A ``cook'' directory will be
                appended if there is none in the specified path.

        --libdir=[4mPATH[0m
                This directory contains installed data, such as the error
                message catalogues.  On a network, this directory may be
                shared between machines with identical hardware and operating
                systems; it may be mounted read-only.  Defaults to
                [4m${exec_prefix}/lib/cook[24m unless otherwise specified.  A
                ``cook'' directory will be appended if there is none in the
                specified path.

        --mandir=[4mPATH[0m
                This directory contains the on-line manual entries.  On a
                network, this directory may be shared between all machines; it
                may be mounted read-only.  Defaults to [4m${prefix}/man[24m unless
                otherwise specified.

        [4mconfigure[24m ignores most other arguments that you give it; use the
        --help option for a complete list.

        On systems that require unusual options for compilation or linking
        that the [4mCook[24m package's [4mconfigure[24m script does not know about, you can
        give [4mconfigure[24m initial values for variables by setting them in the
        environment.  In Bourne-compatible shells, you can do that on the
        command line like this:
                [1m$ [22mCC='gcc -traditional' LIBS=-lposix ./configure
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1m$[0m
        Here are the [4mmake[24m variables that you might want to override with
        environment variables when running [4mconfigure[24m.

        Variable: CC
                C compiler program.  The default is [4mcc[24m.

        Variable: CPPFLAGS
                Preprocessor flags, commonly defines and include search paths.
                Defaults to empty.  It is common to use
                CFLAGS=-I/usr/local/include to access other installed
                packages.

        Variable: INSTALL
                Program to use to install files.  The default is [4minstall[24m if
                you have it, [4mcp[24m otherwise.

        Variable: LIBS
                Libraries to link with, in the form -l[4mfoo[24m -l[4mbar[24m.  The
                [4mconfigure[24m script will append to this, rather than replace it.
                It is common to use LIBS=-L/usr/local/lib to access other
                installed packages.

        If you need to do unusual things to compile the package, the author
        encourages you to figure out how [4mconfigure[24m could check whether to do
        them, and mail diffs or instructions to the author so that they can be
        included in the next release.

[1mBUILDING COOK[0m
        All you should need to do is use the
                [1m% [22mmake
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1m%[0m
        command and wait.  When this finishes you should see a directory
        called [4mbin[24m containing nine files: [4mc_incl[24m, [4mcook[24m, [4mcookfp[24m, [4mcooktime[24m,
        [4mfind_libs[24m, [4mmake2cook[24m and [4mroffpp[24m.

        [1mcook    [4m[22mcook[24m program is a file construction tool, and may invoke the
                following tools in some of its recipes.

        [1mcookfp  [22mThe [4mcookfp[24m program is a utility distributed with [4mCook[24m which
                calculates the fingerprints of files.  It uses the same
                algorithm as the fingerprints used by [4mcook[24m itself.  For more
                information, see [4mcook[24m(1) and [4mcookfp[24m(1).

        [1mcooktime[0m
                The [4mcooktime[24m program is a utility distributed with [4mCook[24m which
                allows the time-last-modified and time-last-accessed stamps of
                files to be set to specific times.  For more information, see
                [4mcooktime[24m(1).

        [1mc_incl  [22mThe [4mc_incl[24m program is a utility distributed with [4mCook[24m which
                examines C files and determines all the files it includes
                directly and indirectly.  For more information, see [4mc_incl[24m(1).

        [1mfind_libs[0m
                The [4mfind_libs[24m program is a utility distributed with [4mCook[24m which
                tracks down the names of library files, given cc-style library
                options (-L and -l).  For more information, see [4mfind_libs[24m(1).

        [1mmake2cook[0m
                The [4mmake2cook[24m program is a utility to help convert Makefiles
                into cookbooks.  An exact 1:1 semantic mapping is not
                possible, so some addition editing is often required.

        [1mroffpp  [22mThe [4mroffpp[24m program is a utility distributed with [4mCook[24m which
                acts as a proprocessor for *roff files, removing source (.so)
                directives.  It accepts include search path command line
                options just as [4m/lib/cpp[24m does.  For more information, see
                [4mroffpp[24m(1).

        You can remove the program binaries and object files from the source
        directory by using the
                [1m% [22mmake clean
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1m%[0m
        command.  To remove all of the above files, and also remove the
        [4mMakefile[24m and [4mcommon/config.h[24m and [4mconfig.status[24m files, use the
                [1m% [22mmake distclean
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1m%[0m
        command.

        The file [4metc/configure.in[24m is used to create [4mconfigure[24m by a GNU program
        called [4mautoconf[24m.  You only need to know this if you want to regenerate
        [4mconfigure[24m using a newer version of [4mautoconf[24m.

[1mTESTING COOK[0m
        The [4mCook[24m program comes with a test suite.  To run this test suite, use
        the command
                [1m% [22mmake sure
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1mPassed All Tests[0m
                [1m%[0m

        The tests take a few seconds each, with a few very fast, and a couple
        very slow, but it varies greatly depending on your CPU.

        If all went well, the message
                Passed All Tests
        should appear at the end of the make.

   [1mKnown Problems[0m
        If test 46 fails, this is often caused by optimization bugs in gcc.
        Edit the Makefile to change -O2 to -O, and delete common/fp/*.o to
        cause them to be re-built.  Make and test again.

        If you are using Sun's tmpfs file system as your /tmp directory, some
        tests will fail.  This is because the tmpfs file system does not
        support file locking.  Set the COOK_TMP environment variable to
        somewhere else before running the tests.  Something like
                [1m% [22msetenv COOK_TMP /usr/tmp
                [1m%[0m
        is usually sufficient if you are using C shell, or
                [1m$ [22mCOOK_TMP=/usr/tmp
                [1m$ [22mexport COOK_TMP
                [1m$[0m
        if you are using Bourne shell.  Remember, this must be done before
        running the tests.

        Tests 121 and 122 can sometimes have problems on Solaris, where they
        give false negatives.  If you work out why, please let the author
        know.

[1mINSTALLING COOK[0m
        As explained in the [4mSITE[24m [4mCONFIGURATION[24m section, above, the [4mCook[0m
        package is installed under the [4m/usr/local[24m tree by default.  Use the
        --prefix=[4mPATH[24m option to [4mconfigure[24m if you want some other path.  More
        specific installation locations are assignable, use the --help option
        to [4mconfigure[24m for details.

        All that is required to install the [4mCook[24m package is to use the
                [1m% [22mmake install
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1m%[0m
        command.  Control of the directories used may be found in the first
        few lines of the [4mMakefile[24m file and the other files written by the
        [4mconfigure[24m script; it is best to reconfigure using the [4mconfigure[0m
        script, rather than attempting to do this by hand.

[1mPRINTED MANUALS[0m
        The easiest way to get copies of the manuals is to get the
        [4mcook.2.21.rm.ps.gz[24m and [4mcook.2.21.ug.ps.gz[24m files from the archive site.
        These are compressed PostScript files of the Reference Manual and User
        Guide, respectively.  The Reference Manual (about 36 pages) contains
        the README file, the BUILDING file and internationalization notes, as
        well as all of the manual pages for all of the commands.  The User
        Guide (about 56 pages) tells you how to use the Cook package.

        This distribution contains the sources to all of the documentation for
        [4mCook[24m.  The author used the GNU groff package and a postscript printer
        to prepare the documentation.  If you do not have this software, you
        will need to substitute commands appropriate to your site.

        If you have the GNU Groff package installed [4mbefore[24m you run the
        [4mconfigure[24m script, the [4mMakefile[24m will contain instructions for
        constructing the documentation.  If you alreday used the [4mmake[24m command,
        above, this has already been done.  The following command
                [1m% [22mmake groff_all
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1m%[0m
        can be used to do this explicitly, if you managed to get to this point
        without doing it.  Please note that there may be some warnings from
        groff, particularly for the .txt files; this is normal.

        Once the documents have been formatted, you only need to print them.
        The following command
                [1m% [22mlpr lib/en/refman.ps lib/en/user-guide.ps
                [1m%[0m
        will print the English PostScript version of the Reference Manual and
        the User Guide.  Watch the [4mmake[24m output to see what other versions are
        available.

[1mGETTING HELP[0m
        If you need assistance with the [4mCook[24m program, please do not hesitate
        to contact the author at
                Peter Miller <millerp@canb.auug.org.au>
        Any and all feedback is welcome.

        When reporting problems, please include the version number given by
        the
                [1m% [22mcook -version
                [1mcook version [4m[22m2.21.D001[0m
                [4m...warranty[24m [4mdisclaimer...[0m
                [1m%[0m
        command.  Please do not send this example; run the program for the
        exact version number.

        In the [4mcommon/main.h[24m file, there is a define of [4mDEBUG[24m in comments.  If
        the comments are removed, extensive debugging is turned on.  This
        causes some performance loss, but performs much run-time checking and
        adds the [1m-TRACIng [22mcommand line option.

        When the [1m-TRACing [22moption is followed by one or more file names, it
        turns on execution traces in those source files.  It is best to put
        this option on the end of the command, so that the names of the files
        to be traced are not confused with any other filenames or strings on
        the command line.

[1mWINDOWS-NT[0m
        It is possible to build Cook for Windows-NT.  I have done this using
        the Cygnus freeware CygWin32 system, and I believe it has also once
        been done using the commercial NutCracker system.  This document only
        describes the CygWin32 port.

   [1mThe Source[0m
        You need to FTP the CygWin32 system from Cygnus.  It can be found at
                http://sourceware.cygnus.com/cygwin/
        and then follow the links.  The version I used was B20.1.

   [1mMounting Things[0m
        You need to mount a directory onto /tmp, or lots of things, and
        especially [4mbash[24m(1), don't work.  If you are in a heavily networked
        environment, like me, you need to know that using a networked drive
        for /tmp just doesn't work.  I have no idea why.  Use
                mount C:/temp /tmp
        instead.  (Or some other local drive.)

        Just a tip for all of you who, like me, know UNIX much better than you
        know Windows-NT: the left-hand mount argument needs to be specified
        with a drive letter ([4me.g.[24m C:[4m)[24m [4mrather[24m [4mthan[24m [4mwith[24m [4ma[24m [4mdouble[24m [4mslash[24m [4m(e.g.[0m
        [4mnot[24m //C[4m)[24m [4munless[24m [4mits[24m [4mWindows-NT[24m [4mname[24m [4mstarts[24m [4mwith[24m [4m\\.[0m

        You need to mount the Cygnus bin directory at /bin, otherwise shell
        scripts that start with #!/bin/sh don't work, among other things.
        This includes the ./configure script, and the scripts it writes ([4me.g.[0m
        config.status).
                mount Cygnus-Dir/H-i386-cygwin/bin /bin
        You will want to mount your various network drives onto the same
        places they appear on your UNIX hosts.  This means that your cookbooks
        will work without change, even if they contain absolute paths.  And
        your users don't need to learn two names for all the source files.

        Don't forget your home directory.  The trick is to set HOME in the
        cygnus.bat file, before bash starts.  (How you do this with one batch
        file and multiple users I haven't yet figured out.)

        You also need to set the LOGNAME and USER environment variables
        appropriately, or test 14 will fail.

        Mounts persist across Cygwin sessions.  They are stored in a registry
        file somewhere.  You will not need to do all this every time!

   [1mBefore your start[0m
        You will need to install a couple of other pieces of software before
        you build Cook.

        util-linux
                You need to get GNU rx, but to make it work you have to find a
                [4mtsort[24m command, so that GNU rx's [4m./configure[24m script works.  Try
                the latest copy of system/misc/util-linux-?.?.tar.gz from the
                sunsite.unc.edu Linux archive (or a mirror).  Simply build and
                install [4mmisc-utils/tsort.c[24m by hand.

        GNU rx  Once you have [4mtsort[24m installed, you will be able to get GNU rx
                configured.  Get a copy from your local GNU mirror.

   [1mConfigure[0m
        The configure and build step should be the same as for UNIX, as
        described above.  All the problems I encountered were to do with
        getting the mounts just right.  (But expect it to be dog slow compared
        to Linux or FreeBSD on the same box.)

        The configure step is almost the same as for UNIX.  I know you are
        itching to get typing, but read throught to the install section before
        you configure anything.
                [1mbash$ [22m./configure
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1mbash$[0m

   [1mBuild[0m
        The build step is exactly the same as for UNIX, and you shouldn't
        notice any difference...
                [1mbash$ [22mmake
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1mbash$[0m

   [1mTest[0m
        All of the tests should pass, you only need to run them to convince
        yourself the build worked...  (a constant surprize to me, I must say!)
                [1mbash$ [22mmake sure
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1mPassed All Tests[0m
                [1mbash$[0m

        If test 12 fails, it probably means you don't have [4m/bin[24m right.

   [1mInstall[0m
        Installing the software works as usual, though you need to make some
        choices right at the start (I told you to read this all the way
        through first).  If you want to use the ``[4m/usr/local[24m'' prefix (or any
        other install prefix) you mount it right at the start.  For anything
        other than the ``[4m/usr/local[24m'' default prefix, you also needed to give
        a ``[1m--prefix=[4m[22mblahblah''[24m [4margument[24m [4mto[24m [4mthe[24m [4mconfigure[24m [4mscript,[24m [4mright[24m [4mat[24m [4mthe[0m
        [4mstart.[0m
                [1mbash$ [4m[22mmake[24m [4minstall[0m
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1mbash$[0m

[1mCOPYRIGHT[0m
        [4mcook[24m version 2.21
        Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
        1997, 1998, 1999, 2000, 2001, 2002 Peter Miller; All rights reserved.

        The [4mCook[24m package 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.

        It should be in the [4mLICENSE[24m file included with this distribution.

[1mAUTHOR[0m
        Peter Miller   E-Mail:   millerp@canb.auug.org.au
        /\/\*             WWW:   http://www.canb.auug.org.au/~millerp/



Internationalization(Cook)                          Internationalization(Cook)

[1mNAME[0m
        Internationalization

[1mDESCRIPTION[0m
        The Cook package has gone international; it can now speak many
        languages.  This is accomplished by using the GNU Gettext library and
        utilities.  In order to do this, is is necessary to install GNU
        Gettext prior to configuring, making and installing the Cook package,
        as described in the [4mBUILDING[24m file.

   [1mInternationalization[0m
        This is the process of identifying all of the error messages in the
        source code, and providing error message catalogues in a variety of
        languages.  The error message identification was performed by the Cook
        package's author, and the various GNU translation teams provided the
        translations.  Users of the Cook package do not need to do anything to
        internationalize it, this has already been done.

   [1mLocalization[0m
        The programs in the Cook package are "localizable" when properly
        installed; the programs they contain can be made to speak your own
        native language.

        By default, the Cook package will be installed to allow translation of
        messages.  It will automatically detect whether the system provides a
        usable `gettext' function.

[1mINSTRUCTIONS FOR USERS[0m
        As a user, if your language has been installed for this package, you
        only have to set the `LANG' environment variable to the appropriate
        ISO 639 two-letter code prior to using the programs in the package.
        For example, let's suppose that you speak German.  At the shell
        prompt, merely execute
                setenv LANG de
        (in `csh'), or
                LANG=de; export LANG
        (in `sh').  This can be done from your [4m.cshrc[24m or [4m.profile[24m file,
        setting this automatically each time you login.

        An operating system might already offer message localization for many
        of its programs, while other programs have been installed locally with
        the full capabilities of GNU Gettext.  Using the GNU Gettext extended
        syntax for the `LANG' environment variable may break the localization
        of already available through the operating system.  In this case,
        users should set both the `LANGUAGE' and `LANG' environment variables,
        as programs using GNU Gettext give preference to the `LANGUAGE'
        environment variable.

        For example, some Swedish users would rather read translations in
        German when Swedish is not available.  This is easily accomplished by
        setting `LANGUAGE' to `sv:de' while leaving `LANG' set to `sv'.

[1mDIRECTORY STRUCTURE[0m
        All files which may require translation are located below the [4mlib[0m
        directory of the source distribution.  It is organized as one
        directory below [4mlib[24m for each localization.  Localizations include all
        documentation as well as the error messages.

   [1mLocalization Directory Names[0m
        Each localization is contained in a sub-directory of the [4mlib[0m
        directory, with a unique name.  Each localization sub-directory has a
        name of the form:
localization +--------+
------------+[4ml[24m-[4ma[24m-[4mn[24m-[4mg[24m-[4mu[24m-[4ma[24m-[4mg[24m-[4me[24m-+-----------------------------------------------------
                        --------+-------+  -------------+------+   ------
                         --------[4mt[24m+[4me[24m-[4mr[24m-[4mr[24m-[4mi[24m-[4mt[24m-[4mo[24m-[4mr[24m-[4my[24m+-----    ---.---+[4mc[24m-[4mo[24m-[4md[24m-[4me[24m-[4ms[24m-[4me[24m-[4mt[24m+-----


        [4mlanguage[24m  is one of the 2-letter names from the ISO 639 standard.  See
                  [4mhttp://www.ics.uci.edu/pub/ietf/http/related/iso639.txt[24m for
                  a list.

        [4mterritory[24m is one of the 2-letter country codes from the ISO 3166
                  standard.  See [4mftp://rs.internic.net/netinfo/-[0m
                  [4miso3166-countrycodes[24m for a list.

        [4mcodeset[24m   is one of the codeset names defined in RFC 1345.  This
                  simplifies the task of moving localizations between
                  charsets, because GNU Recode understands them.  See
                  [4mhttp://info.internet.isi.edu/1s/in-notes/rfc/files/-[0m
                  [4mrfc1345.txt[24m for a list.

        Here are some examples of localization names:

                       +---------------------------------------+
                       |   Name             Description        |
                       +---------------------------------------+
                       |en.ascii      English, ASCII encoding  |
                       |en_us.ascii   English with US spelling |
                       |de.latin1     German, Latin-1 encoding |
                       +---------------------------------------+
   [1mLocalization Directory Contents[0m
        Each localization sub-directory in turn contains sub-directories.
        These are:

                     +-------------------------------------------+
                     | Directory              Contents           |
                     +-------------------------------------------+
                     |LC_MESSAGES   The error message (PO) files |
                     |building      The BUILDING file            |
                     |man1          The section 1 manual entries |
                     |readme        The README file              |
                     |refman        The Reference Manual         |
                     |user-guide    The User Guide               |
                     +-------------------------------------------+
        The structure is identical below each of the localization directories.
        The sub-directories of all localizations will have the same names.

[1mINSTRUCTIONS FOR TRANSLATORS[0m
        When translating the error messages, all of the substitutions
        described in [4mcook_sub[24m(5) are also available.  Substitution variable
        names and function names may be abbreviated, in the same way that
        command line options are abbreviated, but abbreviation should probably
        be avoided.  Substitution names will [4mnever[24m be internationalized,
        otherwise the substitutions will stop working, Catch-22.

        While Cook was written by an English speaker, the English localization
        is necessary, to translate the ``terse programmer'' style error
        messages into something more user friendly.

        Messages which include command line options need to leave the command
        line options untranslated, because they are not yet internationalized,
        though they may be one day.

        Each LC_MESSAGES directory within each localization contains a number
        of PO files.  There is one for each program in the Cook package, plus
        one called common.po containing messages common to all of them.  The
        MO file for each program is generated by naming the program specific
        PO file and also the common PO file.



C_INCL(1)                   General Commands Manual                  C_INCL(1)



[1mNAME[0m
        c_incl - determine dependencies

[1mSYNOPSIS[0m
        [1mc_incl [22m[ [4moption[24m...  ] [4mfilename[0m
        [1mc_incl -Help[0m
        [1mc_incl -VERSion[0m

[1mDESCRIPTION[0m
        The [4mc_incl[24m program is used to traverse source files looking for
        include dependencies suitable for [collect]ion or #include-cooked-ing
        by cook.

        The filename ``-'' is understood to mean the standard input.  When you
        use this file name, caching is ignored.

        Several input languages are supported, see the options list for
        details.

[1mOPTIONS[0m
        The following options are understood.

        [1m-C      [22mThe source file is a C source file.  It is assumed that it
                will have the dependencies resolved by the [4mcpp[24m(1) command.
                The same include semantics as the [4mcpp[24m(1) command will be
                employed.  This is the default.  This is short-hand for
                ``--language=c''

        [1m--Language=[4m[22mname[0m
                This option may be used to specify the language of the source
                file.  Know names include ``C'', ``M4'', ``optimistic'' and
                ``roff''.

                The ``optimistic'' language will take on almost anything.  It
                accepts an include keyword in any case, including mixed, with
                leading white space, but at most one leading punctuation
                character.  It assumes that the filename follows the include
                keyword and does not contain white space, and does not start
                or end with punctuation characters (it strips off any it may
                find).  The rest of the line is ignored.  The drawback is that
                it will sometimes recognise commands and other text as
                unintended include directives, hence the name.  This is often
                used to recognise include directives in a wide variety of
                assembler input.

        [1m-Roff   [22mThe source file is a *roff source file.  It is assumed that it
                will have the dependencies resolved by the [4mroffpp[24m(1) command.
                The same include semantics as the [4mroffpp[24m(1) command will be
                employed.  This is short-hand for ``--language=roff''

        [1m-Verbose[0m
                Tell what is happening.  [1m-I[4m[22mpath[0m
                Specify include path, a la [4mcc[24m(1).

        [1m-I-[0m
                Any directories you specify with [1m-I [22moptions before the [1m-I-[0m
                option are searched only for the case of [4m#include[24m [4m"file"[24m; they
                are  not  searched for [4m#include[24m [4m<file>[24m.

                If  additional  directories are specified with [1m-I [22moptions
                after  the [1m-I-[22m, these directories are searched for all
                [4m#include[24m directives.  (Ordinarily all [1m-I [22mdirectories are used
                this way.)

                In addition, the [4m-I-[24m option inhibits the  use  of the current
                directory (where the current input file came from) as the
                first search directory for [4m#include[24m [4m"file"[24m.  There is no way
                to override this effect of [4m-I-[24m.  With [4m-I.[24m you can specify
                searching the directory which was current when c_incl was
                invoked.  That is not exactly the same as what the
                preprocessor does by default, but it is often satisfactory.

                The [4m-I-[24m option does not inhibit the use of the standard system
                directories for header files.  Thus, [4m-I-[24m and [4m-No_System[24m are
                independent.

        [1m-Absolute_Paths[0m
                This option may be used to allow absolute paths in the output.
                This is usually the default.

        [1m-No_Absolute_Paths[0m
                This option may be used to exclude absolute paths from the
                output.

        [1m-Absent_Local_Ignore[0m
                For files included using a [4m#include[24m [4m''filename.h''[24m directive,
                ignore the file if it cannot be found.

        [1m-Absent_Local_Mention[0m
                For files included using a [4m#include[24m [4m''filename.h''[24m directive,
                print the file name even if the file cannot be found.  This is
                the default (it probably needs to be built).

        [1m-Absent_Local_Error[0m
                For files included using a [4m#include[24m [4m''filename.h''[24m directive,
                print a fatal error if the file cannot be found.

        [1m-Absent_System_Ignore[0m
                For files included with a [4m#include[24m [4m<filename.h>[24m directive,
                ignore the file if it cannot be found.  This is the default
                (it was probably ifdef'ed out).

        [1m-Absent_System_Mention[0m
                For files included with a [4m#include[24m [4m<filename.h>[24m directive,
                print the file name even if the file cannot be found.

        [1m-Absent_System_Error[0m
                For files included with a [4m#include[24m [4m<filename.h>[24m directive,
                print a fatal error if the file cannot be found.

        [1m-Absent_Program_Ignore[0m
                If the file named on the command line cannot be found, behave
                as if the file were found, but was empty.

        [1m-Absent_Program_Error[0m
                If the file named on the command line cannot be found, print a
                fatal error message.  This is the default.

        [1m-Escape_Newlines[0m
                This option may be used to request that newlines in the output
                are escaped with backslash (``\'') characters.

        [1m-Help[0m
                Give information on how to use [4mc_incl[24m.

        [1m-EXclude [4m[22mfilename[0m
                This option may be used to nominate include file names which
                are not to be used.

        [1m-VERSion[0m
                Tell what version of [4mc_incl[24m is being run.

        [1m-Interior_Files [4m[22mfilename[24m...
                This option may be used to tell [4mc_incl[24m about include files
                which don't exist yet.  This is because they are interior to
                the dependency graph, but [4mcook[24m(1) hasn't finished walking it
                yet.  Often used with Cook's [interior-files] function.
                ([1mNote: [22mthe [4mfilename[24m list has an arbitrary number of files; it
                ends at the next option or end-of-line, so you need to be
                careful where you put the input filename.)

        [1m-No_System[0m
                Do not search the [4m/usr/include[24m directory.  By default this is
                searched last.  This option implies the -No_Absolute_Paths
                option, unless explicitly contradicted.

        [1m-CAche[0m
                This option may be used to turn caching on.  This is the
                default.

        [1m-No_Cache[0m
                This option may be used to turn caching off.

        [1m-PREfix [4m[22mstring[0m
                This option may be used to print a string before any of the
                filenames are printed.  It will not be printed if no file
                names are printed.

        [1m-Quote_FileNames[0m
                This option may be used to have [4mc_incl[24m quote filenames.  This
                permits filenames to contain characters which are special to
                Cook, including spaces.

        [1m-SUFfix [4m[22mstring[0m
                This option may be used to print a string after all of the
                filenames are printed.  It will not be printed if no file
                names are printed.

        [1m-Output [4m[22mfilename[0m
                This option may be used to specify the output file.  Defaults
                to the standard output if not set.

        [1m-No_Source_Relative_Includes[0m
                This option will give a fatal error if a [4m#include[0m
                [4m''filename.h''[24m directive is used.  This is necessary when you
                are using Cook's search_list functionality to stitch together
                a baseline and a private work area.

        [1m-RECursion[0m
                This option may be used to specify that nested include files
                are to be scanned, so that their includes may also be
                discovered.  This is the default.

        [1m-No_RECursion[0m
                This option may be use to specify that nested include files
                are [4mnot[24m to be scanned.  This option is recommended for use
                with the Cook cascade-for recipes.  This option implies
                -[1mNo_Cache[22m, unless a [1m-Cache [22moption is specified.

        [1m-Remove_Leading_Path [4m[22mpath[0m
                This option may be used to remove path prefixes from the
                included filenames.  May be used more than once.  This is
                necessary when you are using Cook's search_list functionality
                to stitch together a baseline and a private work area; usually
                as ``[prepost "-rlp=" "" [search_list]]''

        [1m-STripdot[0m
                This option may be used to specify that leading redundant dot
                directories are to be removed from paths before processing.
                This is the default.

        [1m-No_STripdot[0m
                This option may be used to specify that leading redundant dot
                directories need not be removed from paths before processing.
                (Some path flattening may still occur.)

        [1m-Substitute_Leading_Path [4m[22mfrom[24m [4mto[0m
                This option may be used to modify path prefixes from the
                included filenames.  May be used more than once.  This is
                necessary when you are performing heterogeneous builds in the
                same directory tree.  By using an ``arch'' variable to hold
                the architecture, and placing each architecture's objects in a
                separate directory tree, this option may be used as ``-slp
                [arch] "'[arch]'"'' (The outer quotes protect from Cook, the
                inner quotes protect from the shell.)  If you need more
                intricate editing, used [4msed[24m(1).

        Any other options will generate an error.

        All options may be abbreviated; the abbreviation is documented as the
        upper case letters, all lower case letters and underscores (_) are
        optional.  You must use consecutive sequences of optional letters.

        All options are case insensitive, you may type them in upper case or
        lower case or a combination of both, case is not important.

        For example: the arguments "-help", "-HEL" and "-h" are all
        interpreted to mean the [1m-Help [22moption.  The argument "-hlp" will not be
        understood, because consecutive optional characters were not supplied.

        Options and other command line arguments may be mixed arbitrarily on
        the command line.

        The GNU long option names are understood.  Since all option names for
        [4mc_incl[24m are long, this means ignoring the extra leading '-'.  The
        "[1m--[4m[22moption[24m[1m=[4m[22mvalue[24m" convention is also understood.

[1mCACHING[0m
        The caching mechanism use by the [4mc_incl[24m program caches the results of
        searching files for include files (in a file called [4m.c_inclrc[24m in the
        current directory).  The cache is only refreshed when a file changes.

        The use of this cache has been shown to dramatically increase the
        performance of the [4mc_incl[24m program.  Typically, only a small
        proportions files in a project change between builds, resulting in a
        very high cache hit rate.

        When using caching, always use the same command line options,
        otherwise weird and wonderful things will happen.

        The [4m.c_inclrc[24m file is a binary file.  If you wish to rebuild the
        cache, simply delete this file with the [4mrm[24m(1) command.  Being a binary
        file, the [4m.c_inclrc[24m file is not portable across machines or operating
        systems, so you will need to delete it when you move your sources.  It
        is a binary file for performance.

        Accesses to the [4m.c_inclrc[24m file use file locking, so recipies using
        [4mc_incl[24m need not use the single-thread clause.

[1mEXIT STATUS[0m
        The [4mc_incl[24m command will exit with a status of 1 on any error.  The
        [4mc_incl[24m command will only exit with a status of 0 if there are no
        errors.

[1mCOPYRIGHT[0m
        [4mc_incl[24m version 2.21
        Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
        1997, 1998, 1999, 2000, 2001, 2002 Peter Miller; All rights reserved.

        The [4mc_incl[24m program comes with ABSOLUTELY NO WARRANTY; for details use
        the '[4mc_incl[24m [4m-VERSion[24m [4mLicense[24m' command.  This is free software and you
        are welcome to redistribute it under certain conditions; for details
        use the '[4mc_incl[24m [4m-VERSion[24m [4mLicense[24m' command.

[1mAUTHOR[0m
        Peter Miller   E-Mail:   millerp@canb.auug.org.au
        /\/\*             WWW:   http://www.canb.auug.org.au/~millerp/



COOK(1)                     General Commands Manual                    COOK(1)



[1mNAME[0m
        cook - a file construction tool

[1mSYNOPSIS[0m
        [1mcook [22m[ [4moption[24m...  ][ [4mfilename[24m...  ]
        [1mcook -Help[0m
        [1mcook -VERSion[0m

[1mDESCRIPTION[0m
        The [4mcook[24m program is a tool for constructing files.  It is given a set
        of files to create, and instructions detailing how to construct them.
        In any non-trivial program there will be prerequisites to performing
        the actions necessary to creating any file, such as extraction from a
        source-control system.  The [4mcook[24m program provides a mechanism to
        define these.

        When a program is being developed or maintained, the programmer will
        typically change one file of several which comprise the program.  The
        [4mcook[24m program examines the last-modified times of the files to see when
        the prerequisites of a file have changed, implying that the file needs
        to be recreated as it is logically out of date.

        The [4mcook[24m program also provides a facility for implicit recipes,
        allowing users to specify how to form a file with a given suffix from
        a file with a different suffix.  For example, to create [4mfilename[24m[1m.o[0m
        from [4mfilename[24m[1m.c[0m

        Options and filenames may be arbitrarily mixed on the command line; no
        processing is done until all options and filenames on the command line
        have been scanned.

        The [4mcook[24m program will attempt to create the named files from the
        recipes given to it.  The recipes are contained in a file called
        [4mHowto.cook[24m in the currect directory.  This file may, in turn, include
        other files containing additional recipes.

        If no [4mfilename[24ms are given on the command line the targets of the first
        recipe defined are cooked.

[1mOPTIONS[0m
        The valid options for [4mcook[24m are listed below.  Any other options (words
        on the command line beginning with `[1m-[22m') will cause a diagnostic
        message to be issued.

        [1m-Action[0m
                Execute the commands given in the recipes.  This is the
                default.

        [1m-No_Action[0m
                Do not execute the commands given in the recipes.

        [1m-Book [4m[22mfilename[0m
                Tells cook to used the named cookbook, rather than the default
                ``Howto.cook'' file.

        [1m-CAScade[0m
                This option may be used to enable the use of cascaded
                ingredients.  This is the default.

        [1m-No_CAScade[0m
                This option may be used to disable the use of cascaded
                ingredients.

        [1m-Continue[0m
                If cooking a target should fail, continue with other recipes
                for which the failed target is not an ingredient, directly or
                indirectly.

        [1m-No_Continue[0m
                If cooking a target should fail, [4mcook[24m will exit.  This is the
                default.

        [1m-Errok[0m
                When a command is executed, the exit code will be ignored.

        [1m-No_Errok[0m
                When a command is executed, if the exit code is positive it
                will be deemed to fail, and thus the recipe containing it to
                have failed.  This is the default.

        [1m-FingerPrint[0m
                When [4mcook[24m examines a file to determine if it has changed, it
                uses the last-modified time information available in the file
                system.  There are times when this is altered, but the file
                contents do not actually change.  The fingerprinting facility
                examines the file contents when it appears to have changed,
                and compares the old fingerprint against the present file
                contents.  (See [4mcookfp[24m(1) for a description of the
                fingerprinting algorithm.)  If the fingerprint did not change,
                the last-modified time in the file system is ignored.  Note
                that this has implications if you are in the habit of using
                the [4mtouch[24m(1) command - [4mcook[24m will do nothing until you actually
                change the file.

        [1m-No_FingerPrint[0m
                Do not use fingerprints to supplement the last-modified time
                file information.  This is the default.

        [1m-FingerPrint_Update[0m
                This option may be used to scan the directory tree below the
                current directory and update the file fingerprints.  This
                helps when you use another tool (such as RCS or ClearCase)
                which alters the file but preserves the file's modification
                time.

        [1m-Force[0m
                Always perform the actions of recipes, irrespective of the
                last-modified times of any of the ingredients.  This option is
                useful if something beyond the scope of the cookbook has been
                modified; for example, a bug fix in a compiler.

        [1m-No_Force[0m
                Perform the actions of the recipes if any of the ingredients
                are logically out of date.  This is the default.

        [1m-Help[0m
                Provide information about how to execute [4mcook[24m on [4mstdout[24m, and
                perform no other function.

        [1m-Include [4m[22mfilename[0m
                Search the named directory before the standard places for
                included cookbooks.  Each directory so named will be scanned
                in the order given.  The standard places are [4m$HOME/.cook[24m then
                [4m/usr/local/share/cook[24m.

        [1m-Include_Cooked[0m
                This option may be used to require the cooking of files named
                on [4m#include-cooked[24m and [4m#include-cooked-nowarn[24m include lines in
                cookbooks.  The files named will be included, if present.  If
                the files named need to be updated or created, this will be
                done, and then the cookbook re-read.  This is the default.

        [1m-No_Include_Cooked[0m
                This option may be used to inhibit the implicit cooking of
                files named on [4m#include-cooked[24m and [4m#include-cooked-nowarn[0m
                include lines in cookbooks.  The files will be included, if
                present, but they will not be updated or created, even if
                required.

        [1m-Include_Cooked_Warning[0m
                This option enables the warnings about derived dependencies in
                derived cookbooks.  This is usually the default.

        [1m-No_Include_Cooked_Warning[0m
                This option disables the warnings about derived dependencies
                in derived cookbooks.

        [1m-List[0m
                Causes [4mcook[24m to automatically redirect the [4mstdout[24m and [4mstderr[24m of
                the session.  Output will continue to come to the terminal,
                unless [4mcook[24m is executing in the background.  The name of the
                file will be the name of the cookbook with any suffix removed
                and ".list" appended; this will usually be [4mHowto.list[24m.  This
                is the default.

        [1m-List [4m[22mfilename[0m
                Causes [4mcook[24m to automatically redirect the [4mstdout[24m and [4mstderr[24m of
                the session into the named file.  Output will continue to come
                to the terminal, unless [4mcook[24m is executing in the background.

        [1m-No_List[0m
                No automatic redirection of the output of the session will be
                made.

        [1m-No_List [4m[22mfilename[0m
                No automatic redirection of the output of the session will be
                made, however subsequent [1m-List [22moptions will default to listing
                to the named file.

        [1m-Meter[0m
                After each command is executed, print a summary of the
                command's CPU usage.

        [1m-No_Meter[0m
                Do not print a CPU usage summary after each command.  This is
                the default.

        [1m-Pairs[0m
                This option may be used to generate a list of pair-wise file
                dependencies, similar to [4mlorder[24m(1) output.  This may be used
                to draw file dependency diagrams.  It can also be useful when
                debugging cookbooks.

        [1m-PARallel [22m[ [4mnumber[24m ]
                This option may be used to specify the number of parallel
                executions threads.  The number defaults to 4 if no specific
                number of threads is specified.  See also the [4mparallel_jobs[0m
                variable.

                Use of this option on single-processor machines needs to be
                done with great care, as it can bring other processing to a
                complete halt.  Several users doing so simultaneously on a
                multi-processor machine will have a similar effect.  It is
                also to rapidly run out of virtual memory and temporary disk
                space if the parallel tasks are complex.

        [1m-No_PARallel[0m
                This option may be used to specify that a single execution
                thread is to be used.  This is the default.

        [1m-Precious[0m
                When commands in the body of a recipe fail, do not delete the
                targets of the recipe.

        [1m-No_Precious[0m
                When commands in the body of a recipe fail, delete the targets
                of the recipe.  This is the default.

        [1m-Reason[0m
                Two options are provided for tracing the inferences [1mcook [22mmakes
                when attempting to cook a target.  The [1m-Reason [22moption will
                cause [4mcook[24m will emit copious amounts of information about the
                inferences it is making when cooking targets.  This option may
                be used when you think [1mcook [22mis acting strangely, or are just
                curious.

        [1m-No_Reason[0m
                This option may be used to cause [4mcook[24m will not emit
                information about the inferences it is making when cooking
                targets.  This is the default.

        [1m-SCript[0m
                This option may be used to request a shell script be printed
                on the standard output.  This shell script may be used to
                construct the files; it captures many of the semantics of the
                cookbook.  This can be useful when a project needs to be
                distributed, and the recipients do not have [4mcook(1)[24m installed.
                It can also be very useful when debugging cookbooks.

        [1m-Silent[0m
                Do not echo commands before they are executed.

        [1m-No_Silent[0m
                Echo commands before they are executed.  This is the default.

        [1m-STar[0m
                Emit progress indicators once a second.  These progress
                indicators include

                              +   Reading the cookbook
                              -   Executing a collect function
                              *   Building the dependency graph
                              #   Walking the dependency graph
                              @   Writing fingerprint files.

        [1m-No_STar[0m
                Do not emit progress indicators.  This is the default.

        [1m-Strip_Dot[0m
                Remove leading "./" from filenames before attempting to cook
                them; applies to all filenames and all recipes.  This is the
                default.

        [1m-No_Strip_Dot[0m
                Leave leading "./" on filenames while cooking.

        [1m-Touch[0m
                Update the last-modified times of the target files, rather
                than execute the actions bound to recipes.  This can be useful
                if you have made a modification to a file that you know will
                make a system of files logically out of date, but has no
                significance; for example, adding a comment to a widely used
                include file.

        [1m-No_Touch[0m
                Execute the actions bound to recipes, rather than update the
                last-modified times of the target files.  This is the default.

        [1m-TErminal[0m
                When listing, also send the output stream to the terminal.
                This is the default.

        [1m-No_TErminal[0m
                When listing, do not send the output to the terminal.

        [1m-Time_Adjust[0m
                This option causes [1mcook [22mto check the last-modified time of the
                targets of recipes, and updates them if necessary, to make
                sure they are consistent with (younger than) the last-modified
                times of the ingredients.  This results in more system calls,
                and can slow things down on some systems.  This correspondes
                to the [4mtime-adjust[24m recipe flag.

        [1m-No_Time_Adjust[0m
                Do not update the file last-modified times after performing
                the body of a recipe.  This is the default.  This correspondes
                to the [4mno-time-adjust[24m recipe flag.

        [1m-Web[0m
                This option may be used to request a HTML web page be printed
                on the standard output.  This web page may be used to document
                the file dependencies; it captures many of the semantics of
                the cookbook.  It can also be very useful when debugging
                cookbooks.

        [4mname[24m[1m=[4m[22mvalue[0m
                Assign the [4mvalue[24m to the named variable.  The value may contain
                spaces if you can convince the shell to pass them through.

        All options may be abbreviated; the abbreviation is documented as the
        upper case letters, all lower case letters and underscores (_) are
        optional.  You must use consecutive sequences of optional letters.

        All options are case insensitive, you may type them in upper case or
        lower case or a combination of both, case is not important.

        For example: the arguments "-help", "-HEL" and "-h" are all
        interpreted to mean the [1m-Help [22moption.  The argument "-hlp" will not be
        understood, because consecutive optional characters were not supplied.

        Options and other command line arguments may be mixed arbitrarily on
        the command line.

        The GNU long option names are understood.  Since all option names for
        [4mcook[24m are long, this means ignoring the extra leading '-'.  The
        "[1m--[4m[22moption[24m[1m=[4m[22mvalue[24m" convention is also understood.

[1mEXIT STATUS[0m
        The [4mcook[24m command will exit with a status of 1 on any error.  The [4mcook[0m
        command will only exit with a status of 0 if there are no errors.

[1mFILES[0m
        The following files are used by [1mcook[22m:

        [4mHowto.cook[0m
                This file contains instructions to [4mcook[24m for how to construct
                files.

        [4m/usr/local/share/cook[0m
                This directory contains "system" cookbooks for various tools
                and activities.

        [4m.cook.fp[0m
                This text file is used to remember fingerprints between
                invokations.

[1mENVIRONMENT VARIABLES[0m
        The following environment variables are used by [1mcook[22m:

        COOK    May be set to contain command-line options, changing the
                default behaviour of [4mcook[24m.  May be overridden by the command
                line.

        PAGER   Use to paginate the output of the [1m-Help [22mand [1m-VERSion [22moptions.
                Defaults to [4mmore[24m(1) if not set.

        COOK_AUTOMOUNT_POINTS
                A colon-separated list of directories which the automounter
                may use to mount file systems.  Use with extreme care, as this
                distorts Cook's idea of the shape of the filesystem.

                This feature assumes that paths below the automounter's mount
                directory are echoes of paths without it.  [4mE.g.[24m When /home is
                the trigger, and /tmp_mnt/home is where the on-demand NFS
                mount is performed, with /home appearing to processes to be a
                symlink.

                This is the behavior of the Sun automounter.  The AMD
                automounter is capable of being configured in this way, though
                it is not typical of the examples in the manual.  Nor is it
                typical of the out-of-the-box Linux AMD configuration in many
                distributions.

                Defauls to ``/tmp_mnt:/a:/.automount'' if not set.

[1mCOPYRIGHT[0m
        [4mcook[24m version 2.21
        Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
        1997, 1998, 1999, 2000, 2001, 2002 Peter Miller; All rights reserved.

        The [4mcook[24m program comes with ABSOLUTELY NO WARRANTY; for details use
        the '[4mcook[24m [4m-VERSion[24m [4mLicense[24m' command.  This is free software and you
        are welcome to redistribute it under certain conditions; for details
        use the '[4mcook[24m [4m-VERSion[24m [4mLicense[24m' command.

[1mAUTHOR[0m
        Peter Miller   E-Mail:   millerp@canb.auug.org.au
        /\/\*             WWW:   http://www.canb.auug.org.au/~millerp/



cook_bom(1)                 General Commands Manual                cook_bom(1)



[1mNAME[0m
        cook_bom - bill of materials

[1mSYNOPSIS[0m
        [1mcook_bom [22m[ [4moption[24m...  ] [4mdirname[24m [ [4moutfile[24m ]
        [1mcook_bom -Help[0m
        [1mcook_bom -VERSion[0m

[1mDESCRIPTION[0m
        The [4mcook_bom[24m program is used to scan a directory and generate a
        cookbook fragment containing a bill of materials for that directory.
        It also includes a recursive reference, via an ``#include-cooked''
        directive, to the bills of materials for nested directories.

        Output is sent to the standard output unless an output filename is
        specified.

[1mOPTIONS[0m
        The following options are understood:

        [1m-DIRectory [4m[22mpathname[0m
                This option may be used to specify a directory search path,
                similar to [4mcook[24m(1) [search_list] functionality.

        [1m-Help[0m
                Provide some help with using the [4mcook_bom[24m program.

        [1m-IGnore [4m[22mstring[0m
                This option may be used to specify filename patterns to be
                ignored.  It may be given as many times as required.

        [1m-PREfix [4m[22mstring[0m
                This option may be manipulate the name of the manifest files.
                Defaults to the empty string if not set.

        [1m-SUFfix [4m[22mstring[0m
                This option may be manipulate the name of the manifest files.
                Defaults to ``/manifest.cook if not set.

        [1m-VERSion[0m
                Print the version of the [4mcook_bom[24m program being executed.

        All other options will produce a diagnostic error.

        All options may be abbreviated; the abbreviation is documented as the
        upper case letters, all lower case letters and underscores (_) are
        optional.  You must use consecutive sequences of optional letters.

        All options are case insensitive, you may type them in upper case or
        lower case or a combination of both, case is not important.

        For example: the arguments "-help", "-HEL" and "-h" are all
        interpreted to mean the [1m-Help [22moption.  The argument "-hlp" will not be
        understood, because consecutive optional characters were not supplied.

        Options and other command line arguments may be mixed arbitrarily on
        the command line.

        The GNU long option names are understood.  Since all option names for
        [4mcook_bom[24m are long, this means ignoring the extra leading '-'.  The
        "[1m--[4m[22moption[24m[1m=[4m[22mvalue[24m" convention is also understood.

[1mEXIT STATUS[0m
        The [4mcook_bom[24m command will exit with a status of 1 on any error.  The
        [4mcook_bom[24m command will only exit with a status of 0 if there are no
        errors.

[1mEXAMPLE[0m
        The intended use of this command is to automatically generate a
        project file manifest in an efficient way.  If you have a cookbook of
        the form
                all_files_in_. = ;
                #include manifest.cook
                manifest = [all_files_in_.];

                set fingerprint mkdir unlink;

                %0manifest.cook: ["if" [in "%0" ""] "then" "." "else" "%0"]
                {
                        cook_bom
                                [addprefix '--dir=' [search_list]]
                                "--ignore='*~'"
                                [need]
                                [target]
                                ;
                }
        At the end of this fragment, the manifest variable contains a complete
        list of all files in the directory tree.  This variable may then be
        taken apart with the match_mask function to build ingredients lists.

        The constructed [4mmanifest.cook[24m files work for both whole-project and
        recursive (not recommended) builds.

[1mCOPYRIGHT[0m
        [4mcook_bom[24m version 2.21
        Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
        1997, 1998, 1999, 2000, 2001, 2002 Peter Miller; All rights reserved.

        The [4mcook_bom[24m program comes with ABSOLUTELY NO WARRANTY; for details
        use the '[4mcook_bom[24m [4m-VERSion[24m [4mLicense[24m' command.  This is free software
        and you are welcome to redistribute it under certain conditions; for
        details use the '[4mcook_bom[24m [4m-VERSion[24m [4mLicense[24m' command.

[1mAUTHOR[0m
        Peter Miller   E-Mail:   millerp@canb.auug.org.au
        /\/\*             WWW:   http://www.canb.auug.org.au/~millerp/



GPL(GNU)                   Free Software Foundation                   GPL(GNU)



                              GNU GENERAL PUBLIC LICENSE
                                 Version 2, June 1991

        Copyright (C) 1989, 1991 Free Software Foundation, Inc.
        59 Temple Place, Suite 330, Boston, MA 02111, USA
        Everyone is permitted to copy and distribute verbatim copies of this
        license document, but changing it is not allowed.

                                       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.
                              GNU GENERAL PUBLIC LICENSE
           TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

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

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

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

        a)  You must cause the modified files to carry prominent notices
            stating that you changed the files and the date of any change.

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

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

        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.

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

        a)  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,

        b)  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,

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

        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.

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

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

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

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

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

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

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

                                     NO WARRANTY

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

        12. 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 OF TERMS AND CONDITIONS
               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.

            < one line to give the program's name and a brief idea of what it
            does.  >
            Copyright (C) 19yy < 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,
            USA.

        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:

            Gnomovision version 69, Copyright (C) 19yy 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.

        The hypothetical commands `show w' and `show c' should show the
        appropriate parts of the General Public License.  Of course, the
        commands you use may be called something other than `show w' and `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:

            Yoyodyne, Inc., hereby disclaims all copyright interest in the
            program `Gnomovision' (which makes passes at compilers) written by
            James Hacker.

            < signature of Ty Coon, > 1 April 1989
            Ty Coon, President of Vice

        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.


cook_rsh(1)                 General Commands Manual                cook_rsh(1)



[1mNAME[0m
        cook - load balancing rsh

[1mSYNOPSIS[0m
        [1mcook [22m[ [4moption[24m...  ] [4marchitecture[24m [4mcommand[24m [ [4margument[24m...  ]
        [1mcook -Help[0m

[1mDESCRIPTION[0m
        The [4mcook[24m program is a wrapper around [4mrsh[24m(1) which does simple load
        balancing.  It obtains its load information by running the [4mrup[24m(1)
        command, and selects the most suitable host hased on the architecture
        you specify, and the least load of all hosts of that architecture.

        The first command line argument is the architecture name which is used
        to get the list of possible hosts.  From that list the [4mrup[24m(1) command
        is run to determine the host with the lowest load, which is in turn
        used as the first argument of the eventual [4mrsh[24m(1) command.

[1mCOOKBOOKS[0m
        In order to make use of this program, somewhere in your cookbook, you
        need to add a line which reads
                parallel_rsh = "cook";
        If the host chosen is the same as the caller (build host) then this
        program just exec the command skipping the rsh.  So it costs nothing
        to use this in a one machine network!

        For each recipe you want distributed to a remote host, you need to add
        a host-binding attribute to.  Typical usage is where you have a muti-
        architecture build.
                %1/%0%.o: %0%.c
                    host-binding %1 {
                    cc -o [target] -c [resolve %0%.c]; }
        In the recipe given here, each architecture has its object files
        placed into a separate architecture-specific directory tree.  The
        architecture name (%1) is used in the host-binding, so that the
        compiles may be load-balanced to all machines of that architecture.

        If you need a command to run on a specific host (say, because that's
        where a specific application license resides), then simply use the
        host name in the host-binding attribute, rather than an architecture
        name.

[1mDEFINING THE CLASSES[0m
        The [4m/usr/local/share/cook/host_lists.pl[24m file is expected to exist, and
        to contain variable definitions used to determine if hosts are members
        of particular architectures.

        The [4m/usr/local/share/cook/host_lists.pl[24m file defines a perl HOL "hash
        of lists" The hash is %ArchNames and it maps names of architectures as
        user want to see them, to list references as the actual lists are
        stored.

        The names of each architecture could be any form you wish but the
        convention is to use the GNUish names such as "sparc-sun-solaris2.8".

        For each architecture, define one or more lists of machines according
        to what function each machine set may do.  This can be as simple or as
        elaborate as required.  The form of the list variable name can be any
        valid perl identifier but may as well be like the architecture name
        with dash changed to underbar and dot removed, and the type added.
        For example one might define solaris hosts as:
                @sparc_sun_solaris28_hosts = (
                   "mickey", "minny", "scrooge" );
        And linux hosts as:
                @i386_linux22_hosts = (
                   "goofy", "scrooge" );

        If there is a need to define different sets of machines for different
        types of jobs then add a suffix to the names in the  [4mhost-binding[0m
        directive on each of the recipes, and lists here with the same suffix.

        The hash to map argument names to lists is defined like:
                %ArchNames = (
                  "sparc-solaris2.8",     => @sparc_solaris28_hosts,
                  "i586-unknown-linux22", => @i386_linux22_hosts, );

        Of course if users have differing opinions as to what the architecture
        names should look like, you can define "alias" mappings as well.
                  "sun4-SunOS-5.8",       => @sparc_solaris28_hosts,
        Or maybe the level is of no importance, then define
                  "sparc-solaris",        => @sparc_solaris28_hosts,
                  "sparc-solaris2.7",     => @sparc_solaris28_hosts,
        Also, this list isn't allowed to be empty.

        And finally, curtesy of Perl, the last line of the file must read
                1; for obscure and magical reasons.

[1mSYSLOG LOGGING[0m
        Typical commands seen during a build would look like
                sh -c 'cd /aegis/dd/gumby2.2.C079 && \ sh -ce
                /aegis/dd/gumby2.2.C079/.6.1; \ echo $? >
                /aegis/dd/gumby2.2.C079/.6.2'
        So we can extract the project/ change from the command quite easily
        and logging it via syslog would be a trivial addition.

[1mOPTIONS[0m
        This command is not usually given any options.

        [1m-h      [22mHelp - show usage info

        [1m-vP     [22mVerbose - report choice

        [1m-T[4m[22mn[24m     Trace value for testing

[1mFILES[0m
        /usr/local/share/cook/exclude.hosts
                This file is used to list those host which must not be used by
                this script.  Simply list excuded hosts, one hostname per
                line.  If the file is absent, all hosts reported by rup(1) may
                be used.

        /usr/local/share/cook/host_lists.pl
                This file defines the classes of hosts for each architecture.

[1mAUTHOR[0m
        Jerry Pendergraft <jerry@endocardial.com>



cookfp(1)                   General Commands Manual                  cookfp(1)



[1mNAME[0m
        cookfp - calculate file fingerprint

[1mSYNOPSIS[0m
        [1mcookfp [22m[ [4moption[24m...  ][ [4mfilename[24m...  ]
        [1mcookfp -Help[0m
        [1mcookfp -VERSion[0m

[1mDESCRIPTION[0m
        The [4mcookfp[24m program is used to calculate the fingerprints of files.  A
        fingerprint is a hash of the contents of a file.  The default
        fingerprint is cryptographically strong, so the probability of two
        different files having the same fingerprint is less than 1 in 2**200.

        The fingerprint is based on Dan Berstien <djb@silverton.berkeley.edu>
        public domain fingerprint 0.50 beta package 930809, posted to the
        alt.sources newsgroup.  This program produces identical results; the
        expected test results were generated using Dan's package.

        The fingerprint is a base-64-sanely-encoded fingerprint of the input.
        Imagine this fingerprint as something universal and permanent.  A
        fingerprint is 76 characters long, containing the following:

        1.  A Snefru-8 (version 2.5, 8 passes, 512->256) hash.  (Derived from
            the Xerox Secure Hash Function.)

        2.  An MD5 hash, as per RFC 1321.  (Derived from the RSADSI MD5
            Message-Digest Algorithm.)

        3.  A CRC checksum, as in the new cksum utility.

        4.  Length modulo 2^40.

        The output format is not expected to be compatible with anything.
        However, options are available to produce the purported output of
        Merkle's snefru program, the purported output of RSADSI's mddriver -x,
        or the purported output of the POSIX cksum program.

        If no files are named as input, the standard input will be used.  The
        special file name ``-'' is understood to mean the standard input.

[1mOPTIONS[0m
        The following options are understood:

        [1m-Checksum[0m
                Print the CRC32 checksum and length of the named file(s).

        [1m-Identifier[0m
                Print a condensed form of the fingerprint (obtained by
                performing a CRC32 checksum on the full fingerprint described
                above - a definite overkill).  This is an 8-digit hexadecimal
                number, useful for generating unique short identifiers out of
                long names.  The first character is forced to be a letter (g-
                p), so there is no problem in using the output as a variable
                name.

        [1m-Help[0m
                Provide some help with using the [4mcookfp[24m program.

        [1m-Message_Digest[0m
                Print the RSA Data Security, Inc. MD5 Message-Digest Algorithm
                hash of the named file(s).

        [1m-Snefru [22mPrint the Snefru hash of the named file(s), derived from the
                Xerox Secure Hash Function.

        [1m-VERSion[0m
                Print the version of the [4mcookfp[24m program being executed.

        All other options will produce a diagnostic error.

        All options may be abbreviated; the abbreviation is documented as the
        upper case letters, all lower case letters and underscores (_) are
        optional.  You must use consecutive sequences of optional letters.

        All options are case insensitive, you may type them in upper case or
        lower case or a combination of both, case is not important.

        For example: the arguments "-help", "-HEL" and "-h" are all
        interpreted to mean the [1m-Help [22moption.  The argument "-hlp" will not be
        understood, because consecutive optional characters were not supplied.

        Options and other command line arguments may be mixed arbitrarily on
        the command line.

        The GNU long option names are understood.  Since all option names for
        [4mcookfp[24m are long, this means ignoring the extra leading '-'.  The
        "[1m--[4m[22moption[24m[1m=[4m[22mvalue[24m" convention is also understood.

[1mEXIT STATUS[0m
        The [4mcookfp[24m command will exit with a status of 1 on any error.  The
        [4mcookfp[24m command will only exit with a status of 0 if there are no
        errors.

[1mCOPYRIGHT[0m
        [4mcookfp[24m version 2.21
        Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
        1997, 1998, 1999, 2000, 2001, 2002 Peter Miller; All rights reserved.

        The [4mcookfp[24m program comes with ABSOLUTELY NO WARRANTY; for details use
        the '[4mcookfp[24m [4m-VERSion[24m [4mLicense[24m' command.  This is free software and you
        are welcome to redistribute it under certain conditions; for details
        use the '[4mcookfp[24m [4m-VERSion[24m [4mLicense[24m' command.

[1mAUTHOR[0m
        Peter Miller   E-Mail:   millerp@canb.auug.org.au
        /\/\*             WWW:   http://www.canb.auug.org.au/~millerp/

        Portions of this program are derived from sources from other people,
        sometimes with liberal copyrights, and sometimes in the public domain.
        These include:

        Dan Bernstien
                See [4mcommon/fp/README[24m for details.

        Gary S Brown.
                See [4mcommon/fp/crc32.c[24m for details.

        RSA Data Security, Inc.
                See [4mcommon/fp/md5.c[24m for details.

        Xerox Corporation
                See [4mcommon/fp/snefru.c[24m for details.

        In addition to the above copyright holders, there have been numerous
        authors and contributors, see the named files for details.  Files
        names are relative to the root of the [4mcook[24m distribution.



COOKTIME(1)                 General Commands Manual                COOKTIME(1)



[1mNAME[0m
        cooktime - set file times

[1mSYNOPSIS[0m
        [1mcooktime [22m[ [4moption[24m...  ] [4mfilename[24m...
        [1mcooktime -Help[0m
        [1mcooktime -VERSion[0m

[1mDESCRIPTION[0m
        The [4mcooktime[24m program is used to set the modified time or access time
        of a file.  This can be used to defend against unwanted logical
        dependencies when making "minor" changes to files.

        If no option is specified, the default action is as if "[4m-Modify[24m [4mnow[24m"
        was specified.

[1mOPTIONS[0m
        The following options are understood.

        [1m-Access [4m[22mdate[0m
                This option may be used to set the last-access time of the
                files.  The date is relatively free-format; rember to use
                quotes to insulate spaces from the shell.

        [1m-Modify [4m[22mdate[0m
                This option may be used to set the last-modify time of the
                files.  The date is relatively free-format; rember to use
                quotes to insulate spaces from the shell.

        [1m-Report[0m
                When use alone, produces a listing of access times and modify
                times for the named files.  When used with -Access or -Modify,
                produces a listing of the changes made.

        [1m-Help[0m
                Give some information on how to use the [4mcooktime[24m command.

        Any other option will generate a diagnostic error.

        All options may be abbreviated; the abbreviation is documented as the
        upper case letters, all lower case letters and underscores (_) are
        optional.  You must use consecutive sequences of optional letters.

        All options are case insensitive, you may type them in upper case or
        lower case or a combination of both, case is not important.

        For example: the arguments "-help", "-HEL" and "-h" are all
        interpreted to mean the [1m-Help [22moption.  The argument "-hlp" will not be
        understood, because consecutive optional characters were not supplied.

        Options and other command line arguments may be mixed arbitrarily on
        the command line.

        The GNU long option names are understood.  Since all option names for
        [4mcooktime[24m are long, this means ignoring the extra leading '-'.  The
        "[1m--[4m[22moption[24m[1m=[4m[22mvalue[24m" convention is also understood.

[1mEXIT STATUS[0m
        The [4mcooktime[24m command will exit with a status of 1 on any error.  The
        [4mcooktime[24m command will only exit with a status of 0 if there are no
        errors.

[1mCOPYRIGHT[0m
        [4mcooktime[24m version 2.21
        Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
        1997, 1998, 1999, 2000, 2001, 2002 Peter Miller; All rights reserved.

        The [4mcooktime[24m program comes with ABSOLUTELY NO WARRANTY; for details
        use the '[4mcooktime[24m [4m-VERSion[24m [4mLicense[24m' command.  This is free software
        and you are welcome to redistribute it under certain conditions; for
        details use the '[4mcooktime[24m [4m-VERSion[24m [4mLicense[24m' command.

[1mAUTHOR[0m
        Peter Miller   E-Mail:   millerp@canb.auug.org.au
        /\/\*             WWW:   http://www.canb.auug.org.au/~millerp/



FIND_LIBS(1)                General Commands Manual               FIND_LIBS(1)



[1mNAME[0m
        find_libs - find pathnames of libraries

[1mSYNOPSIS[0m
        [1mfind_libs [22m[ [1m-L[4m[22mpath[24m ...  ][ [1m-l[4m[22mname[24m ...  ]
        [1mfind_libs -Help[0m
        [1mfind_libs -VERSion[0m

[1mDESCRIPTION[0m
        The [4mfind_libs[24m program is used to find the actual pathname of a library
        specified on a [4mcc[24m(1) command line.  This allows [4mcook[24m(1) to know these
        dependencies.

[1mOPTIONS[0m
        The following options are understood.

        [1m-L[4m[22mpath[0m
                Specify a path to search for libraries on.  If more than one
                is specified, they will be scanned in the order given before
                the standard [4m/usr/lib[24m and [4m/lib[24m places.  This is like the same
                argument to [4mcc[24m(1), and the usual find_libs option abbreviation
                rules do not apply.

        [1m-l[4m[22mname[0m
                Name a library to be searched for.  This is like the same
                argument to [4mcc[24m(1), and the usual find_libs option abbreviation
                rules do not apply.

        [1m-Help[0m
                Give some information on how to use the [4mfind_libs[24m command.

        [1m-VERSion[0m
                Tell the version of the [4mfind_libs[24m command currently executing.

        All other options will result in a diagnostic error.

        All options may be abbreviated; the abbreviation is documented as the
        upper case letters, all lower case letters and underscores (_) are
        optional.  You must use consecutive sequences of optional letters.

        All options are case insensitive, you may type them in upper case or
        lower case or a combination of both, case is not important.

        For example: the arguments "-help", "-HEL" and "-h" are all
        interpreted to mean the [1m-Help [22moption.  The argument "-hlp" will not be
        understood, because consecutive optional characters were not supplied.

        Options and other command line arguments may be mixed arbitrarily on
        the command line.

        The GNU long option names are understood.  Since all option names for
        [4mfind_libs[24m are long, this means ignoring the extra leading '-'.  The
        "[1m--[4m[22moption[24m[1m=[4m[22mvalue[24m" convention is also understood.

[1mEXIT STATUS[0m
        The [4mfind_libs[24m command will exit with a status of 1 on any error.  The
        [4mfind_libs[24m command will only exit with a status of 0 if there are no
        errors.

[1mCOPYRIGHT[0m
        [4mfind_libs[24m version 2.21
        Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
        1997, 1998, 1999, 2000, 2001, 2002 Peter Miller; All rights reserved.

        The [4mfind_libs[24m program comes with ABSOLUTELY NO WARRANTY; for details
        use the '[4mfind_libs[24m [4m-VERSion[24m [4mLicense[24m' command.  This is free software
        and you are welcome to redistribute it under certain conditions; for
        details use the '[4mfind_libs[24m [4m-VERSion[24m [4mLicense[24m' command.

[1mAUTHOR[0m
        Peter Miller   E-Mail:   millerp@canb.auug.org.au
        /\/\*             WWW:   http://www.canb.auug.org.au/~millerp/



make2cook(1)                General Commands Manual               make2cook(1)

[1mNAME[0m
        make2cook - translate makefiles into cookbooks

[1mSYNOPSIS[0m
        [1mmake2cook [22m[ [4moption[24m...  ][ [4minfile[24m [ [4moutfile[24m ]]
        [1mmake2cook -Help[0m
        [1mmake2cook -VERSion[0m

[1mDESCRIPTION[0m
        The [4mmake2cook[24m program is used to translate [4mMakefile[24ms into cookbooks.
        This command is provided to ease the transition to using the [4mcook[0m
        command.

        If no input file is named, or the special name  ``-'' is used, input
        will be taken from the standard input.  If no output file is named, or
        the special name  ``-'' is used, output will be taken from the
        standard output.

[1mSEMANTICS[0m
        There is no one-to-one semantic mapping between [4mmake[24m semantics and
        [4mcook[24m semantics, so the results will probably need some manual editing.

        The functionality provided by classic [4mmake[24m [4m(1)[24m implementations is
        accurately reproduced.  Extensions, such as those offered by GNU Make
        or BSD make, are not always understood, or are sometimes not
        reproduced identically.

        The following subsections enumerate a few of the things which are
        understood and not understood.  They are probably not complete.

   [1mUnderstood[0m
        The [4mcook[24m program requires variables to be defined before they are
        used, whereas [4mmake[24m will default them to be empty.  This is understood,
        and empty definitions are inserted as required.

        Most of the builtin variables of GNU Make are understood.

        Most of the builtin rules of classic make, GNU Make and BSD make are
        reproduced.

        [1mFor best results [22mthere should be a blank line after every rule, so
        that there can be no confusion where one rule ends and a new one
        begins.

        Builtin variables are defaulted from the environment, if an
        environment variable of the same name is set.

        The GNU Make [4moverride[24m variable assignment is understood.

        The GNU Make ``+='' assignment is understood.

        The GNU Make ``:='' variable assignment is understood.

        Traditional make assignments are macros, they are expanded on use,
        rather than on assignment.  The [4mcook[24m program has only variables.
        Assignment statements are re-arranged to ensure the correct results
        when variables are referenced.

        Single and double suffix rules are understood.  The .SUFFIXES rules
        are understood and honoured.  Hint: if you want to suppress the
        builtin-recipes, use a .SUFFIXES rule with no dependencies.

        The .PHONY rule is understood, and is translated into a [4mset[24m [4mforced[0m
        flag in appropriate recipes, except files from implicit recipes.

        The .PRECIOUS rule is understood, and is translated into a [4mset[0m
        [4mprecious[24m flag in the appropriate recipes, except files from implicit
        recipes.

        The .DEFAULT rule is understood, and is translated into an implicit
        recipe.

        The .IGNORE rule is understood, and is translated into a [4mset[24m [4merrok[0m
        statement.

        The .SILENT rule is understood, and is translated into a [4mset[24m [4msilent[0m
        statement.

        Most GNU Make functions are understood.  The [4mfilter[24m and [4mfilter-out[0m
        functions only understand a single pattern.  The [4msort[24m function does
        not remove duplicates (wrap the [4mstringset[24m function around it if you
        need this).

        The GNU Make static pattern rules are understood.  They are translated
        into recipe predicates.

        The GNU Make and BSD make [4minclude[24m variants are understood.

        The bizarre irregularities surrounding archive files in automatic
        variables and suffix rules are understood, and translated into
        consistent readable recipes.  The [4mmake[24m semantics are preserved.

        The BSD make [4m.CURDIR[24m variable is understood, and translated to an
        equivalent expression.  It cannot be assigned to.

        The GNU Make and BSD make conditionals are understood, provided that
        they bracket whole segments of the makefile, and that these segments
        are syntactically valid.  Cconditionals may also appear within rule
        body commands.  Conditionals are [4mnot[24m understood within the lines of a
        [4mdefine[24m.

        The GNU Make [4mdefine[24m is understood, but its use as a kind of ``function
        definition'' is [4mnot[24m understood.

        The GNU Make [4mexport[24m and [4munexport[24m directives are understood.

   [1mNot Understood[0m
        The [4mcook[24m program tokenizes its input, whereas make does textual
        replacement.  The shennanigans required to construct a make macro
        containing a single space are not understood.  The translation will
        result in a [4mcook[24m variable which is empty.

        References to automatic variables within macro definitions will not
        work.

        The GNU Make [4mforeach[24m function is olny partially understood.  This has
        no exact [4mcook[24m equivalent.

        The GNU Make [4morigin[24m function is not understood.  This has no [4mcook[0m
        equivalent.

        The [4marchive[24m(([4mmember[24m)) notation is not understood.  These semantics are
        not available from [4mcook[24m.

        The [4mMAKEFILES[24m and [4mMAKELEVEL[24m variables are not translated, If you wish
        to reproduce this functionality, you must edit the output.

        The [4mMAKEFLAGS[24m and [4mMFLAGS[24m variables will be translated to use the Cook
        [4moptions[24m function, which has a different range of values.

        Many variants of make can use builtin rules to make the Makefile if it
        is absent.  [4mCook[24m is unable to cook the cookbook if it is absent.

        Wildcards are not understood in rule targets, rule dependencies or
        include directives.  If you want these, you will have to edit the
        output to use the [4m[wildcard][24m function.

        Home directory tildes (~) are not understood in targets and
        dependencies.  If you want this, you will have to edit the output to
        use the [4m[home][24m function.

        The -l[4mhome[24m dependency is not understood to mean a library.  If you
        want this, you will have to edit the output to use the [4m[collect[0m
        [4mfindlibs[24m [4m-l[24mname[4m][24m function.

        The [4m.EXPORT_ALL_VARIABLES[24m rule is not understood.  This has no [4mcook[0m
        equivalent.

[1mOPTIONS[0m
        The following options are understood:

        [1m-Help[0m
                Provide some help with using the [4mmake2cook[24m command.

        [1m-Environment[0m
                This option causes fragments to test for environment variables
                when performing the default settings for variables.  (This
                corresponds to the make -e option.)

        [1m-History_Commands[0m
                This option causes [4mmake2cook[24m to include recipes for [4mRCS[24m and
                [4mSCCS[24m in the output.

        [1m-Line_Numbers[0m
                Insert line number directives into the output, so that it is
                possible to tell where the lines came from.  Most useful when
                debugging.  [4mmake2cook[24m program.

        [1m-No_Internal_Rules[0m
                This option may be used to supress all generation of recipes
                corresponding to make's internal rules.  (This corresponds to
                the make -r option.)

        [1m-VERSion[0m
                Print the version of the [4mmake2cook[24m program being executed.

        All other options will produce a diagnostic error.

        All options may be abbreviated; the abbreviation is documented as the
        upper case letters, all lower case letters and underscores (_) are
        optional.  You must use consecutive sequences of optional letters.

        All options are case insensitive, you may type them in upper case or
        lower case or a combination of both, case is not important.

        For example: the arguments "-help", "-HEL" and "-h" are all
        interpreted to mean the [1m-Help [22moption.  The argument "-hlp" will not be
        understood, because consecutive optional characters were not supplied.

        Options and other command line arguments may be mixed arbitrarily on
        the command line.

        The GNU long option names are understood.  Since all option names for
        [4mmake2cook[24m are long, this means ignoring the extra leading '-'.  The
        "[1m--[4m[22moption[24m[1m=[4m[22mvalue[24m" convention is also understood.

[1mEXIT STATUS[0m
        The [4mmake2cook[24m command will exit with a status of 1 on any error.  The
        [4mmake2cook[24m command will only exit with a status of 0 if there are no
        errors.

[1mCOPYRIGHT[0m
        [4mmake2cook[24m version 2.21
        Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
        1997, 1998, 1999, 2000, 2001, 2002 Peter Miller; All rights reserved.

        The [4mmake2cook[24m program comes with ABSOLUTELY NO WARRANTY; for details
        use the '[4mmake2cook[24m [4m-VERSion[24m [4mLicense[24m' command.  This is free software
        and you are welcome to redistribute it under certain conditions; for
        details use the '[4mmake2cook[24m [4m-VERSion[24m [4mLicense[24m' command.

[1mAUTHOR[0m
        Peter Miller   E-Mail:   millerp@canb.auug.org.au
        /\/\*             WWW:   http://www.canb.auug.org.au/~millerp/



ROFFPP(1)                   General Commands Manual                  ROFFPP(1)



[1mNAME[0m
        roffpp - replace .so requests within *roff sources

[1mSYNOPSIS[0m
        [1mroffpp [22m[ [4moption[24m...  ][ [4minfile[24m [ [4moutfile[24m ]]
        [1mroffpp -Help[0m
        [1mroffpp -VERSion[0m

[1mDESCRIPTION[0m
        The [4mroffpp[24m command may be used to copies the input file to the output
        file, including files named using [4m.so[24m directives along the way, and
        removing the [4m.so[24m directives.

        This is useful when processing large multi-file documents with filters
        such as [4mtbl[24m(1) or [4meqn[24m(1) which do not understand the [4m.so[24m directive.
        The [4m.nx[24m directive is not understood.  The [4mroffpp[24m program is not a
        general *roff interpreter, so many constructs will be beyond it,
        fortunately, most of them have nothing to do with include files.
        Include files which cannot be found, probably from uninterpreted *roff
        constructs, if the files really does exist, will simply be passed
        through unchanged, for *roff to interpret at a later time.

        The [4mroffpp[24m program also allows the user to specify an include search
        path.  This allows, for example, common files to be kept in a central
        location.

        Only directives of the form
                [1m.so [4m[22mfilename[0m
        are processed.  If the directive is introduced using the single quote
        form, or the dot is not the first character of the line, the directive
        will be ignored.

        Any extra arguments on the line are ignored, and quoting is not
        understood.  All characters are interpreted literally.

        Examples of directives which will be ignored include
                'so /usr/lib/tmac/tmac.an
                .if n .so yuck
        This list is not exhaustive.

        The special file name `[1m-[22m' on the command line means the standard input
        or standard output, as appropriate.  Files which are omitted are also
        assumed to be the standard input or standard output, as appropriate.

        The output attempts to keep file names and line numbers in sync by
        using the [1m.lf [22mdirective.  The [1m.lf [22mdirective is also understood as
        input.  This is compatible with [4mgroff[24m(1) and the other GNU text
        utilities included in the groff package.

[1mOPTIONS[0m
        The following options are understood.

        [1m-I[4m[22mpath[0m
                Specify include path, a la [4mcc[24m(1).  Include paths are searched
                in the order specified.  The include search path defaults to
                the current directory if and only if the user does not specify
                any include search paths.

        [1m-Help[0m
                Give information on how to use [4mroffpp[24m.

        [1m-VERSion[0m
                Tell what version of [4mroffpp[24m is being run.

        Any other option will generate a diagnostic error.

        All options may be abbreviated; the abbreviation is documented as the
        upper case letters, all lower case letters and underscores (_) are
        optional.  You must use consecutive sequences of optional letters.

        All options are case insensitive, you may type them in upper case or
        lower case or a combination of both, case is not important.

        For example: the arguments "-help", "-HEL" and "-h" are all
        interpreted to mean the [1m-Help [22moption.  The argument "-hlp" will not be
        understood, because consecutive optional characters were not supplied.

        Options and other command line arguments may be mixed arbitrarily on
        the command line.

        The GNU long option names are understood.  Since all option names for
        [4mroffpp[24m are long, this means ignoring the extra leading '-'.  The
        "[1m--[4m[22moption[24m[1m=[4m[22mvalue[24m" convention is also understood.

[1mEXIT STATUS[0m
        The [4mroffpp[24m command will exit with a status of 1 on any error.  The
        [4mroffpp[24m command will only exit with a status of 0 if there are no
        errors.

[1mCOPYRIGHT[0m
        [4mroffpp[24m version 2.21
        Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
        1997, 1998, 1999, 2000, 2001, 2002 Peter Miller; All rights reserved.

        The [4mroffpp[24m program comes with ABSOLUTELY NO WARRANTY; for details use
        the '[4mroffpp[24m [4m-VERSion[24m [4mLicense[24m' command.  This is free software and you
        are welcome to redistribute it under certain conditions; for details
        use the '[4mroffpp[24m [4m-VERSion[24m [4mLicense[24m' command.

[1mAUTHOR[0m
        Peter Miller   E-Mail:   millerp@canb.auug.org.au
        /\/\*             WWW:   http://www.canb.auug.org.au/~millerp/



Table of Contents(Cook)                                Table of Contents(Cook)



         The README File . . . . . . . . . . . . . . . . . . . . . . . . .   0
         Release Notes . . . . . . . . . . . . . . . . . . . . . . . . . .   3
         How to Build the Sources  . . . . . . . . . . . . . . . . . . . .   9
             Windows NT  . . . . . . . . . . . . . . . . . . . . . . . . .  12
         Internationalization  . . . . . . . . . . . . . . . . . . . . . .  14
c_incl(1)                                                                  determine include dependencies 15
cook(1)  a file construction tool  . . . . . . . . . . . . . . . . . . . .  17
cook_bom(1)                                                                bill of materials 21
cook_lic(1)                                                                GNU General Public License 22
cook_rsh(1)                                                                load balancing rsh 36
cookfp(1)                                                                  calculate file fingerprint 39
cooktime(1)                                                                set file times 43
find_libs(1)                                                               find pathnames of libraries 45
make2cook(1)                                                               translate makefiles into cookbooks 48
roffpp(1)                                                                  replace .so requests within *roff sources 53



Permuted Index(Cook)                                      Permuted Index(Cook)


cook_rsh(1)    36   cook_rsh - load        balancing rsh
cook_bom(1)    21   cook_bom -             bill of materials
cook_bom(1)    21   cook_                  bom - bill of
                                           materials
cookfp(1)      39   cookfp -               calculate file
                                           fingerprint

c_incl(1)      15                          c_incl - determine
                                           dependencies
cook(1)        17   cook - a file          construction tool
cook(1)        17                          cook - a file
                                           construction tool


cook_bom(1)    21                          cook_bom - bill of
                                           materials
make2cook(1)   48   make2cook -            cookbooks
                    translate makefiles
                    into


cookfp(1)      39                          cookfp - calculate
                                           file fingerprint
cook_rsh(1)    36                          cook_rsh - load
                                           balancing rsh
cooktime(1)    43                          cooktime - set file
                                           times

make2cook(1)   48   make2                  cook - translate
                                           makefiles into
                                           cookbooks
c_incl(1)      15   c_incl - determine     dependencies
c_incl(1)      15   c_incl -               determine
                                           dependencies

cook(1)        17   cook - a               file construction
                                           tool
cookfp(1)      39   cookfp - calculate     file fingerprint
cooktime(1)    43   cooktime - set         file times



find_libs(1)   45                          find_libs - find
                                           pathnames of
                                           libraries
find_libs(1)   45   find_libs -            find pathnames of
                                           libraries


cookfp(1)      39   cookfp - calculate     fingerprint
                    file
c_incl(1)      15   c_                     incl - determine
                                           dependencies
make2cook(1)   48   make2cook -            into cookbooks
                    translate makefiles

find_libs(1)   45   find_libs - find       libraries
                    pathnames of
find_libs(1)   45   find_                  libs - find
                                           pathnames of
                                           libraries
cook_rsh(1)    36   cook_rsh -             load balancing rsh

make2cook(1)   48                          make2cook -
                                           translate makefiles
                                           into cookbooks
make2cook(1)   48   make2cook -            makefiles into
                    translate              cookbooks
cook_bom(1)    21   cook_bom - bill of     materials

find_libs(1)   45   find_libs - find       pathnames of
                                           libraries
roffpp(1)      53   roffpp -               replace .so requests
                                           within *roff sources
roffpp(1)      53   roffpp - replace .so   requests within
                                           *roff sources

roffpp(1)      53                          roffpp - replace .so
                                           requests within
                                           *roff sources
roffpp(1)      53   roffpp - replace .so   roff sources
                    requests within *


cook_rsh(1)    36   cook_rsh - load        rsh
                    balancing
cook_rsh(1)    36   cook_                  rsh - load balancing
                                           rsh
cooktime(1)    43   cooktime -             set file times


roffpp(1)      53   roffpp - replace .     so requests within
                                           *roff sources
roffpp(1)      53   roffpp - replace .so   sources
                    requests within
                    *roff
cooktime(1)    43   cooktime - set file    times

cook(1)        17   cook - a file          tool
                    construction
make2cook(1)   48   make2cook -            translate makefiles
                                           into cookbooks
roffpp(1)      53   roffpp - replace .so   within *roff sources
                    requests



Reference Manual               Cook                      -cmxcvii
