#251 List of small mistakes found in documentation of Artistic Style

2.x
open
nobody
None
5
2014-04-22
2013-11-11
Mofi
No

I read very carefully the documentation of Artistic Style and found some mistakes which I want to report with this ticket.

Foreword on the suggestions for corrections on documentation page:

Occurrences of paren or parens in describing text no referencing name of an option should be replaced by parenthesis or parentheses or whatever is the right word in the context.

There are 4 occurrences of filename and 7 occurrences of file name. In the detailed list below I make the suggestions to standardize the spelling to file name.

There are 4 occurrences of filepath and only 1 occurrence of file path. In the detailed list below I make the suggestions to standardize the spelling to file path.


Detailed list of mistakes (in my point of view) with the suggestions for correction:


The chapter Wildcards and Recursion contains the 2 sentences:

For Linux use double quotes around paths whose filename contains wildcards.
For Windows use double quotes around paths whose filename contains spaces.

Both filename should be replaced by file name.


The chapter Usage contains the sentence:

The block parens [ ] indicate that more than one option or more than one filename can be entered.

I suggest to write brackets instead of parens as parens is not an English word and parentheses are round brackets. And filename should be changed to file name.


Description of --style=linux / --style=knf / -A8 contains the sentence:

Brackets are attached to everything else including, statements within a function, ...

The comma after the word including should be removed as misplaced here.


Description of --min-conditional-indent=# / -m# contains the sentence:

The lines will be aligned with the paren on the preceding line.

I suggest to write parenthesis instead of paren.


Description of --pad-header / -H contains the sentence:

Insert space padding after paren headers only (e.g. 'if', 'for', 'while'...).

It is not 100% clear if paren means here parenthesis or parent. The example makes it clear that a space is inserted between the keyword and the first parenthesis which belongs to the condition/loop statement. I suggest to write parent instead of "paren" as I think, this is the right word here.


Description of --unpad-paren / -U contains the sentence:

This option can be used in combination with the paren padding options ...

I suggest to replace paren by parenthesis in this sentence.

And this explanation contains also the sentence:

For example, if a source has parens padded on both the inside and outside, ...

I suggest to write parentheses instead of parens.


Description of --break-elseifs / -e contains in the example code before reformatting:

else if (isFoo2()) }
    bar2;
}

The first brace must be an opening brace { instead of a closing brace } as the example code after reformatting shows.


Description of --align-reference=name / -W3 contains the sentence:

Pointers are not changes by this option.

changes should be changed, a classic typing error.


Description of --add-one-line-brackets / -J contains the sentence:

Add one line brackets to unbracketed one line conditional statements (e.g. 'if', 'for', 'while'...).

There are 2 spaces between statements and (e.g.. The first space which is a non breaking space should be deleted.


Description of --remove-comment-prefix / -xp contains the sentence:

Text that is less than one is indent is indented to one indent.

The second is in this sentence between one and indent is misplaced and should be removed.


Description of --max-code-length=# / -xC# contains the sentence:

Lines without logical conditionals will break on a logical conditional (||, &&, ...), comma, paren, semicolon, or space.

The word paren should be replaced by parenthesis.


The chapter Objective-C Options contains in first paragraph the sentence:

If you are not getting the paren and square bracket alignment you want, try increasing this value.

The word paren should be replaced by parenthesis.


Description of --pad-method-colon=none / -xP0 contains the sentence:

Colons immediately preceding a paren will not be padded.

The word paren should be replaced by parenthesis.


Description of --suffix=#### contains the sentence:

Append the suffix #### instead of '.orig' to original filename (e.g. --suffix=.bak).

The word filename should be changed to file name.


Description of --recursive / -r / -R contains the 2 sentences:

Linux users should place the filepath and name in double quotes ...
Windows users should place the filepath and name in double quotes ...

Both filepath should be replaced by file path.


Description of --exclude=#### contains the 2 sentences:

Excludes are matched from the end of the filepath.
The filepath and name may be placed in double quotes (e.g. --exclude="foo bar.cpp").

Both filepath should be replaced by file path.


That's all.

Discussion