* bulleted list conventions
@ 2022-10-22 18:30 Mike Frysinger
2022-10-22 18:44 ` Mike Frysinger
0 siblings, 1 reply; 3+ messages in thread
From: Mike Frysinger @ 2022-10-22 18:30 UTC (permalink / raw)
To: linux-man
[-- 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 --]
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: bulleted list conventions
2022-10-22 18:30 bulleted list conventions Mike Frysinger
@ 2022-10-22 18:44 ` Mike Frysinger
2022-10-22 22:12 ` Alejandro Colomar
0 siblings, 1 reply; 3+ messages in thread
From: Mike Frysinger @ 2022-10-22 18:44 UTC (permalink / raw)
To: linux-man
[-- 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 --]
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: bulleted list conventions
2022-10-22 18:44 ` Mike Frysinger
@ 2022-10-22 22:12 ` Alejandro Colomar
0 siblings, 0 replies; 3+ messages in thread
From: Alejandro Colomar @ 2022-10-22 22:12 UTC (permalink / raw)
To: linux-man, Mike Frysinger
[-- 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 --]
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2022-10-22 22:12 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-10-22 18:30 bulleted list conventions Mike Frysinger
2022-10-22 18:44 ` Mike Frysinger
2022-10-22 22:12 ` Alejandro Colomar
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.