Re: bulleted list conventions

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 3130 bytes --]

Hi Mike!

On 10/22/22 20:44, Mike Frysinger wrote:
> On 23 Oct 2022 00:15, Mike Frysinger wrote:
>> man-pages(7) is silent on how to handled lists.  the only reference i can see
>> is in an aside in an unrelated section:
>>         When enumerating a list of error codes, the codes are in bold
>>         (this list usually uses the .TP macro).
>>
>> glancing through existing man pages, it seems that `.IP` is the answer.  but
>> beyond that, we only have chaos.  can we pick & document a standard here ?
>>
>> for numbered lists, the tags are manually maintained, but use a few diff
>> styles like:
>> 	.IP 1
>> 	.IP 1.
>> 	.IP 1)
>> 	.IP (1)
>> 	.IP [1]
>> 	.IP 1:
>>
>> there's also alternative lists that use a few diff styles:
>> 	.IP a)
>> 	.IP (a)
>>
>> for unordered lists, there's a couple of diff bullet point styles:
>> 	*
>> 	\(bu
>> 	\-
>> 	o
>> 	+
>> the * form seems to be the most dominate, but \(bu shows up a good amount.
>> * is a bit easier to type, but \(bu renders "more correctly" ?  *shrug*
>>
>> finally there's the matter of indentation level.  3 seems to be the most
>> common, but there's a healthy amount of 2 in there too.
>> 	.IP * 3
>> 	.IP * 2

Yeah, this has been one of the greatest inconsistencies of the man-pages; so 
much that I haven't yet dared to try an fix it.  But I'd like to see it fixed 
some day.

> 
> hmm, it looks like groff alredy documents the answer.
> https://man7.org/linux/man-pages/man7/groff_man_style.7.html
>> Two convenient uses for .IP are
>>   (2) to set a paragraph with a short tag that is not
>>       semantically important, such as a bullet
>>       (•)—obtained with the \(bu special character
>>       escape sequence—or list enumerator, as seen in
>>       this very paragraph.

Hmm, I was going to suggest exactly this, without knowing groff suggested it :)

I like it because it uses a symbol that's normally not used in code, so it can't 
be confused, and also the 3-space indent as it clearly separates the bullet from 
the paragraph text, while still being minimal.

> 
> since man-pages(7) makes no reference to groff_man_style(7), and only a single
> reference to groff_man(7) for syntax on a specific macro, can we document this
> in the man-pages(7) page explicitly ?

Sure, would you mind suggesting a patch?


> * use .IP
> * use (1) and (a) style

We discussed about this in the mailing list some time ago.  We concluded that 
there should be 3 different types of lists:

-  Ordered lists.  They represent ordered steps, and use numbers.
-  Alternatives.  They represent exclusive alternatives, and use letters.
-  Bullet lists.  Lists that don't fall in the previous ones; use a bullet.

> * use \(bu for bullet lists
> * use indent of 3

LGTM.

> * (as a tip) use .RS & .RE for indented lists

RS/RE are for indented stuff, be it a list or not.  I'm not sure if it's 
necessary to add it explicitly.  But if you think it is, it could make sense.

> -mike

Cheers,

Alex

P.S.: Please email me too :)

-- 
<http://www.alejandro-colomar.es/>

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