Re: Diff: Introductory Clause Comma Crap
Mr. MCINTYRE:
> Mr. MACINTYRE... you must mean my dad!
:^)
> commas are really subjective, so a massive comma diff is always likely
> to be problematic. sentence clauses do not always need commas. sometimes
> commas just make the text harder to read.
However, the comma rules which are specified at the Web site whose URL
was attached to VARIK's previous message _do_ exist for a reason; the
correct application of these rules tends to increase clarity. But there
do exist unjustifiable "stylistic" choices.
> in a if/then sentence structure, "then" indicates the second
> clause. the comma is redundant. "then" performs the role of a comma
However, omitting the comma which is placed after an introductory
clause but before "then" can lead to confusion.
= BEGIN PROOF =
Let there exist a sentence $s =$ "If $x > y$ then $z$.".
For all sentences, the meaning of a sentence is ambiguous iff
$\#\left\{\textrm{FEASIBLE MEANING OF SENTENCE}\left\} > 1$.
Sentence $s$ can be interpreted as "if $x > y$ then, $z$",
which is approximately semantically equivalent to "if $x > y$ at
the previously-mentioned point in time, then $z$". Although such
an interpretation is not terribly often correct, bad habits, e.g.,
overlooking such potential sources of confusion, are formed quickly.
However, sentence $s$ can also be interpreted as "if $x > y$, then
$z$", which is not semantically equivalent to "if $x > y$ at the
previously-mentioned point in time, then $z$".
Therefore, the meaning of sentence $s$ is ambiguous as a result of
omitting the comma which would have been placed after the
introductory clause but before "then".
Therefore, omitting the comma which is placed after the
introductory clause but before "then" can lead to ambiguity.
= END PROOF =
> i think you should follow philip's advice to supply a small diff, check
> whether such changes made wholesale would be welcome, then proceed.
WILCO.
> i;d be happy to look over a diff where the clauses are not marked with
> "then", such as here:
See the attached diffs.
> in this case it is really hard to tell where one clause ends and another
> starts - the comma improves readability. in addition, "an nosuchinstance"
> should
> be "a nosuchinstance".
Fixing incorrect article usage was not the goal of the previous diff assortment;
the solution to this type of problem shall receive a dedicated
twenty-thousand-line message. :^)
KUTGW,
Varik "NOT A COMPUTER PROGRAMMER!!!" Valefor
= BEGIN SLIGHTLY-LESS-LONG-ASS DIFFS =
diff --git a/share/man/man4/audio.4 b/share/man/man4/audio.4
index 94a1c227c2f..00d099e392d 100644
--- a/share/man/man4/audio.4
+++ b/share/man/man4/audio.4
@@ -166,11 +166,13 @@ Bytes per sample; if specified, it must be large enough
to hold all bits.
By default it's set to the smallest power of two large enough to hold
.Va bits .
.It Va sig
-If set (i.e. non-zero) then the samples are signed,
-otherwise they are unsigned.
+If set (i.e., non-zero), then the samples are signed;
+otherwise, they are unsigned.
+\"This sentence was a run-on.
.It Va le
If set, then the byte order is little endian;
-if not it is big endian;
+if not, it is big endian;
+\""[I]f not" is an introductory phrase, and introductory phrases are followed
by commas.
-it's meaningful only if
+It's meaningful only if
+\"The capitalisation of this sentence was fixed.
.Va bps
> 1.
diff --git a/usr.bin/openssl/openssl.1 b/usr.bin/openssl/openssl.1
index e364586f5ad..7c0af459fae 100644
--- a/usr.bin/openssl/openssl.1
+++ b/usr.bin/openssl/openssl.1
@@ -1121,7 +1121,7 @@ commands.
.It Fl binary
Normally the input message is converted to "canonical" format which is
effectively using CR/LF as end of line, as required by the S/MIME
specification.
-When this option is present no translation occurs.
+When this option is present, no translation occurs.
This is useful when handling binary data which may not be in MIME format.
.It Fl CAfile Ar file
A file containing trusted CA certificates, used with
@@ -1971,7 +1971,8 @@ Encrypt the private key with DES, triple DES, or
any other cipher supported by
.Nm openssl .
A pass phrase is prompted for.
-If none of these options is specified the key is written in plain text.
+If none of these options are specified, the key is written in plain text.
+\""[I]s" was changed to "are" to maintain consistency with the rest of this
manual page.
This means that using the
.Nm ec
utility to read in an encrypted key with no
@@ -1982,7 +1983,7 @@ These options can only be used with PEM format output
files.
.It Fl in Ar file
The input file to read a key from,
or standard input if not specified.
-If the key is encrypted a pass phrase will be prompted for.
+If the key is encrypted, a pass phrase will be prompted for.
.It Fl inform Cm der | pem
The input format.
.It Fl noout
@@ -3356,7 +3358,7 @@ is acceptable, such as
.It Fl in Ar file
The input file to read from,
or standard input if not specified.
-If the key is encrypted
Re: Diff: Introductory Clause Comma Crap
On Sun, Nov 01, 2020 at 04:14:19PM -0500, VARIK VALEFOR wrote:
> Mr. MCINTYRE:
>
> > Mr. MACINTYRE... you must mean my dad!
> :^)
>
> > commas are really subjective, so a massive comma diff is always likely
> > to be problematic. sentence clauses do not always need commas. sometimes
> > commas just make the text harder to read.
> However, the comma rules which are specified at the Web site whose URL
> was attached to VARIK's previous message _do_ exist for a reason; the
> correct application of these rules tends to increase clarity. But there
> do exist unjustifiable "stylistic" choices.
>
well, there are not so much comma rules as comma suggestions.
> > in a if/then sentence structure, "then" indicates the second
> > clause. the comma is redundant. "then" performs the role of a comma
> However, omitting the comma which is placed after an introductory
> clause but before "then" can lead to confusion.
>
> = BEGIN PROOF =
> Let there exist a sentence $s =$ "If $x > y$ then $z$.".
>
> For all sentences, the meaning of a sentence is ambiguous iff
> $\#\left\{\textrm{FEASIBLE MEANING OF SENTENCE}\left\} > 1$.
>
> Sentence $s$ can be interpreted as "if $x > y$ then, $z$",
> which is approximately semantically equivalent to "if $x > y$ at
> the previously-mentioned point in time, then $z$". Although such
> an interpretation is not terribly often correct, bad habits, e.g.,
> overlooking such potential sources of confusion, are formed quickly.
>
> However, sentence $s$ can also be interpreted as "if $x > y$, then
> $z$", which is not semantically equivalent to "if $x > y$ at the
> previously-mentioned point in time, then $z$".
>
> Therefore, the meaning of sentence $s$ is ambiguous as a result of
> omitting the comma which would have been placed after the
> introductory clause but before "then".
>
> Therefore, omitting the comma which is placed after the
> introductory clause but before "then" can lead to ambiguity.
> = END PROOF =
>
yes, the point being that there are not so much rules as suggestions.
> > i think you should follow philip's advice to supply a small diff, check
> > whether such changes made wholesale would be welcome, then proceed.
> WILCO.
>
roger that!
> > i;d be happy to look over a diff where the clauses are not marked with
> > "then", such as here:
> See the attached diffs.
>
> > in this case it is really hard to tell where one clause ends and another
> > starts - the comma improves readability. in addition, "an nosuchinstance"
> > should
> > be "a nosuchinstance".
> Fixing incorrect article usage was not the goal of the previous diff
> assortment;
> the solution to this type of problem shall receive a dedicated
> twenty-thousand-line message. :^)
>
if our manual pages require a twenty thousand line article fix diff i am
hanging up my boots.
i committed your diff - with thanks - but changed audio.4 to work
without commas.
thanks,
jmc
> KUTGW,
> Varik "NOT A COMPUTER PROGRAMMER!!!" Valefor
>
> = BEGIN SLIGHTLY-LESS-LONG-ASS DIFFS =
> diff --git a/share/man/man4/audio.4 b/share/man/man4/audio.4
> index 94a1c227c2f..00d099e392d 100644
> --- a/share/man/man4/audio.4
> +++ b/share/man/man4/audio.4
> @@ -166,11 +166,13 @@ Bytes per sample; if specified, it must be large enough
> to hold all bits.
> By default it's set to the smallest power of two large enough to hold
> .Va bits .
> .It Va sig
> -If set (i.e. non-zero) then the samples are signed,
> -otherwise they are unsigned.
> +If set (i.e., non-zero), then the samples are signed;
> +otherwise, they are unsigned.
> +\"This sentence was a run-on.
> .It Va le
> If set, then the byte order is little endian;
> -if not it is big endian;
> +if not, it is big endian;
> +\""[I]f not" is an introductory phrase, and introductory phrases are
> followed by commas.
> -it's meaningful only if
> +It's meaningful only if
> +\"The capitalisation of this sentence was fixed.
> .Va bps
> > 1.
>
>
>
> diff --git a/usr.bin/openssl/openssl.1 b/usr.bin/openssl/openssl.1
> index e364586f5ad..7c0af459fae 100644
> --- a/usr.bin/openssl/openssl.1
> +++ b/usr.bin/openssl/openssl.1
> @@ -1121,7 +1121,7 @@ commands.
> .It Fl binary
> Normally the input message is converted to "canonical" format which is
> effectively using CR/LF as end of line, as required by the S/MIME
> specification.
> -When this option is present no translation occurs.
> +When this option is present, no translation occurs.
> This is useful when handling binary data which may not be in MIME format.
> .It Fl CAfile Ar file
> A file containing trusted CA certificates, used with
> @@ -1971,7 +1971,8 @@ Encrypt the private key with DES, triple DES, or
> any other cipher supported by
> .Nm openssl .
> A pass phrase is prompted for.
> -If none of these options is specified the key is written in plain text.
> +If none of these options are specified, the key is written in plain text.
> +\""[I]s" was changed to "are" to maintain consistency
Re: Diff: Introductory Clause Comma Crap
Mr. GUENTHER: > As a procedural side-note, I would like to suggest that before going on a > quest to make a change that touches so many files cross OpenBSD's code > base, that it would be wise to send out a diff with just a couple examples > and verify that the particular item of concern and the proposed fix is > agreed upon before spending the time to search and edit many other pages. The quoted suggestion is rather good and shall be followed in the future -- in fact, this approach should have been obvious. KUTGW, Varik "NOT A COMPUTER PROGRAMMER!!!" Valefor -- On Sat, 31 Oct 2020 10:47:42 -0900 Philip Guenther wrote: > On Sat, Oct 31, 2020 at 10:19 AM VARIK VALEFOR wrote: > > > This message contains even more grammatical fixes for the OpenBSD > > manual pages. To ensure that the changes which are proposed in this > > message can be justified, this message primarily fixes only a single > > type of error: the absence of commas after introductory clauses. > > > > As a procedural side-note, I would like to suggest that before going on a > quest to make a change that touches so many files cross OpenBSD's code > base, that it would be wise to send out a diff with just a couple examples > and verify that the particular item of concern and the proposed fix is > agreed upon before spending the time to search and edit many other pages. > > This is true not just for documentation changes but code changes, of > course: doing lots of work before there's "buy-in" is risking your time. > > > Philip Guenther
Diff: Introductory Clause Comma Crap
Sir or Madam:
This message contains even more grammatical fixes for the OpenBSD
manual pages. To ensure that the changes which are proposed in this
message can be justified, this message primarily fixes only a single
type of error: the absence of commas after introductory clauses.
Unless otherwise specified, for all changes which are proposed in this
message, a change adds a comma after an introductory clause; for all
introductory clauses, a comma _must_ follow an introductory clause.*
However, these changes should not only be made because the changes fix
incorrect things; rather, these changes should be made because many
changes greatly increase the clarity of the manual pages; incorrect
comma usage can lead to the misinterpretation of things, which is
bad... especially in the case of a user manual.
Mr. MACINTYRE mentioned that VARIK's previous message was fairly
unreadable; as such, some spacing has been added to these diffs,
thereby hopefully improving the readability of this message. Any
advice regarding the formatting of this sort of message would be
welcomed; poorly-formatted, i.e., unreadable, messages waste time, and
wasting time sucks.
KUTGW,
Varik "NOT A COMPUTER PROGRAMMER!!!" Valefor
*https://owl.purdue.edu/owl/general_writing/punctuation/commas/commas_after_introductions.html
= BEGIN DIFFS =
diff --git a/bin/csh/csh.1 b/bin/csh/csh.1
index f984356e846..2e89bcc0c3a 100644
--- a/bin/csh/csh.1
+++ b/bin/csh/csh.1
@@ -1039,7 +1039,7 @@ and
If braces
.Ql {
.Ql }
-appear in the command form then the modifiers
+appear in the command form, then the modifiers
must appear within the braces.
The current implementation allows only one
.Ql \&:
@@ -1282,7 +1282,7 @@ is given to the command as its standard input.
The file
.Ar name
is used as the standard output.
-If the file does not exist then it is created;
+If the file does not exist, then it is created;
if the file exists, it is truncated; its previous contents are lost.
.Pp
If the variable
@@ -1469,7 +1469,7 @@ l symbolic link
.Pp
The specified name is command and filename expanded and then tested
to see if it has the specified relationship to the real user.
-If the file does not exist or is inaccessible then all enquiries return
+If the file does not exist or is inaccessible, then all enquiries return
false, i.e.,
.Ql 0 .
Command executions succeed, returning true, i.e.,
@@ -1477,7 +1477,7 @@ Command executions succeed, returning true, i.e.,
if the command exits with status 0, otherwise they fail, returning
false, i.e.,
.Ql 0 .
-If more detailed status information is required then the command
+If more detailed status information is required, then the command
should be executed outside an expression and the variable
.Ar status
examined.
@@ -1510,7 +1510,7 @@ non-seekable inputs.)
.Ss Built-in commands
Built-in commands are executed within the shell.
If a built-in command occurs as any component of a pipeline
-except the last then it is executed in a sub-shell.
+except the last, then it is executed in a sub-shell.
.Pp
.Bl -tag -width Ds -compact -offset indent
.It Ic alias
@@ -1562,7 +1562,7 @@ statement as discussed below.
.It Ic chdir Ar name
Change the shell's working directory to directory
.Ar name .
-If no argument is given then change to the home directory of the user.
+If no argument is given, then change to the home directory of the user.
If
.Ar name
is not found as a subdirectory of the current directory (and does not begin
@@ -1759,11 +1759,11 @@ executed (this is a bug).
.It Ic endif
If the specified
.Ar expr
-is true then the commands up to the first
+is true, then the commands up to the first
.Ic else
are executed; otherwise if
.Ar expr2
-is true then the commands up to the
+is true, then the commands up to the
second
.Ic else
are executed, etc.
diff --git a/lib/libagentx/subagentx.3 b/lib/libagentx/subagentx.3
index d283ff198e8..23055f4a94c 100644
--- a/lib/libagentx/subagentx.3
+++ b/lib/libagentx/subagentx.3
@@ -524,8 +524,8 @@ Set the return value to an opaque value.
.It Fn subagentx_varbind_counter64
Set the return value to an uint64_t of type counter64.
.It Fn subagentx_varbind_notfound
-When the request is of type GET return an nosuchinstance error.
-When the request is of type GETNEXT or GETBULK return an endofmibview error.
+When the request is of type GET, return an nosuchinstance error.
+When the request is of type GETNEXT or GETBULK, return an endofmibview error.
On endofmibview the next object is queried.
This function can only be called on objects that contain one or more *_dynamic
indices.
diff --git a/lib/libc/crypt/crypt.3 b/lib/libc/crypt/crypt.3
index c8ebf9861d4..721b073e8f7 100644
--- a/lib/libc/crypt/crypt.3
+++ b/lib/libc/crypt/crypt.3
@@ -74,7 +74,7 @@ currently supports a single form.
If it begins
with a string character
.Pq Ql $
-and a number then a different algorithm is used depending on the number.
+and a number, then a different
Re: Diff: Introductory Clause Comma Crap
On Sat, Oct 31, 2020 at 03:14:30PM -0400, VARIK VALEFOR wrote:
> Sir or Madam:
>
> This message contains even more grammatical fixes for the OpenBSD
> manual pages. To ensure that the changes which are proposed in this
> message can be justified, this message primarily fixes only a single
> type of error: the absence of commas after introductory clauses.
>
> Unless otherwise specified, for all changes which are proposed in this
> message, a change adds a comma after an introductory clause; for all
> introductory clauses, a comma _must_ follow an introductory clause.*
> However, these changes should not only be made because the changes fix
> incorrect things; rather, these changes should be made because many
> changes greatly increase the clarity of the manual pages; incorrect
> comma usage can lead to the misinterpretation of things, which is
> bad... especially in the case of a user manual.
>
> Mr. MACINTYRE mentioned that VARIK's previous message was fairly
> unreadable; as such, some spacing has been added to these diffs,
> thereby hopefully improving the readability of this message. Any
> advice regarding the formatting of this sort of message would be
> welcomed; poorly-formatted, i.e., unreadable, messages waste time, and
> wasting time sucks.
>
hi.
Mr. MACINTYRE... you must mean my dad!
thank you for your mail. please read guenther's followup - he makes some
very good points.
commas are really subjective, so a massive comma diff is always likely
to be problematic. sentence clauses do not always need commas. sometimes
commas just make the text harder to read.
look at your very first change:
> KUTGW,
> Varik "NOT A COMPUTER PROGRAMMER!!!" Valefor
>
> *https://owl.purdue.edu/owl/general_writing/punctuation/commas/commas_after_introductions.html
>
> = BEGIN DIFFS =
> diff --git a/bin/csh/csh.1 b/bin/csh/csh.1
> index f984356e846..2e89bcc0c3a 100644
> --- a/bin/csh/csh.1
> +++ b/bin/csh/csh.1
> @@ -1039,7 +1039,7 @@ and
> If braces
> .Ql {
> .Ql }
> -appear in the command form then the modifiers
> +appear in the command form, then the modifiers
in a if/then sentence structure, "then" indicates the second
clause. the comma is redundant. "then" performs the role of a comma.
but depending on the wording, and the number of clauses, a comma might
help to make it more readable.
but you can;t just add them everywhere.
i think you should follow philip's advice to supply a small diff, check
whether such changes made wholesale would be welcome, then proceed.
i;d be happy to look over a diff where the clauses are not marked with
"then", such as here:
> diff --git a/lib/libagentx/subagentx.3 b/lib/libagentx/subagentx.3
> index d283ff198e8..23055f4a94c 100644
> --- a/lib/libagentx/subagentx.3
> +++ b/lib/libagentx/subagentx.3
> @@ -524,8 +524,8 @@ Set the return value to an opaque value.
> .It Fn subagentx_varbind_counter64
> Set the return value to an uint64_t of type counter64.
> .It Fn subagentx_varbind_notfound
> -When the request is of type GET return an nosuchinstance error.
> -When the request is of type GETNEXT or GETBULK return an endofmibview error.
> +When the request is of type GET, return an nosuchinstance error.
> +When the request is of type GETNEXT or GETBULK, return an endofmibview error.
> On endofmibview the next object is queried.
> This function can only be called on objects that contain one or more
> *_dynamic
> indices.
in this case it is really hard to tell where one clause ends and another
starts - the comma improves readability. in addition, "an nosuchinstance" should
be "a nosuchinstance".
good luck!
jmc
> must appear within the braces.
> The current implementation allows only one
> .Ql \&:
> @@ -1282,7 +1282,7 @@ is given to the command as its standard input.
> The file
> .Ar name
> is used as the standard output.
> -If the file does not exist then it is created;
> +If the file does not exist, then it is created;
> if the file exists, it is truncated; its previous contents are lost.
> .Pp
> If the variable
> @@ -1469,7 +1469,7 @@ l symbolic link
> .Pp
> The specified name is command and filename expanded and then tested
> to see if it has the specified relationship to the real user.
> -If the file does not exist or is inaccessible then all enquiries return
> +If the file does not exist or is inaccessible, then all enquiries return
> false, i.e.,
> .Ql 0 .
> Command executions succeed, returning true, i.e.,
> @@ -1477,7 +1477,7 @@ Command executions succeed, returning true, i.e.,
> if the command exits with status 0, otherwise they fail, returning
> false, i.e.,
> .Ql 0 .
> -If more detailed status information is required then the command
> +If more detailed status information is required, then the command
> should be executed outside an expression and the variable
> .Ar status
> examined.
> @@ -1510,7 +1510,7 @@ non-seekable inputs.)
> .Ss Built-in commands
> Built-in commands are executed within the shell.
> If a built-in
Re: Diff: Introductory Clause Comma Crap
On Sat, Oct 31, 2020 at 10:19 AM VARIK VALEFOR wrote: > This message contains even more grammatical fixes for the OpenBSD > manual pages. To ensure that the changes which are proposed in this > message can be justified, this message primarily fixes only a single > type of error: the absence of commas after introductory clauses. > As a procedural side-note, I would like to suggest that before going on a quest to make a change that touches so many files cross OpenBSD's code base, that it would be wise to send out a diff with just a couple examples and verify that the particular item of concern and the proposed fix is agreed upon before spending the time to search and edit many other pages. This is true not just for documentation changes but code changes, of course: doing lots of work before there's "buy-in" is risking your time. Philip Guenther
