[man page corrections for 2011.09.15] Second and last listing

[Roger]

Here's the last of the corrections.  I missed a few in the beginning of the
Bash Manual Page because; the errors were intermittent and the grammar
improved significantly.  Later, I realized there are just pockets within the
Man page that could be improved on.

Anyways...


-------------------------------------------------------------------------------

Section: SHELL BUILTIN COMMANDS
         read

Location: Option -e

Sentence: "Readline uses the current (or default, if line editing was not
          previously active) editing settings."

Should read:  "Readline uses the current editing settings, or default if line
              editing was not previously active.

Comments: Run-on sentence after the last parentheses.

-------------------------------------------------------------------------------

Section: SHELL BUILTIN COMMANDS
         return

Location: First paragraph, third sentence.

Sentence: "If used outside a function, but during execution of a script by
the . (source) command, it causes the shell to stop executing that script and
return either n or the exit status of the last command executed within the
script as the  exit status  of the  script.   If  used outside a function and
not during execution of a script by ., the return status is false."

Comment: Add "of" to "If used outside a function,"
         Replace "it" with "return" command name for clarity.
         Replace "as the exit status" with "for the exit status".

Fixed Sentence: "If used outside of a function, but during execution of a 
script by the
. (source) command, return  causes the shell to stop executing the script and
return either n or the exit status of the last command executed within the
script for the exit status of the script."

-------------------------------------------------------------------------------

Section: SHELL BUILTIN COMMANDS
         return

Location: First paragraph, fourth sentence.

Sentence: "If  used outside a function and not during execution of a script
by ., the return status is false."

Comment: Add of in front of "a function", Spelling "the" == then"!,
Also add, "by . (source command)," to prevent leaving a period by itself on a
line and possibly mislead reader?

Fixed Sentence: "If  used outside of a function and not during execution of a
script by . (source) command, then return status is false."

Additional Comment:  To add a little clarity, reinstate what the return command
states for an error on the command line shell. ie.

$ return
can only `return' from a function or sourced script

As one might think they can use a return on the last line of a script?

-------------------------------------------------------------------------------

Section: SHELL BUILTIN COMMANDS
         set

Location: Option -k

Sentence: "All arguments in the form of assignment statements are placed in the
environment for a command,"

Fixed Sentence: "All arguments in the form of assignment statements are placed
in (or exported to) the environment for a command,"

Comment: Better wording might be "exported to the environment"

-------------------------------------------------------------------------------

Section: SHELL BUILTIN COMMANDS
         set

Location: Option -p

Comment: Great, I know exactly what option -p does, but have no idea what
situation I would use it for.  How about a one sentence suggestion?

-------------------------------------------------------------------------------

Section: SHELL BUILTIN COMMANDS
         shopt

Location: Second paragraph

Sentence: "If  either  -s  or  -u  is  used with no optname arguments, the
display is limited to those options which are set or unset"

Comment: Again, "the display is limited", most people are thinking their
"monitors, CRT, LCD displays" are being limited somehow.  A better suggestion
would be to write as:

Fixed Sentence: "If  either  -s  or  -u  is  used with no optname arguments,
shopt only shows those options which are set or unset"

or

Fixed Sentence: "If  either  -s  or  -u  is  used with no optname arguments,
shopt only outputs those options which are set or unset"

... personally, I prefer the first "only show" options as "only show" might
translate better across other languages?

-------------------------------------------------------------------------------

Section: SHELL BUILTIN COMMANDS
         test

Location: First paragraph, first sentence.

Sentence: "Return  a  status of 0 or 1..."

Comment: I see true and false also being equivalent further reading into this
section.  Should true=0 & false=1 be also mentioned within this first sentence?

Might be helpful to restate this here?

-------------------------------------------------------------------------------

Section: SHELL BUILTIN COMMANDS
         type

Location: First paragraph, first sentence.

Sentence: "With  no  options, indicate how each name would be interpreted if
used as a command name."

Comment: Seems "name" is redundantly used here, causing confusion?  Simplify by
just stating "name" as "command name" initially?

Fixed Sentence: "With  no  options, indicate how each command name would be
interpreted."

-------------------------------------------------------------------------------

Section: SHELL BUILTIN COMMANDS
         type
Location: Sixth(?) sentence.

Sentence: "If a command is hashed, -p and -P print the hashed value, not
necessarily the file that appears first in PATH."

Comment: Add add instead of a comma "," or a dash "-", or "which is not"?

Sentence: "If a command is hashed, -p and -P print the hashed value which is
not necessarily the file that appears first in PATH."

Additional Comment: Think "which" is over used quite a lot today, but of all
the options, makes the sentence the clearest of all options.  If I'm typing
quickly, I usually use a dash for clarity.

-------------------------------------------------------------------------------

Section: SHELL BUILTIN COMMANDS
         ulimit

Location: Third paragraph, first sentence.

Sentence: "If  limit  is  given,  it  is the new value of the specified
resource (the -a option is display only)."

Comment: Run-on sentence, use "while or another sentence. Replace display with
"show only" or "output only". Might be wise to also state "what is
displayed/shown".

Fixed Sentence: "If  limit  is  given,  it  is the new value of the specified
resource (while the -a option only shows set values)."

-------------------------------------------------------------------------------

Section: SHELL BUILTIN COMMANDS

Location: Third paragraph, third sentence.

Sentence: "Values are in 1024-byte increments, except for -t, which is in
seconds, -p, which is in units of 512-byte blocks, and  -T,  -b, -n, and -u,
which are unscaled values."

Comment: Too many commas/ands within listing, causing a run-on sentence.

Fixed Sentence: "Values are in 1024-byte increments; except for -t which is in
seconds, -p which is in units of 512-byte blocks and -T -b -n -u which are
unscaled values.

Additional Comment: I don't think commas are needed within dash options, as
such, I dropped them along with the word "and".  Another suggestion might be to
drop the overly used words "which is" "which are" and replace with "for"?

Fixed Sentence: "Values are in 1024-byte increments; except for -t for seconds,
-p for units of 512-byte blocks and -T -b -n -u for unscaled values.

(... think this last "Fixed Sentence" suggestion is the best.)

-------------------------------------------------------------------------------

OK.  That does it. I've read the whole current Bash Manual Page!  If it were not
for this E-Ink technology, I likely would never have read this entire Manual.
A long read, but kind of necessary for how much scripting I do.

One last correction, I noticed a *lot* of double spacing within the manual,
especially within the SHELL BUILTIN COMMANDS type command.


---
Roger
http://rogerx.freeshell.org/