[man page corrections for 2011.09.12]

[Roger]

I ran into a few previous grammar errors earlier within the Bash Manual Page,
but the manual became error free at a point so I didn't bother noting them
until I got to about this point.

One thing I have noticed, most lists with embedded commas, "and's" and "or's"
are already well written!  Most people writing lists with more then two items,
always forget to match tense or make other errors.

Most of what I'm seeing, are sporadic errors.  But no matter, errors cause
reading comprehension problems.  I don't require any explanation on the
following, as I already know what's there and what is meant to be explained.
So the following comments/fixes are merrily suggestions.  However, as far
as the 'fc' command's Manual Page content, I can always Google and research
to further my knowledge from others' posts, etc.

Questions I posted in-line, I really don't need answers too... again, they're
only suggestive in nature.

Hope this helps beginners reading the Bash GNU Info/Manual Page.

(Really enjoying being able to study the manual page using this E-Ink
technology.  Never was able to study these Man pages like this in the past 10+
years!  If I find anymore, I'll post and add a date in the subject line of the
email.)


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

Section: SHELL BUILTIN COMMANDS
    declare
    typeset

Location: First paragraph, last sentence.

Sentence: "The following options can be used to restrict output to variables
with the specified attribute or to give variables attributes:"

Comment: Usage of "restrict output" is confusing.  "Restrict a variable's
type" might be a better wording, based on my C knowledge.  (In other words, I'm
thinking of putting something into a variable within memory, while the previous
sentence describes "output".)

Fixed: "The following options can be used for restricting the type of data a
variable contains according to the specified attribute, or give variables
attributes."

Additional Comment: I think I've got the main idea of the sentence described
more clearer now, but it might still need a few finishing touches.

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

Section: SHELL BUILTIN COMMANDS
    declare
    typeset

Location: Second to third paragraph. (Paragraph after option list.)

Sentence: "Using `+' instead of `-' turns off the attribute instead, with the
exceptions that +a may not be used to destroy an array variable and +r will not
remove the readonly attribute.  When used in a function, makes  each  name
local,  as with the local command, unless the -g option is supplied, If a
variable name is followed by =value, the value of the variable is set to
value."

Fix: "When used in a function, makes each name local...".  Kind of left
hanging as if to say when a "+" or "-" is used in a function, but now I
realize, the sentence should read "When type/declare is used in a function
...".  The sentence should reiterate the builtin command, as we were just
talking about a + and - signs.

Run-on Sentence: "unless the -g option is supplied, If a ..."

Fixed: "unless the -g option is supplied.  If a ..."

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

Section: SHELL BUILTIN COMMANDS
    exec

Location: Fourth sentence from the last sentence.

Sentence: "If command cannot be executed for  some  reason,  a  non-interactive
shell exits, unless the shell option execfail is enabled, in which case it
returns failure."

Comments: "unless" usage is confusing/wordy. Just omit it.  Also, might need a
semi-colon instead of a comma.  I just noticed, reading the sentence didn't
flow right with the word "unless" and the comma before "in which" is of a lot
less concern.  But replacing the comma with a semi-colon does put those three
circumstances in a much brighter light!  From what I know, one situation
semi-colons can be used is in replace of commas where there is a greater need
of an emphasis on pause.

Fixed: "If command cannot be executed for  some  reason,  a  non-interactive
shell exits, or the shell option execfail is enabled; in which case it
returns failure."

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

Section: SHELL BUILTIN COMMANDS
    exec

Location: Second sentence from the last sentence.

Sentence: "If command is not specified, any  redirections take  effect  in the
current shell, and the return status is 0."

Comments: "and" here doesn't require a comma.

Fixed: "If command is not specified, any  redirections take  effect  in the
current shell and the return status is 0."

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

Section: SHELL BUILTIN COMMANDS
    export

Location: Second sentence

Sentence: "If no names are given, or if the -p option  is  supplied,  a list of
all names that are exported in this shell is printed."

Comment: No comma needed after "or". Also, restructured the last part of the
sentence for better flow.

Fixed: "If no names are given or if the -p option is supplied, a list of all
exported names within this shell are printed."

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

Section: SHELL BUILTIN COMMANDS
    fc

Location: Whole first paragraph.

Comment: I'm confused from the whole paragraph.  Can be clarified within the
first sentence by describing what Fix Command fixes in Bash within the first
few words.  Basically, the word "history" isn't mentioned until the 19th word
inward.  So for 19 words read, the reader doesn't have any idea they're reading
about a command that edits the history file.

Fixed: "Fix Command within history list."

Additional comment: Sounds as if fc edits the history memory list and not the
history file.  Maybe clarify further "the type of history list". All grammar
and punctuation seems proper within the command description, but I'm thinking
the examples for the first "first last" and second "pat=rep command" are
confusing.  Within my ten years, I've never used this command so I can't help
more on clarifying further for others. :-/

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

Section: SHELL BUILTIN COMMANDS
    getopt

Location: Third paragraph, third sentence.

Sentence: "In normal operation diagnostic messages are printed when invalid
options or missing  option arguments are encountered."

Comment: Missing comma.

Fixed: "In normal operation, diagnostic messages are printed when invalid
options or missing option arguments are encountered."

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

Section: SHELL BUILTIN COMMANDS
    history

Location: Switches/Options (-a,) -n, -r, -w

Comment: These options describe all very similar, if not identical operations.
If I'm not mistaken, some are pertaining to the "history list within memory" and
some pertaining to the "history list file".  The following is a suggestion for
a more clear description for readers on the following -n, -r, -w ... and maybe
need a little more.


Sentence: "-n  Read the history lines not already read from the history file
into the current history list.  These are lines appended to the history file
since the beginning of the current bash session."

Fixed: "-n  Read the history lines not already read from the history file
into the current history list in memory. These lines are appended to the
history file since the beginning of the current bash session."
(Reversed "are/lines" within this sentence. Difference between -n & -r???)


Sentence: "-r  Read the contents of the history file and use them as the
current history."

Fixed: "-r  Read the contents of the history file and use them as the
current history list within memory.  (In case the file was edited since the
shell was started.)"


Sentence: "-w  Write the current history to the history file, overwriting
the history file's contents."

Fixed: "-w  Write the current history list within memory to the history file,
overwriting the history file's contents."

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

Section: SHELL BUILTIN COMMANDS
    jobs

Location: jobspec, "spec" suffix.

Comment: Does the term spec seem a little general? I know it's defined
previously within initial commandspec previously.  However, isn't common usage
to specify the "job ID", as such, should say so?  Maybe a good sentence
somewhere ing the beginning of the Bash Manual explaining *spec is a synonym for
ID number.

Sentence:   "-r     Restrict output to running jobs."
            "-s     Restrict output to stopped jobs."

Comment: Again, the term restrict is used again when "show only" would is more
commonly used.

Sentence: "If jobspec is given, output is restricted to information about that
job."

Proposed Fix: "If jobspec is given, shows only information about the specified 
job."

<shrugs> after reading over "restrict" 20-40 times, I'm getting used to seeing
it now.  It's just the first 10-20 times reading it, it doesn't spawn the
thought of "only showing specified stdout".  My comments for this command are
really just thoughts or some ideas.

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

Section: SHELL BUILTIN COMMANDS
    local

Location: Last sentence of only paragraph.

Sentence: "The return status is 0 unless local is used outside a function, an
invalid name is  supplied, or name is a readonly variable."

Comment: I've found out in the past months, semi-colons are really neat things
and are not frowned upon, matter of fact think they're encouraged.  Google
semi-colon usage.  Semi-colons are used where a lot of commas are used, such a
lists.  You can replace the major comma with a semi-colon or place a semi-colon
any where a longer pause is needed compared to a regular pause instated by a
comma.)

Fix: "The return status is 0; unless local is used outside a function, an
invalid name is  supplied, or name is a readonly variable."

Additional Comment: A lot more can be done with this sentence, but over all I
just fixed the "one too many comments" by replacing one with a semi-colon.
Didn't feel like over-writing the original author's style, the semi-colons
preserve his/her style. ;-)

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


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