make-stds.texi manual feedback

[David Apps]

Thank you for your message.

I recognize that other people might not share my concerns. 
I recognize that these documents have a large audience and that not 
everybody will react in the same way to the text as I did.

I have not read all the documents that describe the standards.
I read this text while reading the make manual.

The quality of the material that I read was so high that when I noticed 
things that seemed inconsistent, I thought that I should give some 
feedback. 
I imagined that the main authors do not have time to carefully read all 
the material very often.

The two extracts that I mentioned in my feedback come one after the 
other.

> Do not install executables here in this directory 
> (they probably belong in $(libexecdir) or $(sbindir)). 
> Also do not install files that are modified in the normal course of 
their use 
> (programs whose purpose is to change the configuration of the system 
excluded).

When I read the first sentence, the words "here in this directory" 
caught my attention. 
The context seemed only to need "here" or "in this directory". 
To use both "here" and "in this directory" seemed inconsistent with the 
other text that I read. 
Using both "here" and "in this directory" seemed to create a special 
emphasis. 
I paused and reread but could not work out the reason for this special 
emphasis.

The situation seemed even stranger when I read the next sentence. 
"Also do not install files that are modified in the normal course of 
their use" 
seemed to need either "here" or "in this directory" to make the 
sentence more specific. 
I wondered whether the author had edited using text substitution and 
had accidentally added either "here" or "in this directory" to the 
first sentence instead of to the second sentence.

In summary, I think that this part of the text does not come up to the 
high quality of the other text that I read. 
The phrase "here in this directory" seemed to me to add special 
emphasis. 
The text does not make the reason for this special emphasis clear to a 
reader like me who is new to the subject. 
The lack of "here" or "in this directory" (or similar phrase) in the 
second sentence creates a lack of balance that caused me to wonder 
whether the author had made a mistake while editing.

Those are my reasons for wanting to send feedback. 
I believe that many better ways to word these phrases exist. 
I think that moving "here" or "in this directory" from the first 
sentence to the second sentence would help a lot.

Thank you.

David