FreeBSD Man Pages: MAKE(1)

[Dennis Jensen]

First I hope this is the proper way to submit this kind of thing if not please give me the URL so that I can make sure that I submit future corrections in the most appropriate manner.

The following is a break out of the issues that I found within this document  I have outlined the issues below and I will be sending a MSWord Document of my finished version that I am using for myself in a subsequent email in case there is an issue with receiving it.  I also tried to include just enough of the surrounding text to help pinpoint the issue and the issues are top to bottom as they were found in the document when read from top to bottom.  Final Note:  I tried to catch as much as possible but I might have missed a few things.

https://www.freebsd.org/cgi/man.cgi?query=make&apropos=0&sektion=0&manpath=FreeBSD+10.3-RELEASE+and+Ports&arch=default&format=html

Where >> appears it points to where the problem resides and is followed
eventually by: >>>> pointing to the proposed correction that needs to be made.
Note not all corrections are presented this way and some are posted as questions.

-d   [-]flags
>>     Turn on debugging, and specify which portions of make are to
>>     print debugging information.  Unless the flags are preceded by
>>     `-' they are added to the MAKEFLAGS environment variable and will

>>>>   These turn on debugging and specify the portions that make is to
>>>>   print debugging information for.  Unless the flags are preceded by
>>>>   "-" they are added to the MAKEFLAGS environment variable and will

On the last line other than replacing the single quotes with double quotes
it does not mention what will happen if the flag is proceeded by "-" and/or
under what circumstances you would want to do this.  I mean if you did not
want the flag to be used would you simply not add it to the list ??  So what
is the significance of the "-" why use it at all ??


-j  max_jobs
>>     scripts which change directories on each command invocation and
>>>>   scripts that change directories on each command invocation and


-N     Display the commands which would have been executed, but do not
>>>>   Display the commands that would have been executed, but do not


SHELL COMMANDS
     Makefiles should be written so that the mode of make operation does not
>>   change their behavior.  For example, any command which needs to use
>>>> change their behavior.  For example, any command that needs to use


MAKE       The name that make was executed with (argv[0]).  For com-
           patibility make also sets .MAKE with the same value.  The
           preferred variable to use is the environment variable
           MAKE because it is more compatible with other versions of
           make and cannot be confused with the special target with
           the same name.

Should not the  "MAKE"  be green and in italics ? 
Should there be a period (.MAKE) proceeding it as referenced in part of the 
description for it (which is to say — there are two instances where MAKE is 
missing a preceding period) ?


.MAKE.ALWAYS_PASS_JOB_QUEUE
     Tells make whether to pass the descriptors of the job
     token queue even if the target is not tagged with .MAKE
>>   The default is `yes' for backwards compatability with
     FreeBSD 9.0 and earlier.

>>>> The default is `yes' for backwards compatibility with


MAKEFLAGS    The environment variable `MAKEFLAGS' may contain anything
>>           that may be specified on make's command line.  Anything
>>           specified on make's command line is appended to the
>>           `MAKEFLAGS' variable which is then entered into the envi-
>>           ronment for all programs which make executes.

Should not the  "MAKEFLAGS"  be green and in italics ?

>>>>        that may be specified on the make's command line.  Anything
>>>>        specified on the make's command line is appended to the
>>>>        `MAKEFLAGS' variable that is then entered into the envi-
>>>>        ronment for all programs that make executes.


.MAKE.LEVEL     The recursion depth of make.  The initial instance	of
                make will be 0, and an incremented value is put into the
                environment to be seen by the next	generation.  This
                allows tests like:  .if ${.MAKE.LEVEL} == 0 to protect
>>              things which should only be evaluated in the initial
                instance of make.

.MAKE.LEVEL     This is the recursion depth of make.  The initial instance	of

>>>>            things that should only be evaluated in the initial


.MAKE.MAKEFILES
>>       The list of makefiles read by make, which is useful for
>>>>     The list of makefiles read by make that are useful for

Note: I would argue that "useful for tracking dependencies" is essential to the meaning
of that sentence and thus "that" should be used instead of "which" necessitating the
removal of the comma and the tense of the verb should be plural regardless


         meta         Puts make into "meta" mode, where meta files
                      are created for each target to capture the
                      command run, the output generated and if
                      filemon(4) is available, the system calls
>>                    which are of interest to make.  The captured
                      output can be very useful when diagnosing
                      errors.

First off the above reads very poorly and as such I am not even sure how to fix it
because it is fairly hard to determine exactly what is being conveyed as such it 
should probably be revisited and cleaned up to be more clear and concise.

For instance if we remove the comma clauses that normally mean they are not 
essential to the sentence we get:
(This) puts make into "meta" mode the output generated and the system calls
that are of interest to make.
This makes very little overall sense and seems like some verbiage is missing
that would complete the concept.  Other than that I have the following grammatical
error:

>>>>                  that are of interest to make.  The captured


         curdirOk= bf  Normally make will not create .meta files in
                      '.CURDIR'.  This can be overridden by setting
>>                    bf to a value which represents True.

>>>>                  bf to a value that represents True.


>>       ignore-cmd   Some makefiles have commands which are simply

>>>>     ignore-cmd   Some makefiles have commands that are simply



.MAKE.META.BAILIWICK
>>       In "meta" mode, provides a list of prefixes which match
>>>>     In "meta" mode, this variable provides a list of prefixes that match


.MAKEOVERRIDES   This variable is used to record the names of variables
                 assigned to on the command line, so that they may be
                 exported as part of `MAKEFLAGS'.  This behaviour can be

Okay I am not even sure what is really being said in this first paragraph it
appears some verbiage got misplaced.  Further unless you are attempting to 
right this in "Queens English" instead of "Anglish" (aka American English)
the spelling is — behavior — and if you are trying to implement this documentation
in the "Queens English" it needs an extreme major overhaul as it is mostly
written in "Anglish" — personally it makes no difference to me and this is just a
matter of consistency — either English or Anglish do not write it in both.
Possible rewrite of the above assuming my assumption of what it is trying to say
is correct:

.MAKEOVERRIDES   This variable is used to record the names of variables
                 that had assignments made to them on the command line, so that
                 they may be exported as part of "MAKEFLAGS".  This behavior can be


>>            Variable expansion is performed on the value before it's
              used, so expressions such as
                     ${.CURDIR:S,^/usr/src,/var/obj,}

>>>>          Variable expansion is performed on the value before it is

As a general rule contractions should never be used in professional documentation.


PWD       Alternate path to the current directory.  make normally
          sets `.CURDIR' to the canonical path given by getcwd(3).
          However, if the environment variable `PWD' is set and
          gives a path to the current directory, then make sets
          `.CURDIR' to the value of `PWD' instead.  This behaviour
          is disabled if `MAKEOBJDIRPREFIX' is set or `MAKEOBJDIR'
          contains a variable transform.  `PWD' is set to the value
          of `.OBJDIR' for all programs which make executes.

To many tiny errors so I just did a full rewrite below:

PWD       This is an alternate path to the current directory.  make normally
          sets ".CURDIR" to the canonical path given by getcwd(3).
          However, if the environment variable "PWD" is set and
          gives a path to the current directory, then make sets
          ".CURDIR" to the value of "PWD" instead.  This behavior
          is disabled if "MAKEOBJDIRPREFIX" is set or "MAKEOBJDIR"
          contains a variable transform.  "PWD" is set to the value
          of ".OBJDIR" for all programs that make executes.

Also it would be great if there were a hyper-link or something that denoted
what "MAKEOBJDIRPREFIX" and/or "MAKEOBJDIR" are as that sentence by itself 
does not make much sense without the context of what these two items are 
and/or mean.  Further is there a reason PWD is not green and in italics?


.TARGETS   >>> Is there a reason this variable is not green and in italics ?

VPATH       Colon-separated (``:'') lists of directories that make
            will search for files.  The variable is supported for
            compatibility with old make programs only, use `.PATH'
            instead.

Simply rewrite below:

VPATH       (Deprecated) A colon-separated (":") list of directories
            that make will search for files.  This variable is only
            supported for compatibility with older make programs and
            will be removed sometime in the future.  As such, the
            ".PATH" variable should be used instead.

Again is there a reason this variable is not green and in italics ?
If yes to this question some kind of legend on the page should be
put into place to understand why some are green and in italics and
others are not.  Basically a consistency and clarity issue.


:Mpattern
>>     Select only those words that match pattern.  The standard shell
. . .
>>     will normalise the inter-word spacing, removing all leading and
>>     trailing space, and converting multiple consecutive spaces to single
>>     spaces.

>>>>   Select only those words that match the pattern given.  The standard shell
. . .
>>>>   will normalize the inter-word spacing, removing all leading and
>>>>   trailing spaces, and convert multiple consecutive spaces into a single
>>>>   space.


:Npattern
       This is identical to `:M', but selects all words which do not match
       pattern.

A quick corrective rewrite is shown below:

:Npattern
       This is identical to ":M", but selects all words which do not match
       the pattern given.


:Ox    Randomize words in variable.  The results will be different each
       time you are referring to the modified variable; use the assignment
>>     with expansion (`:=') to prevent such behaviour.  For example,

:Ox    Randomize the words in the variable.  The results will be different each
>>>>   with expansion (":=") to prevent such behavior.  For example:

:S/old_string/new_string/[1gW]
>>     Variable expansion occurs in the normal fashion inside both
>>     old_string and new_string with the single exception that a backslash
>>     is used to prevent the expansion of a dollar sign (`$'), not a pre-
>>     ceding dollar sign as is usual.

This entire paragraph was unclear and it took me a while to figure out what it
was trying to communicate.  So below is a rewrite to make it much easier to
understand the first time it is read.  This rewrite not be the best as I tried
to adhere somewhat to what had been written already.

>>>>   Variable expansion occurs in the normal fashion inside both
>>>>   old_string and new_string with the single exception that a preceding
>>>>   backslash is used to prevent the expansion of a dollar sign ("$"), 
>>>>   instead of another preceding dollar sign as is usual.


:C/pattern/replacement/[1gW]
>>     string replacement.  Normally, the first occurrence of the pattern 
>>     pattern in each word of the value is substituted with replacement.
>>     instances of the search pattern pattern as occur in the word or
	  
The redundancy of pattern "pattern" is unnecessary the point is communicated
fine by just using "pattern"  (the quotes here denote green italics)

>>>>   string replacement.  Normally, the first occurrence of the 
>>>>   pattern in each word of the value is substituted with the replacement.
>>>>   instances of the search pattern as occurs in the word or


:?true_string:false_string
>>     If the variable name (not its value), when parsed as a .if condi-
>>     which actually tests defined(NUMBERS), to determine is any words

>>>>   If the variable name (not its value), when parsed as an .if condition
>>>>   which actually tests defined(NUMBERS), to determine if any words


:old_string=new_string
>>     Variable expansion occurs in the normal fashion inside both
>>     old_string and new_string with the single exception that a backslash
>>     is used to prevent the expansion of a dollar sign (`$'), not a pre-
>>     ceding dollar sign as is usual

Again this entire paragraph is confusing as to what it is trying to
communicate below is the replacement paragraph that makes it easier to
understand its meaning the first time its read.

>>>>   Variable expansion occurs in the normal fashion inside both
>>>>   old_string and new_string with the single exception that a preceding
>>>>   backslash is used to prevent the expansion of a dollar sign ("$"), 
>>>>   instead of another preceding dollar sign as is usual.


:[range]
>>     white space.  Some modifiers suppress this behaviour, causing a

>>>>   white space.  Some modifiers suppress this behavior, causing a


.error message
       The message is printed along with the name of the makefile and
>>     line number, then make will exit.

       The message is printed along with the name of the makefile and
>>>>   the line number and then make will exit.


.info message
       The message is printed along with the name of the makefile and
>>     line number.

>>>>   the line number.


.unexport variable	...
>>     all globals are unexported, and .MAKE.EXPORTED deleted.

>>>>   all globals are unexported, and .MAKE.EXPORTED is deleted.


.unexport-env
>>     note that any variables which originated in the parent environ-

>>>>   note any variables that originated in the parent environment


.warning message
>>     The message prefixed by `warning:' is printed along with the name
>>     of the makefile and line number.

>>>>   The message prefixed by "warning:" is printed along with the name
>>>>   of the makefile and the line number.


>>     The operator may be any one of the following:

       ||       Logical OR.

>>     &&       Logical AND; of higher precedence than ``||''.


>>>>   The operator(s) may be any one of the following:
>>>>   &&       Logical AND; this has a higher precedence than "||".


I believe the following are all "functions" as such they should be denoted as such
with full syntax much like all the other commands have been shown — as follows:

defined(variable)
       Takes a variable as an argument and evaluates to true if
       the variable has been defined.

make(target)
       Takes a target as an argument and evaluates to true if the
       target was specified as part of make's command line or was
       declared the default target (either implicitly or explicitly,
       see .MAIN) before the line containing the conditional.

empty(variable[-??])
       Takes a variable, with possible modifiers, and evaluates to true
       if the expansion of the variable would result in an empty
       string.

exists(file)
       Takes a file as an argument and evaluates to true if the
       file exists.  The file is searched for on the system search path
       (see .PATH).

target(target)
       Takes a target as an argument and evaluates to true if the
	target has been defined.

commands(target)
       Takes a target name as an argument and evaluates to true if the
       target has been defined and has commands associated with it.

Note: since they were not presented there seems to be no way to know what
modifiers can be used with empty() nor what those modifiers might do.  This
should definitely be added into this documentation here or at least a reference
to point to where it is documented.


     When make is evaluating one of these conditional expressions, and it
>>   encounters a (white-space separated) word it doesn't recognize, either
>>   the ``make'' or ``defined'' expression is applied to it, depending	on the
>>   form of the conditional.  If the form is `.ifdef', `.ifndef', or `.if'
>>   the ``defined'' expression is applied.  Similarly, if the form is
>>   `.ifmake' or `.ifnmake, the' ``make'' expression is applied.

>>>> encounters a (white-space separated) word it does not recognize, either
>>>> the "make( )" or "defined( )" expression is applied to it, depending on the
>>>> form of the conditional.  If the form is ".ifdef", ".ifndef", or ".if"
>>>> the "defined( )" expression is applied.  Similarly, if the form is
>>>> ".ifmake" or ".ifnmake", the "make( )" expression is applied.


>>   .EXEC     Target is never out of date, but always execute commands any-

>>>> .EXEC     Target is never out of date, but always executes commands anyway


.OPTIONAL
>>     If a target is marked with this attribute and make can't figure
       out how to create it, it will ignore this fact and assume the
>>     file isn't needed or already exists.


>>>>   If a target is marked with this attribute and make cannot figure
>>>>   file is not needed or already exists.


>>     the output is always `a', `b1', `b', `x'.
       The ordering imposed by .WAIT is only relevant for parallel
       makes.

>>>>   The output is always:  a  b1  b  x

The output would not have single quotes around it nor would there be any commas and
I only included the extra spacing to help with readability.


.DEFAULT
       This is sort of a .USE rule for any target (that was used only
>>     as a source) that make can't figure out any other way to create.

>>>>   as a source) that make cannot figure out any other way to create.


Consistency Issue:

In some places 'single quotes' are used to surround items and in other places "double quotes" are used to surround similar items and even in other places ''double single quotes'' are used to surround similar items.  Documentation should always be consistent in its use of such punctuation.  From what I can see the use of "double quotes" should be used for most things and then the use of 'single quotes' should be reserved for special things that actually require a single quote over a double quote.  This usage by the way tends to be the norm in most technical documentation that I have read or written.

Also as noted within the preceding issues, language source should be consistent as well.  Either use the "Queen’s English" throughout or use Anglish (American English) throughout.  It is unprofessional to mix languages within the same document and since a majority of this document is written in Anglish I would suggest sticking with that rather than re-writing most of it to fit the grammar/spelling of the "Queen’s English” which I have nothing against btw.

Tabs In Lines:

I am not sure if this is just a copy/paste issue but when copying the text off the page there appears to be tabs embedded within lines for no apparent reason as they do not align anything and seem to have been used instead normal spaces.  These should be replaced with a normal spaces.

Hyphenation Breaks:

I understand you are shooting for left aligned and semi-right aligned but in most documentation hyphenation of a word is generally unnecessary if it extends to far put it on the next line or settle on a width that accommodates the general width of lines a bit better — as hyphenations are not easy to read by most and again are not a necessity especially if you are not doing double side alignment which you are not doing.

The Which vs That Grammatically Issue

Note: This is something I always have on hand as a reminder when dealing with Which and That as they always seem to be a bit problematic when writing documentation at least for me anyway.

The rule of thumb for (which vs that), is that "which" clauses are nonrestrictive (and thus nonessential) while "that" clauses are restrictive (and thus essential).  Nonrestrictive clauses and phrases are set off from the rest of a sentence by a pair of commas or by a single comma if they come at the end of the sentence because removing the clause does not change the meaning of the sentence they are just there to simply enhance the sentence.  Restrictive on the other hand is not offset by commas because if removed the complete meaning of the sentence would be changed or the sentence would be rendered unintelligible.

Looking at the following as an example:

1.  The classrooms [that were painted over the summer] are bright and cheerful

2.  The classrooms, [which were painted over the summer], are bright and cheerful

The first sentence, because it uses "that" to launch its adjective clause, tells us that only SOME of the classrooms were painted over the summer.  If we omitted the clause "that were painted over the summer”, we would be left with "The classrooms are bright and cheerful”, a statement that would not be accurate since it implies that ALL the classrooms are bright and cheerful which is not the case.  Therefore, in this sentence, the adjective clause is essential to the meaning of the sentence and thus we call it "restrictive" because it restricts — or limits — the meaning of the nouns it modifies.  So in this sentence it tells us that we are talking ONLY about the classrooms that were painted over the summer — not any others and definitely not ALL the classrooms.

The "which" clause in the second sentence is what we call a nonessential — or nonrestrictive — clause.  Since that sentence intends to tell us that ALL the classrooms were painted and now look bright and cheerful, the information in the adjective clause is not essential.  The sentence would be clear even if the clause were omitted and as such the commas are added.

As a secondary note: the subordinator "that" can never be preceded by a preposition (such as: "from that").  As always, the more natural way of saying it is to keep the preposition at the end and then "that" (or “which” for that matter) can just be omitted altogether, leaving just a bare "from" at the end.  That is perhaps even more common and removes the issue of "that" versus "which".

Note: a preposition is any word or group of words that relates a noun or a pronoun to another word within the sentence.  The following is a list of common prepositions (about, above, according to, across, after, against, along, amid, among, around, at, before, behind, below, beside, besides, between, beyond, by, concerning, down, during, except, for, from, in, into, like, of, off, on, over, past, since, through, toward, underneath, until, up, upon, with, within, and without).  Prepositions are never alone; they are always with an object which is to say a prepositional phrase consists of a preposition and an object.  The object of preposition is always a noun or pronoun, or perhaps one or two of each.  When discerning the object(s) you must choose the most important word as the object(s) of the preposition and it must be a noun or pronoun; not an adjective — which is a fairly common mistake.