Created attachment 173791 [details] A Copy of the Man Page with all my corrections I originally sent the following as an email to freebsd-doc@FreeBSD.org and then sent the attachment separately and was told I should submit this here. So I hope this is the proper way to submit this kind of thing if not please give me the procedural URL so that I can make sure that I submit future corrections in the most appropriate manner. Document: https://www.freebsd.org/cgi/man.cgi?query=make&apropos=0&sektion=0&manpath=FreeBSD+10.3-RELEASE+and+Ports&arch=default&format=html The following is a break out of the issues that I found within this document I have outlined the issues below and I have attached a MSWord Document of my finished version that I am using for myself. 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. Legend: 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. ********** Issues Begin ********** -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.
Created attachment 228610 [details] make(1) patch Create a patch to correct some of the issues identified. - Fix spelling of compatibility - Handle MAKEFLAGS consistently as an environment variable - Expand contractions - Add information on what happens when MAKEFLAGS has a dash prepended to it - Add a Harvard comma to clarify meta mode
The project doesn't have a standard for American vs British English, or whether to use single or double quotes. Color and hyphenation are handled by the man page CGI program, which is known to have a bug or two. That is not a problem with the source man page. Thank you for posting the differences as a comment.