Hi Thaddeus,
On 9/8/21 4:56 PM, Thaddeus H. Black wrote:
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 don't know of a page that does this, and some of them are a bit
inconsistent, so I'd have to search through the source code of the pages
to find one that is a perfect example. So I'll write/draw a schema here:
You could do it like this:
.TP
tag 1
.PP
paragraph 1.1
.IP
paragraph 1.2
.IP
paragraph 1.3
.RS
.TP
tag 1.4
.PP
paragraph 1.4.1
.IP
paragraph 1.4.2
.RS
.TP
tag 1.4.3
.PP
paragraph 1.4.3.1
.IP
paragraph 1.4.3.2
.IP
paragraph 1.4.3.3
.RE
.IP
paragraph 1.4.4
.RE
.IP
paragraph 1.5
Was it helpful?
Disclaimer: I didn't test it; I'm talking from memory.
Disclaimer 2: indentation is just to show results; obviously, don't
indent your input :)
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?
I think tagged paragraphs as subsubsections is much more common (and
logically organized).
+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."
Then I got it very wrongly :). I thought you meant more like "far from
being universally recognized".
"almost" seems good to me.
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/.
almost is good.
(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.)
Thanks,
Alex
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
