Re: bulleted list conventions

Alejandro Colomar <alx.manpages@xxxxxxxxx> · Sun, 23 Oct 2022 00:12:05 +0200

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:
OpenPGP_signature

Description: OpenPGP digital signature