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 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
@@ -3529,8 +3532,8 @@ For pss
mode only this option specifies the salt length.
Two special values are supported:
-1 sets the salt length to the digest length.
-When signing -2 sets the salt length to the maximum permissible value.
-When verifying -2 causes the salt length to be automatically determined
+When signing, -2 sets the salt length to the maximum permissible value.
+When verifying, -2 causes the salt length to be automatically determined
+\"Without commas, these sentences could potentially be needlessly
+\"confusing; "-2" could be misinterpreted as being the number of sets or
+\"causes.
based on the PSS block structure.
.El
.Pp
@@ -5202,7 +5205,7 @@ Normally, the input message is converted to
.Qq canonical
format which uses 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
@@ -5601,7 +5605,7 @@ The policy that the client expects the TSA to use for
creating the
time stamp token.
Either dotted OID notation or OID names defined
in the config file can be used.
-If no policy is requested the TSA uses its own default policy.
+If no policy is requested, the TSA uses its own default policy.
.It Fl text
Output in human-readable text format instead of DER.
.El
@@ -5662,7 +5666,7 @@ The key password source.
The default policy to use for the response.
Either dotted OID notation or OID names defined
in the config file can be used.
-If no policy is requested the TSA uses its own default policy.
+If no policy is requested, the TSA uses its own default policy.
.It Fl queryfile Ar request.tsq
The file containing a DER-encoded time stamp request.
.It Fl section Ar tsa_section
@@ -5907,7 +5911,7 @@ The
should contain one or more CRLs in PEM format.
.It Fl crl_check
Check end entity certificate validity by attempting to look up a valid CRL.
-If a valid CRL cannot be found an error occurs.
+If a valid CRL cannot be found, an error occurs.
.It Fl crl_check_all
Check the validity of all certificates in the chain by attempting
to look up valid CRLs.
@@ -6560,7 +6564,7 @@ Print the full certificate in text form.
A trusted certificate is a certificate which has several
additional pieces of information attached to it such as the permitted
and prohibited uses of the certificate and an alias.
-When a certificate is being verified at least one certificate must be trusted.
+When a certificate is being verified, at least one certificate must be trusted.
By default, a trusted certificate must be stored locally and be a root CA.
The following are x509 trust settings options:
.Bl -tag -width "XXXX"
diff --git a/usr.sbin/vipw/vipw.8 b/usr.sbin/vipw/vipw.8
index f014901e361..3bd5973a9ed 100644
--- a/usr.sbin/vipw/vipw.8
+++ b/usr.sbin/vipw/vipw.8
@@ -77,7 +77,7 @@ Which type of cipher is used to encrypt the password
information
depends on the configuration in
.Xr login.conf 5 .
.Sh ENVIRONMENT
-If the following environment variable exists it will be utilized by
+If the following environment variable exists, it will be utilized by
.Nm vipw :
.Bl -tag -width EDITOR
.It Ev EDITOR
diff --git a/usr.sbin/ypserv/mkalias/mkalias.8
b/usr.sbin/ypserv/mkalias/mkalias.8
index cd3d8d4c751..5abbd4112d9 100644
--- a/usr.sbin/ypserv/mkalias/mkalias.8
+++ b/usr.sbin/ypserv/mkalias/mkalias.8
@@ -72,7 +72,8 @@ Verbose mode.
Use this map as input.
.It Ar output
Use this map as output.
-If the output map isn't given don't create database.
+If the output map isn't given, don't create a database.
+\"An article was also needed in this sentence.
Can be useful together with
.Fl E
or
diff --git a/usr.sbin/ypserv/ypserv/ypserv.8 b/usr.sbin/ypserv/ypserv/ypserv.8
index 11dc16876ab..3f8fe3fe036 100644
--- a/usr.sbin/ypserv/ypserv/ypserv.8
+++ b/usr.sbin/ypserv/ypserv/ypserv.8
@@ -68,12 +68,12 @@ This file can have any name since it's given by the
argument to
.Fl a
(use full path).
.Pp
-If a host isn't secure all queries to the server will result in a YP_NODOM
+If a host isn't secure, all queries to the server will result in a YP_NODOM
result.
.Pp
If the file
diff --git a/usr.sbin/ypserv/ypserv/ypserv.acl.5
b/usr.sbin/ypserv/ypserv/ypserv.acl.5
index 2a3e50a4713..42af8ac8a55 100644
--- a/usr.sbin/ypserv/ypserv/ypserv.acl.5
+++ b/usr.sbin/ypserv/ypserv/ypserv.acl.5
@@ -61,7 +61,7 @@ or failure depending on which of
or
.Ic deny
was specified.
-If no match was found in the list success is returned.
+If no match was found in the list, success is returned.
.Pp
If access is denied every call will cause a
.Dq no such domain
===== END SLIGHTLY-LESS-LONG-ASS DIFFS =====
On Sat, 31 Oct 2020 20:21:54 +0000
Jason McIntyre <j...@kerhand.co.uk> wrote:
> 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
