linux-man.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: "Thaddeus H. Black" <thb@debian.org>
To: "Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>
Cc: linux-man@vger.kernel.org,
	Michael Kerrisk <mtk.manpages@gmail.com>,
	"Dr. Tobias Quathamer" <toddy@debian.org>,
	linux-ext4@vger.kernel.org, debian-doc@lists.debian.org,
	"G. Branden Robinson" <g.branden.robinson@gmail.com>
Subject: Re: [PATCH] filename.7: new manual page
Date: Wed, 8 Sep 2021 14:56:29 +0000	[thread overview]
Message-ID: <YTjPHZEpjzn7Ufg/@b-tk.org> (raw)
In-Reply-To: <a18a8f3d-78a7-15e5-7a6e-0f4740c84667@gmail.com>

[-- Attachment #1: Type: text/plain, Size: 3394 bytes --]

[To limit spam, I'll probably copy future emails only to Alejandro,
Branden, Michael and the linux-man list.]

Alejandro:

I am collecting and applying your and Branden's edits.  Meanwhile,
three questions and some comments occur.

On Mon, Sep 06, 2021 at 04:21:09PM +0200, Alejandro Colomar (man-pages) wrote:
> See man-pages(7):
> 
>    Sections within a manual page
> 
>               [...]              
>               DESCRIPTION
>               [...]              

When in doubt, consistency is best.  Good point.

> You could move sections into subsections of DESCRIPTION, and the current
> subsections into tagged paragraphs (.TP).

Question 1:  do you happen to know of a good example of an existing
manual page that already does this?  If you did, then I could follow the
example.  Otherwise, it might be tricky, for the existing subsections
already have tagged paragraphs and other structure within them.
Perhaps .RS/.RE could be used.  I am not sure.

I notice that bash(1) does not follow your advice but dash(1) does.
However, dash(1) has no subsubsections.  In any event, a manual
page *about* conventions, like filename(7), should *obey*
conventions.  I just need to figure out how to obey with good style
in this instance.

On the other hand, there is an alternative, though I do not say whether
it is a better alternative.  The alternative would be to avoid
subsubsections by using colons ':' in subsection titles, instead,
approximately as follows.

    NAME
    DESCRIPTION
        Legal filenames
        Legal filenames:  reserved characters
        Legal filenames:  reserved names
        Legal filenames:  long names
        Legal filenames:  non-UTF-8 names
        Conventional filenames
        Conventional filenames:  the POSIX Portable Filename Character Set
        Conventional filenames:  special semantics
        Conventional filenames:  the full stop to introduce a format extension
        Soft conventions
        Soft convention:  low line versus hyphen-minus
        Soft convention:  letter case
        Locales and Unicode
        Unconventional filenames
    CONFORMING TO
    SEE ALSO

Question 2:  within the constraints of established manual-page
conventions, which alternative would you and Branden advise?

> > +The format-extension convention is all but universally recognized.
> 
> Non-native English speakers may have trouble understanding "all but". Maybe
> s/all but/not/?

When a reviewer like you informs me that (for whatever reason) he or she
did not understand a sentence the first time he or she read it, this is
valuable feedback; for if the reviewer did not understand it the first
time, then other readers probably also will not understand it the first
time.  The sentence ought to be rewritten to make reading the sentence
twice unnecessary.

In the sentence in question, I did not mean "not" but rather "almost."

Question 3:  in your opinion, would s/all but/almost/ make the sentence
more readable?  If not, then another option would be s/all but/nearly/.

(For information, I have some time to work on the patch today but little
time during the following two or three weeks.  Therefore, if I am slow
to reply after today, this does not mean that I have forgotten!  If not
today, then I will deliver PATCH v2 some time on or before Sept. 28.)

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

  parent reply	other threads:[~2021-09-08 16:07 UTC|newest]

Thread overview: 20+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-09-06 11:40 [PATCH] filename.7: new manual page Thaddeus H. Black
2021-09-06 14:21 ` Alejandro Colomar (man-pages)
2021-09-06 16:59   ` G. Branden Robinson
2021-09-06 21:47     ` Alejandro Colomar (man-pages)
2021-09-08  3:54       ` G. Branden Robinson
2021-09-08 14:56   ` Thaddeus H. Black [this message]
2021-09-08 15:45     ` Alejandro Colomar (man-pages)
2021-09-09  2:15       ` Thaddeus H. Black
2021-09-09  2:45         ` Thaddeus H. Black
2021-09-09  7:24         ` [PATCH 1/3] Remove unnecessary .P after .S[HS] Alejandro Colomar
2021-09-09  7:24         ` [PATCH 2/3] Fix indentation of paragraph, which continues talking about \0 Alejandro Colomar
2021-09-09  7:24         ` [PATCH 3/3] Use subsections instead of sections Alejandro Colomar
2021-09-09  7:28           ` [PATCH] .P -> .PP Alejandro Colomar
2021-09-12 14:20           ` [PATCH 3/3] Use subsections instead of sections Thaddeus H. Black
2021-09-12 14:49             ` Alejandro Colomar (man-pages)
2021-09-12 14:56               ` Alejandro Colomar (man-pages)
2021-09-12 15:22                 ` Thaddeus H. Black
2021-09-12 18:49                   ` G. Branden Robinson
2021-09-12 18:12                 ` G. Branden Robinson
2021-09-12 22:39                   ` Alejandro Colomar (man-pages)

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=YTjPHZEpjzn7Ufg/@b-tk.org \
    --to=thb@debian.org \
    --cc=alx.manpages@gmail.com \
    --cc=debian-doc@lists.debian.org \
    --cc=g.branden.robinson@gmail.com \
    --cc=linux-ext4@vger.kernel.org \
    --cc=linux-man@vger.kernel.org \
    --cc=mtk.manpages@gmail.com \
    --cc=toddy@debian.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).