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 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
