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

quoted

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.

quoted

quoted

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.

quoted

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 .

quoted

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