several wording mistakes in FAQ

[Benno Schulenberg-3]

Hi,

On http://www.gnu.org/software/coreutils/faq/ the second paragraph
says: "This master location of this document is available online at ..."
It should probably read either "The master location of this document
is: ..." or "The master version of this document is available online at ..."

In the third paragraph it says: "consider posting the question to the
bug lists."  lists -> list

The third element of the table of contents still mentions fileutils instead
of coreutils: "Where can I get the latest version of GNU fileutils?"  The
item itself correctly mentions coreutils.

The later elements in that table of contents do not consistently end in
periods.  And in the last element a colon is missing after "cp and mv".

In item 2: "three packages combined implement the core set" --
implement -> implemented.
"14 character limited"?  Not "9-character limited"?
"But all three" -> "But the three"
"These three packages" -> "In 2003 these three packages"
"This greatly simplifies" -> "This greatly simplified"
And in the title a comma is missing after Fileutils.

In item 4: "and although are generally" -> "and although generally"
"using this command." -> "using this command:"

In item 5: "Also with the" -> "Including the"

In item 6: "are in no position to be able to do anything" ->
"are in no position to do anything"
"We can't help you about any" -> "We can't help you with any"
"were severely effected" -> "were severely affected"

In item 8: "has put in to" -> "has put into"

In item 9: "another place that file could be created" ->
"another place that a file could be created"
"You use up their quote" -> "You use up their quota"

Item 10 can probably be deleted.  It still refers to fileutils.

In item 11: "in the front of it" -> "in front of it"

In item 12: "them you can interrupt" -> "then you can interrupt"

In item 13: "expands file globs" -> "expands globbing characters"
(When someone does not know what glob means, googling for
globbing will give preciser results than for globs.)
"You can test that with the echo command. echo rm -i *" ->
"(You can test this with the echo command: echo rm -i * )"
with the command in <code></code> tags.

In item 14: "wild-cards" -> "wildcards", "wild card" -> "wildcard"
"handing the arguments off to" -> "handing the arguments to"
"the expanded out names" -> "the expanded names"
(In my opinion those extra prepositions make the sentences
harder to understand.)
"names in current directory" -> "names in the current directory"
"and hands of the" -> "and hands the"
"but any arbitrary path" -> "or any arbitrary path"
"in a way keeping with" -> "in keeping with"
"and hand the results off to" -> "and hands the results to"
"will fail execute" -> "will fail to execute"
"there is still limit" -> "there is still a limit"
"this limited argument space limit" -> "this limited argument space"
"equivalent to the following question" -> "equivalent to the following example"
"easier to understand what is going on" -> "easier to understand"
"as an extension was using the" -> "as an extension by using the"

In item 16: "you only want to restrict directory listings to only show"
"you want to restrict directory listings to only show"
"This will do what you want." -> "This will do what you want:"
"are using bash, some" -> "are using bash. Some"
"to quote it, this will" -> "to quote it. This will"
"many power file finding features" -> "many powerful file finding features"
"allowed the operating system" -> "allowed by the operating system"

In item 18: "e.g. files with names" -> "that is files with names"

In item 20 it is very unclear what the first sentence is an answer to.
Also: "such as, I have found a bug in the sleep() function, or, ... ." ->
"such as 'I have found a bug in the sleep() function' or '...'."
"are also C program" -> "is also a C program"

In item 21: "the internal shell built in" -> "the internal shell builtin"
"improve the speed performance" -> "improve the speed of execution"

In item 22: "environment variables like LANG, LC_ALL, or LANG" ->
"environment variables like LANG, LC_COLLATE or LC_ALL"
"Unset them, and then set LC_ALL to POSIX".  Unsetting the others
should not be necessary, as LC_ALL overrides them.  So ->
"Simply set LC_ALL to POSIX".

The link at the end of item 23 does not work any more.

In item 25: "until such time at that file was created" ->
"until the time that such file was created"

In item 26: "will allow you change the owner" ->
"will allow you to change the owner"

In item 27: "compile them up again" -> "compile them again"
"make it is possible" -> "make it possible"

In item 31: "A very common case is when this occurs is" ->
"A very common case where this occurs is"
"A related question which is why does ... filesystem?"->
"A related question is 'why does ... filesystem?'"

In item 33: "the cp and move" -> "the cp and mv"
"The best recommended alternative is to use rsync command" ->
"Previously the best alternative was to use the rsync command"

Okay, enough.  :)

Benno

--
http://www.fastmail.fm - Faster than the air-speed velocity of an
                          unladen european swallow

[Bob Proulx]

Benno Schulenberg wrote:
> several wording mistakes in FAQ

Thank you very much for your careful reading of the FAQ!  I have
corrected most of the items you have mentioned.

> On http://www.gnu.org/software/coreutils/faq/ the second paragraph
> says: "This master location of this document is available online at ..."
> It should probably read either "The master location of this document
> is: ..." or "The master version of this document is available online at ..."

Corrected.

> In the third paragraph it says: "consider posting the question to the
> bug lists."  lists -> list

A holdover from when there were three lists.  Corrected.

> The third element of the table of contents still mentions fileutils instead
> of coreutils: "Where can I get the latest version of GNU fileutils?"  The
> item itself correctly mentions coreutils.

That had been intentional.  (In the past.)  The table of contents are
effectively stable URLs to their contents.  So far the table of
contents have never been changed once they have been added.  Since
that was the original URL I had resisted changing it.

However enough time has past that I see that it is now causing more
confusion than it is helping.  And so I have updated the URL for it
too.

> The later elements in that table of contents do not consistently end in
> periods.
> And in the last element a colon is missing after "cp and mv".

Normally table of contents entries should not be sentences and would
not end with punctuation.  These were intended to represent email
subject lines.  Some emails had subjects with sentences and some just
had fragments.  If a change is to be made to make these completely
consistent then all punctuation should be removed rather than added.

Noting that the table of contents become URLs the URLs that are
created are pretty ugly when they contain punctuation.  In order to be
represented as a URL it must be encoded.  Therefore in later entries I
have intentionally avoided using punctuation in the table of contents
so as to avoid creating truly ugly URLs.

Regardless of which is correct I resist making any changes to the
posted URLs since it would break all of the URLs that have been
previously posted over the years.

> In item 2: "three packages combined implement the core set" --
> implement -> implemented.

Corrected.

> "14 character limited"?  Not "9-character limited"?

Traditional Unix filesystems were limited to fourteen characters.  I
am not aware of any filesystems with a nine character limit.

  shellutils-1.12 --limit-to-fourteen-chars-> shellutils-1.
  sh-utils-1.12 --limit-to-fourteen-chars-> sh-utils-1.12

But seeing your confusion I have added some words explaining this in
the paragraph.

> "But all three" -> "But the three"

I will push back on this one.  Either is okay.  Using all three
emphasizes that they are a set.

> "These three packages" -> "In 2003 these three packages"
> "This greatly simplifies" -> "This greatly simplified"

Reasonable.  Updated.

> And in the title a comma is missing after Fileutils.

That was done intentionally to avoid the ugly URL.

> In item 4: "and although are generally" -> "and although generally"
> "using this command." -> "using this command:"

Corrected by adding in all of the pronouns that I had left out.

> In item 5: "Also with the" -> "Including the"

Corrected.

> In item 6: "are in no position to be able to do anything" ->
> "are in no position to do anything"
> "We can't help you about any" -> "We can't help you with any"

The original was quite wordy in that colloquial arrangement.  But was
it actually incorrect?  Updated regardless.  I agree that simpler is
better there.

> "were severely effected" -> "were severely affected"

That was a terrible mistake on my part and I have no excuses.  A very
common trap that I should have been able to avoid.  Corrected!

> In item 8: "has put in to" -> "has put into"

Hmm...  I think those two words were only coincidentally adjacent.
Reworded to avoid the problem.

> In item 9: "another place that file could be created" ->
> "another place that a file could be created"

Corrected.

> "You use up their quote" -> "You use up their quota"

Corrected.

> Item 10 can probably be deleted.  It still refers to fileutils.

I resist removing the entry because it would cause a renumbering of
all following entries.  I usually try to avoid referring to the number
but others do.  Your critique is an example where you are referring to
entries by number.  However the source has no such numbers.  They are
a product of the 'makeinfo' tool.  Rewritten to explain this.  I would
prefer it if makeinfo didn't number the entries but it does.

> In item 11: "in the front of it" -> "in front of it"

Corrected.

> In item 12: "them you can interrupt" -> "then you can interrupt"

Corrected.

> In item 13: "expands file globs" -> "expands globbing characters"
> (When someone does not know what glob means, googling for
> globbing will give preciser results than for globs.)

Very good suggestion!  Updated.

> "You can test that with the echo command. echo rm -i *" ->
> "(You can test this with the echo command: echo rm -i * )"
> with the command in <code></code> tags.

Updated.

> In item 14: "wild-cards" -> "wildcards", "wild card" -> "wildcard"

A spell checker error.  Corrected.

> "handing the arguments off to" -> "handing the arguments to"

It can't be a "hand off" if you remove the "off".  :-) I use the
hand-off phrase many times and I see that you take exception to it on
every use.  It is a phrase that a native English speaker would use in
every day speech to describe the passing of something from one entity
to another.  Since this seems to be a confusing point I will work
around it by using different phrasing.  Rewritten.

> "the expanded out names" -> "the expanded names"
> (In my opinion those extra prepositions make the sentences
> harder to understand.)

Updated.

> "names in current directory" -> "names in the current directory"
> "and hands of the" -> "and hands the"

Rewritten.

> "but any arbitrary path" -> "or any arbitrary path"

Corrected.

> "in a way keeping with" -> "in keeping with"

Rewritten.

> "and hand the results off to" -> "and hands the results to"

Rewritten.

> "will fail execute" -> "will fail to execute"

Corrected.

> "there is still limit" -> "there is still a limit"

Corrected.

> "this limited argument space limit" -> "this limited argument space"

Corrected.

> "equivalent to the following question" -> "equivalent to the following example"
> "easier to understand what is going on" -> "easier to understand"

Removed.  The question being referred to went away in a previous edit.

> "as an extension was using the" -> "as an extension by using the"

Corrected.

> In item 16: "you only want to restrict directory listings to only show"
> "you want to restrict directory listings to only show"

Corrected.

> "This will do what you want." -> "This will do what you want:"

Rewritten.

> "are using bash, some" -> "are using bash. Some"

Reasonable.  It was a long run-on sentence.  Mostly by intent, by the
way.  :-) Updated.

> "to quote it, this will" -> "to quote it. This will"

Rewritten.

> "many power file finding features" -> "many powerful file finding features"

Corrected.

> "allowed the operating system" -> "allowed by the operating system"

Corrected.

> In item 18: "e.g. files with names" -> "that is files with names"

Rome fell so let it lie? :-) But "e.g."  translates to "for example".
"I.e" would have been "that is".

> In item 20 it is very unclear what the first sentence is an answer to.
> Also: "such as, I have found a bug in the sleep() function, or, ... ." ->
> "such as 'I have found a bug in the sleep() function' or '...'."
> "are also C program" -> "is also a C program"

Rewritten.

> In item 21: "the internal shell built in" -> "the internal shell builtin"

An overly aggressive shell checker.  Corrected.

> "improve the speed performance" -> "improve the speed of execution"

Corrected.

> In item 22: "environment variables like LANG, LC_ALL, or LANG" ->
> "environment variables like LANG, LC_COLLATE or LC_ALL"
> "Unset them, and then set LC_ALL to POSIX".  Unsetting the others
> should not be necessary, as LC_ALL overrides them.  So ->
> "Simply set LC_ALL to POSIX".

I need to largely rewrite this one.  We have learned so much since it
was originally written long ago.  When it originally fell upon us it
really looked like a bug.  But then we found out that it was
intentional.  And so we must live with the problem.  Oh well.  I will
correct your items (thank you!) but queue up a more exhaustive edit of
this entry for later.

> The link at the end of item 23 does not work any more.

Which one is 23? :-)  Oh, ls sorting.  Removed the broken link.

> In item 25: "until such time at that file was created" ->
> "until the time that such file was created"

Updated.

> In item 26: "will allow you change the owner" ->
> "will allow you to change the owner"

Corrected.

> In item 27: "compile them up again" -> "compile them again"

Okay.

> "make it is possible" -> "make it possible"

Corrected.

> In item 31: "A very common case is when this occurs is" ->
> "A very common case where this occurs is"

Corrected.

> "A related question which is why does ... filesystem?"->
> "A related question is 'why does ... filesystem?'"

Reasonable.  Updated.

> In item 33: "the cp and move" -> "the cp and mv"

This is an artifact of dropping punctuation for the URL.

  "cp and mv: the --reply=X option is deprecated"

Became:

  "cp and mv the reply option is deprecated"

So that is a won't fix.

> "The best recommended alternative is to use rsync command" ->
> "Previously the best alternative was to use the rsync command"

Both previously and currently.  Rsync is quite useful regardless of 'cp'
and 'mv' accepting --no-clobber options.

  A good alternative is to use the @command{rsync} command using the
  @option{--ignore-existing} option.

> Okay, enough.  :)

Let me think you again for making such a detailed reading and critique
of the documentation!  It is much appreciated.

Thanks again!
Bob

[Benno Schulenberg-3]

Hi Bob,

On Sun, 01 Nov 2009 00:36 -0600, "Bob Proulx" <bob@...> wrote:
> Benno Schulenberg wrote:
> > In item 14: "wild-cards" -> "wildcards", "wild card" -> "wildcard"
>
> A spell checker error.  Corrected.

Still one present: "you provided a wild card" -> wildcard

> > In item 18: "e.g. files with names" -> "that is files with names"
>
> Rome fell so let it lie? :-) But "e.g."  translates to "for example".
> "I.e" would have been "that is".

The change from "for example" to "that is" was intentional.  :)
Because, are there kinds of hidden files that do not start with a dot?
If not, ´file names that start with a dot´ are not an example but
an explication.  Maybe write it as follows: "...I never see hidden files,
that is dot files, that is files whose names start with a dot..."

> > In item 33: "the cp and move" -> "the cp and mv"
>
> This is an artifact of dropping punctuation for the URL.

Ehm, the above text is in the body of the item, not the title.
For variety, maybe turn the word order around, while adding
the relevant @option{} and @command{} markers:

"the cp and move –reply=X option was deprecated" ->
"the option –reply=X for cp and mv was deprecated

One other error: "It did not have any affect" -> effect

By the way, @command{} markers are missing in many places.
For example in item 18: "This is regardless of it being ls",
"the ls command is only listing out", "what is ls doing",
"Suddenly using ls", "with the -l option".

(By the way, after the above "Suddenly" a comma is needed.  It makes
a difference.  :)

Regards,

Benno

--
http://www.fastmail.fm - Same, same, but different...

[Bob Proulx]

Benno Schulenberg wrote:
> Still one present: "you provided a wild card" -> wildcard

Fixed.

> > > In item 18: "e.g. files with names" -> "that is files with names"
> >
> > Rome fell so let it lie? :-) But "e.g."  translates to "for example".
> > "I.e" would have been "that is".
>
> The change from "for example" to "that is" was intentional.  :)
> Because, are there kinds of hidden files that do not start with a dot?
> If not, ´file names that start with a dot´ are not an example but
> an explication.  Maybe write it as follows: "...I never see hidden files,
> that is dot files, that is files whose names start with a dot..."

Unix filesystems use the convention that files that start with a dot
are hidden files.  But the code has been ported to many other systems
and some of those have different conventions for what makes a hidden
file.  I know that the emphasis is on GNU systems but I didn't want to
completely close the door on other non-GNU systems.  IIRC on MS-DOS
whether a file is hidden or not is an attribute.

  http://en.wikipedia.org/wiki/Hidden_file_and_hidden_directory

> > > In item 33: "the cp and move" -> "the cp and mv"

That did look odd didn't it.  Fixed.

> > This is an artifact of dropping punctuation for the URL.
>
> Ehm, the above text is in the body of the item, not the title.

Uhm...  No.  Here is the source:

  @node cp and mv the reply option is deprecated
  @chapter cp and mv: the --reply=X option is deprecated

That results in this URL being generated by 'makeinfo'.

  http://www.gnu.org/software/coreutils/faq/#cp-and-mv-the-reply-option-is-deprecated

> For variety, maybe turn the word order around, while adding
> the relevant @option{} and @command{} markers:
>
> "the cp and move –reply=X option was deprecated" ->
> "the option –reply=X for cp and mv was deprecated

Search engines optimize for ordering.  So if you search for the
commands "cp --reply" or "mv --reply" both of those will hit with a
higher rank the ordering with 'cp' and 'mv' before the 'reply'.
Switching that order will not match the searches that I expect as well
as the present ordering.  It may not be as pretty but I think the
present case serves the need better.

> One other error: "It did not have any affect" -> effect

I can't believe I had multiple affect/effect errors!  Mea culpa.

> By the way, @command{} markers are missing in many places.
> For example in item 18: "This is regardless of it being ls",
> "the ls command is only listing out", "what is ls doing",
> "Suddenly using ls", "with the -l option".

It has been tedious to be technically correct with the markup
throughout the entire document.  Meaning that it is not consistent.
And it has such little effect on the resulting typesetting.  And even
among the experts there is disagreement as to how some things should
be typeset.  I am really just making a best effort there.

> (By the way, after the above "Suddenly" a comma is needed.  It makes
> a difference.  :)

Added.  (That one I had to review. :-)

Thanks again for the review!

Bob

[Benno Schulenberg-3]

Hola Bob,

On Thu, 05 Nov 2009 15:32 -0700, "Bob Proulx" <bob@...> wrote:

> Benno Schulenberg wrote:
> > If not, ´file names that start with a dot´ are not an example but
> > an explication.  Maybe write it as follows: "...I never see hidden files,
> > that is dot files, that is files whose names start with a dot..."
>
> Unix filesystems use the convention that files that start with a dot
> are hidden files.  But the code has been ported to many other systems
> and some of those have different conventions for what makes a hidden
> file.  I know that the emphasis is on GNU systems but I didn't want to
> completely close the door on other non-GNU systems.

But the title of the item already speaks of dot files, not of hidden ones.
And the rest of the item only talks of dot files (twice adding that they
are hidden), and all the examples are about dot files.  Seeing all this
context, really only "that is" makes sense.

In my opinion there is no need to cater for other systems -- the FAQ
is located at gnu.org and it should describe GNU coreutils as clearly as
possible: don't say "for example" when the example given is the only
possibility.  Better the above suggested phrase, to closely bind together
the three possible descriptions of hidden files.


Another strange phrase appears near the end of this item about ´ls´:
"as this is a very similar theme".  Maybe: "as the sometimes surprising
behavior of the globbing character ´*´ is a very common theme".

In the title of item 28 the name of tar should be all lowercase.  I know
you resist changing titles because of posted URLs, but it's better to be
correct.  Also : s/this file this is not possible/this file is not possible/

Regards,

Benno

--
http://www.fastmail.fm - Email service worth paying for. Try it for free