Re: bulleted list conventions

[Mike Frysinger <vapier@gentoo.org>]

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