Re: [PATCH] filename.7: new manual page

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

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/