lists  /  announce  owl-users  owl-dev  john-users  john-dev  passwdqc-users  yescrypt  popa3d-users  /  oss-security  kernel-hardening  musl  sabotage  tlsify  passwords  /  crypt-dev  xvendor  /  Bugtraq  Full-Disclosure  linux-kernel  linux-netdev  linux-ext4  linux-hardening  PHC 
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [day] [month] [year] [list]
Date:   Wed, 8 Sep 2021 17:45:43 +0200
From:   "Alejandro Colomar (man-pages)" <>
To:     "Thaddeus H. Black" <>
        Michael Kerrisk <>,
        "Dr. Tobias Quathamer" <>,,,
        "G. Branden Robinson" <>
Subject: Re: [PATCH] filename.7: new manual page

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:

	tag 1
		paragraph 1.1
		paragraph 1.2
		paragraph 1.3
		tag 1.4
			paragraph 1.4.1
			paragraph 1.4.2
			tag 1.4.3
			paragraph 1.4.4
		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
>          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
>      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.)



Alejandro Colomar
Linux man-pages comaintainer;

Powered by blists - more mailing lists