Message-ID: <20210908035359.rcdgo43qw34yf2ia@localhost.localdomain>
Date:   Wed, 8 Sep 2021 13:54:03 +1000
From:   "G. Branden Robinson" <g.branden.robinson@...il.com>
To:     "Alejandro Colomar (man-pages)" <alx.manpages@...il.com>
Cc:     "Thaddeus H. Black" <thb@...ian.org>, linux-man@...r.kernel.org,
        Michael Kerrisk <mtk.manpages@...il.com>,
        "Dr. Tobias Quathamer" <toddy@...ian.org>,
        linux-ext4@...r.kernel.org, debian-doc@...ts.debian.org
Subject: Re: [PATCH] filename.7: new manual page

[Cc recipients: more typography and man(7) style issues]

Hi Alex,

At 2021-09-06T23:47:37+0200, Alejandro Colomar (man-pages) wrote:
> On 9/6/21 6:59 PM, G. Branden Robinson wrote:
> > In the groff man page corpus, the rule above is honored in general
> > but slightly relaxed for section 7 pages, due to that section's
> > miscellaneous nature--it's hard to argue that section naming
> > conventions for commands, library interfaces, device drivers, or
> > file formats should apply to section 7 pages, because if they did,
> > the page in question would be in one of those sections instead (or
> > portions of it moved thence).
> 
> I would still use DESCRIPTION, I think.

I do as well[1]; while I haven't yet encountered a situation where it
seemed sensible to dispose of it, I would lend writers of section 7
pages that freedom.

> I think we don't lose much by using subsections instead, and we gain
> consistency.

I'm a little uneasy with some of the hacks I've seen to contrive
sub-subsections in man pages.  I saw one within the past few months but
can't remember the specifics.  Sending this mail may prompt my
recollection since that's how my memory seems to work.  I'll follow up
if it does.

> > > See man-pages(7):
> > > 
> > >     Use semantic newlines
> > >         In the source of a manual page,  new  sentences  should
> > >         be started  on  new  lines, and long sentences should be
> > >         split into lines at clause breaks  (commas,  semicolons,
> > >         colons, and  so on).  This convention, sometimes known as
> > >         "semantic newlines", makes it easier to see the  effect
> > >         of  patches, which often operate at the level of
> > >         individual sentences or sentence clauses.
> > > 
> > Maybe I've developed temporary blindness, but I don't see where
> > Thaddeus didn't use semantic newlines in the adjacent quoted
> > material.
> 
> "UTF-8" is an adjective to "characters"; I'd break just after "of",
> since everything after it is a single nominal phrase (I hope I used
> the correct term; I only did syntactical analysis in Spanish at
> school).

Ah, that's a "phrase" rather than a "clause".  The terms are
distinguished in traditional (schoolhouse) English grammar; loosely, a
"phrase" is a set of words operating as a "part of speech" (noun, verb,
adjective, adverb) whereas a "clause" is a group of phrases with a
"subject" and a "predicate".  Generally, sentence can be decomposed into
one or more clauses, each of which can itself be expressed as a sentence
with little or no recasting.

There's nothing about phrases or phrase boundaries in the guidance
quoted above.  At first blush I would recommend against adding it
because it's harder to find such boundaries automatically.  When I
revise man pages in the groff project it's easy to find clause
boundaries with the vi search pattern "/[;!?.]."  (I usually add a
comma and a closing parenthesis to this pattern because I also prefer to
break after commas and multi-word parentheticals, but I'm not militant
about prescribing this expanded sense of semantic newlines.))

Someone trained in linguistics at the university level could doubtless
speak about this subject with much greater precision.  (And then there's
Huddleston and Pullum's iconoclastic _Cambridge Grammar of the English
Language_...)

> There were more obvious points below that infringed this rule, but I
> wanted to point out the first one.

I don't think most native English speakers are likely to interpret the
semantic newline rule as you do because we absorb a different denotation
of "clause" when we're taught elementary formal grammar.

> > It is a typographical best practice.  It is often good typography to
> > keep a line break from occurring between a preposition and its
> > object, or between nouns where one is used as a determiner for the
> > other.  Thaddeus has supplied an example of the former above, and
> > for the latter consider the following[3].
[...]

I goofed up the point I was trying to make here.  I provided a duplicate
example of the case I attributed to Thaddeus.  Let me try that again.

Overflow is guaranteed for a sufficiently large
.RI integer\~ n .

> > English style manuals tend to discourage the Lisp effect of nested
> > parentheses[5].
> 
> Actually, [4].

Hah!  I need a footnote assistance plug-in for Vim.  I'm sure someone
will tell me that Emacs org-mode does this for them.

> I'll go for the brackets in the outer ones, as Maths do, as Thaddeus
> did, and as you pointed out, as man references already use () and
> changing those would be weird at least; printf[3] seems like you're
> pointing to a [3] at the bottom of a page.

Indeed so.  In the next release of groff, ms will bracket footnotes like
this automatically in nroff mode (that is, for terminal output)[2].  I
recently noticed that the me(7) package does not, and I think it should.

> I have trouble myself when reading those expressions, especially when
> mixing that with another negation.  I have to mentally cancel out
> negations first :D

It's a tough problem.  When I was learning Spanish I had trouble
acquiring the practice of reinforcing negatives in sentences ("No
tenemos [no] dios, no tenemos [no] jefes."[??])  How many negatives do I
need?  When do I stop?

Getting back to English, I would be over the moon if my fellow native
speakers would quit misrepresenting the logical negation of "all horses
are animals" as "all horses are not animals".  You see and hear this all
the time, notoriously from journalists.

> I like that reasoning.  I'd like to be able to use .P.  But that would
> mean adding even more inconsistency to the man-pages (of course we
> wouldn't change existing pages to use .P at this point).

Granted.  What I do with groff's man pages is that I tend to queue up
style fixes (mentally if nothing else), applying them when I have a
content fix to make to a page.  Over time, things settle into a new
consistency, but patience is required if churn or flag days are to be
avoided.

> I keep reading that list :)

I'm glad you're still there!

Regards,
Branden

[1] ...except in mixed case since groff 1.23.0 will support this.[3]  :)
[2] https://git.savannah.gnu.org/cgit/groff.git/commit/?id=caeede07cd2e6e10134385cca194c52342f46972
[3] https://git.savannah.gnu.org/cgit/groff.git/commit/?id=9503b794e821ef1cf6f705b25dc7abbadb920ad2
    https://git.savannah.gnu.org/cgit/groff.git/commit/?id=0438b1b905ebe9ac5fc678af06db911d25c3a030

Download attachment "signature.asc" of type "application/pgp-signature" (834 bytes)

Powered by blists - more mailing lists