Date: Tue, 16 Aug 2016 17:55:51 -0500 From: Dennis Jensen <djensen@macsales.com> To: freebsd-doc@freebsd.org Subject: FreeBSD Man Pages: MAKE(1) Message-ID: <B6BD86A2-FC61-4196-B3D0-A2E8273CEB31@macsales.com>
next in thread | raw e-mail | index | archive | help
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=3Dmake&apropos=3D0&sektion=3D0&m= anpath=3DFreeBSD+10.3-RELEASE+and+Ports&arch=3Ddefault&format=3Dhtml 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 ?=20 Should there be a period (.MAKE) proceeding it as referenced in part of = the=20 description for it (which is to say =E2=80=94 there are two instances = where MAKE is=20 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} =3D=3D 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=20 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=20 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=3D 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=20 right this in "Queens English" instead of "Anglish" (aka American = English) the spelling is =E2=80=94 behavior =E2=80=94 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" =E2=80=94 personally it makes no difference to me = and this is just a matter of consistency =E2=80=94 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=20 does not make much sense without the context of what these two items are=20= 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 (`:=3D') to prevent such behaviour. For example, :Ox Randomize the words in the variable. The results will be = different each >>>> with expansion (":=3D") 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 = ("$"),=20 >>>> instead of another preceding dollar sign as is usual. :C/pattern/replacement/[1gW] >> string replacement. Normally, the first occurrence of the = pattern=20 >> pattern in each word of the value is substituted with = replacement. >> instances of the search pattern pattern as occur in the word or =20 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=20 >>>> 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=3Dnew_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 = ("$"),=20 >>>> 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 =E2=80=94= 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. =46rom 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=E2=80=99s 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=E2=80= =99s English=E2=80=9D 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 =E2=80=94 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=E2=80= =9D, we would be left with "The classrooms are bright and cheerful=E2=80=9D= , 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 =E2=80=94 = or limits =E2=80=94 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 =E2=80=94 not any others and definitely not = ALL the classrooms. The "which" clause in the second sentence is what we call a nonessential = =E2=80=94 or nonrestrictive =E2=80=94 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 = =E2=80=9Cwhich=E2=80=9D 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 =E2=80=94 which is a fairly common mistake.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?B6BD86A2-FC61-4196-B3D0-A2E8273CEB31>