[PATCH] findfs: (man) improve the markup, the layout, and the wording

[PATCH] findfs: (man) improve the markup, the layout, and the wording

[Benno Schulenberg]

Mark NAME as a placeholder instead of a literal, and rename it to
TAGNAME to make it clearer what "tag" in the description refers to.

Indent the list of possible tags, to make it clearer where the
description continues.

Drop the angle brackets around placeholders -- those are used
in --help output, but in man pages it is just italics.

Also add a missing section header.

Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
 misc-utils/findfs.8.adoc | 36 ++++++++++++++++++++++--------------
 1 file changed, 22 insertions(+), 14 deletions(-)

diff --git a/misc-utils/findfs.8.adoc b/misc-utils/findfs.8.adoc
index 8783cdc25..02d08f953 100644
--- a/misc-utils/findfs.8.adoc
+++ b/misc-utils/findfs.8.adoc
@@ -16,36 +16,44 @@ findfs - find a filesystem by label or UUID
 
 == SYNOPSIS
 
-*findfs* *NAME*=_value_
+*findfs* _TAGNAME_**=**_value_
 
 == DESCRIPTION
 
-*findfs* will search the block devices in the system looking for a filesystem or partition with specified tag. The currently supported tags are:
+*findfs* will search the block devices in the system for a filesystem or partition
+with the specified tag. The currently supported tags are:
 
-*LABEL*=_<label>_::
-Specifies filesystem label.
+____
+**LABEL=**_label_::
+Specifies a filesystem label.
 
-*UUID*=_<uuid>_::
-Specifies filesystem UUID.
+**UUID=**_uuid_::
+Specifies a filesystem UUID.
 
-*PARTUUID*=_<uuid>_::
-Specifies partition UUID. This partition identifier is supported for example for GUID Partition Table (GPT) partition tables.
+**PARTUUID=**_uuid_::
+Specifies a partition UUID. Partition identifiers are supported for example for GUID Partition Table (GPT) partition tables.
 
-*PARTLABEL*=_<label>_::
-Specifies partition label (name). The partition labels are supported for example for GUID Partition Table (GPT) or MAC partition tables.
+**PARTLABEL=**_label_::
+Specifies a partition label (name). Partition labels are supported for example for GPT and MAC partition tables.
+____
 
-If the filesystem or partition is found, the device name will be printed on stdout. If the input is not in the format of NAME=value, then the input will be copied to the output without any modification.
+If the filesystem or partition is found, the device name will be printed on stdout.
+If the input is not in the format of _TAGNAME_**=**_value_, then the input will be
+copied to the output without any modification.
 
-The complete overview about filesystems and partitions you can get for example by
+You can get a complete overview about the filesystems and partitions in the system
+with one of the following commands:
 
 ____
 *lsblk --fs*
 
-*partx --show <disk>*
+*partx --show* _disk_
 
 *blkid*
 ____
 
+== OPTIONS
+
 include::man-common/help-version.adoc[]
 
 == EXIT STATUS
@@ -53,7 +61,7 @@ include::man-common/help-version.adoc[]
 *0*::
 success
 *1*::
-label or uuid cannot be found
+label or UUID cannot be found
 *2*::
 usage error, wrong number of arguments or unknown option
 
-- 
2.53.0

Re: [PATCH] findfs: (man) improve the markup, the layout, and the wording

[Nuno Silva]

On 2026-02-28, Benno Schulenberg wrote:

> Mark NAME as a placeholder instead of a literal, and rename it to
> TAGNAME to make it clearer what "tag" in the description refers to.
>
> Indent the list of possible tags, to make it clearer where the
> description continues.
>
> Drop the angle brackets around placeholders -- those are used
> in --help output, but in man pages it is just italics.

My apologies if I'm missing some convention from util-linux itself, but:
from a quick check, it looks to me that italics is used for such
placeholders in IEEE 1003.1. Any chance this is or was a de facto
standard to denote placeholders? Or something done this way for
consistency (not that I've done a survey of how common this is)?

(Also see "Utility Operand" and "Utility Option with Option-Argument" in
the table at [1], at the end.)

[1] https://pubs.opengroup.org/onlinepubs/9799919799/frontmatter/typographics.html

> Also add a missing section header.
>
> Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
[...]

(diff snipped as what's above is IMHO sufficient context for my reply)
-- 
Nuno Silva

Re: [PATCH] findfs: (man) improve the markup, the layout, and the wording

[Benno Schulenberg]

[-- Attachment #1.1: Type: text/plain, Size: 654 bytes --]


Op 28-02-2026 om 14:03 schreef Nuno Silva:
> On 2026-02-28, Benno Schulenberg wrote:
>> Drop the angle brackets around placeholders -- those are used
>> in --help output, but in man pages it is just italics.
> 
> My apologies if I'm missing some convention from util-linux itself,

Have a look at some other util-linux man pages.  They all use just
italics for placeholders (normally displayed as underline).

> from a quick check, it looks to me that italics is used for such
> placeholders in IEEE 1003.1.

And italics is exactly what this patch uses for placeholders.  (Not
angle brackets -- those are for --help texts.)


Benno


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 840 bytes --]

Re: [PATCH] findfs: (man) improve the markup, the layout, and the wording

[Nuno Silva]

On 01/03/26 11:25, Benno Schulenberg wrote:
> 
> Op 28-02-2026 om 14:03 schreef Nuno Silva:
>> On 2026-02-28, Benno Schulenberg wrote:
>>> Drop the angle brackets around placeholders -- those are used
>>> in --help output, but in man pages it is just italics.
>>
>> My apologies if I'm missing some convention from util-linux itself,
> 
> Have a look at some other util-linux man pages.  They all use just
> italics for placeholders (normally displayed as underline).
> 
>> from a quick check, it looks to me that italics is used for such
>> placeholders in IEEE 1003.1.
> 
> And italics is exactly what this patch uses for placeholders.  (Not
> angle brackets -- those are for --help texts.)

Oh, sorry - I now realize I misunderstood the original e-mail. It is 
embarassing; I should have double-checked things, namely the syntax 
(which I overlooked in part because I *still* need to configure Gnus - 
where I usually read this list - not to eat some of the characters when 
applying formatting...).

That'd have probably made the meaning obvious. Instead, not being 
acquainted with the syntax, I wrongly intepreted the commit message as 
you meaning angle brackets would be removed because they mean/generate 
italic.


-- 
Apologies again,
Nuno Silva

[PATCH] terminal-colors.d: (man) do not show 'type' as an optional part

[Benno Schulenberg]

That is: remove the square brackets from around 'type' in the synopsis.

Also, do not give the impression that a leading dot by itself is fine
before the 'type'.  That is: a dot is required only when 'name' and/or
'@term' is present.

Also, do not colorize the square brackets as if they were part of the
placeholders.  (And use ++double plus++ passthroughs for the opening
square brackets, to prevent asciidoctor from misinterpreting them.)

Indent the list of file types, for clarity.

And correct or improve some wordings, and remove an inconvenient
blank line in an example.

Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
 lib/terminal-colors.d.5.adoc | 24 ++++++++++--------------
 1 file changed, 10 insertions(+), 14 deletions(-)

diff --git a/lib/terminal-colors.d.5.adoc b/lib/terminal-colors.d.5.adoc
index 40ed8b966..9704fe413 100644
--- a/lib/terminal-colors.d.5.adoc
+++ b/lib/terminal-colors.d.5.adoc
@@ -21,7 +21,7 @@ terminal-colors.d - configure output colorization for various utilities
 
 == SYNOPSIS
 
-/etc/terminal-colors.d/_[[name][@term].][type]_
+*/etc/terminal-colors.d/*++[++_name_**.**|++[++_name_]**@**_term_**.**]_type_
 
 == DESCRIPTION
 
@@ -32,14 +32,14 @@ The _name_ is a utility name. The name is optional and when none is specified th
 The _term_ is a terminal identifier (the *TERM* environment variable). The terminal identifier is optional and when none is specified then the file is used for all unspecified terminals.
 
 The _type_ is a file type. Supported file types are:
-
+____
 *disable*::
 Turns off output colorization for all compatible utilities. See also the NO_COLOR environment variable below.
 *enable*::
 Turns on output colorization; any matching *disable* files are ignored.
-
 *scheme*::
 Specifies colors used for output. The file format may be specific to the utility, the default format is described below.
+____
 
 If there are more files that match for a utility, then the file with the more specific filename wins. For example, the filename "@xterm.scheme" has less priority than "dmesg@xterm.scheme". The lowest priority are those files without a utility name and terminal identifier (e.g., "disable").
 
@@ -56,15 +56,15 @@ The _name_ is a logical name for the color sequence (for example: *error*).
 The names are specific to the utilities. For more details always see
 the *COLORS* section in the man page for the utility.
 
-The _color-sequence_ is a color name, ASCII color sequences, or escape sequences.
+The _color-sequence_ can be a color name, an ANSI color sequence, or an escape sequence.
 
 === Color names
 
-black, blink, blue, bold, brown, cyan, darkgray, gray, green, halfbright, lightblue, lightcyan, lightgray, lightgreen, lightmagenta, lightred, magenta, red, reset, reverse, and yellow.
+Valid color names are: black, blink, blue, bold, brown, cyan, darkgray, gray, green, halfbright, lightblue, lightcyan, lightgray, lightgreen, lightmagenta, lightred, magenta, red, reset, reverse, and yellow.
 
 === ANSI color sequences
 
-The color sequences are composed of sequences of numbers separated by semicolons. The most common codes are:
+An ANSI color sequence is composed of sequences of numbers separated by semicolons. The most common codes are:
 ____
      0   to restore default color
      1   for brighter colors
@@ -94,7 +94,7 @@ For example, to use a red background for alert messages in the output of *dmesg*
 
 === Escape sequences
 
-An escape sequence is necessary to enter a space, backslash, caret, or any
+An escape sequence is needed to enter a space, backslash, caret, or any
 control character anywhere in a string, as well as a hash mark as the first
 character. These C-style backslash-escapes can be used:
 
@@ -137,31 +137,27 @@ _$HOME/.config/terminal-colors.d_
 
 _/etc/terminal-colors.d_
 
-== EXAMPLE
+== EXAMPLES
 
 Disable colors for all compatible utilities:
-
 ____
 *touch /etc/terminal-colors.d/disable*
 ____
 
 Disable colors for all compatible utils on a vt100 terminal:
-
 ____
 *touch /etc/terminal-colors.d/@vt100.disable*
 ____
 
 Disable colors for all compatible utils except *dmesg*(1):
-
 ____
-*touch /etc/terminal-colors.d/disable*
-
+*touch /etc/terminal-colors.d/disable* +
 *touch /etc/terminal-colors.d/dmesg.enable*
 ____
 
 == COMPATIBILITY
 
-The *terminal-colors.d* functionality is currently supported by all util-linux utilities which provides colorized output. For more details always see the *COLORS* section in the man page for the utility.
+The *terminal-colors.d* functionality is currently supported by all util-linux utilities which provide colorized output. For more details always see the *COLORS* section in the man page for the utility.
 
 include::man-common/bugreports.adoc[]
 
-- 
2.53.0

Re: [PATCH] findfs: (man) improve the markup, the layout, and the wording

[Karel Zak]

On Sat, Feb 28, 2026 at 12:52:45PM +0100, Benno Schulenberg wrote:
>  misc-utils/findfs.8.adoc | 36 ++++++++++++++++++++++--------------
>  1 file changed, 22 insertions(+), 14 deletions(-)

>  lib/terminal-colors.d.5.adoc | 24 ++++++++++--------------
>  1 file changed, 10 insertions(+), 14 deletions(-)

Both patches have been applied. Thank you, and sorry for the delay.

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

improvements to terminal-colors.d.5.adoc were undone

[Benno Schulenberg]

[-- Attachment #1.1: Type: text/plain, Size: 819 bytes --]


Op 09-03-2026 om 11:51 schreef Karel Zak:
>>   lib/terminal-colors.d.5.adoc | 24 ++++++++++--------------
>>   1 file changed, 10 insertions(+), 14 deletions(-)
> 
> Both patches have been applied. Thank you, and sorry for the delay.

The second patch was applied in commit 3252142521, but three commits
later, merge commit d708fc7db6 undoes all the improvements I made.  :/

Also, that merge commit says that it just removes the backticks from a
table, but it actually changes back two simple lists to large, bulky
tables.  Before the conversion to adoc, those tables were simple lists.
A year ago, commit b3c3d865eb reduced the bulky tables back to simple
lists.  Can we please keep these simple lists?

In other words: please revert commit f5d2c3e4b0.  And reapply commit
3252142521.


Benno


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 840 bytes --]

Re: improvements to terminal-colors.d.5.adoc were undone

[Karel Zak]

On Mon, Mar 09, 2026 at 05:08:19PM +0100, Benno Schulenberg wrote:
> 
> Op 09-03-2026 om 11:51 schreef Karel Zak:
> > >   lib/terminal-colors.d.5.adoc | 24 ++++++++++--------------
> > >   1 file changed, 10 insertions(+), 14 deletions(-)
> > 
> > Both patches have been applied. Thank you, and sorry for the delay.
> 
> The second patch was applied in commit 3252142521, but three commits
> later, merge commit d708fc7db6 undoes all the improvements I made.  :/

My mistake, sorry I'll fix it.

> Also, that merge commit says that it just removes the backticks from a
> table, but it actually changes back two simple lists to large, bulky
> tables.

The tables are a better solution than the list for translators. See
discussion:
https://github.com/util-linux/util-linux/pull/4089

The list produces things like (po-man/util-linux-man.pot):

#. type: delimited block _
#: ../lib/terminal-colors.d.5.adoc:115
msgid ""                
"`` *\\a* Bell (ASCII 7)`` `` *\\b* Backspace (ASCII 8)`` `` *\\e* Escape "
"(ASCII 27)`` `` *\\f* Form feed (ASCII 12)`` `` *\\n* Newline (ASCII 10)`` "
"`` *\\r* Carriage Return (ASCII 13)`` `` *\\t* Tab (ASCII 9)`` `` *\\v* "
"Vertical Tab (ASCII 11)`` `` *\\?*{nbsp}{nbsp}{nbsp}Delete (ASCII 127)`` `` "
"*\\_* Space`` `` *\\\\* Backslash (\\)`` `` *\\^* Caret (^)`` `` *\\\\#* "
"Hash mark (#)``"       
msgstr ""             


The table is more readable:

#. type: Table
#: ../lib/terminal-colors.d.5.adoc:131
#, no-wrap
msgid ""
"|0\n"
"|to restore default color\n"
"\n"
"|1\n"
"|for brighter colors\n"
"\n"
"|4\n"
"|for underlined text\n"
"\n"
"|5\n"
"|for flashing text\n"
"\n"
"|30\n"
"|for black foreground\n"
"\n"
"|31\n"
"|for red foreground\n"
"\n"
"|32\n"
"|for green foreground\n"
"\n"
"|33\n"
"|for yellow (or brown) foreground\n"
"\n"
"|34\n"
"|for blue foreground\n"
"\n"
"|35\n"
"|for purple foreground\n"
"\n"
"|36\n"
"|for cyan foreground\n"
"\n"
"|37\n"
"|for white (or gray) foreground\n"
"\n"
"|40\n"
"|for black background\n"
"\n"
"|41\n"
"|for red background\n"
"\n"
"|42\n"
"|for green background\n"
"\n"
"|43\n"
"|for yellow (or brown) background\n"
"\n"
"|44\n"
"|for blue background\n"
"\n"
"|45\n"
"|for purple background\n"
"\n"
"|46\n"
"|for cyan background\n"
"\n"
"|47\n"
"|for white (or gray) background\n"
msgstr ""

> A year ago, commit b3c3d865eb reduced the bulky tables back to simple
> lists.  Can we please keep these simple lists?

The list seems unfriendly to translators in some cases.

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: improvements to terminal-colors.d.5.adoc were undone

[Benno Schulenberg]

[-- Attachment #1.1: Type: text/plain, Size: 2877 bytes --]


Op 10-03-2026 om 19:49 schreef Karel Zak:
> The tables are a better solution than the list for translators. See
> discussion:
> https://github.com/util-linux/util-linux/pull/4089

It would have been nice if the commit message had included the
motivation for the change.

> The list produces things like (po-man/util-linux-man.pot):
> 
> #. type: delimited block _
> #: ../lib/terminal-colors.d.5.adoc:115
> msgid ""
> "`` *\\a* Bell (ASCII 7)`` `` *\\b* Backspace (ASCII 8)`` `` *\\e* Escape"
> "(ASCII 27)`` `` *\\f* Form feed (ASCII 12)`` `` *\\n* Newline (ASCII 10)``"
> "`` *\\r* Carriage Return (ASCII 13)`` `` *\\t* Tab (ASCII 9)`` `` *\\v*"
> "Vertical Tab (ASCII 11)`` `` *\\?*{nbsp}{nbsp}{nbsp}Delete (ASCII 127)`` ``"
> "*\\_* Space`` `` *\\\\* Backslash (\\)`` `` *\\^* Caret (^)`` `` *\\\\#*"
> "Hash mark (#)``"
> msgstr ""

Cannot `po4a` be told to put every line of a "delimited block" onto
a separate line, or otherwise into a separate msgid?


> The table is more readable:
> 
> #. type: Table
> #: ../lib/terminal-colors.d.5.adoc:131
> #, no-wrap
> msgid ""
> "|0\n"
> "|to restore default color\n"
> "\n"
> "|1\n"
> "|for brighter colors\n"
> "\n"
> [...]

In the msgid, yes.  But in the man page... it becomes a monstrosity:

        ┌───┬──────────────────────────┐
        │   │                          │
        │0  │ to restore default color │
        ├───┼──────────────────────────┤
        │   │                          │
        │1  │ for brighter colors      │
        ├───┼──────────────────────────┤
        │   │                          │
        │4  │ for underlined text      │
        ├───┼──────────────────────────┤
        <snip>
        ├───┼──────────────────────────┤
        │   │                          │
        │33 │ for yellow (or brown)    │
        │   │ foreground               │
        ├───┼──────────────────────────┤
        <snip>

*Two thirds* of the table are lines and empty space, and only one
third contains information.  Plus: the table uses less than half
the available width of the man page, meaning that some descriptions
get unnecessarily wrapped.  The whole impression is horrible -- a
typograhically-minded person would be banging his head against the
keyboard in frustration.  :(  This horrible look was the reason to
restore the list form as it existed before the change to asciidoc.


Benno


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 840 bytes --]

Re: improvements to terminal-colors.d.5.adoc were undone

[Karel Zak]

On Mon, Mar 09, 2026 at 05:08:19PM +0100, Benno Schulenberg wrote:
> 
> Op 09-03-2026 om 11:51 schreef Karel Zak:
> > >   lib/terminal-colors.d.5.adoc | 24 ++++++++++--------------
> > >   1 file changed, 10 insertions(+), 14 deletions(-)
> > 
> > Both patches have been applied. Thank you, and sorry for the delay.
> 
> The second patch was applied in commit 3252142521, but three commits
> later, merge commit d708fc7db6 undoes all the improvements I made.  :/

Fixed, see https://github.com/util-linux/util-linux/commit/e4889528b3d4d895ea8dbe60ed6b8eb82b3ddf05

Thanks!
    Karel




-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com