Various pages: Use consistent style for lists
A message that is not in the archive (sent off-list or not yet received): [email protected]
Hi Mike,
I finished applying the consistency fixes to all pages. I developed some rules which I'd like to discuss here before pushing to <kernel.org> to agree on them.
I won't send the patches here because they're huge, and @vger.kernel.org would reject them anyway. I'll copy the logs, which are interesting, though.
Also, I'll link to my personal repository, in case you want to have a look at them:
<http://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?id=5c938587972a57f25cd8daa9b69a5296fc0bd95a>
<http://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?id=2c2a870bd2df9f6a05e818f516834a17dd0f17b4>
commit 5c938587972a57f25cd8daa9b69a5296fc0bd95a (HEAD -> main, alx/main, alx/HEAD)
Author: Alejandro Colomar <[email protected]> Date: Wed Oct 26 01:01:32 2022 +0200
Many pages: Use a consistent style for lists
There are different kinds of lists:
Tagged paragraphs
These are fixed in a separate commit (the previous one). They are used for a list of tags and their descriptions. An example is this commit message itself.
Ordered lists
Elements are preceeded by a number in parentheses. These represent a set of steps that have an order.
When there are substeps, they will be numbered like (4.2).
Positional lists
Elements are preceeded by a number in square brackets (index). These represent fields in a set. The index will start at:
0 fields of a C data structure, to be consistent
with arrays.
1 fields of a file, to be consistent with tools like
cut(1).
Alternatives list
Elements are preceeded by a letter in parentheses. These represent a set of (normally) exclusive alternatives.
Bullet lists
Elements are preceeded by bullet symbols. Anything that doesn't fit elsewhere usually is covered by this type of list.
Notes
Not really a list, but the syntax is identical to "positional lists".
There should always be 2 spaces between the list symbol and the elements. This doesn't apply to "tagged paragraphs", which use the default indentation rules.
commit 2c2a870bd2df9f6a05e818f516834a17dd0f17b4
Author: Alejandro Colomar <[email protected]> Date: Sun Oct 23 17:43:43 2022 +0200
Many pages: Use .TP for tagged paragraphs
What do you think about this patch set?
Cheers,
Alex
Signature · 1 line
<http://www.alejandro-colomar.es/>