Added: incubator/ooo/ooo-site/trunk/content/tools/dmake/dmake_4.4.html
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/tools/dmake/dmake_4.4.html?rev=1206839&view=auto
==============================================================================
--- incubator/ooo/ooo-site/trunk/content/tools/dmake/dmake_4.4.html (added)
+++ incubator/ooo/ooo-site/trunk/content/tools/dmake/dmake_4.4.html Sun Nov 27 20:35:52 2011
@@ -0,0 +1,3811 @@
+<HTML><HEAD><TITLE>Manpage of DMAKE 4.4</TITLE>
+</HEAD><BODY>
+<H1>DMAKE - Version 4.4</H1>
+<A HREF="#index">Index</A>
+<HR>
+
+<A NAME="lbAB">&nbsp;</A>
+<H2>NAME</H2>
+
+<B>dmake</B> - maintain program groups, or interdependent files
+<A NAME="lbAC">&nbsp;</A>
+<H2>SYNOPSIS</H2>
+
+
+<B>dmake</B>
+
+[-P#] [-{f|C|K} file] [-{w|W} target ...]
+[macro[[!][*][+][:]]=<I>value</I> ...]
+[-ABcdeEghiknpqrsStTuVxX] [-v[cdfimrtw]] [-m[trae]] [target ...]
+
+<A NAME="lbAD">&nbsp;</A>
+<H2>DESCRIPTION</H2>
+
+<P>
+
+<B>dmake</B>
+
+is a re-implementation of the UNIX Make utility with significant enhancements.
+<B>dmake</B>
+
+executes commands found in an external file called a
+<I>makefile</I>
+
+to update one or more target names.
+Each target may depend on zero or more prerequisite targets.
+If any of the target's prerequisites is newer than the target or if the target
+itself does not exist, then
+<B>dmake</B>
+
+will attempt to make the target.
+<P>
+
+If no
+<B>-f</B>
+
+command line option is present then
+<B>dmake</B>
+
+searches for an existing
+<I>makefile</I>
+
+from the list of prerequisites specified for the special target <I>.MAKEFILES</I>
+(see the STARTUP section for more details).
+If &quot;-&quot; is the name of the file specified to the
+<B>-f</B>
+
+flag then <B>dmake</B> uses standard input as the source of the makefile text.
+<P>
+
+Any macro definitions (arguments with embedded &quot;=&quot;
+signs) that appear on the command line are processed first
+and supercede definitions for macros of the same name found
+within the makefile. In general it is impossible for definitions found
+inside the makefile to redefine a macro defined on the command line, see the
+MACROS section for exceptions.
+<P>
+
+If no
+<I>target</I>
+
+names are specified on the command line, then <B>dmake</B> uses the first
+non-special target found in the makefile as the default target.
+See the
+<B>SPECIAL TARGETS</B>
+
+section for the list of special targets and their function.
+Makefiles written for most previous
+versions of
+<I>Make</I>
+
+will be handled correctly by
+<B>dmake.</B>
+
+Known differences between <B>dmake</B> and other versions of make
+are discussed in the
+<B>COMPATIBILITY</B>
+
+section found at the end of this document.
+<B>dmake</B>
+
+returns 0 if no errors were detected and a non-zero result if an error
+occurred.
+<A NAME="lbAE">&nbsp;</A>
+<H2>OPTIONS</H2>
+
+<DL COMPACT>
+<DT><B>-A</B><DD>
+Enable AUGMAKE special inference rule transformations
+(see the &quot;PERCENT(%) RULES&quot; section), these are set to off by default.
+<DT><B>-B</B><DD>
+Enable the use of spaces instead of &lt;tabs&gt; to begin recipe lines.
+This flag equivalent to the .NOTABS special macro and is further described
+below.
+<DT><B>-c</B><DD>
+Use non-standard comment stripping. If you specify <B>-c</B> then
+<B>dmake</B>
+
+will treat any <B>#</B> character as a start of comment character wherever it
+may appear unless it is escaped by a \.
+<DT><B>-C [+]file</B><DD>
+This option writes to <I>file</I> a copy of standard output and
+standard error from any child processes and from the
+<B>dmake</B>
+
+process itself. If you specify a <B>+</B> prior to the file name then
+the text is appended to the previous contents of <I>file</I>.
+This option is active in the MSDOS implementation only and is ignored
+by non-MSDOS versions of
+<B>dmake.</B>
+
+<DT><B>-d</B><DD>
+Disable the use of the directory cache. Normally <B>dmake</B> caches directories
+as it checks file timestamps. Giving this flag is equivalent to the
+.DIRCACHE attribute or macro being set to <I>no</I>.
+<DT><B>-E</B><DD>
+Read the environment and define all strings of the
+form '<B>ENV-VAR</B>=<I>evalue</I>'
+defined within as macros whose name is <B>ENV-VAR</B>,
+and whose value is '<I>evalue</I>'.
+The environment is processed prior to processing the user
+specified makefile thereby allowing definitions in the makefile to override
+definitions in the environment.
+<DT><B>-e</B><DD>
+Same as -E, except that the environment is processed after the
+user specified makefile has been processed
+(thus definitions in the environment override definitions in the makefile).
+The -e and -E options are mutually exclusive.
+If both are given the latter takes effect.
+<DT><B>-f file</B><DD>
+Use <B>file</B> as the source for the makefile text.
+Only one <B>-f</B> option is allowed.
+<DT><B>-g</B><DD>
+Globally disable group recipe parsing, equivalent to the .IGNOREGROUP
+attribute or macro being set to <I>yes</I> at the start of the makefile.
+<DT><B>-h</B><DD>
+Print the command summary for <B>dmake</B>.
+<DT><B>-i</B><DD>
+Tells <B>dmake</B> to ignore errors, and continue making other targets.
+This is equivalent to the .IGNORE attribute or macro.
+<DT><B>-K file</B><DD>
+Turns on <B>.KEEP_STATE</B> state tracking and tells <B>dmake</B> to use
+<I>file</I> as the state file.
+<DT><B>-k</B><DD>
+Causes <B>dmake</B> to ignore errors caused by command execution and to make
+all targets not depending on targets that could not be made.
+Ordinarily <B>dmake</B> stops after a command returns a non-zero status,
+specifying <B>-k</B> causes <B>dmake</B> to ignore the error
+and continue to make as much as possible.
+<DT><B>-m[trae]</B><DD>
+Measure timing information. Print the time when targets and/or recipes
+are started and finished to stdout. The following format is used:
+<DT><DD>
+<B>{s|e} {target|recipe} time maketarget</B>
+<DT><DD>
+<B>s</B> or <B>e</B> stands for started or ended, <B>target</B> or
+<B>recipe</B> denotes if this line refers to the whole target or a
+recipe. <B>time</B> is displayed in Unix time format, i.e. the number
+of seconds since an epoch. (Since 1970-01-01T00:00:00Z). <B>maketarget</B>
+obviously represents the target the timing information is given for.
+The optional flags <B>[trae]</B> can be used to change the information that
+is displayed. If no optional flags are given only the <B>t</B> flag
+is assumed to be selected, ie. <B>-mt</B>. The optional flags stand for:
+<DL COMPACT><DT><DD>
+<DL COMPACT>
+<DT><B>t</B><DD>
+Display the start and end time of each target.
+<DT><B>r</B><DD>
+Display the start and end time of each recipe.
+<DT><B>a</B><DD>
+Display the target as an absolute path, i.e. prepend the current working
+directory.
+<DT><B>e</B><DD>
+Also display the start and end time of the <B>$(shell command)</B> function
+(aka. shell escape) macros.
+</DL>
+</DL>
+
+<DT><B>-n</B><DD>
+Causes <B>dmake</B> to print out what it would have executed,
+but does not actually execute the commands. A special check is made for
+the string &quot;$(MAKE)&quot; inside a recipe line, if it is found,
+the line is expanded and invoked, thereby enabling recursive makes to give a
+full description of all that they will do.
+This check is disabled inside group recipes.
+<DT><B>-p</B><DD>
+Print out a version of the digested makefile in human readable form.
+(useful for debugging, but cannot be re-read by <B>dmake</B>)
+<DT><B>-P#</B><DD>
+On systems that support multi-processing cause <B>dmake</B> to use <I>#</I>
+concurrent child processes to make targets.
+See the &quot;MULTI PROCESSING&quot; section for more information.
+<DT><B>-q</B><DD>
+Check and see if the target is up to date. Exits with code 0 if up to date,
+1 otherwise.
+<DT><B>-r</B><DD>
+Tells <B>dmake</B> not to read the initial startup makefile, see STARTUP
+section for more details.
+<DT><B>-s</B><DD>
+Tells <B>dmake</B> to do all its work silently and not echo the commands it is
+executing to stdout (also suppresses warnings).
+This is equivalent to the .SILENT attribute or macro.
+<DT><B>-S</B><DD>
+Force sequential execution of recipes on architectures which support
+concurrent makes. For backward compatibility with old makefiles that have
+nasty side-effect prerequisite dependencies.
+<DT><B>-t</B><DD>
+Causes <B>dmake</B> to touch the targets and bring them up to date
+without executing any commands.
+Note that targets will not be created if they do not already exist.
+<DT><B>-T</B><DD>
+Tells <B>dmake</B> to not perform transitive closure on the inference graph.
+<DT><B>-u</B><DD>
+Force an unconditional update. (ie. do everything that would
+be done if everything that a target depended on was out of date)
+<DT><B>-v[cdfimrtw]</B><DD>
+Verbose flag, when making targets print to stdout what we are going to make
+and what we think its time stamp is. The optional flags <B>[cdfimrtw]</B> can be
+used to restrict the information that is displayed. In the absence of any
+optional flags all are assumed to be given (ie. <B>-v</B> is equivalent to
+<B>-vcdfimrtw</B>). The meanings of the optional flags are:
+<DL COMPACT><DT><DD>
+<DL COMPACT>
+<DT><B>c</B><DD>
+Notify of directory cache operations only.
+<DT><B>d</B><DD>
+Notify of change directory operations only.
+<DT><B>f</B><DD>
+Notify of file I/O operations only.
+<DT><B>i</B><DD>
+Notify of inference algorithm operation only.
+<DT><B>m</B><DD>
+Notify of target update operations only.
+<DT><B>r</B><DD>
+Force output of recipe lines and warnings. This switch is usefull when
+debugging makefiles that disable the output using the @ sign for recipe
+lines or the .SILENT target/attribute. It also overrides the -s flag.
+<DT><B>t</B><DD>
+Keep any temporary files created; normally they are automatically deleted.
+<DT><B>w</B><DD>
+Notify of non-essential warnings (these are historical).
+</DL>
+</DL>
+
+<DT><B>-V</B><DD>
+Print the version of <B>dmake</B>, and values of builtin macros.
+<DT><B>-W target</B><DD>
+Run <B>dmake</B> pretending that <I>target</I> is out of date.
+<DT><B>-w target</B><DD>
+<I>What if?</I> Show what would be made if <I>target</I> were out of date.
+<DT><B>-x</B><DD>
+Upon processing the user makefile export all non-internally defined macros
+to the user's environment. This option together with the -e option
+allows SYSV AUGMAKE recursive makes to function as expected.
+<DT><B>-X</B><DD>
+Inhibit the execution of <B>#!</B> lines found at the beginning of a makefile.
+The use of this flag prevents non-termination of recursive make invocations.
+</DL>
+<A NAME="lbAF">&nbsp;</A>
+<H2>INDEX</H2>
+
+Here is a list of the sections that follow and a short description of each.
+Perhaps you won't have to read the entire man page to find
+what you need.
+<DL COMPACT>
+<DT><B>STARTUP</B><DD>
+Describes <B>dmake</B> initialization.
+<DT><B>SYNTAX</B><DD>
+Describes the syntax of makefile expressions.
+<DT><B>ATTRIBUTES</B><DD>
+Describes the notion of attributes and how they are used when
+making targets.
+<DT><B>MACROS</B><DD>
+Defining and expanding macros.
+<DT><B>RULES AND TARGETS<DD>
+How to define targets and their prerequisites.
+<DT>RECIPES</B><DD>
+How to tell <B>dmake</B> how to make a target.
+<DT><B>TEXT DIVERSIONS</B><DD>
+How to use text diversions in recipes and macro expansions.
+<DT><B>SPECIAL TARGETS</B><DD>
+Some targets are special.
+<DT><B>SPECIAL MACROS</B><DD>
+Macros used by <B>dmake</B> to alter the processing of the makefile,
+and those defined by <B>dmake</B> for the user.
+<DT><B>CONTROL MACROS</B><DD>
+Itemized list of special control macros.
+<DT><B>RUNTIME MACROS</B><DD>
+Discussion of special run-time macros such as $@ and $&lt;.
+<DT><B>FUNCTION MACROS</B><DD>
+GNU style function macros, only $(mktmp ...) for now.
+<DT><B>CONDITIONAL MACROS</B><DD>
+Target specific conditional macros.
+<DT><B>DYNAMIC PREREQUISITES</B><DD>
+Processing of prerequisites which contain macro expansions in their name.
+<DT><B>BINDING TARGETS</B><DD>
+The rules that <B>dmake</B> uses to bind
+a target to an existing file in the file system.
+<DT><B>PERCENT(%) RULES</B><DD>
+Specification of recipes to be used by the inference algorithm.
+<DT><B>MAKING INFERENCES</B><DD>
+The rules that <B>dmake</B> uses when inferring how to make a target which
+has no explicit recipe. This and the previous section are really a single
+section in the text.
+<DT><B>MAKING TARGETS</B><DD>
+How <B>dmake</B> makes targets other than libraries.
+<DT><B>MAKING LIBRARIES</B><DD>
+How <B>dmake</B> makes libraries.
+<DT><B>KEEP STATE</B><DD>
+A discussion of how .KEEP_STATE works.
+<DT><B>MULTI PROCESSING</B><DD>
+Discussion of <B>dmake's</B> parallel make facilities for architectures that
+support them.
+<DT><B>CONDITIONALS</B><DD>
+Conditional expressions which control the processing of the makefile.
+<DT><B>EXAMPLES</B><DD>
+Some hopefully useful examples.
+<DT><B>COMPATIBILITY</B><DD>
+How <B>dmake</B> compares with previous versions of make.
+<DT><B>LIMITS</B><DD>
+Limitations of <B>dmake</B>.
+<DT><B>PORTABILITY</B><DD>
+Comments on writing portable makefiles.
+<DT><B>FILES</B><DD>
+Files used by <B>dmake</B>.
+<DT><B>SEE ALSO</B><DD>
+Other related programs, and man pages.
+<DT><B>AUTHOR</B><DD>
+The guy responsible for this thing.
+<DT><B>BUGS</B><DD>
+Hope not.
+</DL>
+<A NAME="lbAG">&nbsp;</A>
+<H2>STARTUP</H2>
+
+When
+<B>dmake</B>
+
+begins execution it first processes the command line and then processes
+an initial startup-makefile.
+This is followed by an attempt to locate and process a user supplied makefile.
+The startup file defines the default values of all required control macros
+and the set of default rules for making targets and inferences.
+When searching for the startup makefile,
+<B>dmake</B>
+
+searches the following locations, in the order specified,
+until a startup file is located:
+<P>
+
+<DL COMPACT><DT><DD>
+<DL COMPACT>
+<DT>1.<DD>
+The location given as the value of the macro
+MAKESTARTUP defined on the command line.
+<DT>2.<DD>
+The location given as the value of the environment variable MAKESTARTUP
+defined in the current environment.
+<DT>3.<DD>
+The location given as the value of the macro
+MAKESTARTUP defined internally within <B>dmake</B>. In this version, the
+internal definition of MAKESTARTUP is &quot;$(DMAKEROOT)/startup.mk&quot;, so you
+can set the environment variable DMAKEROOT to the location of your startup
+directory.
+<P>
+If DMAKEROOT is not changed, for native Windows dmake versions its value
+defaults to &quot;$(ABSMAKECMD:d)startup&quot; (see definition of ABSMAKECMD for
+details).
+For unix like versions build with the autotools build system it defaults
+to the value of &quot;${prefix}/share/startup&quot; at build time. The actual value,
+usually something like /usr/local/share/startup can be checked with the -V
+command line switch.
+</DL>
+</DL>
+
+<P>
+
+The above search is disabled by specifying the -r option on the command line.
+An error is issued if a startup makefile cannot be found and the -r
+option was not specified.
+A user may substitute a custom startup file by defining
+the MAKESTARTUP environment variable or by redefining the
+MAKESTARTUP macro on the command line.
+To determine where
+<B>dmake</B>
+
+looks for the default startup file, check your environment or issue the command
+<I>&quot;dmake -V&quot;</I>.
+<P>
+
+A similar search is performed to locate a default user makefile when no
+<B>-f</B> command line option is specified.
+By default, the prerequisite list of the special target .MAKEFILES
+specifies the names of possible makefiles and the search order that
+<B>dmake</B> should use to determine if one exists.
+A typical definition for this target is:
+<DL COMPACT><DT><DD>
+<P>
+.MAKEFILES : makefile.mk Makefile makefile
+<P>
+</DL>
+
+<B>dmake</B> will first look for makefile.mk and then the others.
+If a prerequisite
+cannot be found <B>dmake</B> will try to make it before going on to the next
+prerequisite. For example, makefile.mk can be checked out of an RCS file
+if the proper rules for doing so are defined in the startup file.
+<P>
+
+If the first line of the user makefile is of the form:
+<DL COMPACT><DT><DD>
+<P>
+#!command command_args
+<P>
+</DL>
+
+then <B>dmake</B> will expand and run the command prior to reading any
+additional input. If the return code of the command is zero then <B>dmake</B>
+will continue on to process the remainder of the user makefile, if the return
+code is non-zero then dmake will exit.
+<P>
+
+<B>dmake</B> builds the internal dependency graph as it parses a user specified
+makefile. The graph is rooted at the special target <B>.ROOT</B>. .ROOT is the
+top level target that dmake builds when it starts to build targets. All user
+specified targets (those from the command line or taken as defaults from
+the makefile) are made prerequisites of the special target <B>.TARGETS</B>.
+<B>dmake</B> by default creates the relationship that .ROOT depends on .TARGETS
+and as a result everything is made. This approach allows the user to customize, within
+their makefile, the order and which, target, is built first. For example the
+default makefiles come with settings for .ROOT that specify:
+<P>
+<DL COMPACT><DT><DD>
+.ROOT .PHONY .NOSTATE .SEQUENTIAL : .INIT .TARGETS .DONE
+</DL>
+
+<P>
+with .INIT and .DONE defined as:
+<P>
+<DL COMPACT><DT><DD>
+.INIT .DONE .PHONY:;
+</DL>
+
+<P>
+which nicely emulates the behaviour of Sun's make extensions. The building of
+.ROOT's prerequisites is always forced to be sequential. However, this
+definition is trivially chaned by supplying the definition:
+<P>
+<DL COMPACT><DT><DD>
+.ROOT : .TARGETS
+</DL>
+
+<P>
+which skips the preamble and postamble phases of building .TARGETS.
+<A NAME="lbAH">&nbsp;</A>
+<H2>SYNTAX</H2>
+
+This section is a summary of the syntax of makefile statements.
+The description is given in a style similar to BNF, where { } enclose
+items that may appear zero or more times, and [ ] enclose items that
+are optional. Alternative productions for a left hand side are indicated
+by '->', and newlines are significant. All symbols in <B>bold</B> type
+are text or names representing text supplied by the user.
+<P>
+<DL COMPACT><DT><DD>
+
+<P>
+<PRE>
+<DL COMPACT>
+<DT>Makefile<DD>-> { Statement }
+
+
+<DT>Statement<DD>-> Macro-Definition
+-> Conditional-Macro-Definition
+-> Conditional
+-> Rule-Definition
+-> Attribute-Definition
+
+
+<DT>Macro-Definition<DD>-> <B>MACRO = LINE</B>
+-> <B>MACRO [!</B>]*= LINE
+-> <B>MACRO [!</B>]:= LINE
+-> <B>MACRO [!</B>]*:= LINE
+-> <B>MACRO [!</B>]+= LINE
+-> <B>MACRO [!</B>]+:= LINE
+
+
+<DT>Conditional-Macro-Definition -> <DD><B>TARGET</B> ?= Macro-Definition
+
+
+<DT>Conditional -> <DD><B>.IF</B> expression
+ Makefile
+[ <B>.ELIF</B> expression
+ Makefile ]
+[ <B>.ELSE</B>
+ Makefile ]
+<B>.END</B>
+
+
+<DT>expression<DD>-> <B>LINE</B>
+-> <B>STRING == LINE</B>
+-> <B>STRING != LINE</B>
+-> <B>STRING &lt;= LINE</B>
+-> <B>STRING &gt;= LINE</B>
+-> <B>(</B> expression <B>)</B>
+-> expression <B>||</B> expression
+-> expression <B>&amp;&amp;</B> expression
+
+
+<DT>Rule-Definition -> <DD>target-definition
+ [ recipe ]
+</DL>
+
+target-definition -> targets [attrs] op { <B>PREREQUISITE</B> } [<B>;</B> rcp-line]
+
+
+<DL COMPACT>
+<DT>targets<DD>-> target { targets }
+-> <B>&quot;</B>target<B>&quot;</B> { targets }
+
+
+<DT>target<DD>-> special-target
+-> <B>TARGET</B>
+
+
+<DT>attrs<DD>-> attribute { attrs }
+-> <B>&quot;</B>attribute<B>&quot;</B> { attrs }
+
+
+<DT>op<DD>-> <B>:</B> { modifier }
+
+
+<DT>modifier<DD>-> <B>:</B>
+-> <B>^</B>
+-> <B>!</B>
+-> <B>-</B>
+-> <B>|</B>
+
+
+<DT>recipe<DD>-> { <B>TAB</B> rcp-line }
+-> [<B>@</B>][<B>%</B>][<B>-</B>] <B>[
+
+
+<DT> <DD> </B>{ <B>LINE</B> }
+
+<DT> <DD><B>]</B>
+
+
+<DT>rcp-line<DD>-> [<B>@</B>][<B>%</B>][<B>-</B>][<B>+</B>] <B>LINE</B>
+
+
+<DT>Attribute-Definition<DD>-> attrs <B>:</B> targets
+
+
+<DT>attribute<DD>-> <B>.EPILOG</B>
+-> <B>.ERRREMOVE</B>
+-> <B>.EXECUTE</B>
+-> <B>.GROUP</B>
+-> <B>.IGNORE</B>
+-> <B>.IGNOREGROUP</B>
+-> <B>.LIBRARY</B>
+-> <B>.MKSARGS</B>
+-> <B>.NOINFER</B>
+-> <B>.NOSTATE</B>
+-> <B>.PHONY</B>
+-> <B>.PRECIOUS</B>
+-> <B>.PROLOG</B>
+-> <B>.SETDIR=</B><I>path</I>
+-> <B>.SILENT</B>
+-> <B>.SEQUENTIAL</B>
+-> <B>.SWAP</B>
+-> <B>.USESHELL</B>
+-> <B>.SYMBOL</B>
+-> <B>.UPDATEALL</B>
+
+
+<DT>special-target<DD>-> <B>.ERROR</B>
+-> <B>.EXIT</B>
+-> <B>.EXPORT</B>
+-> <B>.GROUPEPILOG</B>
+-> <B>.GROUPPROLOG</B>
+-> <B>.IMPORT</B>
+-> <B>.INCLUDE</B>
+-> <B>.INCLUDEDIRS</B>
+-> <B>.MAKEFILES</B>
+-> <B>.REMOVE</B>
+-> <B>.SOURCE</B>
+-> <B>.SOURCE.</B><I>suffix</I>
+-> .<I>suffix1</I>.<I>suffix2</I>
+</PRE>
+
+</DL>
+</DL>
+
+<P>
+<P>
+
+Where, <B>TAB</B> represents a &lt;tab&gt; character, <B>STRING</B> represents an
+arbitrary sequence of characters, and
+<B>LINE</B> represents a
+possibly empty sequence of characters terminated by a non-escaped
+(not immediately preceded by a backslash '\') new-line character.
+<B>MACRO</B>, <B>PREREQUISITE</B>,
+and <B>TARGET</B> each represent a string of characters not
+including space or tab which respectively form the name of a macro,
+prerequisite or target.
+The name may itself be a macro expansion expression.
+A <B>LINE</B> can be continued over several physical lines by terminating it with
+a single backslash character. Comments are initiated by the
+pound <B>#</B> character and extend to the end of line.
+All comment text is discarded, a '#' may be placed into the makefile text
+by escaping it with '\' (ie. \# translates to # when it is parsed).
+An exception to this occurs when a # is seen inside
+a recipe line that begins with a &lt;tab&gt; or is inside a group recipe.
+If you specify the <B>-c</B> command line switch then this behavior is
+disabled and
+<B>dmake</B>
+
+will treat all # characters as start of comment indicators unless they
+are escaped by \.
+A set of continued lines may be commented out by placing a single # at the
+start of the first line.
+A continued line cannot span more than one makefile.
+<P>
+
+<B>white space</B> is defined to be any combination of
+&lt;space&gt;, &lt;tab&gt;, and the sequence \&lt;nl&gt;
+when \&lt;nl&gt; is used to terminate a LINE.
+When processing <B>macro</B> definition lines,
+any amount of white space is allowed on either side of the macro operator
+and white space is stripped from both before and after the macro
+value string.
+The sequence \&lt;nl&gt; is treated as white space during recipe expansion
+and is deleted from the final recipe string.
+You must escape the \&lt;nl&gt; with another \ in order to get a \ at the end
+of a recipe line.
+The \&lt;nl&gt; sequence is deleted from macro values when they are expanded.
+<P>
+
+When processing <B>target</B> definition lines,
+the recipe for a target must, in general, follow the first definition
+of the target (See the RULES AND TARGETS section for an exception), and
+the recipe may not span across multiple makefiles.
+Any targets and prerequisites found on a target definition line are taken
+to be white space separated tokens.
+The rule operator (<I>op</I> in SYNTAX section) is also considered
+to be a token but does not require
+white space to precede or follow it. Since the rule operator begins with a `:',
+traditional versions of make do not allow the `:' character to
+form a valid target name. <B>dmake</B> allows `:' to be present in
+target/prerequisite names as long as the entire target/prerequisite name is
+quoted. For example:
+<P>
+ a:fred : test
+<P>
+would be parsed as TARGET = a, PREREQUISITES={fred, :, test}, which
+is not what was intended. To fix this you must write:
+<P>
+ &quot;a:fred&quot; : test
+<P>
+Which will be parsed as expected. Quoted target and prerequisite
+specifications may also contain white space thereby allowing the use of
+complex function macro expressions..
+See the EXAMPLES section for how to apply <B>&quot;</B> quoting
+to a list of targets.
+<A NAME="lbAI">&nbsp;</A>
+<H2>ATTRIBUTES</H2>
+
+<B>dmake</B>
+
+defines several target attributes. Attributes may be
+assigned to a single target, a group of targets, or to all targets in the
+makefile. Attributes are used to modify
+<B>dmake</B> actions during target update.
+The recognized attributes are:
+<P>
+<DL COMPACT>
+<DT><B>.EPILOG</B><DD>
+Insert shell epilog code when executing a group recipe associated with
+any target having this attribute set.
+<DT><B>.ERRREMOVE</B><DD>
+Always remove any target having this attribute if an error is encountered
+while making them. Setting this attribute overrides the .PRECIOUS attribute.
+<DT><B>.EXECUTE</B><DD>
+If the -n flag was given then execute the recipe associated with any
+target having this attribute set.
+<DT><B>.FIRST</B><DD>
+Used in conjunction with .INCLUDE. Terminates the inclusion with the first
+successfully included prerequisite.
+<DT><B>.GROUP</B><DD>
+Force execution of a target's recipe as a group recipe.
+<DT><B>.IGNORE</B><DD>
+Ignore an error when trying to make any target with this attribute set.
+<DT><B>.IGNOREGROUP</B><DD>
+Disable the special meaning of '[' to initiate a group recipe.
+<DT><B>.LIBRARY</B><DD>
+Target is a library.
+<DT><B>.MKSARGS</B><DD>
+If running in an MSDOS environment then use MKS extended argument passing
+conventions to pass arguments to commands. Non-MSDOS
+environments ignore this attribute.
+<DT><B>.NOINFER</B><DD>
+Any target with this attribute set will not be subjected
+to transitive closure if it is inferred as a prerequisite
+of a target whose recipe and prerequisites are being inferred.
+(i.e. the inference algorithm will not use any prerequisite with this attribute
+set, as a target)
+If specified as '.NOINFER:' (ie. with no prerequisites or targets) then the
+effect is equivalent to specifying <B>-T</B> on the command line.
+<DT><B>.NOSTATE</B><DD>
+Any target with this attribute set will not have command line flag
+information stored in the state file if .KEEP_STATE has been enabled.
+<DT><B>.PHONY</B><DD>
+Any target with this attribute set will have its recipe executed
+each time the target is made even if a file matching the target name can
+be located. Any targets that have a .PHONY attributed target as a
+prerequisite will be made each time the .PHONY attributed prerequisite is
+made.
+<DT><B>.PRECIOUS</B><DD>
+Do not remove associated target under any circumstances.
+Set by default for any targets whose corresponding files exist in the file
+system prior to the execution of <B>dmake</B>.
+<DT><B>.PROLOG</B><DD>
+Insert shell prolog code when executing a group recipe associated with
+any target having this attribute set.
+<DT><B>.SEQUENTIAL</B><DD>
+Force a sequential make of the associated target's prerequisites.
+<DT><B>.SETDIR</B><DD>
+Change current working directory to specified directory when making the
+associated target. You must
+specify the directory at the time the attribute is specified. To do this
+simply give <I>.SETDIR=path</I> as the attribute. <I>path</I> is expanded and
+the result is used as the value of the directory to change to.
+If <I>path</I> contains <B>$$@</B> then the name of the target to be built is
+used in computing the path to change directory to.
+If path is surrounded by single quotes then path is not expanded, and is used
+literally as the directory name.
+If the <I>path</I> contains any `:' characters then the entire attribute string
+must be quoted using &quot;.
+If a target having this attribute set also has the .IGNORE
+attribute set then if the change to the specified directory fails it will be
+ignored, and no error message will be issued.
+<DT><B>.SILENT</B><DD>
+Do not echo the recipe lines when making any target with this attribute set,
+and do not issue any warnings.
+<DT><B>.SWAP</B><DD>
+Under MSDOS
+when making a target with this attribute set swap the <B>dmake</B> executable
+to disk prior to executing the recipe line. Also see the '%' recipe line
+flag defined in the RECIPES section.
+<DT><B>.SYMBOL</B><DD>
+Target is a library member and is an entry point into a module in the
+library. This attribute is used only when searching a library for a target.
+Targets of the form lib((entry)) have this attribute set automatically.
+<DT><B>.USESHELL</B><DD>
+Force each recipe line of a target to be executed using a shell.
+Specifying this attribute is equivalent to specifying the '+' character at the
+start of each line of a non-group recipe.
+<DT><B>.UPDATEALL</B><DD>
+Indicates that all the targets listed in this rule are updated by the
+execution of the accompanying recipe.
+A common example is the production of the
+<I>y.tab.c</I>
+
+and
+<I>y.tab.h</I>
+
+files by
+<B>yacc</B>
+
+when it is run on a grammar. Specifying .UPDATEALL in such a rule
+prevents the running of yacc twice, once for the y.tab.c file and once
+for the y.tab.h file. .UPDATEALL targets that are specified in a single rule
+are treated as a single target and all timestamps are updated whenever any
+target in the set is made. As a side-effect, <B>dmake</B> internally sorts
+such targets in ascending alphabetical order and the value of $@ is always
+the first target in the sorted set.
+</DL>
+<P>
+
+All attributes are user setable and except for .UPDATEALL and .MKSARGS
+may be used in one of two forms.
+The .MKSARGS attribute is restricted to use as a global attribute, and
+the use of the .UPDATEALL attribute is restricted to rules
+of the second form only.
+<P>
+ ATTRIBUTE_LIST : <I>targets</I>
+<P>
+assigns the attributes specified by ATTRIBUTE_LIST to each target in
+<I>targets</I>
+
+or
+<P>
+ <I>targets</I> ATTRIBUTE_LIST : ...
+<P>
+assigns the attributes specified by ATTRIBUTE_LIST to each target in
+<I>targets.</I>
+
+In the first form if
+<I>targets</I>
+
+is empty (ie. a NULL list), then the
+list of attributes will apply to all targets in the makefile
+(this is equivalent to the common Make construct of <I>&quot;.IGNORE :&quot;</I>
+but has been modified to the notion of an attribute instead of
+a special target).
+Not all of the attributes have global meaning.
+In particular, .LIBRARY, .NOSTATE, .PHONY, .SETDIR, .SYMBOL and .UPDATEALL
+have no assigned global meaning.
+<P>
+
+Any attribute may be used with any target, even with the special targets.
+Some combinations are useless (e.g. .INCLUDE .PRECIOUS: ... ),
+while others are useful (e.g. .INCLUDE .IGNORE : &quot;file.mk&quot; will not complain
+if file.mk cannot be found using the include file search rules,
+see the section on SPECIAL TARGETS for a description of .INCLUDE).
+If a specified attribute will not be used with the special target a warning
+is issued and the attribute is ignored.
+<A NAME="lbAJ">&nbsp;</A>
+<H2>MACROS</H2>
+
+<B>dmake</B>
+
+supports six forms of macro assignment.
+<P>
+<DL COMPACT>
+<DT><B>MACRO = LINE</B><DD>
+This is the most common and familiar form of macro assignment. It assigns
+LINE literally as the value of MACRO.
+Future expansions of MACRO recursively expand its value.
+<DT><B>MACRO *= LINE</B><DD>
+This form behaves exactly as the simple '=' form with the exception that if
+MACRO already has a value then the assignment is not performed.
+<DT><B>MACRO := LINE</B><DD>
+This form differs from the simple '=' form in that it expands LINE
+prior to assigning it as the value of MACRO.
+Future expansions of MACRO do not recursively expand its value.
+<DT><B>MACRO *:= LINE</B><DD>
+This form behaves exactly as the ':=' form with the exception that if
+MACRO already has a value then the assignment and expansion are not performed.
+<DT><B>MACRO += LINE</B><DD>
+This form of macro assignment allows macro values to grow. It takes the
+literal value of LINE and appends it to the previous value of MACRO separating
+the two by a single space.
+Future expansions of MACRO recursively expand its value.
+<DT><B>MACRO +:= LINE</B><DD>
+This form is similar to the '+=' form except that the value of LINE is expanded
+prior to being added to the value of MACRO.
+</DL>
+<P>
+
+Macro expressions specified on the command line allow the macro value
+to be redefined within the makefile only if the macro is defined using
+the '+=' and '+:=' operators. Other operators will define a macro that cannot
+be further modified.
+<P>
+
+Each of the preceeding macro assignment operators may be prefixed by <B>!</B>
+to indicate that the assignment should be forced and that no warnings should
+be issued. Thus, specifying <B>!</B> has the effect of silently forcing the
+specified macro assignment.
+<P>
+
+When <B>dmake</B> defines a non-environment macro it strips leading and
+trailing white space from the macro value.
+Macros imported from the environment via either the .IMPORT special
+target (see the SPECIAL TARGETS section), or the <B>-e</B>, or <B>-E</B> flags
+are an exception to this rule. Their values are
+always taken literally and white space is never stripped.
+In addition, named macros defined using the .IMPORT special target do
+not have their values expanded when they are used within a makefile.
+In contrast, environment macros that are imported
+due to the specification of the <B>-e</B> or <B>-E</B> flags
+are subject to expansion when used.
+<P>
+
+To specify a macro expansion
+enclose the name in () or {} and precede it with a dollar sign $.
+Thus $(TEST) represents an expansion of the macro variable named TEST.
+If TEST is
+defined then $(TEST) is replaced by its expanded value. If TEST is not
+defined then $(TEST) expands to the NULL string (this is equivalent to
+defining a macro as 'TEST=' ). A short form may be used for single character
+named macros. In this case the parentheses are optional, and $(I) is
+equivalent to $I.
+Macro expansion is recursive, hence, if the value string contains an expression
+representing a macro expansion, the expansion is performed. Circular macro
+expansions are detected and cause an error to be issued.
+<P>
+
+When defining a macro the given macro name is first expanded before being used
+to define the macro. Thus it is possible to define macros whose names
+depend on values of other macros. For example, suppose CWD is defined as
+<P>
+ CWD = $(PWD:b)
+<P>
+then the value of $(CWD) is the name of the current directory.
+This can be used to define macros specific to this directory, for
+example:
+<P>
+ _$(CWD).prt = list of files to print...
+<P>
+The actual name of the defined macro is a function of the current directory.
+A construct such as this is useful when processing a hierarchy of directories
+using .SETDIR attributed targets and a collection of small distributed
+makefile stubs.
+<P>
+
+Macro variables may be defined within the makefile, on the command
+line, or imported from the environment.
+<P>
+
+<B>dmake</B>
+
+supports several non-standard macro expansions:
+The first is of the form:
+<DL COMPACT><DT><DD>
+<DL COMPACT>
+<DT><I>$(macro_name:modifier_list:modifier_list:...)</I><DD>
+</DL>
+</DL>
+
+<P>
+
+where
+<I>modifier_list</I>
+
+may be a combination of:
+<DL COMPACT><DT><DD>
+<P>
+
+
+<PRE>
+
+<DL COMPACT>
+<DT>b or B<DD>- file (not including suffix) portion of path names
+
+<DT>d or D<DD>- directory portion of all path names
+
+<DT>e or E<DD>- suffix portion of path names
+
+<DT>f or F<DD>- file (including suffix) portion of path names
+
+<DT>i or I<DD>- inferred names of targets
+
+<DT>l or L<DD>- macro value in lower case
+
+<DT>u or U<DD>- macro value in upper case
+
+<DT>1<DD>- return the first white space separated token from value
+</DL>
+</DL>
+
+or a single one of:
+<DL COMPACT><DT><DD>
+
+<DL COMPACT>
+<DT>m or M<DD>- map escape codes found in macro to their ASCII value
+
+<DT>s or S<DD>- simple pattern substitution
+
+<DT>t or T<DD>- tokenization.
+
+<DT>^<DD>- prepend a prefix to each token
+
+<DT>+<DD>- append a suffix to each token
+
+</DL>
+</DL>
+</PRE>
+
+Thus if we have the example:
+<DL COMPACT><DT><DD>
+test = d1/d2/d3/a.out f.out d1/k.out
+</DL>
+
+The following macro expansions produce the values on the right of '->' after
+expansion.
+<DL COMPACT><DT><DD>
+<P>
+
+
+<PRE>
+
+<DL COMPACT>
+<DT>$(test:d)<DD>-> d1/d2/d3/ d1/
+
+<DT>$(test:b)<DD>-> a f k
+
+<DT>$(test:f)<DD>-> a.out f.out k.out
+
+<DT>${test:db}<DD>-> d1/d2/d3/a f d1/k
+
+<DT>${test:s/out/in/:f}<DD>-> a.in f.in k.in
+
+<DT>$(test:f:t+)<DD>-> a.out+f.out+k.out
+
+<DT>$(test:e)<DD>-> .out .out .out
+
+<DT>$(test:u)<DD>-> D1/D2/D3/A.OUT F.OUT D1/K.OUT
+
+<DT>$(test:1)<DD>-> d1/d2/d3/a.out
+</DL>
+</DL>
+</PRE>
+
+<P>
+
+If a token ends in a string composed from the value of the macro DIRBRKSTR
+(ie. ends in a directory separator string, e.g. '/' in UNIX) and you use the
+<B>:d</B> modifier then the expansion returns the directory name less the
+final directory separator string. Thus successive pairs of :d modifiers
+each remove a level of directory in the token string.
+<P>
+
+The map escape codes modifier changes the following escape codes \a =&gt; &lt;bel&gt;,
+\b =&gt; &lt;backspace&gt;, \f =&gt; &lt;formfeed&gt;, \n =&gt; &lt;nl&gt;, \r =&gt; &lt;cr&gt;,
+\t =&gt; &lt;tab&gt;, \v =&gt; &lt;vertical tab&gt;, \&quot; =&gt; &quot;, and \xxx =&gt; &lt;xxx&gt; where
+xxx is the octal representation of a character into the corresponding ASCII
+value.
+<P>
+
+The tokenization, prepend and append modifier may use the same escape codes
+that are supported by the map escape codes modifier in the string that is
+inserted, prepended or added by the respective macro modifier.
+These modifiers may quote this string to include otherwise problematic
+characters. E.g. spaces, colons and parentheses.
+<P>
+
+The tokenization modifier takes all white space separated tokens from the
+macro value and separates them by the separator string. Thus the
+expansion:
+<P>
+
+<DL COMPACT><DT><DD>
+<PRE>
+$(test:f:t&quot;+\n&quot;)
+</DL>
+produces:
+<DL COMPACT><DT><DD>a.out+
+f.out+
+k.out
+</PRE>
+
+</DL>
+
+<P>
+
+The prefix operator <B>^</B> takes all white space separated tokens from the
+macro value and prepends <I>string</I> to each.
+<P>
+
+<DL COMPACT><DT><DD>
+<PRE>
+$(test:f:^mydir/)
+</DL>
+produces:
+<DL COMPACT><DT><DD>mydir/a.out mydir/f.out mydir/k.out
+</PRE>
+
+</DL>
+
+<P>
+
+The suffix operator <B>+</B> takes all white space separated tokens from the
+macro value and appends <I>string</I> to each.
+<P>
+
+<DL COMPACT><DT><DD>
+<PRE>
+$(test:b:+.c)
+</DL>
+produces:
+<DL COMPACT><DT><DD>a.c f.c k.c
+</PRE>
+
+</DL>
+
+<P>
+
+The next non-standard form of macro expansion allows for recursive macros.
+It is possible to specify a $(<I>macro_name</I>) or ${<I>macro_name</I>} expansion
+where <I>macro_name</I> contains more $( ... ) or ${ ... } macro expansions
+itself.
+<P>
+
+For example $(CC$(_HOST)$(_COMPILER)) will first expand CC$(_HOST)$(_COMPILER)
+to get a result and use that result as the name of the macro to expand.
+This is useful for writing a makefile for more than one target
+environment. As an example consider the following hypothetical case.
+Suppose that _HOST and _COMPILER are imported from the environment
+and are set to represent the host machine type and the host compiler
+respectively.
+<DL COMPACT><DT><DD>
+<P>
+<PRE>
+CFLAGS_VAX_CC = -c -O # _HOST == &quot;_VAX&quot;, _COMPILER == &quot;_CC&quot;
+CFLAGS_PC_MSC = -c -ML # _HOST == &quot;_PC&quot;, _COMPILER == &quot;_MSC&quot;
+
+# redefine CFLAGS macro as:
+
+CFLAGS := $(CFLAGS$(_HOST)$(_COMPILER))
+</PRE>
+
+<P>
+</DL>
+
+This causes CFLAGS to take on a value that corresponds to the
+environment in which the make is being invoked.
+<P>
+
+The final non-standard macro expansion is of the form:
+<DL COMPACT><DT><DD>
+<P>
+string1{token_list}string2
+</DL>
+
+<P>
+
+where string1, string2 and token_list are expanded. After expansion,
+string1 is prepended to each token found in token_list and
+string2 is appended to each resulting token from the previous prepend.
+string1 and string2 are not delimited by white space
+whereas the tokens in token_list are.
+A null token in the token list
+is specified using &quot;&quot;.
+Thus using another example we have:
+<DL COMPACT><DT><DD>
+<P>
+
+
+<PRE>
+
+<DL COMPACT>
+<DT>test/{f1 f2}.o<DD>--&gt; test/f1.o test/f2.o
+
+<DT>test/ {f1 f2}.o<DD>--&gt; test/ f1.o f2.o
+
+<DT>test/{f1 f2} .o<DD>--&gt; test/f1 test/f2 .o
+
+<DT>test/{f1 }.o<DD>--&gt; test/f1.o test/.o
+
+
+<DT>and<DD>
+
+
+<DT>test/{d1 d2}/{f1 f2}.o --&gt; <DD>test/d1/f1.o test/d1/f2.o
+test/d2/f1.o test/d2/f2.o
+
+</DL>
+</DL>
+</PRE>
+
+This last expansion is activated only when the first characters of
+<I>token_list</I>
+appear immediately after the opening '{' with no intervening white space.
+The reason for this restriction is the following incompatibility with
+Bourne Shell recipes. The line
+<DL COMPACT><DT><DD>
+<P>
+{ echo hello;}
+<P>
+</DL>
+
+is valid /bin/sh syntax; while
+<DL COMPACT><DT><DD>
+<P>
+{echo hello;}
+<P>
+</DL>
+
+
+is not. Hence the latter triggers the enhanced macro expansion while the former
+causes it to be suppressed.
+See the SPECIAL MACROS section for a description of the special macros that
+<B>dmake</B> defines and understands.
+<A NAME="lbAK">&nbsp;</A>
+<H2>RULES AND TARGETS</H2>
+
+A makefile contains a series of entries that specify dependencies.
+Such entries are called <I>target/prerequisite</I> or <I>rule</I> definitions.
+Each rule definition
+is optionally followed by a set of lines that provide a recipe for updating
+any targets defined by the rule.
+Whenever
+<B>dmake</B>
+
+attempts to bring a target up to date and an explicit recipe is provided with
+a rule defining the target, that recipe is used to update the
+target. A rule definition begins with a line having the following syntax:
+<P>
+<DL COMPACT><DT><DD>
+<PRE>
+<I>&lt;targets&gt;</I> [<I>&lt;attributes&gt;</I>] <I>&lt;ruleop&gt;</I> [<I>&lt;prerequisites&gt;</I>] [;<I>&lt;recipe&gt;</I>]
+</PRE>
+
+</DL>
+
+<P>
+<I>targets</I>
+
+is a non-empty list of targets. If the target is a
+special target (see SPECIAL TARGETS section below) then it must appear alone
+on the rule line. For example:
+<P>
+<DL COMPACT><DT><DD>
+.IMPORT .ERROR : ...
+</DL>
+
+<P>
+is not allowed since both .IMPORT and .ERROR are special targets.
+Special targets are not used in the construction of the dependency graph and
+will not be made.
+<P>
+
+<I>attributes</I>
+
+is a possibly empty list of attributes. Any attribute defined in the
+ATTRIBUTES section above may be specified. All attributes will be applied to
+the list of named targets in the rule definition. No other targets will
+be affected.
+<P>
+<DL COMPACT>
+<DT>NOTE:<DD>
+As stated earlier,
+if both the target list and prerequisite list are empty but the attributes
+list is not, then the specified attributes affect all targets in the makefile.
+<P>
+</DL>
+<P>
+
+<I>ruleop</I>
+
+is a separator which is used to identify the targets from the prerequisites.
+Optionally it also provides a facility for modifying the way in which
+<B>dmake</B>
+
+handles the making of the associated targets.
+In its simplest form the operator is a single ':', and need not be separated
+by white space from its neighboring tokens. It may additionally be followed
+by any of the modifiers { !, ^, -, :, | }, where:
+<P>
+<DL COMPACT>
+<DT><B>!</B><DD>
+says execute the recipe for the associated targets once for each out of date
+prerequisite. Ordinarily the recipe is executed
+once for all out of date prerequisites at the same time.
+<DT><B>^</B><DD>
+says to insert the specified prerequisites, if any, before any
+other prerequisites already associated with the specified targets.
+In general, it is not useful to specify ^ with an empty
+list of prerequisites.
+<DT><B>-</B><DD>
+says to clear the previous list of prerequisites before adding
+the new prerequisites. Thus,
+<P>
+ .SUFFIXES :
+<BR>
+
+ .SUFFIXES : .a .b
+<P>
+can be replaced by
+<P>
+ .SUFFIXES :- .a .b
+<P>
+however the old form still works as expected. NOTE: .SUFFIXES is ignored by
+<B>dmake</B>
+
+it is used here simply as an example.
+<DT><B>:</B><DD>
+When the rule operator is not modified by a second ':'
+only one set of rules may be specified for making a target.
+Multiple definitions may be used to add to the
+list of prerequisites that a target depends on.
+However, if a target is multiply defined
+only one definition may specify a recipe
+for making the target.
+<P>
+When a target's rule operator is modified by a second ':'
+(:: for example) then this definition may not be the only
+definition with a recipe for the target. There may be other :: target
+definition lines that specify a different set of prerequisites with a
+different recipe for updating the target.
+Any such target is made if any of the definitions
+find it to be out of date
+with respect to the related prerequisites
+and the corresponding recipe is used to update the
+target. By definition all '::' recipes that are found to be out of date for
+are executed.
+<P>
+In the following simple example, each rule has a `::' <I>ruleop</I>. In such an
+operator we call the first `:' the operator, and the second `:' the modifier.
+<P>
+<PRE>
+a.o :: a.c b.h
+ first recipe for making a.o
+
+a.o :: a.y b.h
+ second recipe for making a.o
+</PRE>
+
+<P>
+If a.o is found to be out of date with respect to a.c then the first recipe
+is used to make a.o. If it is found out of date with respect to a.y then
+the second recipe is used. If a.o is out of date with respect to
+b.h then both recipes are invoked to make a.o.
+In the last case the order of invocation corresponds to the order in which the
+rule definitions appear in the makefile.
+<DT><B>|</B><DD>
+Is defined only for PERCENT rule target definitions. When specified it
+indicates that the following construct should be parsed using the old
+semantinc meaning:
+<P>
+<PRE>
+%.o :| %.c %.r %.f ; some rule
+
+is equivalent to:
+
+%.o : %.c ; some rule
+%.o : %.r ; some rule
+%.o : %.f ; some rule
+</PRE>
+
+</DL>
+<P>
+
+Targets defined using a single `:' operator
+with a recipe may be redefined again with a new recipe by using a
+`:' operator with a `:' modifier.
+This is equivalent to a target having been
+initially defined with a rule using a `:' modifier.
+Once a target is defined using a `:'
+modifier it may not be defined again with a recipe using only the `:' operator
+with no `:' modifier. In both cases the use of a `:' modifier creates a new
+list of prerequisites and makes it the current prerequisite list for the target.
+The `:' operator with no recipe always modifies the current list
+of prerequisites.
+Thus assuming each of the following definitions has a recipe attached, then:
+<DL COMPACT><DT><DD>
+<P>
+<PRE>
+joe : fred ... (1)
+joe :: more ... (2)
+
+and
+
+joe :: fred ... (3)
+joe :: more ... (4)
+
+</PRE>
+
+</DL>
+
+are legal and mean: add the recipe associated with (2), or (4) to the set
+of recipes for joe, placing them after existing recipes for
+making joe.
+The constructs:
+<DL COMPACT><DT><DD>
+<P>
+<PRE>
+joe :: fred ... (5)
+joe : more ... (6)
+
+and
+
+joe : fred ... (7)
+joe : more ... (8)
+
+</PRE>
+
+</DL>
+
+are errors since we have two sets of perfectly good recipes for
+making the target.
+<P>
+
+<I>prerequisites</I>
+
+is a possibly empty list of targets that must be brought up to date before
+making the current target.
+<P>
+
+<I>recipe</I>
+
+is a short form and allows the user to specify short rule definitions
+on a single line.
+It is taken to be the first recipe line in a larger recipe
+if additional lines follow the rule definition.
+If the semi-colon is present but the recipe line is empty (ie. null string)
+then it is taken
+to be an empty rule. Any target so defined causes the
+<I>Don't know how to make ...</I>
+
+error message to be suppressed when
+<B>dmake</B>
+
+tries to make the target and fails.
+This silence is maintained for rules that are terminated
+by a semicolon and have no following recipe lines, for targets listed on the
+command line, for the first target found in the makefile, and for any target
+having no recipe but containing a list of prerequisites (see the COMPATIBILITY
+section for an exception to this rule if the AUGMAKE (<B>-A</B>) flag
+was specified.
+<A NAME="lbAL">&nbsp;</A>
+<H2>RECIPES</H2>
+
+The traditional format used by most versions of Make defines the recipe
+lines as arbitrary strings that may contain macro expansions. They
+follow a rule definition line and may be spaced
+apart by comment or blank lines.
+The list of recipe lines defining the recipe is terminated by a new target
+definition, a macro definition, or end-of-file.
+Each recipe line
+<B>MUST</B>
+
+begin with a <B>&lt;TAB&gt;</B> character which
+may optionally be followed with one or all
+of the characters
+<I>'@%+-'</I>.
+
+The
+<I>'-'</I>
+
+indicates that non-zero exit values (ie. errors)
+are to be ignored when this recipe line is executed, the
+<I>'+'</I>
+
+indicates that the current recipe line is to be executed using the shell, the
+<I>'%'</I>
+
+indicates that
+<B>dmake</B>
+
+should swap itself out to secondary storage (MSDOS only) before running the
+recipe and the
+<I>'@'</I>
+
+indicates that the recipe line should NOT be echoed to the terminal prior to
+being executed. Each switch is off by default
+(ie. by default, errors are significant, commands are echoed, no swapping is
+done and a shell is
+used only if the recipe line contains a character found in the value of the
+SHELLMETAS macro).
+Global settings activated via command line options or special attribute or
+target names may also affect these settings.
+An example recipe:
+<P>
+<DL COMPACT><DT><DD>
+<PRE>
+target :
+ first recipe line
+ second recipe line, executed independent of first.
+ @a recipe line that is not echoed
+ -and one that has errors ignored
+ %and one that causes dmake to swap out
+ +and one that is executed using a shell.
+</PRE>
+
+</DL>
+
+<P>
+
+The second and new format of the recipe block begins the block with the
+character '[' (the open group character) in the last non-white space
+position of a line, and terminates the
+block with the character ']' (the close group character)
+in the first non-white space position of a line.
+In this form each recipe line need not have a leading TAB. This is
+called a recipe group. Groups so defined are fed intact as a single
+unit to a shell for execution whenever the corresponding target needs to
+be updated. If the open group character '[' is preceded
+by one or all of -, @ or %
+then they apply to the entire group in the same way that they
+apply to single recipe lines. You may also specify '+' but it is
+redundant as a shell is already being used to run the recipe.
+See the MAKING TARGETS section for a description of how
+<B>dmake</B>
+
+invokes recipes.
+Here is an example of a group recipe:
+<P>
+<DL COMPACT><DT><DD>
+<PRE>
+target :
+[
+ first recipe line
+ second recipe line
+ tall of these recipe lines are fed to a
+ single copy of a shell for execution.
+]
+</PRE>
+
+</DL>
+
+<P>
+<A NAME="lbAM">&nbsp;</A>
+<H2>TEXT DIVERSIONS</H2>
+
+<B>dmake</B>
+
+supports the notion of text diversions.
+If a recipe line contains the macro expression
+<DL COMPACT><DT><DD>
+<P>
+$(mktmp[,[<I>file</I>][,<I>text</I>]] <I>data</I>)
+<P>
+</DL>
+
+then all text contained in the <I>data</I> expression is expanded and
+is written to a temporary file. The <I>data</I> in the file will always
+be terminated from a new line character. The return
+value of the macro is the name of the temporary file unless the <I>text</I>
+parameter is defined. In this case the return value is the expanded value
+of <I>text</I>.
+<P>
+
+<I>data</I>
+
+can be any text and must be separated from the 'mktmp' portion of the
+macro name by white-space. The only restriction on the data text is that
+it must contain a balanced number of parentheses of the same kind as are
+used to initiate the $(mktmp ...) expression. For example:
+<DL COMPACT><DT><DD>
+<P>
+$(mktmp $(XXX))
+<P>
+</DL>
+
+is legal and works as expected, but:
+<DL COMPACT><DT><DD>
+<P>
+$(mktmp text (to dump to file)
+<P>
+</DL>
+
+is not legal. You can achieve what you wish by either defining a macro that
+expands to '(' or by using {} in the macro expression; like this:
+<DL COMPACT><DT><DD>
+<P>
+${mktmp text (to dump to file}
+<P>
+</DL>
+
+Since the temporary file is opened when the
+macro containing the text diversion expression is expanded, diversions may
+be nested and any diversions that are created as part of ':=' macro
+expansions persist for the duration of the
+<B>dmake</B>
+
+run.
+If the <I>data</I> text is to contain new lines the map escape codes macro
+expasion can be used. For example the expression:
+<DL COMPACT><DT><DD>
+<P>
+<PRE>
+mytext:=this is a\ntest of the text diversion
+all:
+ cat $(mktmp $(mytext:m))
+</PRE>
+
+<P>
+</DL>
+
+is replaced by:
+<DL COMPACT><DT><DD>
+<P>
+cat /tmp/mk12294AA
+<P>
+</DL>
+
+where the temporary file contains two lines both of which are terminated
+by a new-line.
+A second more illustrative example generates a response file to an MSDOS
+link command:
+<DL COMPACT><DT><DD>
+<P>
+<PRE>
+OBJ = fred.obj mary.obj joe.obj
+all : $(OBJ)
+ link @$(mktmp $(^:t&quot;+\n&quot;))
+</PRE>
+
+<P>
+</DL>
+
+The result of making `all' in the second example is the command:
+<DL COMPACT><DT><DD>
+<P>
+link @/tmp/mk02394AA
+<P>
+</DL>
+
+where the temporary file contains:
+<DL COMPACT><DT><DD>
+<P>
+<PRE>
+fred.obj+
+mary.obj+
+joe.obj
+</PRE>
+
+<P>
+</DL>
+
+The last line of the file is terminated by a new-line which is always
+inserted at the end of the <I>data</I> string.
+<P>
+
+If the optional <I>file</I> specifier is present then its expanded value
+is the name of the temporary file to create. An example that would be useful
+for MSDOS users with a Turbo-C compiler
+<DL COMPACT><DT><DD>
+<P>
+$(mktmp,turboc.cfg $(CFLAGS))
+<P>
+</DL>
+
+will place the contents of CFLAGS into a local <I>turboc.cfg</I> file.
+The second optional argument, <I>text</I>, if present alters the name
+of the value returned by the $(mktmp ...) macro.
+<P>
+
+Under MS-DOS text diversions may be a problem. Many DOS tools require
+that path names which contain directories use the \ character to delimit
+the directories. Some users however wish to use the '/' to delimit pathnames
+and use environments that allow them to do so.
+The macro USESHELL is set to &quot;yes&quot; if the
+current recipe is forced to use a shell via the .USESHELL or '+' directives,
+otherwise its value is &quot;no&quot;.
+The
+<B>dmake</B>
+
+startup files define the macro DIVFILE whose value is either the
+value of TMPFILE or the value of TMPFILE edited to replace any '/' characters
+to the appropriate value based on the current shell and whether it will be
+used to execute the recipe.
+<P>
+
+Previous versions of
+<B>dmake</B>
+
+defined text diversions using &lt;+, +&gt; strings,
+where &lt;+ started a text diversion and +&gt; terminated one.
+<B>dmake</B>
+
+is backward compatible with this construct only
+if the &lt;+ and +&gt; appear literally
+on the same recipe line or in the same macro value string. In such instances
+the expression:
+<P>
+ &lt;+data+&gt;
+<P>
+is mapped to:
+<P>
+ $(mktmp data)
+<P>
+which is fully output compatible with the earlier construct. &lt;+, +&gt;
+constructs whose text spans multiple lines must be converted by hand to use
+$(mktmp ...).
+<P>
+
+If the environment variable TMPDIR is defined then the
+temporary file is placed into the directory specified by that variable.
+A makefile can modify the location of temporary files by
+defining a macro named TMPDIR and exporting it using the .EXPORT special
+target.
+<A NAME="lbAN">&nbsp;</A>
+<H2>SPECIAL TARGETS</H2>
+
+This section describes the special targets that are recognized by <B>dmake</B>.
+Some are affected by attributes and others are not.
+<DL COMPACT>
+<DT><B>.ERROR</B><DD>
+If defined then the recipe associated with this target is executed
+whenever an error condition is detected by <B>dmake</B>. All attributes that
+can be used with any other target may be used with this target. Any
+prerequisites of this target will be brought up to date during its processing.
+NOTE: errors will be ignored while making this target, in extreme cases this
+may cause some problems.
+<DT><B>.EXIT</B><DD>
+If this target is encountered while parsing a makefile then the parsing of the
+makefile is immediately terminated at that point.
+<DT><B>.EXPORT</B><DD>
+All prerequisites associated with this target are assumed to
+correspond to macro names and they and their values
+are exported to the environment as environment strings at the point in
+the makefile at which this target appears.
+Any attributes specified with this target are ignored.
+Only macros which have been assigned a value in the makefile prior to the
+export directive are exported, macros as yet undefined
+or macros whose value contains any of the characters &quot;+=:*&quot;
+are not exported.
+<P>
+Note that macros that are not expanded during the macro assignment and contain
+other macros will be written into the environment containing these other
+macros in the form of $(macroname).
+<DT><B>.IMPORT</B><DD>
+Prerequisite names specified for this target are searched for in the
+environment and defined as macros with their value taken from the environment.
+If the special name <B>.EVERYTHING</B> is used as a prerequisite name then
+all environment variables defined in the environment are imported.
+The functionality of the <B>-E</B> flag can be forced by placing the construct
+<I>.IMPORT : .EVERYTHING</I> at the start of a makefile. Similarly, by
+placing the construct at the end, one can emulate the effect of the <B>-e</B>
+command line flag.
+If a prerequisite name cannot be found in the environment
+an error message is issued.
+.IMPORT accepts the .IGNORE attribute. When given, it causes <B>dmake</B>
+to ignore the above error.
+See the MACROS section for a description of the processing of imported macro
+values.
+<DT><B>.INCLUDE</B><DD>
+Parse another makefile just as if it had been located at the point of the
+.INCLUDE in the current makefile.
+The list of prerequisites gives the list of
+makefiles to try to read. If the list contains multiple makefiles then they
+are read in order from left to right. The following search rules are used
+when trying to locate the file. If the filename is surrounded by &quot; or just
+by itself then it is searched for in the current directory. If it is not
+found it is then searched for in each of the directories specified
+as prerequisites of the .INCLUDEDIRS special target.
+If the file name is surrounded by &lt; and &gt;, (ie.
+&lt;my_spiffy_new_makefile&gt;) then it is searched for only in the directories
+given by the .INCLUDEDIRS special target. In both cases if the file name is a
+fully qualified name starting at the root of the file system then it is only
+searched for once, and the .INCLUDEDIRS list is ignored.
+If .INCLUDE fails to find the file it invokes the inference engine to
+try to infer and hence make the file to be included. In this way the
+file can be checked out of an RCS repository for example.
+.INCLUDE accepts
+the .IGNORE, .SETDIR, and .NOINFER attributes.
+If the .IGNORE attribute is given and the file
+cannot be found then <B>dmake</B> continues processing,
+otherwise an error message is generated.
+If the .NOINFER attribute is given and the file
+cannot be found then <B>dmake</B> will not attempt to
+<I>infer and make</I> the file.
+The .SETDIR attribute causes
+<B>dmake</B>
+
+to change directories to the specified directory prior to attempting the
+include operation. If all fails <B>dmake</B> attempts to <I>make</I> the file
+to be included. If making the file fails then <B>dmake</B> terminates unless
+the .INCLUDE directive also specified the .IGNORE attribute.
+If .FIRST is specified along with .INCLUDE then <B>dmake</B> attempts to
+include each named prerequisite and will terminate the inclusion with the
+first prerequisite that results in a successful inclusion.
+<DT><B>.INCLUDEDIRS</B><DD>
+The list of prerequisites specified for this target defines the set of
+directories to search when trying to include a makefile.
+<DT><B>.KEEP_STATE</B><DD>
+This special target is a synonym for the macro definition
+<P>
+ .KEEP_STATE := _state.mk
+<P>
+It's effect is to turn on STATE keeping and to define <I>_state.mk</I>
+as the state file.
+<DT><B>.MAKEFILES</B><DD>
+The list of prerequisites is the set of files to try to read as the default
+makefile. By default this target is defined as:
+<P>
+ .MAKEFILES : makefile.mk Makefile makefile
+<P>
+<DT><B>.SOURCE</B><DD>
+The prerequisite list of this target defines a set of directories to check
+when trying to locate a target file name. See the section on BINDING of
+targets for more information.
+<DT><B>.SOURCE.suff</B><DD>
+The same as .SOURCE, except that the .SOURCE.suff list is searched first when
+trying to locate a file matching the a target whose name ends in the suffix
+.suff.
+<DT><B>.REMOVE</B><DD>
+The recipe of this target is used whenever <B>dmake</B> needs to remove
+intermediate targets that were made but do not need to be kept around.
+Such targets result from the application of transitive closure on the
+dependency graph.
+</DL>
+<P>
+
+In addition to the special targets above,
+several other forms of targets are recognized and are considered special,
+their exact form and use is defined in the sections that follow.
+<A NAME="lbAO">&nbsp;</A>
+<H2>SPECIAL MACROS</H2>
+
+<B>dmake</B>
+
+defines a number of special macros. They are divided into three classes:
+control macros, run-time macros, and function macros.
+The control macros are used by
+<B>dmake</B>
+
+to configure its actions, and are the preferred method of doing so.
+In the case when a control macro has the same function as a special
+target or attribute they share the same name as the special target or
+attribute.
+The run-time macros are defined when
+<B>dmake</B>
+
+makes targets and may be used by the user inside recipes.
+The function macros provide higher level functions dealing with macro
+expansion and diversion file processing.
+<A NAME="lbAP">&nbsp;</A>
+<H2>CONTROL MACROS</H2>
+
+To use the control macros simply assign them a value just like any other
+macro. The control macros are divided into three groups:
+string valued macros, character valued macros, and boolean valued macros.
+<P>
+
+The following are all of the string valued macros.
+This list is divided into two groups. The first group gives the string
+valued macros that are defined internally and cannot be directly set by the
+user.
+<DL COMPACT>
+<DT><B>ABSMAKECMD</B><DD>
+<B>Warning!</B> This macro's value is differently defined for a native Windows
+dmake executable (compiled with MS Visual C++ or MinGW) and dmake for other
+operating systems or build with other compilers.
+<P>
+In the first case its value is the absolute filename of the executable of
+the current dmake process, otherwise it is defined as the NULL string.
+<DT><B>INCDEPTH</B><DD>
+This macro's value is a string of digits representing
+the current depth of makefile inclusion.
+In the first makefile level this value is zero.
+<DT><B>MFLAGS</B><DD>
+Is the list of flags
+that were given on the command line including a leading switch character.
+The -f flag is not included in this list.
+<DT><B>MAKECMD</B><DD>
+Is the name with which <B>dmake</B> was invoked.
+<DT><B>MAKEDIR</B><DD>
+Is the full path to the initial directory in which
+<B>dmake</B>
+
+was invoked.
+<DT><B>MAKEFILE</B><DD>
+Contains the string &quot;-f <I>makefile</I>&quot; where, <I>makefile</I> is the name
+of initial user makefile that was first read.
+<DT><B>MAKEFLAGS</B><DD>
+Is the same as $(MFLAGS) but has no leading switch
+character. (ie. MFLAGS = -$(MAKEFLAGS))
+<DT><B>MAKEMACROS</B><DD>
+Contains the complete list of macro expressions that were specified on the
+command line.
+<DT><B>MAKETARGETS</B><DD>
+Contains the name(s) of the target(s), if any, that were
+specified on the command line.
+<DT><B>MAKEVERSION</B><DD>
+Contains a string indicating the current <B>dmake</B> version number.
+<DT><B>MAXPROCESSLIMIT</B><DD>
+Is a numeric string representing the maximum number of processes that
+<B>dmake</B> can use when making targets using parallel mode.
+<DT><B>NULL</B><DD>
+Is permanently defined to be the NULL string.
+This is useful when comparing a conditional expression to an NULL value.
+<DT><B>PWD</B><DD>
+Is the full path to the
+current directory in which make is executing.
+<DT><B>SPACECHAR</B><DD>
+Is permanently defined to contain one space character. This is useful
+when using space characters in function macros, e.g. subst, that
+otherwise would get deleted (leading/trailing spaces) or for using
+spaces in function macro parameters.
+<DT><B>TMPFILE</B><DD>
+Is set to the name of the most recent temporary file opened by <B>dmake</B>.
+Temporary files are used for text diversions and for group recipe processing.
+<DT><B>TMD</B><DD>
+Stands for &quot;To Make Dir&quot;, and
+is the path from the present directory (value of $(PWD)) to the directory
+that <B>dmake</B> was started up in (value of $(MAKEDIR)). If the present
+directory is the directory that <B>dmake</B> was started up in TMD will be
+set to the relative path &quot;.&quot;. This allows to create valid paths by prepending
+$(TMD)$(DIRSEPSTR) to a relative path.
+This macro is modified when .SETDIR attributes are processed.
+<DT><B>USESHELL</B><DD>
+The value of this macro is set to &quot;yes&quot; if the current recipe is forced to
+use a shell for its execution via the .USESHELL or '+' directives, its value
+is &quot;no&quot; otherwise.
+<P>
+</DL>
+<P>
+
+The second group of string valued macros control
+<B>dmake</B>
+
+behavior and may be set by the user.
+<DL COMPACT>
+<DT><B>.DIRCACHE</B><DD>
+If set to &quot;yes&quot; enables the directory cache (this is the default). If set to
+&quot;no&quot; disables the directory cache (equivalent to -d command-line flag).
+<DT><B>.DIRCACHERESPCASE</B><DD>
+If set to &quot;yes&quot; causes the directory cache, if enabled, to respect
+file case, if set to &quot;no&quot; facilities of the native OS are used to
+match file case.
+<DT><B>NAMEMAX</B><DD>
+Defines the maximum length of a filename component. The value of the variable
+is initialized at startup to the value of the compiled macro NAME_MAX. On
+some systems the value of NAME_MAX is too short by default. Setting a new
+value for NAMEMAX will override the compiled value.
+<DT><B>.NOTABS</B><DD>
+When set to &quot;yes&quot; enables the use of spaces as well as &lt;tabs&gt; to begin
+recipe lines.
+By default a non-group recipe is terminated by a line without any leading
+white-space or by a line not beggining with a &lt;tab&gt; character.
+Enabling this mode modifies the first condition of
+the above termination rule to terminate a
+non-group recipe with a line that contains only white-space.
+This mode does not effect the parsing of group recipes bracketed by [].
+<DT><B>AUGMAKE</B><DD>
+If set to &quot;yes&quot; value will enable the transformation of special
+meta targets to support special AUGMAKE inferences (See the COMPATIBILITY
+section).
+<DT><B>DIRBRKSTR</B><DD>
+Contains the string of chars used to terminate
+the name of a directory in a pathname.
+Under UNIX its value is &quot;/&quot;, under MSDOS its value is &quot;/\:&quot;.
+<DT><B>DIRSEPSTR</B><DD>
+Contains the string that is used to separate directory components when
+path names are constructed. It is defined with a default value at startup.
+<DT><B>DIVFILE</B><DD>
+Is defined in the startup file and gives the name that should be returned for
+the diversion file name when used in
+$(mktmp ...) expansions, see the TEXT DIVERSION section for details.
+<DT><B>DYNAMICNESTINGLEVEL</B><DD>
+Specifies the maximum number of recursive dynamic macro expansions. Its
+initial value is 100.
+<DT><B>.KEEP_STATE</B><DD>
+Assigning this macro a value tells
+<B>dmake</B>
+
+the name of the state file to use and turns on the keeping of state
+information for any targets that are brought up to date by the make.
+<DT><B>GROUPFLAGS</B><DD>
+This macro gives the set of flags to pass to the shell when
+invoking it to execute a group recipe. The value of the macro is the
+list of flags with a leading switch indicator. (ie. `-' under UNIX)
+<DT><B>GROUPSHELL</B><DD>
+This macro defines the full
+path to the executable image to be used as the shell when
+processing group recipes. This macro must be defined if group recipes are
+used. It is assigned a default value in the startup makefile. Under UNIX
+this value is /bin/sh.
+<DT><B>GROUPSUFFIX</B><DD>
+If defined, this macro gives the string to use as a suffix
+when creating group recipe files to be handed to the command interpreter.
+For example, if it is defined as .sh, then all
+temporary files created by <B>dmake</B> will end in the suffix .sh.
+Under MSDOS if you are using command.com as your GROUPSHELL, then this suffix
+must be set to .bat in order for group recipes to function correctly.
+The setting of GROUPSUFFIX and GROUPSHELL is done automatically for
+command.com in the startup.mk files.
+<DT><B>MAKE</B><DD>
+Is defined in the startup file by default.
+Initially this macro is defined to have the value &quot;$(MAKECMD) $(MFLAGS)&quot;.
+The string $(MAKE) is recognized when using the -n switch.
+<DT><B>MAKESTARTUP</B><DD>
+This macro defines the full path to the initial startup
+makefile. Use the <B>-V</B> command line option to discover its initial
+value.
+<DT><B>MAXLINELENGTH</B><DD>
+This macro defines the maximum size of a single line of
+makefile input text. The size is specified as a number, the default value
+is defined internally and is shown via the <B>-V</B> option.
+A buffer of this size plus 2 is allocated for reading makefile text. The
+buffer is freed before any targets are made, thereby allowing files containing
+long input lines to be processed without consuming memory during the actual
+make.
+This macro can only be used to extend the line length beyond it's default
+minimum value.
+<DT><B>MAXPROCESS</B><DD>
+Specify the maximum number of child processes to use when making targets.
+The default value of this macro is &quot;1&quot; and its value cannot exceed the value
+of the macro MAXPROCESSLIMIT. Setting the value of MAXPROCESS on the command
+line or in the makefile is equivalent to supplying a corresponding value to
+the -P flag on the command line.
+<DT><B>PREP</B><DD>
+This macro defines the number of iterations to be expanded
+automatically when processing % rule definitions of the form:
+<P>
+% : %.suff
+<P>
+See the sections on PERCENT(%) RULES for details on how PREP is used.
+<DT><B>SHELL</B><DD>
+This macro defines the full path to the executable
+image to be used as the shell when
+processing single line recipes. This macro must be defined if recipes
+requiring the shell for execution are to be used.
+It is assigned a default value in the startup makefile.
+Under UNIX this value is /bin/sh.
+<DT><B>SHELLFLAGS</B><DD>
+This macro gives the set of flags to pass to the shell when
+invoking it to execute a single line recipe. The value of the macro is the
+list of flags with a leading switch indicator. (ie. `-' under UNIX)
+<DT><B>SHELLMETAS</B><DD>
+Each time
+<B>dmake</B>
+
+executes a single recipe line (not a group recipe) the line is
+searched for any occurrence of a character defined in the value of SHELLMETAS.
+If such a character is found the recipe line is defined to require a shell
+to ensure its correct execution. In such instances
+a shell is used to invoke the recipe line.
+If no match is found the recipe line is executed without the use of a shell.
+<P>
+</DL>
+<P>
+
+There is only one character valued macro defined by <B>dmake</B>:
+<B>SWITCHAR</B> contains the switch character used
+to introduce options on command lines. For UNIX its value is `-', and for
+MSDOS its value may be `/' or `-'.
+The macro is internally defined and is not user setable.
+The MSDOS version of <B>dmake</B> attempts to first extract SWITCHAR from an
+environment variable of the same name. If that fails it then attempts to
+use the undocumented getswitchar system call, and returns the result of
+that. Under MSDOS version 4.0 you must set the value of the environment
+macro SWITCHAR to '/' to obtain predictable behavior.
+<P>
+
+All boolean macros currently understood by
+<B>dmake</B>
+
+correspond directly to the previously defined attributes.
+These macros provide
+a second way to apply global attributes, and represent the
+preferred method of doing so. They are used by assigning them a
+value. If the value is not a NULL string then the boolean condition
+is set to on.
+If the value is a NULL string then the condition is set to off.
+There are five conditions defined and they correspond directly to the
+attributes of the same name. Their meanings are defined in the ATTRIBUTES
+section above.
+The macros are:
+<B>.EPILOG</B>,
+<B>.IGNORE</B>,
+<B>.MKSARGS</B>,
+<B>.NOINFER</B>,
+<B>.PRECIOUS</B>,
+<B>.PROLOG</B>,
+<B>.SEQUENTIAL</B>,
+<B>.SILENT</B>,
+<B>.SWAP</B>, and
+<B>.USESHELL</B>.
+Assigning any of these a non NULL value will globally set
+the corresponding attribute to on.
+<A NAME="lbAQ">&nbsp;</A>
+<H2>RUNTIME MACROS</H2>
+
+These macros are defined
+when <B>dmake</B> is making targets, and may take on different values for each
+target. <B>$@</B> is defined to be the full target name, <B>$?</B> is the
+list of all out of date prerequisites, <B>$&amp;</B> is the list of all
+prerequisites, <B>$&gt;</B> is the name of the library if the current target is a
+library member, and
+<B>$&lt;</B> is the list of prerequisites specified in the current rule.
+If the current target had a recipe inferred then <B>$&lt;</B> is the name of the
+inferred prerequisite even if the target had a list of prerequisites supplied
+using an explicit rule that did not provide a recipe. In such situations
+<B>$&amp;</B> gives the full list of prerequisites.
+<P>
+
+<B>$*</B> is defined as
+<B>$(@:db)</B> when making targets with explicit recipes and is defined as the
+value of % when making targets whose recipe is the result of an inference.
+In the first case <B>$*</B> is the target name with no suffix,
+and in the second case, is the value of the matched % pattern from
+the associated %-rule.
+<B>$^</B> expands to the set of out of date prerequisites taken from the
+current value of <B>$&lt;</B>.
+In addition to these,
+<B>$$</B> expands to $, <B>{{</B> expands to {, <B>}}</B> expands to }, and the
+strings <B>&lt;+</B> and <B>+&gt;</B> are recognized
+as respectively starting and terminating a text diversion when they appear
+literally together in the same input line.
+<P>
+
+The difference between $? and $^ can best be illustrated by an example,
+consider:
+<DL COMPACT><DT><DD>
+<P>
+<PRE>
+fred.out : joe amy hello
+ rules for making fred
+
+fred.out : my.c your.h his.h her.h # more prerequisites
+</PRE>
+
+<P>
+</DL>
+
+Assume joe, amy, and my.c are newer then fred.out. When
+<B>dmake</B>
+
+executes the recipe for making fred.out the values of the following macros
+will be:
+<DL COMPACT><DT><DD>
+<P>
+<PRE>
+
+
+<DL COMPACT>
+<DT>$@<DD>--&gt; fred.out
+
+<DT>$*<DD>--&gt; fred
+
+<DT>$?<DD>--&gt; joe amy my.c # note output of $? vs $^
+
+<DT>$^<DD>--&gt; joe amy
+
+<DT>$&lt;<DD>--&gt; joe amy hello
+
+<DT>$&amp;<DD>--&gt; joe amy hello my.c your.h his.h her.h
+</PRE>
+
+<P>
+</DL>
+</DL>
+
+<A NAME="lbAR">&nbsp;</A>
+<H2>FUNCTION MACROS</H2>
+
+<B>dmake</B>
+
+supports a full set of functional macros. One of these, the $(mktmp ...)
+macro, is discussed in detail in the TEXT DIVERSION section and is not
+covered here.
+<P>
+
+Note that some of these macros take comma separated parameters
+but that these parameters must not contain literal whitespaces. Whitespaces
+in macros used in these parameters are allowed.
+<DL COMPACT><DT><DD>
+<P>
+<DL COMPACT>
+<DT>$(<B>and</B> <B>macroterm ...</B>)<DD>
+expands each <B>macroterm</B> in turn until there are no more or one of
+them returns an empty string. If all expand to non-empty strings the
+macro returs the string &quot;t&quot; otherwise it returns an empty string.
+<P>
+<DT>$(<B>assign</B> <B>expression</B>)<DD>
+Causes <I>expression</I> to be parsed as a macro assignment expression and results
+in the specified assignment being made. An error is issued if the assignment
+is not syntatically correct. <I>expression</I> may contain white space. This is
+in effect a dynamic macro assignment facility and may appear anywhere any
+other macro may appear. The result of the expanding a dynamic macro
+assignment expression is the name of the macro that was assigned and $(NULL)
+if the <I>expression</I> is not a valid macro assignment expression.
+Some examples are:
+<DL COMPACT><DT><DD>
+<P>
+<PRE>
+$(assign foo := fred)
+$(assign $(ind_macro_name) +:= $(morejunk))
+</PRE>
+
+</DL>
+
+<DT>$(<B>echo</B> <B>list</B>)<DD>
+Echo's the value of <I>list</I>. <I>list</I> is not expanded.
+<DT>$(<B>eq</B>,<I>text_a</I>,<I>text_b</I> <B>true</B> <B>false</B>)<DD>
+expands
+<I>text_a</I>
+
+and
+<I>text_b</I>
+
+and compares their results. If equal it returns the result of the expansion
+of the
+<B>true</B>
+
+term, otherwise it returns the expansion of the
+<B>false</B>
+
+term.
+<DT>$(<B>!eq</B>,<I>text_a</I>,<I>text_b</I> <B>true</B> <B>false</B>)<DD>
+Behaves identically to the previous macro except that the
+<B>true</B>
+
+string is chosen if the expansions of the two strings are not equal
+<DT>$(<B>foreach</B>,<I>var</I>,<I>list</I> <B>data</B>)<DD>
+Implements iterative macro expansion over <I>data</I> using <B>var</B> as the
+iterator taking on values from <I>list</I>. <I>var</I> and <I>list</I> are
+expanded and the result is the concatenation of expanding <I>data</I> with
+<I>var</I> being set to each whitespace separated token from <I>list</I>.
+For example:
+<DL COMPACT><DT><DD>
+<DL COMPACT><DT><DD>
+<P>
+<PRE>
+list = a b c
+all :; echo [$(foreach,i,$(list) [$i])]
+</PRE>
+
+<P>
+</DL>
+
+will output
+<DL COMPACT><DT><DD>
+<P>
+<PRE>
+[[a] [b] [c]]
+</PRE>
+
+<P>
+</DL>
+
+The iterator variable is defined as a local variable to this foreach
+instance. The following expression illustrates this:
+<DL COMPACT><DT><DD>
+<P>
+<PRE>
+$(foreach,i,$(foreach,i,$(sort c a b) root/$i) [$i/f.h])
+</PRE>
+
+<P>
+</DL>
+
+when evaluated the result is:
+<DL COMPACT><DT><DD>
+<P>
+<PRE>
+[root/a/f.h] [root/b/f.h] [root/c/f.h]
+</PRE>
+
+<P>
+</DL>
+
+The specification of list must be a valid macro expression, such as:
+<DL COMPACT><DT><DD>
+<P>
+<PRE>
+$($(assign list=a b c))
+$(sort d a b c)
+$(echo a b c)
+</PRE>
+
+<P>
+</DL>
+
+and cannot just be the list itself. That is, the following foreach
+expression:
+<DL COMPACT><DT><DD>
+<P>
+<PRE>
+$(foreach,i,a b c [$i])
+</PRE>
+
+<P>
+</DL>
+
+yields:
+<DL COMPACT><DT><DD>
+<P>
+<PRE>
+&quot;b c [a]&quot;
+</PRE>
+
+<P>
+</DL>
+
+when evaluated.
+</DL>
+
+<DT>$(<B>nil</B> <B>expression</B>)<DD>
+Always returns the value of $(NULL) regardless of what <I>expression</I> is.
+This function macro can be used to discard results of expanding
+macro expressions.
+<DT>$(<B>not</B> <B>macroterm</B>)<DD>
+expands <B>macroterm</B> and returs the string &quot;t&quot; if the result of the
+expansion is the empty string; otherwise, it returns the empty string.
+<DT>$(<B>null</B>,<I>text</I> <B>true</B> <B>false</B>)<DD>
+expands the value of
+<I>text.</I>
+
+If it is NULL then the macro returns the value of the expansion of <B>true</B>
+and the expansion of <B>false</B> otherwise. The terms <B>true</B>, and
+<B>false</B> must be strings containing no white-space.
+<DT>$(<B>!null</B>,<I>text</I> <B>true</B> <B>false</B>)<DD>
+Behaves identically to the previous macro except that the
+<B>true</B>
+
+string is chosen if the expansion of
+<I>text</I>
+
+is not NULL.
+<DT>$(<B>or</B> <B>macroterm ...</B>)<DD>
+expands each <B>macroterm</B> in turn and returs the empty string if
+each term expands to the empty string; otherwise, it returs the string
+&quot;t&quot;.
+<DT>$(<B>shell</B> <B>command</B>)<DD>
+is a shell escape macro. It runs <I>command</I> as if it were part of a
+recipe and returns, separated by a single space, all the non-white
+space terms written to stdout by the command.
+For example:
+<DL COMPACT><DT><DD>
+<DL COMPACT><DT><DD>
+<P>
+$(shell ls *.c)
+<P>
+</DL>
+
+will return <I>&quot;a.c b.c c.c d.c&quot;</I> if the files exist in the current
+directory. The recipe modification flags <B>[+@%-]</B> are honored if they
+appear as the first characters in the command. For example:
+<DL COMPACT><DT><DD>
+<P>
+$(shell +ls *.c)
+<P>
+</DL>
+
+will run the command using the current shell.
+<P>
+
+<B>Note</B> that if the macro is part of a recipe it will be evaluated after
+all previous recipe lines have been executed. For obvious reasons it will be
+evaluated before the current recipe line or group recipe is executed.
+</DL>
+
+<DT>$(<B>shell,expand</B> <B>command</B>)<DD>
+Is an extension to the <B>$(shell command)</B> function macro that expands the
+result of running <B>command</B>.
+<DT>$(<B>sort</B> <B>list</B>)<DD>
+Will take all white-space separated tokens in <I>list</I> and will
+return their sorted equivalent list.
+<DT>$(<B>strip</B> <B>data</B>)<DD>
+Will replace all strings of white-space in data by a single space.
+<DT>$(<B>subst</B>,<I>pat</I>,<I>replacement</I> <B>data</B>)<DD>
+Will search for <I>pat</I> in
+<B>data</B>
+
+and will replace any occurrence of
+<I>pat</I>
+
+with the
+<I>replacement</I>
+
+string. The expansion
+<DL COMPACT><DT><DD>
+<P>
+$(subst,.o,.c $(OBJECTS))
+<P>
+</DL>
+
+is equivalent to:
+<DL COMPACT><DT><DD>
+<P>
+$(OBJECTS:s/.o/.c/)
+<P>
+</DL>
+
+<DT>$(<B>uniq</B> <B>list</B>)<DD>
+Will take all white-space separated tokens in <I>list</I> and will
+return their sorted equivalent list containing no duplicates.
+</DL>
+</DL>
+
+<A NAME="lbAS">&nbsp;</A>
+<H2>CONDITIONAL MACROS</H2>
+
+<B>dmake</B>
+
+supports conditional macros. These allow the definition of target specific
+macro values. You can now say the following:
+<DL COMPACT><DT><DD>
+<P>
+<B>target</B> ?= <I>MacroName MacroOp Value</I>
+<P>
+</DL>
+
+This creates a definition for <I>MacroName</I> whose value is <I>Value</I>
+only when <B>target</B> is being made. You may use a conditional macro
+assignment anywhere that a regular macro assignment may appear, including
+as the value of a $(assign ...) macro.
+<P>
+
+The new definition is associated with the most recent cell definition
+for <B>target</B>. If no prior definition exists then one is created. The
+implications of this are immediately evident in the following example:
+<P>
+<DL COMPACT><DT><DD>
+<PRE>
+foo := hello
+
+all : cond;@echo &quot;all done, foo=[$(foo)] bar=[$(bar)]&quot;
+
+cond ?= bar := global decl
+
+cond .SETDIR=unix::;@echo $(foo) $(bar)
+cond ?= foo := hi
+
+cond .SETDIR=msdos::;@echo $(foo) $(bar)
+ cond ?= foo := hihi
+</PRE>
+
+</DL>
+
+<P>
+The first conditional assignment creates a binding for 'bar' that is
+activated when 'cond' is made. The bindings following the :: definitions are
+activated when their respective recipe rules are used. Thus the
+first binding serves to provide a global value for 'bar' while any of the
+cond :: rules are processed, and the local bindings for 'foo' come into
+effect when their associated :: rule is processed.
+<P>
+
+Conditionals for targets of .UPDATEALL are all activated before the
+target group is made. Assignments are processed in order. Note that
+the value of a conditional macro assignment is NOT AVAILABLE until the
+associated target is made, thus the construct
+<P>
+<DL COMPACT><DT><DD>
+<PRE>
+mytarget ?= bar := hello
+mytarget ?= foo := $(bar)
+</PRE>
+
+</DL>
+
+<P>
+results in $(foo) expanding to &quot;&quot;, if you want the result to be &quot;hello&quot;
+you must use:
+<P>
+<DL COMPACT><DT><DD>
+<PRE>
+mytarget ?= bar := hello
+mytarget ?= foo = $(bar)
+</PRE>
+
+</DL>
+
+<P>
+Once a target is made any associated conditional macros are deactivated
+and their values are no longer available. Activation occurrs after all
+inference, and .SETDIR directives have been processed and after $@ is
+assigned, but before prerequisites are processed; thereby making the values of
+conditional macro definitions available during construction of prerequisites.
+<P>
+
+If a %-meta rule target has associated conditional macro assignments,
+and the rule is chosen by the inference algorithm then the conditional
+macro assignments are inferred together with the associated recipe.
+<A NAME="lbAT">&nbsp;</A>
+<H2>DYNAMIC PREREQUISITES</H2>
+
+<B>dmake</B>
+
+looks for prerequisites whose names contain macro expansions during target
+processing. Any such prerequisites are expanded and the result of the
+expansion is used as the prerequisite name. As an example the line:
+<P>
+ fred : $$@.c
+<P>
+causes the $$@ to be expanded when <B>dmake</B> is making fred, and it resolves
+to the target <I>fred</I>.
+This enables dynamic prerequisites to be generated. The value
+of @ may be modified by any of the valid macro modifiers. So you can say for
+example:
+<P>
+ fred.out : $$(@:b).c
+<P>
+where the $$(@:b) expands to <I>fred</I>.
+Note the use of $$ instead of $ to indicate the dynamic expansion, this
+is due to the fact that the rule line is expanded when it is initially parsed,
+and $$ then returns $ which later triggers the dynamic prerequisite expansion.
+If you really want a $ to be part of a prerequisite name you must use $$$$.
+Dynamic macro expansion is performed in all user defined rules,
+and the special targets .SOURCE*, and .INCLUDEDIRS.
+<P>
+
+If dynamic macro expansion results in multiple white space separated tokens
+then these are inserted into the prerequisite list inplace of the dynamic
+prerequisite. If the new list contains additional dynamic prerequisites they
+will be expanded when they are processed. The level of recursion in this
+expansion is controlled by the value of the variable <B>DYNAMICNESTINGLEVEL</B>
+and is set to 100 by default.
+<A NAME="lbAU">&nbsp;</A>
+<H2>BINDING TARGETS</H2>
+
+This operation takes a target name and binds it to an existing file, if
+possible.
+<B>dmake</B>
+
+makes a distinction between the internal target name of a target and its
+associated external file name.
+Thus it is possible for a target's internal name and its external
+file name to differ.
+To perform the binding, the following set of rules is used.
+Assume that we are
+trying to bind a target whose name is of the form <I>X.suff</I>,
+where <I>.suff</I> is the suffix and <I>X</I> is the stem portion
+(ie. that part which contains the directory and the basename).
+<B>dmake</B>
+
+takes this target name and performs a series of search operations that try to
+find a suitably named file in the external file system.
+The search operation is user controlled
+via the settings of the various .SOURCE targets.
+<DL COMPACT><DT><DD>
+<DL COMPACT>
+<DT>1.<DD>
+If target has the .SYMBOL attribute set then look for it in the library.
+If found, replace the target name with the library member name and continue
+with step 2. If the name is not found then return.
+<DT>2.<DD>
+Extract the suffix portion (that following the `.') of the target name.
+If the suffix is not null, look up the special target .SOURCE.&lt;suff&gt;
+(&lt;suff&gt; is the suffix).
+If the special target exists then search each directory given in
+the .SOURCE.&lt;suff&gt; prerequisite list for the target.
+If the target's suffix was null (ie. <I>.suff</I> was empty) then
+perform the above search but use the special target .SOURCE.NULL instead.
+If at any point a match is found then terminate the search.
+If a directory in the prerequisite list is the special name `.NULL ' perform
+a search for the full target name without prepending any directory portion
+(ie. prepend the NULL directory).
+<DT>3.<DD>
+The search in step 2. failed. Repeat the same search but this time
+use the special target .SOURCE.
+(a default target of '.SOURCE : .NULL' is defined by <B>dmake</B> at startup,
+and is user redefinable)
+<DT>4.<DD>
+The search in step 3. failed.
+If the target has the library member attribute (.LIBMEMBER)
+set then try to find the target in the library which was passed along
+with the .LIBMEMBER attribute (see the MAKING LIBRARIES section).
+The bound file name assigned to a target which is successfully
+located in a library is the same name that would be assigned had the search
+failed (see 5.).
+<DT>5.<DD>
+The search failed. Either the target was not found in any of the search
+directories or no applicable .SOURCE special targets exist.
+If applicable .SOURCE special targets exist, but the target was not found,
+then <B>dmake</B> assigns the first name searched as the bound file name.
+If no applicable .SOURCE special targets exist,
+then the full original target name becomes the bound file name.
+</DL>
+</DL>
+
+<P>
+
+There is potential here for a lot of search operations. The trick is to
+define .SOURCE.x special targets with short search lists and leave .SOURCE
+as short as possible.
+The search algorithm has the following useful side effect.
+When a target having the .LIBMEMBER (library member) attribute is searched for,
+it is first searched for as an ordinary file.
+When a number of library members require updating it is desirable to compile
+all of them first and to update the library at the end in a single operation.
+If one of the members does not compile and <B>dmake</B> stops, then
[... 1252 lines stripped ...]