bulleted list conventions

bulleted list conventions

[Mike Frysinger]

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

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
-mike

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

Re: bulleted list conventions

[Mike Frysinger]

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

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

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.

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 ?
* use .IP
* use (1) and (a) style
* use \(bu for bullet lists
* use indent of 3
* (as a tip) use .RS & .RE for indented lists
-mike

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

Re: bulleted list conventions

[Alejandro Colomar]

[-- 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 --]