Bump .Dd as well.
Submitted by: bde (earlier version)
Details
Details
- Reviewers
emaste wblock imp - Group Reviewers
manpages - Commits
- rS306748: style(9): Some additional clarification
Diff Detail
Diff Detail
- Repository
- rS FreeBSD src repository - subversion
- Lint
Lint Not Applicable - Unit
Tests Not Applicable
Event Timeline
| share/man/man9/style.9 | ||
|---|---|---|
| 119 ↗ | (On Diff #20549) | This is a stray comma. i.e. is latin for 'That is' and you wouldn't put a comma after that phrase. |
| 128 ↗ | (On Diff #20549) | This changes the meaning from 'include these first' to 'only include these first when you have to' which is not desirable and is more than a 'clarification'. |
| 132–136 ↗ | (On Diff #20549) | I think this note should be removed entirely because the vast majority of files will have #include <sys/cdefs.h> at the top. This wasn't the case when this advise was written. |
| share/man/man9/style.9 | ||
|---|---|---|
| 119 ↗ | (On Diff #20549) | (This change comes from bde@.) I'm familiar with "id est." Actually, I would put a comma after that phrase in English as well. (That's why igor(1) suggests commas after i.e. and e.g.) |
| 128 ↗ | (On Diff #20549) | This comes from bde@. I'm happy to change it. I don't like the "Include foo or bar but not both and include it first" sentence as-is. I didn't want to drag you into grammar bikeshedding, since you had previously expressed disinterest in that. |
| 132–136 ↗ | (On Diff #20549) | Fair enough. |
| share/man/man9/style.9 | ||
|---|---|---|
| 119 ↗ | (On Diff #20549) | I would also put a comma after that phrase; some random sites suggest the comma is typical in American English and not in British English. The Chicago Manual of Style and AP Stylebook both ask for the comma. |
Comment Actions
- Clarify section on kernel includes. Explicitly order cdefs.h, types/params, then alpha-sorted other headers.
- Remove stale reference to types/param.h including cdefs.h.
| share/man/man9/style.9 | ||
|---|---|---|
| 119 ↗ | (On Diff #20549) | Checked with my wife who is a professional editor and you are correct. Always put a , after i.e. |
| share/man/man9/style.9 | ||
|---|---|---|
| 122–126 ↗ | (On Diff #20557) | I'm not sure this clarifies things. It seems to imply you might have #include <sys/cdefs.h> #include <sys/types.h> #include <sys/foo.h> while it's actually an optional #include <sys/cdefs.h>
__FBSDID("$FreeBSD$"); |
| 153 ↗ | (On Diff #20557) | Maybe Do not include files from /usr/include in files in the kernel.? |
| share/man/man9/style.9 | ||
|---|---|---|
| 119 ↗ | (On Diff #20557) | In normal English, the need for the comma is clearer. Which helps to illustrate my normal suggestion, just use English. We are not worried about saving space and Latin is not the dominant language of computers. The concern here should be for clarity first. |
| 124 ↗ | (On Diff #20557) | As above, please consider s/i.e./that is/ s/e.g./for example/. |
| 127 ↗ | (On Diff #20557) | "one of" can be replaced with "either". |
| 131 ↗ | (On Diff #20557) | This can be imperative rather than a suggestion (without markup): If either sys/types.h or sys/param.h is needed, include it before other include files. |
| 134 ↗ | (On Diff #20557) | Semicolons should be avoided in most documentation. Here, mixed with code, it is really bad, but easy to replace with a real sentence break: .Po .In sys/param.h includes .In sys/types.h . Do not include both. .Pc |
| 153 ↗ | (On Diff #20557) | Agreed. |
Comment Actions
- Replace two latin abbreviations with appropriate English substitutes
- one of -> either
- imperative types/param firstness
- Adopt vangyzen's userspace header sentence
Comment Actions
A couple of minor niggles
| share/man/man9/style.9 | ||
|---|---|---|
| 119 ↗ | (On Diff #20652) | Actually do we even need "that is" here? It seems clear enough w/o it. |
| 124 ↗ | (On Diff #20652) | It's only included first if it is needed for __FBSDID and other VCS tags, so this can be more clearly stated as if sys/cdefs.h is needed for __FBSDID, include it first. Otherwise, it had been included alphabetically. The only reason to include it these days, apart from some rare corner cases, is for FBSDID. WE should go for clarity over enumerating every possible edge case. |
| share/man/man9/style.9 | ||
|---|---|---|
| 119 ↗ | (On Diff #20652) | Agreed, simpler is better. |
Comment Actions
(Oops, keep forgetting to submit this reply.)
| share/man/man9/style.9 | ||
|---|---|---|
| 134 ↗ | (On Diff #20557) | Is it good style to put two sentences in a parenthesis? The two clauses are extremely short and I think this is actually a clear use of a semicolon. The sentence as-is expresses one idea and justifies it. (In code, it is nonsensical to use semicolons with C preprocessor directives like #include, so it is clearly a use of the English language semicolon.) |