Re: Patch to add documentation for spec files

[craig at jcb-sc dot com]

>Thanks.  I have applied almost all of your suggested edits to generate
>this new version of the patch.  There was one thing I left out:
>
>: >+ @samp{%i} subsitution.  (See below).
>: 
>: `.)', not `).', when it ends a complete parenthetical sentence.
>
>This may be a style issue here, but I prefer my way.  The way I see it,
>is that the period is not part of the sentance, it is a construct that 
>separates the sentance from whatever follows it.  The parentheses on
>the other hand *are* part of the sentance, since they are affecting
>its voice and interpretation.  Hence the period should come after the 
>closing parenthesis not before it.

First, I see what you're saying, but, the *sentence* is parenthetical,
not the sentence *fragment* resulting from moving the punctuation outside
the parens.  I.e. stripping off the parens should leave a contiguous
sentence.  Consider:

  She told me no.  (Why in the world did I ask her in the first place?)

If this is recast using your interpretation, the result is a parenthetical
sentence fragment, with the *parenthetical* aspect appearing to be the
question, not the fragment itself:

  She told me no.  (Why in the world did I ask her in the first place)?

I don't see any reason to make an exception to this rule for ending a
sentence with `.'.

Second, it's generally unwise, unless you're an English Ph.D. with some
kind of standing (organizationally or otherwise) to try to rewrite rules
of style and usage within the context of an existing project.

The Ph.D. at least would give you some legitimacy, but, even so, you'd
have to make your changes global in fairly short order, else you'd end
up with inconsistencies that'd generate lots of "bug" reports, both
against the form you claimed was no longer correct *and* against your
new form.

I've got no such legitimacy myself, so I try not to rewrite such rules.
I learned (most of) them while working as a tech writer in a group with
quite a number of Ph.D.'s, who made very carefully considered decisions
about just how and why to make changes to the rules of style and usage,
and implemented them across *all* of the technical documentation coming
from that company.

Within the context of GNU work, I believe, one rule change I know of
was made, perhaps, with no Ph.D. "legitimacy" perhaps, but it at least
has been made "globally" and, since it reflects some (British?) style
and thus has pre-existing legitimacy, *and* since (like your change
tries to) it actually makes sense, I believe it's been reasonably
successful.  I.e. no readers actually confused by the results, and
(probably) few bug reports about the results being "wrong".  I'm referring
to the rule that moves unquoted punctuation outside of quotes, thus
changing from the American English (IIRC) style, e.g.

  A list of spec rules is put into a "spec file."

to the more *technically* consistent, British (?) style:

  A list of spec rules is put into a "spec file".

Due to the way double quotes are typeset, the former (presumably) *looks*
better to the reader, but the latter is more consistent with how other
forms of quoting, including implicit ones such as switching to a monospace
font for an example or using italics for a term, are necessarily expressed
(though, unfortunately, not yet unforced) for technical correctness.
Consider:

  The result of evaluating the expression is @var{foo}; this value can
  be stored in a variable.

(Okay, not an illustration of great writing, but the point is that the
semicolon comes *outside* whatever quoting is used to render @var,
so the reader doesn't get misled into thinking the semicolon is part
of the variable name.)

(FWIW, the problem of "enforcement" is that the rules we have, and the
software that implements them, don't assure truly readable results in
all cases.  Consider:

  You must use a fully qualified domain name such as @samp{example.com}.

The problem here is that if @samp gets rendered in boldface, the reader
will not necessarily be able to tell whether the period after ".com" is
boldface, and "example.com" is *not* a fully qualified domain name,
so the reader (myself, certainly ;-) is left wondering whether the
closing period was accidentally left off, as so often happens, the
correct sentence being:

  You must use a fully qualified domain name such as @samp{example.com.}.

Enforcement might include not allowing a @samp to be immediately preceded
or followed by any symbol that, itself, is not easily discernible
vis-a-vis whether it is part of the @samp in all supported renderings.)

So, by going with this quoting-punctuation change across all GNU docs
(if I'm remembering where I read this rule correctly), consistency was
actually *increased*.

That would not be the case for your usage of punctuation with regard
to complete parenthetical sentences.

An example of GNU making a mistake in style was the insistence on
trying to use "gender-neutral" language ("The user views per file using
a text editor") in one particular document.  I objected strenuously
to that decision, mainly because it's (IMO) a wrong-headed solution to
a mis-stated problem, but also because, when I failed to convince, it meant
I had to discontinue working on (by offering suggestions to), even frequently
reading, that document, due to the increased effort no longer being worth
the results obtained.

The result is that one document (or more) in the GNU project is (still?)
written in a "native" language that is not English, but claims to be.  That
means not only that no official English *translation* of the document will
be permitted -- since the whole point of this aspect of the PC movement
is to *eliminate* the gender-specific form of English, it's unlikely the
FSF people who supported this move would allow such a translation as
an official product of the FSF -- but that cutting-and-pasting across
documents (say, from my g77 manual) is no longer feasible without
some kind of translation (automated, but probably human), among other
difficulties that are typical of trying to maintain a set of documents,
each written in its own style or language.

Had the decision been made to offer gender-neutral *translations* of
GNU documents, I would not have objected in the least.  Had it been
to make *all* GNU documents gender-neutral, I would have objected, but
probably continued working on g77 docs (at least), though (if it had
been permitted) in classic English instead, leaving the translation to
the official, gender-neutral, version to others.

After all, learning to read *quickly* and write *effectively* in a new
language takes time.  If *I'm* going to learn a new language, it's more
likely to be Esperanto, Spanish, French, or German than gender-neutral
English, because I see it as less likely to succeed than even Esperanto.

In summary, don't change the rules, unless you're willing to make the
changes *globally* and take responsibility for all the problems (however
spurious you might consider them) that result from your changes.

        tq vm, (burley)