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:
signature.asc
Description: PGP signature
