diff options
| author | Alejandro Colomar <alx@kernel.org> | 2022-10-29 23:50:33 +0200 |
|---|---|---|
| committer | Alejandro Colomar <alx@kernel.org> | 2022-10-29 23:51:46 +0200 |
| commit | 48fea6deb5057a9cd8ebefb73682aa077e629c94 (patch) | |
| tree | 4a282febdbd86f726b0f2b1f010b0cd429f7f67a /man7/man-pages.7 | |
| parent | 22356d97e388c79993c94d43109087d3c8740187 (diff) | |
| download | man-pages-48fea6deb5057a9cd8ebefb73682aa077e629c94.tar.gz | |
man-pages.7: Document how to write lists
Reported-by: Mike Frysinger <vapier@gentoo.org>
Acked-by: Douglas McIlroy <douglas.mcilroy@dartmouth.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
Diffstat (limited to 'man7/man-pages.7')
| -rw-r--r-- | man7/man-pages.7 | 58 |
1 files changed, 58 insertions, 0 deletions
diff --git a/man7/man-pages.7 b/man7/man-pages.7 index cda5b4d0f8..03b0e6c154 100644 --- a/man7/man-pages.7 +++ b/man7/man-pages.7 @@ -620,6 +620,64 @@ makes it easier to see the effect of patches, which often operate at the level of individual sentences, clauses, or phrases. .\" +.SS Lists +There are different kinds of lists: +.TP +Tagged paragraphs +These are used for a list of tags and their descriptions. +When the tags are constants (either macros or numbers) +they are in bold. +Use the +.B .TP +macro. +.IP +An example is this "Tagged paragraphs" subsection is itself. +.TP +Ordered lists +Elements are preceeded by a number in parentheses (1), (2). +These represent a set of steps that have an order. +.IP +When there are substeps, +they will be numbered like (4.2). +.TP +Positional lists +Elements are preceeded by a number (index) in square brackets [4], [5]. +These represent fields in a set. +The first index will be: +.IP +.RS +.PD 0 +.TP +.B 0 +When it represents fields of a C data structure, +to be consistent with arrays. +.TP +.B 1 +When it represents fields of a file, +to be consistent with tools like +.BR cut (1). +.PD +.RE +.TP +Alternatives list +Elements are preceeded by a letter in parentheses (a), (b). +These represent a set of (normally) exclusive alternatives. +.TP +Bullet lists +Elements are preceeded by bullet symbols +.RB ( \e(bu ). +Anything that doesn't fit elsewhere is +usually covered by this type of list. +.TP +Numbered notes +Not really a list, +but the syntax is identical to "positional lists". +.PP +There should always be exactly +2 spaces between the list symbol and the elements. +This doesn't apply to "tagged paragraphs", +which use the default indentation rules. +.\" .SS Formatting conventions (general) Paragraphs should be separated by suitable markers (usually either .I .PP |