Message-ID: <20210906165926.jujqqjkzraxvsgmc@localhost.localdomain>
Date:   Tue, 7 Sep 2021 02:59:28 +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: this message is only about typography and man(7) style]

Hi Alex,

At 2021-09-06T16:21:09+0200, Alejandro Colomar (man-pages) wrote:
> > +.TH FILENAME 7 2021-09-06 "Linux" "Linux Programmer's Manual"
> > +.SH NAME
> > +.P
> 
> I don't know the history of this (actually, I've always wondered why),
> but .PP and .P are equivalent, AFAIK, and we use .PP.

Yes, they are equivalent.  I know of no man(7) implementation that
distinguishes .LP, .PP, and .P semantically.  groff_man(7)[1] briefly
summarizes the historical growth of the man(7) macro, register, and
string name repertoire.

In the groff project, after years of being on the fence about the issue,
as a style matter I settled on using and recommending simply ".P"[2].  I
think it relieves the occasional man page author from having to retain
a small amount of knowledge, the kind that has you wondering above.

> > +.SH LEGAL FILENAMES
> 
> See man-pages(7):
> 
>    Sections within a manual page
>        The  list  below  shows conventional or suggested sections.
>        Most manual pages should include at least  the  highlighted
>        sections.   Arrange  a new manual page so that sections are
>        placed in the order shown in the list.
> 
>               NAME
>               SYNOPSIS
>               CONFIGURATION    [Normally only in Section 4]
>               DESCRIPTION
>               OPTIONS          [Normally only in Sections 1, 8]
>               EXIT STATUS      [Normally only in Sections 1, 8]
>               RETURN VALUE     [Normally only in Sections 2, 3]
>               ERRORS           [Typically only in Sections 2, 3]
>               ENVIRONMENT
>               FILES
>               VERSIONS         [Normally only in Sections 2, 3]
> 
>               ATTRIBUTES       [Normally only in Sections 2, 3]
>               CONFORMING TO
>               NOTES
>               BUGS
>               EXAMPLES
>               AUTHORS          [Discouraged]
>               REPORTING BUGS   [Not used in man‐pages]
>               COPYRIGHT        [Not used in man‐pages]
>               SEE ALSO
> 
>        Where a traditional heading would  apply,  please  use  it;
>        this kind of consistency can make the information easier to
>        understand.  If you must, you can create your own  headings
>        if they make things easier to understand (this can be espe‐
>        cially useful for pages in Sections 4 and 5).  However, be‐
>        fore  doing this, consider whether you could use the tradi‐
>        tional headings, with some subsections (.SS)  within  those
>        sections.
> 
> You could move sections into subsections of DESCRIPTION, and the
> current subsections into tagged paragraphs (.TP).

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

> > +.P
> > +A filename on a Linux system can consist of almost any sequence of UTF-8
> 
> 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.
> 
> 
> > +characters or, indeed, almost any sequence of bytes.
> > +The exceptions are as follows.

Maybe I've developed temporary blindness, but I don't see where Thaddeus
didn't use semantic newlines in the adjacent quoted material.

> Please, use a separate line and
> .B \e0
> 
> We avoid \f.

Yes!  Thus does the moral arc of the universe bend toward justice!

...or at least readable man(7) source.

> > +from\~\fB0\fR, the printable digit-zero character.
> 
> Why did you use the non-breaking space here (and other places)?  I
> don't think it's necessary.

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

Integer overflow is guaranteed for large values
.RI of\~ n .

I know of no hard rule here, but I have inferred that such break
prevention tends to be applied much more frequently adjacently to one-
or two-character nouns, and seldom to never for longer ones.  I believe
the reason for the practice is to make reading more comfortable; it
would be nice to only _ever_ break lines at phrase and clause
boundaries, but applying a hard rule along these lines leads to worse
esthetics (if the line is adjusted to both margins with large amounts of
inter-word space) or ergonomics (if the line length varies dramatically
within a paragraph).

> > +Workarounds typically exist, chiefly via quotation, escape and the
> > explicit +termination of options processing [see
> > +.BR sh (1)];
> 
> I'd have used parentheses there. No?  Was it, as in Mathematics, to
> clearly differentiate the inner from the outer parentheses?  If so, we
> typically nest parentheses in the manual pages (as in here (see?)).
> 
> However, I don't think it's wrong per se to use brackets...  Is it
> common in other places?  Maybe the add some readability to the text,
> and we hould use them.

English style manuals tend to discourage the Lisp effect of nested
parentheses[5].  The reference I've cited is consistent with other
practices I've seen in the humanities, which is to turn to parentheses
as a first resort and then adopt brackets only when already within a
parenthesized context, whereas mathematical usage is to apply
parentheses to the innermost level of nesting.

Here, however, it would be jarring to change the man page citation style
in a context-dependent manner, so Thaddeus inverted the ordering.  This
is a good practice.  In technical writing, and arguably in _all_
writing, the demands of clarity must outweigh any syntactical or
semantic rules.  Our brains are more powerful parsing engines than any
machine we have yet been able to contrive; it's okay to expect people to
use them.  :D

That blank check having been written, a Hegelian synthesis applies: if
your construction cannot simultaneously serve the demands of grammar,
clarity, and good style...recast until it does!

> Non-native English speakers may have trouble understanding "all but".
> Maybe s/all but/not/?

I think it's okay.  From my limited knowledge of non-English languages,
I expect it to calque in a way that will not startle the intuition.
Personally, I acquired the construction when I was in primary school,
but I admit that saying so invites a charge of being anecdotal.  Or
precocious.  Or loquacious.

> > +.SS Capitalization
> > +.P
> > +A loosely observed convention favors small letters in filenames where no
> > +reason to use capitals exists.
> 
> Most manual pages talking about capitalization typically use the term
> 'case' (uppercase, lowercase, case sensitive, ...); probably because
> of 'toupper()' and 'tolower()'.  I think, for consistency, using the
> same terminology would be better.

This circle could be squared with the subsection heading "Letter case".

> > +.P
> > +Names of types and of certain other entities are sometimes capitalized in
> > +programming languages like\~C++ and Python.
> 
> Do you mean normal user conventions?  I mean, the standard C++ library
> (and the language) doesn't use uppercase, AFAIR.  Not even in the
> cases where C used it (e.g., _Bool)

Stroustrup models first-letter capitalization of namespace, exception,
class, and struct names in _The C++ Programming Language_ (3rd edition,
1997), so it's reasonably likely to show up in projects written in that
language even if it's not in the standard library (which is much too
huge for me to characterize in this respect).

> > +.SH CONFORMING TO
> > +.P
> > +POSIX.1-2008, SUSv4.
> The SUSv4 part of the standard is the same that is in POSIX.1-2008?
> Or does it have any extensions regarding filenames that isn't in
> POSIX?
> 
> If both standards have the same exact contents about filenames, I'd
> simplify this with POSIX.1-2008 only.

Thaddeus is using a citation form modeled in standards(7), a Linux
man-pages project page.  Perhaps that page should offer some guidance
for standards that appear in a comma-separated list in the paragraph
tags.

> > +.BR iswcntrl (3),
> > +.BR iswgraph (3),
> > +.BR mbrtowc (3),
> > +.BR wcrtomb (3),

I think it suffices to mention these functions only in passing in the
body of the man page.  Few readers are going to go straight from
learning what a Unix filename is to multi-byte and wide character string
encoding in C, and the few with that degree of ambition have already
been steered in the right direction.

In my opinion the "See also" section of a man page serves us best if
there are two things it is _not_:

(1) a recapitulation of all man page cross-references encountered in the
    page so far; and
(2) a militantly strict subset of (1).

In my view, "See also" is there to help two kinds of reader:

(A) the kind who has not found the man page they were seeking, but might
    be in the right "neighborhood", and needs a hint to find the correct
    one (a wholly irrelevant page is best abandoned, and the output of
    "man -k" returned to); and
(B) the kind who has found the page they are looking for but require
    greater depth on subsidiary, dependent, or closely-related topics.

As with many things, identifying the members of such a set demands
judgment, and judgment can be difficult, which is why some man page
writers have a tendency to degenerate toward the more robotic
interpretation that I discourage above.  But if that roboticism is what
is sought, we should design a robot to take care of it.  One such
automaton could be a man page cross-reference macro like mdoc(7) has
(possibly with an optional argument to suppress inclusion for case (2)
above), enabling the macro package to generate the "See also" section by
itself.

But I think that machine is something we _don't_ want[5].  We _want_ the
"See also" section of a man page to be a curated product of judgment.

Regards,
Branden

[1] https://man7.org/linux/man-pages/man7/groff_man.7.html

[2] https://git.savannah.gnu.org/cgit/groff.git/commit/?id=cf49e0fe7fdbaff94e21ebdcd3380c3559c2525d

commit cf49e0fe7fdbaff94e21ebdcd3380c3559c2525d
Author: G. Branden Robinson <g.branden.robinson@...il.com>
Date:   Wed Jun 16 00:24:38 2021 +1000

    [man]: Elevate "P" as canonical paragraph macro.

    Unfairly and capriciously elevate "P" as the preferred paragraphing
    macro for the man(7) language.  This is slightly ahistorical; the
    original man macro package from 1979 in fact did not recognize the
    name "P" at all, but did support "LP" and "PP".

    However, "P" did show up in AT&T System III Unix (1980) and later in
    4.3BSD (1986).  I speculate that "LP" and "PP" were supported to
    accommodate the varying paragraphing preferences of those accustomed
    to the ms(7) macro package.  However, anyone familiar with that
    package knows that these two macros mean different things, and have
    differing indentation behavior, which man(7) does not simulate.  In
    that respect, "LP" and "PP" imply too much to ms veterans, and
    nothing useful at all to other man(7) users; the "L" and first "P"
    are superfluous.

    Further, ".P" is frequently typed, and per sound principles of
    Huffman coding, it should be short.  Thus do I hope to buy the
    complaisance of grognards with the cheap bribe of "less typing", a
    preoccupation whose star has not dimmed among Unix geeks in 50
    years.

    * tmac/an-old.tmac (P): Define this is as the "canonical"
      paragraphing macro.

      (LP, PP): Make these aliases of P.

[3] You could also say the following.

Integer overflow is guaranteed for large values of\~\c
.IR n .

But I discourage the use of \c except where necessary because it tends
to confuse people (although in groff Git HEAD I've finally got this
escape sequence described carefully enough that it no longer maddens me
as it did when I first became a contributor[6]).  In the above, if we
omit the output line continuation escape sequence \c, then the line can
break after "of" because that's what a newline in the *roff input stream
_means_.

[4] https://www.eliteediting.com.au/parentheses-within-parentheses/

[5] I do still want an "MR" man page cross referencing macro[7] (and
mandoc(1) maintainer Ingo Schwarze is still trying to talk me out of
it), but not so that "See also" can be autogenerated.

[6] https://man7.org/linux/man-pages/man7/groff.7.html#Line_continuation
[7] https://lists.gnu.org/archive/html/groff/2021-08/msg00000.html

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

Powered by blists - more mailing lists