bug-coreutils
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: several wording mistakes in FAQ


From: Bob Proulx
Subject: Re: several wording mistakes in FAQ
Date: Sun, 1 Nov 2009 00:36:33 -0600
User-agent: Mutt/1.5.18 (2008-05-17)

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




reply via email to

[Prev in Thread] Current Thread [Next in Thread]