* Re: [PATCH 1/4] hwclock: remove two comments about parameters that no longer exist
From: Karel Zak @ 2025-04-08 11:44 UTC (permalink / raw)
To: Benno Schulenberg; +Cc: util-linux
In-Reply-To: <20250406152147.9225-1-bensberg@telfort.nl>
On Sun, Apr 06, 2025 at 05:21:44PM +0200, Benno Schulenberg wrote:
> sys-utils/hwclock.c | 5 -----
> 1 file changed, 5 deletions(-)
All four patches have been applied. Thank you!
--
Karel Zak <kzak@redhat.com>
http://karelzak.blogspot.com
^ permalink raw reply
* Re: [PATCH 1/8] setarch: (man) remove a synopsis line that mistakenly mentions `arch`
From: Karel Zak @ 2025-04-08 10:47 UTC (permalink / raw)
To: Benno Schulenberg; +Cc: util-linux
In-Reply-To: <20250407151503.23394-1-bensberg@telfort.nl>
On Mon, Apr 07, 2025 at 05:14:32PM +0200, Benno Schulenberg wrote:
> Bug existed since commit 0554182555 from seven years ago.
Patches 2-8 have been applied; the first one is postponed.
Thanks!
Karel
--
Karel Zak <kzak@redhat.com>
http://karelzak.blogspot.com
^ permalink raw reply
* Re: [PATCH 1/8] setarch: (man) remove a synopsis line that mistakenly mentions `arch`
From: Karel Zak @ 2025-04-08 10:33 UTC (permalink / raw)
To: Benno Schulenberg; +Cc: util-linux
In-Reply-To: <20250407151503.23394-1-bensberg@telfort.nl>
On Mon, Apr 07, 2025 at 05:14:32PM +0200, Benno Schulenberg wrote:
> -*arch* [options] [_program_ [_argument_...]]
This is not a bug. We use symlinks for setarch to support specific
architectures. It would be beneficial to describe this in the man
page in better way...
$ find /usr/bin -type l -lname 'setarch'
/usr/bin/i386
/usr/bin/linux64
/usr/bin/uname26
/usr/bin/x86_64
/usr/bin/linux32
Karel
--
Karel Zak <kzak@redhat.com>
http://karelzak.blogspot.com
^ permalink raw reply
* [PATCH 2/8] choom: (man) add the missing SYNOPSIS section header, and improve wording
From: Benno Schulenberg @ 2025-04-07 15:14 UTC (permalink / raw)
To: util-linux
In-Reply-To: <20250407151503.23394-1-bensberg@telfort.nl>
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
sys-utils/choom.1.adoc | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
diff --git a/sys-utils/choom.1.adoc b/sys-utils/choom.1.adoc
index 51d43e7b9..b699e967d 100644
--- a/sys-utils/choom.1.adoc
+++ b/sys-utils/choom.1.adoc
@@ -8,7 +8,9 @@
== NAME
-choom - display and adjust OOM-killer score.
+choom - display or adjust OOM-killer score
+
+== SYNOPSIS
*choom* *-p* _PID_
@@ -18,7 +20,7 @@ choom - display and adjust OOM-killer score.
== DESCRIPTION
-The *choom* command displays and adjusts Out-Of-Memory killer score setting.
+The *choom* command displays or adjusts the Out-Of-Memory killer score setting.
== OPTIONS
--
2.48.1
^ permalink raw reply related
* [PATCH 8/8] column: (man) fix broken markup, and improve other markup and wordings
From: Benno Schulenberg @ 2025-04-07 15:14 UTC (permalink / raw)
To: util-linux
In-Reply-To: <20250407151503.23394-1-bensberg@telfort.nl>
Since commit aa4efb2030 from five months ago, almost the entire text
of the section OPTIONS was underlined / in italics. Correct that.
Also improve various other markup and wordings, and unswap the names of
--table-column and --table-columns in the first paragraph of OPTIONS.
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
text-utils/column.1.adoc | 73 +++++++++++++++++++++++-----------------
1 file changed, 42 insertions(+), 31 deletions(-)
diff --git a/text-utils/column.1.adoc b/text-utils/column.1.adoc
index 9585e7fc0..97b7fec5b 100644
--- a/text-utils/column.1.adoc
+++ b/text-utils/column.1.adoc
@@ -59,15 +59,20 @@ This is the default mode (required for backwards compatibility).
This mode is enabled with the *-x, --fillrows* option.
*create a table*::
-Determine the number of columns the input contains and create a table. This mode is enabled with the *-t, --table* option. Output is aligned to the terminal width in interactive mode and 80 columns in non-interactive mode (see *--output-width* for more details). Custom formatting can be applied by using various *--table-\** options.
+Determine the number of columns the input contains and create a table.
+This mode is enabled with the *-t*/*--table* option.
+Output is aligned to the terminal width in interactive mode, and to 80 columns
+in non-interactive mode (see *--output-width* for more details).
+Custom formatting can be applied by using various **--table-*** options.
Input is taken from _file_, or otherwise from standard input. Empty lines are ignored and all invalid multibyte sequences are encoded with the x<hex> convention.
== OPTIONS
-The argument _columns_ for *--table-\** options is a comma separated list of
-user supplied names, defined with *--table-column _name1_,_name2_,...*, indices of columns, as they
-appear in the input, beginning with 1, or names, defined by a *--table-columns* attribute.
+The argument _columns_, for the **--table-*** options below, is a comma-separated list
+of user-supplied names defined with *--table-columns* _name1_**,**_name2_**,**...,
+or indices of columns as they appear in the input, beginning with 1,
+or names defined through a *--table-column* attribute.
It's possible to mix names and indices. The special placeholder '0' (e.g. -R0) may
be used to specify all columns and '-1' (e.g. -R -1) to specify the last visible column.
It's possible to use ranges like '1-5' when addressing columns by indices.
@@ -76,80 +81,86 @@ It's possible to use ranges like '1-5' when addressing columns by indices.
Use JSON output format to print the table. The option *--table-columns* is required and the option *--table-name* is recommended.
*-c, --output-width* _width_::
-Output is formatted to a width specified as a number of characters. The original name of this option is *--columns*; this name is deprecated since v2.30. Note that input longer than _width_ is not truncated by default. The default is the terminal width and 80 columns in non-interactive mode. The column headers are never truncated.
+Output is formatted to a width specified as a number of characters.
+Note that input longer than _width_ is not truncated by default.
+The default is the terminal width in interactive mode, and 80 columns in non-interactive mode.
+The column headers are never truncated.
+
-The placeholder "unlimited" (or 0) can be used to prevent restricting output width. This is recommended for example when redirecting output to a file.
+The placeholder *unlimited* (or *0*) can be used to prevent restricting the output width.
+This is recommended when redirecting output to a file.
++
+(The original long name of this option was *--columns*; this name is deprecated since v2.30.)
*-d, --table-noheadings*::
-Omit printing the header. This option allows the use of user supplied column names on the command line, but keeps the header hidden when printing the table.
+Omit printing the header. This option allows having user-supplied column names on the command line, but keeps the header hidden when printing the table.
*-o, --output-separator* _string_::
Column delimiter for table output (default is two spaces).
*-s, --separator* _separators_::
-Possible input item delimiters (default is whitespace).
+Possible input-item delimiters (default is whitespace).
*-S, --use-spaces* _number_::
-When not in table mode, use whitespaces instead of tabulators to align the columns. This option specifies the minimum number of whitespaces that separate two columns.
+When not in table mode, use spaces instead of tabulators to align the columns. This option specifies the minimum number of spaces that separate two columns.
*-t, --table*::
Determine the number of columns the input contains and create a table. Columns are by default delimited with whitespace, or with characters supplied using the *--output-separator* option. Table output is useful for pretty-printing.
*-C, --table-column* _attributes_::
-Define a column with a comma separated list of column attributes.
+Define a column with a comma-separated list of attributes.
This option can be used more than once, every use defines a single column.
-Attributes replace some of *--table-* options. For example, *--table-column name=FOO,right*
-defines a column where text is aligned to right. The option is
-mutually exclusive to *--table-columns*.
+Attributes replace some of the **--table-*** options: for example,
+*--table-column name=FOO,right* defines a column where text is aligned to the right.
+The option is mutually exclusive with *-N*/*--table-columns*.
+
Supported attributes are:
+
-*name=string*;;
+**name=**_string_;;
Column name.
*trunc*;;
Truncate column text when necessary. The same as *--table-truncate*.
*right*;;
Right align text. The same as *--table-right*.
-*width=number*;;
-Column width. It's used only as a hint. To force it, specify the *strictwidth* attribute
+**width=**_number_;;
+Column width. It's used only as a hint. To enforce it, specify the *strictwidth* attribute
as well.
*strictwidth*;;
-Strictly follow column *width=* setting.
+Strictly follow the *width=* setting.
*noextreme*;;
-Ignore unusually long cell width. See *--table-noextreme* for more details.
+Ignore unusually long content width. See *--table-noextreme* for more details.
*wrap*;;
Allow using a multi-line cell for long text if necessary. See *--table-wrap* for more details.
*hide*;;
Don't print the column. See *--table-hide* for more details.
-*json=type*;;
-Define column type for JSON output. Supported types are string, number and boolean.
+**json=**_type_;;
+Define the column type for JSON output. Supported types are *string*, *number* and *boolean*.
*-N, --table-columns* _names_::
-Specify column names with a comma separated list. The names are used
-for the table header and column addressing in option arguments. See also *--table-column*.
+Specify column names with a comma-separated list. The names are used for the table header
+and for column addressing in option arguments. See also *--table-column*.
*-l, --table-columns-limit* _number_::
-Specify maximum number of input columns. The last column will contain all remaining line data if the limit is smaller than the number of the columns in the input data.
+Specify the maximum number of input columns. The last column will contain all remaining line data if the limit is smaller than the number of columns in the input data.
*-R, --table-right* _columns_::
-Right align text in specified columns.
+Right align text in the specified columns.
*-T, --table-truncate* _columns_::
-Specify columns where text can be truncated when necessary, otherwise very long table entries may be printed on multiple lines.
+Specify the columns where text can be truncated when necessary, otherwise very long table entries may be printed on multiple lines.
*-E, --table-noextreme* _columns_::
-Specify columns where is possible to ignore unusually long (longer than average) cells when calculate column width. The option has impact to the width calculation and table formatting, but the printed text is not affected.
+Specify the columns where longer-than-average content should be ignored when calculating the column width. The option influences width calculation and table formatting, but the printed text is not affected.
+
-The option is used for the last visible column by default.
+This option is active by default for the last visible column.
*-e, --table-header-repeat*::
Print header line for each page.
*-W, --table-wrap* _columns_::
-Specify columns where multi-line cells can be used for long text.
+Specify the columns where multi-line cells can be used for long text.
*-H, --table-hide* _columns_::
-Don't print specified columns. The special placeholder '-' may be used to hide all unnamed columns (see *--table-columns*).
+Don't print the specified columns. The special placeholder '*-*' may be used to hide all unnamed columns (see *--table-columns*).
*-O, --table-order* _columns_::
Specify the output column order.
@@ -167,10 +178,10 @@ Preserve whitespace-only lines in the input. The default is to ignore all empty
Specify the column to use for a tree-like output. Note that the circular dependencies and other anomalies in child and parent relation are silently ignored.
*-i, --tree-id* _column_::
-Specify the column that contains each line's unique child IDs for a child-parent relation.
+Specify the column that contains each line's unique child ID for a child-parent relation.
*-p, --tree-parent* _column_::
-Specify the column that contains each line's parent IDs for a child-parent relation.
+Specify the column that contains each line's parent ID for a child-parent relation.
*-x, --fillrows*::
Fill rows before filling columns.
--
2.48.1
^ permalink raw reply related
* [PATCH 1/8] setarch: (man) remove a synopsis line that mistakenly mentions `arch`
From: Benno Schulenberg @ 2025-04-07 15:14 UTC (permalink / raw)
To: util-linux
Bug existed since commit 0554182555 from seven years ago.
Also, correct the markup for --show and --pid, improve the wording,
and reduce redundancy by reshuffling the --pid option.
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
sys-utils/setarch.8.adoc | 22 +++++++++-------------
1 file changed, 9 insertions(+), 13 deletions(-)
diff --git a/sys-utils/setarch.8.adoc b/sys-utils/setarch.8.adoc
index 1d8c390b3..7ad710dff 100644
--- a/sys-utils/setarch.8.adoc
+++ b/sys-utils/setarch.8.adoc
@@ -16,8 +16,6 @@ setarch - change reported architecture in new program environment and/or set per
*setarch* *--list*|*-h*|*-V*
-*arch* [options] [_program_ [_argument_...]]
-
== DESCRIPTION
*setarch* modifies execution domains and process personality flags.
@@ -31,28 +29,26 @@ Since version 2.33 the _arch_ command line argument is optional and *setarch* ma
*--list*::
List the architectures that *setarch* knows about. Whether *setarch* can actually set each of these architectures depends on the running kernel.
-*--show[=personality]*::
+*--show*[**=**_personality_]::
Show the currently active personality and flags.
-If the *personality* argument is provided, it is shown instead of the current one.
-*personality* is a hexadecimal number with values was described in *sys/personality.h*.
-+
-If *--pid=pid* option is provided, show them of the specifies process.
+If the _personality_ argument is provided, that personality is shown instead of the current one.
+_personality_ is a hexadecimal number whose possible values are described in *sys/personality.h*.
+
+*-p*, **--pid=**_pid_::
+When used with *--show*, show the personality and flags of the specified process.
*--uname-2.6*::
-Causes the _program_ to see a kernel version number beginning with 2.6. Turns on *UNAME26*.
+Causes the specified _program_ to see a kernel version number beginning with 2.6. Turns on *UNAME26*.
*-v*, *--verbose*::
Be verbose.
*-3*, *--3gb*::
-Specifies _program_ should use a maximum of 3GB of address space. Supported on x86. Turns on *ADDR_LIMIT_3GB*.
+The specified _program_ should use a maximum of 3GB of address space. Supported on x86. Turns on *ADDR_LIMIT_3GB*.
*--4gb*::
This option has no effect. It is retained for backward compatibility only, and may be removed in future releases.
-*-p*, *--pid=pid*::
-With *--show* option, show the currently active personality and flags of the specifies process.
-
*-B*, *--32bit*::
Limit the address space to 32 bits to emulate hardware. Supported on ARM and Alpha. Turns on *ADDR_LIMIT_32BIT*.
@@ -82,7 +78,7 @@ SVr4 bug emulation that will set *mmap*(2) page zero as read-only. Use when _pro
include::man-common/help-version.adoc[]
-== EXAMPLE
+== EXAMPLES
....
setarch --addr-no-randomize mytestprog
--
2.48.1
^ permalink raw reply related
* [PATCH 7/8] mount: (man) shorten an overlong line, and improve some markup
From: Benno Schulenberg @ 2025-04-07 15:14 UTC (permalink / raw)
To: util-linux
In-Reply-To: <20250407151503.23394-1-bensberg@telfort.nl>
Also, in the synopis mention -F separately to make it more obvious that
it applies only to -A, swap two options to make a line more similar to
the preceding one, and improve some wording.
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
sys-utils/mount.8.adoc | 15 ++++++++-------
1 file changed, 8 insertions(+), 7 deletions(-)
diff --git a/sys-utils/mount.8.adoc b/sys-utils/mount.8.adoc
index f4a704556..bb4151225 100644
--- a/sys-utils/mount.8.adoc
+++ b/sys-utils/mount.8.adoc
@@ -47,15 +47,16 @@ mount - mount a filesystem
*mount* [*-l*] [*-t* _fstype_]
-*mount* *-a* [*-fFnrsvw*] [*-t* _fstype_] [*-O* _optlist_]
+*mount* *-a* [*-F*] [*-fnrsvw*] [*-t* _fstype_] [*-O* _optlist_]
*mount* [*-fnrsvw*] [*-o* _options_] _device_|_mountpoint_
-*mount* [*-fnrsvw*] [*-t* _fstype_] [*-o* _options_] _device mountpoint_
+*mount* [*-fnrsvw*] [*-o* _options_] [*-t* _fstype_] _device mountpoint_
*mount* *--bind*|*--rbind*|*--move* _olddir newdir_
-*mount* *--make-*[*shared*|*slave*|*private*|*unbindable*|*rshared*|*rslave*|*rprivate*|*runbindable*] _mountpoint_
+*mount* *--make-*[*r*]{*shared*|*slave*|*private*|*unbindable*} _mountpoint_
+
== DESCRIPTION
@@ -765,8 +766,8 @@ Note that *mount*(8) still sanitizes and canonicalizes the source and target pat
*X-mount.noloop*::
Do not create and mount a loop device, even if the source of the mount is a regular file.
-*X-mount.subdir=*__directory__::
-Allow mounting sub-directory from a filesystem instead of the root directory. For now, this feature is implemented by temporary filesystem root directory mount in unshared namespace and then bind the sub-directory to the final mount point and umount the root of the filesystem. The sub-directory mount shows up atomically for the rest of the system although it is implemented by multiple *mount*(2) syscalls.
+**X-mount.subdir=**_directory_::
+Allow mounting a sub-directory of a filesystem instead of the root directory. For now, this feature is implemented by a temporary filesystem root-directory mount in an unshared namespace and then binding the sub-directory to the final mount point and unmounting the root of the filesystem. The sub-directory mount shows up atomically for the rest of the system although it is implemented by multiple *mount*(2) syscalls.
+
Note that this feature will not work in session with an unshared private mount namespace (after *unshare --mount*) on old kernels or with *mount*(8) without support for file-descriptors-based mount kernel API. In this case, you need *unshare --mount --propagation shared*.
+
@@ -1513,7 +1514,7 @@ Set behavior on error:
*panic*;;
If an error is encountered, cause a kernel panic.
-[**lock**|**umount**|*repair*];;
+**lock**|**umount**|*repair*;;
These mount options don't do anything at present; when an error is encountered only a console message is printed.
=== Mount options for umsdos
@@ -1590,7 +1591,7 @@ Parity bytes for FEC (default: 2). Optional.
**verity.roothashsig=**__path__::
Path to *pkcs7*(1ssl) signature of root hash hex string. Requires crypt_activate_by_signed_key() from cryptsetup and kernel built with *CONFIG_DM_VERITY_VERIFY_ROOTHASH_SIG*. For device reuse, signatures have to be either used by all mounts of a device or by none. Optional.
-**verity.oncorruption=**__ignore__|__restart__|__panic__::
+**verity.oncorruption=**{*ignore*|*restart*|*panic*}::
Instruct the kernel to ignore, reboot or panic when corruption is detected. By default the I/O operation simply fails. Requires Linux 4.1 or newer, and libcrypsetup 2.3.4 or newer. Optional.
+
Supported since util-linux v2.35.
--
2.48.1
^ permalink raw reply related
* [PATCH 6/8] mount: (man) fix some indentation issues, and improve a few wordings
From: Benno Schulenberg @ 2025-04-07 15:14 UTC (permalink / raw)
To: util-linux
In-Reply-To: <20250407151503.23394-1-bensberg@telfort.nl>
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
sys-utils/mount.8.adoc | 31 ++++++++++++++++++++-----------
1 file changed, 20 insertions(+), 11 deletions(-)
diff --git a/sys-utils/mount.8.adoc b/sys-utils/mount.8.adoc
index 5103b91c5..f4a704556 100644
--- a/sys-utils/mount.8.adoc
+++ b/sys-utils/mount.8.adoc
@@ -567,6 +567,7 @@ mount -t tmpfs none /mnt -o \
....
____
++
For more details, see *selinux*(8).
*defaults*::
@@ -746,6 +747,7 @@ and xfs.
Note that comma is used as a separator between mount options, it means
that auto-fstypes values have to be properly quoted, don’t forget that the shell
strips off quotes and thus double quoting is required. For example:
++
____
mount -t auto -o'X-mount.auto-fstypes="noext2,ext3"' /dev/sdc1 /mnt/test
____
@@ -933,17 +935,23 @@ Set the umask applied to directories only. The default is the umask of the curre
Set the umask applied to regular files only. The default is the umask of the current process. The value is given in octal.
**allow_utime=**__value__::
-This option controls the permission check of mtime/atime.
+This option controls the permission check of mtime/atime. Possible values:
*20*;;
-If current process is in group of file's group ID, you can change timestamp.
-
+If the current process is in the group of the file's group ID,
+you can change the timestamp.
++
*2*;;
-Other users can change timestamp.
+Other users can change the timestamp.
-The default is set from 'dmask' option. (If the directory is writable, *utime*(2) is also allowed. I.e. ~dmask & 022)
-
-Normally *utime*(2) checks that the current process is owner of the file, or that it has the *CAP_FOWNER* capability. But FAT filesystems don't have UID/GID on disk, so the normal check is too inflexible. With this option you can relax it.
++
+The default is set from the above *dmask* option. (If the directory
+is writable, *utime*(2) is also allowed. That is: ~dmask & 022.)
+ +
+Normally *utime*(2) checks that the current process is the owner of the
+file, or that it has the *CAP_FOWNER* capability. But FAT filesystems
+don't have UID/GID on disk, so the normal check is too inflexible.
+With this option you can relax it.
**check=**__value__::
Three different levels of pickiness can be chosen:
@@ -1584,11 +1592,11 @@ Path to *pkcs7*(1ssl) signature of root hash hex string. Requires crypt_activate
**verity.oncorruption=**__ignore__|__restart__|__panic__::
Instruct the kernel to ignore, reboot or panic when corruption is detected. By default the I/O operation simply fails. Requires Linux 4.1 or newer, and libcrypsetup 2.3.4 or newer. Optional.
-
++
Supported since util-linux v2.35.
-
-For example commands:
-
++
+For example, the commands:
++
....
mksquashfs /etc /tmp/etc.raw
veritysetup format /tmp/etc.raw /tmp/etc.verity --root-hash-file=/tmp/etc.roothash
@@ -1598,6 +1606,7 @@ mount -o verity.hashdevice=/tmp/etc.verity,verity.roothashfile=/tmp/etc.roothash
verity.roothashsig=/tmp/etc.roothash.p7s /tmp/etc.raw /mnt
....
++
create squashfs image from _/etc_ directory, verity hash device and mount verified filesystem image to _/mnt_. The kernel will verify that the root hash is signed by a key from the kernel keyring if roothashsig is used.
== LOOP-DEVICE SUPPORT
--
2.48.1
^ permalink raw reply related
* [PATCH 5/8] eject: (man) add the missing SYNOPSIS header
From: Benno Schulenberg @ 2025-04-07 15:14 UTC (permalink / raw)
To: util-linux
In-Reply-To: <20250407151503.23394-1-bensberg@telfort.nl>
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
sys-utils/eject.1.adoc | 2 ++
1 file changed, 2 insertions(+)
diff --git a/sys-utils/eject.1.adoc b/sys-utils/eject.1.adoc
index 52988601d..1ee3b2137 100644
--- a/sys-utils/eject.1.adoc
+++ b/sys-utils/eject.1.adoc
@@ -18,6 +18,8 @@ for conditions under which this file may be redistributed.
eject - eject removable media
+== SYNOPSIS
+
*eject* [options] _device_|_mountpoint_
== DESCRIPTION
--
2.48.1
^ permalink raw reply related
* [PATCH 4/8] blkzone: (man) reduce two overblown tables to legible proportions
From: Benno Schulenberg @ 2025-04-07 15:14 UTC (permalink / raw)
To: util-linux
In-Reply-To: <20250407151503.23394-1-bensberg@telfort.nl>
Before version 2.37, before asciidoctor was used, the first three lines
of the first table looked like this:
start Zone start sector
len Zone length in number of sectors
wptr Zone write pointer position
After the move to asciidoctor, the first three lines of the first table
in the generated man page looked like this:
┌────────┬────────────────────────────┐
│ │ │
│start │ Zone start sector │
├────────┼────────────────────────────┤
│ │ │
│len │ Zone length in number of │
│ │ sectors │
├────────┼────────────────────────────┤
│ │ │
│wptr │ Zone write pointer │
│ │ position │
├────────┼────────────────────────────┤
Three to four screen lines for just one line of information!
Reduce the tables to sane proportions again by simply using blocks
of preformatted text.
(The substition of xN for x? is needed because somehow the ? in the
indented text is a special character in groff.)
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
sys-utils/blkzone.8.adoc | 44 +++++++++++++++++++---------------------
1 file changed, 21 insertions(+), 23 deletions(-)
diff --git a/sys-utils/blkzone.8.adoc b/sys-utils/blkzone.8.adoc
index 8456b5e42..ac5413ed0 100644
--- a/sys-utils/blkzone.8.adoc
+++ b/sys-utils/blkzone.8.adoc
@@ -29,31 +29,29 @@ The command *blkzone report* is used to report device zone information.
By default, the command will report all zones from the start of the block device. Options may be used to modify this behavior, changing the starting zone or the size of the report, as explained below.
Report output:
-[cols=",",]
-|===
-|start |Zone start sector
-|len |Zone length in number of sectors
-|cap |Zone capacity in number of sectors
-|wptr |Zone write pointer position
-|reset |Reset write pointer recommended
-|non-seq |Non-sequential write resources active
-|cond |Zone condition
-|type |Zone type
-|===
+....
+ start Zone start sector
+ len Zone length in number of sectors
+ cap Zone capacity in number of sectors
+ wptr Zone write pointer position
+ reset Reset write pointer recommended
+ non-seq Non-sequential write resources active
+ cond Zone condition
+ type Zone type
+....
Zone conditions:
-[cols=",",]
-|===
-|cl |Closed
-|nw |Not write pointer
-|em |Empty
-|fu |Full
-|oe |Explicitly opened
-|oi |Implicitly opened
-|ol |Offline
-|ro |Read only
-|x? |Reserved conditions (should not be reported)
-|===
+....
+ cl Closed
+ nw Not write pointer
+ em Empty
+ fu Full
+ oe Explicitly opened
+ oi Implicitly opened
+ ol Offline
+ ro Read only
+ xN Reserved conditions (should not be reported)
+....
=== capacity
--
2.48.1
^ permalink raw reply related
* [PATCH 3/8] hexdump: (man) normalize the synopsis, and shrink a list and two tables
From: Benno Schulenberg @ 2025-04-07 15:14 UTC (permalink / raw)
To: util-linux
In-Reply-To: <20250407151503.23394-1-bensberg@telfort.nl>
Simply use blocks of preformatted text for the tables, as asciidoctor
inflates true tables to overblown proportions on a man page.
Also, correct the code for DEL from FF to 7F.
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
text-utils/hexdump.1.adoc | 55 ++++++++++++++++++---------------------
1 file changed, 25 insertions(+), 30 deletions(-)
diff --git a/text-utils/hexdump.1.adoc b/text-utils/hexdump.1.adoc
index 153953817..c92733a51 100644
--- a/text-utils/hexdump.1.adoc
+++ b/text-utils/hexdump.1.adoc
@@ -48,9 +48,9 @@ hexdump - display file contents in hexadecimal, decimal, octal, or ascii
== SYNOPSIS
-*hexdump* _options file_ ...
+*hexdump* [options] _file_ ...
-*hd* _options file_ ...
+*hd* [options] _file_ ...
== DESCRIPTION
@@ -116,29 +116,24 @@ If an iteration count and/or a byte count is specified, a single slash must be p
The format is required and must be surrounded by double quote (" ") marks. It is interpreted as a fprintf-style format string (see *fprintf*(3)), with the following exceptions:
-1.::
-An asterisk (*) may not be used as a field width or precision.
+. An asterisk (*) may not be used as a field width or precision.
-2.::
-A byte count or field precision _is_ required for each *s* conversion character (unlike the *fprintf*(3) default which prints the entire string if the precision is unspecified).
+. A byte count or field precision _is_ required for each *s* conversion character
+(unlike the *fprintf*(3) default which prints the entire string if the precision is unspecified).
-3.::
-The conversion characters *h*, *l*, *n*, *p*, and *q* are not supported.
-
-4.::
-The single character escape sequences described in the C standard are supported:
+. The conversion characters *h*, *l*, *n*, *p*, and *q* are not supported.
+. The single character escape sequences described in the C standard are supported:
++
____
-|===
-|NULL |\0
-|<alert character> |\a
-|<backspace> |\b
-|<form-feed> |\f
-|<newline> |\n
-|<carriage return> |\r
-|<tab> |\t
-|<vertical tab> |\v
-|===
+ \0 NULL
+ \a alert character
+ \b backspace
+ \f form-feed
+ \n newline
+ \r carriage return
+ \t tab
+ \v vertical tab
____
=== Conversion strings
@@ -159,16 +154,16 @@ Output characters in the default character set. Non-printing characters are disp
*_u*::
Output US ASCII characters, with the exception that control characters are displayed using the following, lower-case, names. Characters greater than 0xff, hexadecimal, are displayed as hexadecimal strings.
-
++
____
-|===
-|000 nul |001 soh |002 stx |003 etx |004 eot |005 enq
-|006 ack |007 bel |008 bs |009 ht |00A lf |00B vt
-|00C ff |00D cr |00E so |00F si |010 dle |011 dc1
-|012 dc2 |013 dc3 |014 dc4 |015 nak |016 syn |017 etb
-|018 can |019 em |01A sub |01B esc |01C fs |01D gs
-|01E rs |01F us |0FF del | | |
-|===
+ 00 nul 08 bs 10 dle 18 can 7F del
+ 01 soh 09 ht 11 dc1 19 em
+ 02 stx 0A lf 12 dc2 1A sub
+ 03 etx 0B vt 13 dc3 1B esc
+ 04 eot 0C ff 14 dc4 1C fs
+ 05 enq 0D cr 15 nak 1D gs
+ 06 ack 0E so 16 syn 1E rs
+ 07 bel 0F si 17 etb 1F us
____
=== Colors
--
2.48.1
^ permalink raw reply related
* [PATCH 4/4] zramctl: (man) mention the required arguments for -p and -r
From: Benno Schulenberg @ 2025-04-06 15:21 UTC (permalink / raw)
To: util-linux
In-Reply-To: <20250406152147.9225-1-bensberg@telfort.nl>
Also, sort the options strictly alphabetically ("r" before "raw").
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
sys-utils/zramctl.8.adoc | 15 +++++++++------
sys-utils/zramctl.c | 4 ++--
2 files changed, 11 insertions(+), 8 deletions(-)
diff --git a/sys-utils/zramctl.8.adoc b/sys-utils/zramctl.8.adoc
index 4cc402e5c..c08f1e005 100644
--- a/sys-utils/zramctl.8.adoc
+++ b/sys-utils/zramctl.8.adoc
@@ -54,18 +54,21 @@ Define the status output columns to be used. If no output arrangement is specifi
+
The default list of columns may be extended if _list_ is specified in the format _+list_ (e.g., *zramctl -o+COMP-RATIO*).
-*-p*, *--algorithm-params*::
-Set the algorithm parameters, for example, *level=9 dict=/etc/dictionary* to set compression level and pre-trained dictionary. Parameters are algorithm specific.
-
*--output-all*::
Output all available columns.
+*-p*, *--algorithm-params* _parameter_...::
+Specify the parameters for the selected compression algorithm.
+For example, *level=9 dict=/etc/dictionary* sets the compression level
+and pre-trained dictionary. Parameters are algorithm-specific.
+
+*-r*, *--reset* _zramdev_...::
+Reset the specified zram device(s).
+The settings of a zram device can be changed only after a reset.
+
*--raw*::
Use the raw format for status output.
-*-r*, *--reset*::
-Reset the options of the specified zram device(s). Zram device settings can be changed only after a reset.
-
*-s*, *--size* _size_::
Create a zram device of the specified _size_. Zram devices are aligned to memory pages; when the requested _size_ is not a multiple of the page size, it will be rounded up to the next multiple. When not otherwise specified, the unit of the _size_ parameter is bytes.
+
diff --git a/sys-utils/zramctl.c b/sys-utils/zramctl.c
index b9ea5998e..fdb173ea5 100644
--- a/sys-utils/zramctl.c
+++ b/sys-utils/zramctl.c
@@ -751,9 +751,9 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -n, --noheadings don't print headings\n"), out);
fputs(_(" -o, --output <list> columns to use for status output\n"), out);
fputs(_(" --output-all output all columns\n"), out);
- fputs(_(" -p, --algorithm-params <parameters>\n"
+ fputs(_(" -p, --algorithm-params <parameter>...\n"
" parameters for the compression algorithm\n"), out);
- fputs(_(" -r, --reset reset all specified devices\n"), out);
+ fputs(_(" -r, --reset <device>... reset the specified zram devices\n"), out);
fputs(_(" --raw use raw status output format\n"), out);
fputs(_(" -s, --size <size> device size\n"), out);
fputs(_(" -t, --streams <number> number of compression streams\n"), out);
--
2.48.1
^ permalink raw reply related
* [PATCH 3/4] zramctl: restore normal description indentations in the usage text
From: Benno Schulenberg @ 2025-04-06 15:21 UTC (permalink / raw)
To: util-linux; +Cc: LiviaMedeiros
In-Reply-To: <20250406152147.9225-1-bensberg@telfort.nl>
Commit 19c12e63b1 from four months ago changed the indentation of *all*
the option descriptions in the usage text. That was the wrong thing to
do, as it invalidates all existing translations for no good reason.
When one of the options is (or needs to become) overlong, then the thing
to do is: to put the description of this option on the next line.
So, restore the indentation of the descriptions to what they were
before commit 19c12e63b1, and wrap the description of -p.
Also, make the description of -b fit within 80 columns, and sort the
options better: alphabetically, but single letter before long option.
CC: LiviaMedeiros <livia@cirno.name>
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
sys-utils/zramctl.c | 23 ++++++++++++-----------
1 file changed, 12 insertions(+), 11 deletions(-)
diff --git a/sys-utils/zramctl.c b/sys-utils/zramctl.c
index 36cc55ff9..b9ea5998e 100644
--- a/sys-utils/zramctl.c
+++ b/sys-utils/zramctl.c
@@ -745,17 +745,18 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_("Set up and control zram devices.\n"), out);
fputs(USAGE_OPTIONS, out);
- fputs(_(" -a, --algorithm <alg> compression algorithm to use\n"), out);
- fputs(_(" -b, --bytes print sizes in bytes rather than in human readable format\n"), out);
- fputs(_(" -f, --find find a free device\n"), out);
- fputs(_(" -n, --noheadings don't print headings\n"), out);
- fputs(_(" -o, --output <list> columns to use for status output\n"), out);
- fputs(_(" --output-all output all columns\n"), out);
- fputs(_(" -p, --algorithm-params <params> algorithm parameters to use\n"), out);
- fputs(_(" --raw use raw status output format\n"), out);
- fputs(_(" -r, --reset reset all specified devices\n"), out);
- fputs(_(" -s, --size <size> device size\n"), out);
- fputs(_(" -t, --streams <number> number of compression streams\n"), out);
+ fputs(_(" -a, --algorithm <alg> compression algorithm to use\n"), out);
+ fputs(_(" -b, --bytes print sizes in bytes, not in human-readable form\n"), out);
+ fputs(_(" -f, --find find a free device\n"), out);
+ fputs(_(" -n, --noheadings don't print headings\n"), out);
+ fputs(_(" -o, --output <list> columns to use for status output\n"), out);
+ fputs(_(" --output-all output all columns\n"), out);
+ fputs(_(" -p, --algorithm-params <parameters>\n"
+ " parameters for the compression algorithm\n"), out);
+ fputs(_(" -r, --reset reset all specified devices\n"), out);
+ fputs(_(" --raw use raw status output format\n"), out);
+ fputs(_(" -s, --size <size> device size\n"), out);
+ fputs(_(" -t, --streams <number> number of compression streams\n"), out);
fputs(USAGE_SEPARATOR, out);
fprintf(out, USAGE_HELP_OPTIONS(27));
--
2.48.1
^ permalink raw reply related
* [PATCH 2/4] textual: fix a mistruncated message, and fix a typo
From: Benno Schulenberg @ 2025-04-06 15:21 UTC (permalink / raw)
To: util-linux; +Cc: Petr Písař
In-Reply-To: <20250406152147.9225-1-bensberg@telfort.nl>
The phrase "in human-readable form" was chosen rather than
"in human-readable format" because it's shorter and lets
the line fit *just* within 80 columns.
Reported-by: Petr Písař <petr.pisar@atlas.cz>
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
sys-utils/lsipc.c | 2 +-
sys-utils/setpriv.c | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/sys-utils/lsipc.c b/sys-utils/lsipc.c
index 7b041790b..d292ab96c 100644
--- a/sys-utils/lsipc.c
+++ b/sys-utils/lsipc.c
@@ -338,7 +338,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" --noheadings don't print headings\n"), out);
fputs(_(" --notruncate don't truncate output\n"), out);
fputs(_(" --time-format=<type> display dates in short, full or iso format\n"), out);
- fputs(_(" -b, --bytes print SIZE in bytes rather\n"), out);
+ fputs(_(" -b, --bytes print SIZE in bytes rather than in human-readable form\n"), out);
fputs(_(" -c, --creator show creator and owner\n"), out);
fputs(_(" -e, --export display in an export-able output format\n"), out);
fputs(_(" -J, --json use the JSON output format\n"), out);
diff --git a/sys-utils/setpriv.c b/sys-utils/setpriv.c
index daa3ab366..433db6031 100644
--- a/sys-utils/setpriv.c
+++ b/sys-utils/setpriv.c
@@ -1025,7 +1025,7 @@ int main(int argc, char **argv)
case SECCOMP_FILTER:
if (opts.seccomp_filter)
errx(EXIT_FAILURE,
- _("duplicate --secccomp-filter option"));
+ _("duplicate --seccomp-filter option"));
opts.seccomp_filter = optarg;
break;
case RESET_ENV:
--
2.48.1
^ permalink raw reply related
* [PATCH 1/4] hwclock: remove two comments about parameters that no longer exist
From: Benno Schulenberg @ 2025-04-06 15:21 UTC (permalink / raw)
To: util-linux
Commit 336f7c5f68 from nine years ago removed the 'universal' and
'testing' parameters of do_adjustment() but forgot to update the
leading comment.
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
sys-utils/hwclock.c | 5 -----
1 file changed, 5 deletions(-)
diff --git a/sys-utils/hwclock.c b/sys-utils/hwclock.c
index 9977e0600..7ae7fca11 100644
--- a/sys-utils/hwclock.c
+++ b/sys-utils/hwclock.c
@@ -943,11 +943,6 @@ done:
* Hardware clock set time is subtracted from read_time to 'refer back', or
* delay, the trigger point. Fractional parts must be accounted for in this
* way, because the Hardware Clock can only be set to a whole second.
- *
- * <universal>: the Hardware Clock is kept in UTC.
- *
- * <testing>: We are running in test mode (no updating of clock).
- *
*/
static void
do_adjustment(const struct hwclock_control *ctl, struct adjtime *adjtime_p,
--
2.48.1
^ permalink raw reply related
* Re: Message typos in util-linux-2.41-rc2
From: Benno Schulenberg @ 2025-04-06 11:28 UTC (permalink / raw)
To: Petr Pisar, util-linux
In-Reply-To: <Z_JbYZ-SdnjxZB0K@album.bayer.uni.cx>
[-- Attachment #1.1: Type: text/plain, Size: 940 bytes --]
Hello Petr,
Op 06-04-2025 om 12:45 schreef Petr Pisar:
> # FIXME: Wrong manual section: setuid(1)
> #: lsfd-cmd/lsfd.c:2197
> msgid ""
> " --_drop-privilege (testing purpose) do setuid(1) just after"
> "starting\n"
Here, the "(1)" does not refer to the man page section, but indicates the
actual parameter that is passed to setuid():
https://github.com/util-linux/util-linux/blob/master/lsfd-cmd/lsfd.c#L2645
> # FIXME: Superfluous \t\t\t\t
> #: sys-utils/ipcrm.c:[...]
All of these tab things have already been fixed:
https://github.com/util-linux/util-linux/commit/3d9573b981
> # FIXME: missing "than in human readable format"
> #: sys-utils/lsipc.c:340
> msgid " -b, --bytes print SIZE in bytes rather\n"
> # FIXME: Typo in --seccomp-filter option name
> #: sys-utils/setpriv.c:1028
> msgid "duplicate --secccomp-filter option"
Thanks. Will fix.
Benno
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 840 bytes --]
^ permalink raw reply
* Message typos in util-linux-2.41-rc2
From: Petr Pisar @ 2025-04-06 10:45 UTC (permalink / raw)
To: util-linux
[-- Attachment #1: Type: text/plain, Size: 2039 bytes --]
Hello,
when translation util-linux-2.41-rc2 to Czech language I found these issues in
the orginial messages:
# FIXME: Wrong manual section: setuid(1)
#: lsfd-cmd/lsfd.c:2197
msgid ""
" --_drop-privilege (testing purpose) do setuid(1) just after "
"starting\n"
# FIXME: Superfluous \t\t\t\t
#: sys-utils/ipcrm.c:59
msgid ""
" -m, --shmem-id <id> \t\t\t\tremove shared memory segment by id\n"
# FIXME: Superfluous \t\t\t\t
#: sys-utils/ipcrm.c:60
msgid ""
" -M, --shmem-key <key> \t\t\t\tremove shared memory segment by key\n"
# FIXME: Superfluous \t\t\t\t
#: sys-utils/ipcrm.c:61
msgid ""
" --posix-shmem <name> \t\t\t\tremove POSIX shared memory segment by "
"name\n"
# FIXME: Superfluous \t\t\t\t
#: sys-utils/ipcrm.c:62
msgid " -q, --queue-id <id> \t\t\t\tremove message queue by id\n"
# FIXME: Superfluous \t\t\t\t
#: sys-utils/ipcrm.c:63
msgid " -Q, --queue-key <key> \t\t\t\tremove message queue by key\n"
# FIXME: Superfluous \t\t\t\t
#: sys-utils/ipcrm.c:64
msgid ""
" --posix-mqueue <name> \t\t\t\tremove POSIX message queue by name\n"
# FIXME: Superfluous \t\t\t\t
#: sys-utils/ipcrm.c:65
msgid " -s, --semaphore-id <id> \t\t\t\tremove semaphore by id\n"
# FIXME: Superfluous \t\t\t\t
#: sys-utils/ipcrm.c:66
msgid " -S, --semaphore-key <key> \t\t\t\tremove semaphore by key\n"
# FIXME: Superfluous \t\t\t\t
#: sys-utils/ipcrm.c:67
msgid " --posix-semaphore <name> \t\t\t\tremove POSIX semaphore by name\n"
# FIXME: See, no superfluous \t\t\t\t here.
#: sys-utils/ipcrm.c:68
msgid ""
" -a, --all[=shm|pshm|msg|pmsg|sem|psem]\tremove all (in the specified "
"category)\n"
# FIXME: Superfluous \t\t\t\t
#: sys-utils/ipcrm.c:69
msgid " -v, --verbose \t\t\t\texplain what is being done\n"
# FIXME: missing "than in human readable format"
#: sys-utils/lsipc.c:340
msgid " -b, --bytes print SIZE in bytes rather\n"
# FIXME: Typo in --seccomp-filter option name
#: sys-utils/setpriv.c:1028
msgid "duplicate --secccomp-filter option"
-- Petr
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply
* uuid_clear.3: Some remarks and a patch with editorial changes for this man page
From: Bjarni Ingi Gislason @ 2025-04-05 0:22 UTC (permalink / raw)
To: util-linux
[-- Attachment #1: Type: text/plain, Size: 1338 bytes --]
Package: uuid-dev
Version: 2.40.4-5
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with a new version
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z < "man page"
[Use
grep -n -e ' $' -e '\\~$' -e ' \\f.$' -e ' \\"' <file>
to find (most) trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
troff:<stdin>:10: warning: name 'Aq' not defined
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.12.20-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1), LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages uuid-dev depends on:
ii libc6-dev [libc-dev] 2.41-6
ii libuuid1 2.40.4-5
uuid-dev recommends no packages.
uuid-dev suggests no packages.
-- no debconf information
[-- Attachment #2: chk_man.err.uuid_clear.3 --]
[-- Type: text/plain, Size: 4611 bytes --]
Input file is uuid_clear.3
Output from "mandoc -T lint uuid_clear.3": (shortened list)
1 input text line longer than 80 bytes: The \fBlibuuid\fP li...
1 input text line longer than 80 bytes: The \fBuuid_clear\fP...
1 skipping insecure request: mso
6 skipping paragraph macro: sp after SH
1 skipping unknown macro: LINKSTYLE blue R < >
1 undefined string, using "": Aq
-.-.
Output from
test-nroff -mandoc -t -ww -z uuid_clear.3: (shortened list)
1 name 'Aq' not defined
-.-.
Wrong distance (not two spaces) between sentences in the input file.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
Mark a final abbreviation point as such by suffixing it with "\&".
Some sentences (etc.) do not begin on a new line.
Split (sometimes) lines after a punctuation mark; before a conjunction.
Lines with only one (or two) space(s) between sentences could be split,
so latter sentences begin on a new line.
Use
#!/usr/bin/sh
sed -e '/^\./n' \
-e 's/\([[:alpha:]]\)\. */\1.\n/g' $1
to split lines after a sentence period.
Check result with the difference between the formatted outputs.
See also the attachment "general.bugs"
42:Theodore Y. Ts\(cqo
58:The \fBlibuuid\fP library is part of the util\-linux package since version 2.15.1. It can be downloaded from \c
-.-.
Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Add "\:" to split the string for the output, "\<newline>" in the source.
Line 39, length 104
The \fBuuid_clear\fP() function sets the value of the supplied uuid variable \fIuu\fP to the NULL value.
Line 58, length 111
The \fBlibuuid\fP library is part of the util\-linux package since version 2.15.1. It can be downloaded from \c
Line 59, length 85
.URL "https://www.kernel.org/pub/linux/utils/util\-linux/" "Linux Kernel Archive" "."
Longest line is number 58 with 111 characters
-.-.
Only one space character is after a possible end of sentence
(after a punctuation, that can end a sentence).
uuid_clear.3:42:Theodore Y. Ts\(cqo
uuid_clear.3:58:The \fBlibuuid\fP library is part of the util\-linux package since version 2.15.1. It can be downloaded from \c
-.-.
Put a subordinate sentence (after a comma) on a new line.
uuid_clear.3:54:For bug reports, use the issue tracker at \c
-.-.
Remove quotes when there is a printable
but no space character between them
and the quotes are not for emphasis (markup),
for example as an argument to a macro.
uuid_clear.3:10:.TH "UUID_CLEAR" "3" "2024-12-16" "util\-linux 2.40.4" "Programmer\*(Aqs Manual"
uuid_clear.3:30:.SH "NAME"
uuid_clear.3:32:.SH "SYNOPSIS"
uuid_clear.3:37:.SH "DESCRIPTION"
uuid_clear.3:40:.SH "AUTHORS"
uuid_clear.3:55:.URL "https://github.com/util\-linux/util\-linux/issues" "" "."
uuid_clear.3:56:.SH "AVAILABILITY"
uuid_clear.3:59:.URL "https://www.kernel.org/pub/linux/utils/util\-linux/" "Linux Kernel Archive" "."
-.-.
Use ".na" (no adjustment) instead of ".ad l" (and ".ad" to begin the
same adjustment again as before).
15:.ad l
23:. ad l
26:. ad l
-.-.
Section headings (.SH and .SS) do not need quoting their arguments.
30:.SH "NAME"
32:.SH "SYNOPSIS"
37:.SH "DESCRIPTION"
40:.SH "AUTHORS"
43:.SH "SEE ALSO"
52:.SH "REPORTING BUGS"
56:.SH "AVAILABILITY"
-.-.
Put a (long) web address on a new line to reduce the posibility of
splitting the address between two output lines.
Or inhibit hyphenation with "\%" in front of the name.
55:.URL "https://github.com/util\-linux/util\-linux/issues" "" "."
59:.URL "https://www.kernel.org/pub/linux/utils/util\-linux/" "Linux Kernel Archive" "."
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z ":
troff:<stdin>:10: warning: name 'Aq' not defined
-.-.
Additionally:
Add a new line (\n) to the end of the file.
-.-
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
[-- Attachment #3: uuid_clear.3.diff --]
[-- Type: text/plain, Size: 756 bytes --]
--- uuid_clear.3 2025-04-05 00:04:44.296483330 +0000
+++ uuid_clear.3.new 2025-04-05 00:08:47.373477627 +0000
@@ -7,6 +7,8 @@
.\" Source: util-linux 2.40.4
.\" Language: English
.\"
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
.TH "UUID_CLEAR" "3" "2024-12-16" "util\-linux 2.40.4" "Programmer\*(Aqs Manual"
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
@@ -56,4 +58,4 @@ For bug reports, use the issue tracker a
.SH "AVAILABILITY"
.sp
The \fBlibuuid\fP library is part of the util\-linux package since version 2.15.1. It can be downloaded from \c
-.URL "https://www.kernel.org/pub/linux/utils/util\-linux/" "Linux Kernel Archive" "."
\ No newline at end of file
+.URL "https://www.kernel.org/pub/linux/utils/util\-linux/" "Linux Kernel Archive" "."
[-- Attachment #4: general.bugs --]
[-- Type: text/plain, Size: 1998 bytes --]
Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)
[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>
To find trailing space use
grep -n -e ' $' -e ' \\f.$' -e ' \\"' <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
It should also check its input files for too long (> 80) lines.
This is just a simple quality control measure.
The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
"git" has a "tool" to point out whitespace,
see for example "git-apply(1)" and git-config(1)")
Not beginning each input sentence on a new line.
Line length and patch size should thus be reduced.
The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.
See man-pages(7), item "semantic newline".
-.-
The difference between the formatted output of the original and patched file
can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -d -u <out1> <out2>
and for groff, using
\"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - \"
instead of 'nroff -mandoc'
Add the option '-t', if the file contains a table.
Read the output from 'diff -d -u ...' with 'less -R' or similar.
-.-.
If 'man' (man-db) is used to check the manual for warnings,
the following must be set:
The option "-warnings=w"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT="-ww -b -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-
^ permalink raw reply
* Re: [PATCH 09/10] coresched: reduce excessive whitespace and verbosity in usage text
From: Karel Zak @ 2025-04-03 12:08 UTC (permalink / raw)
To: Benno Schulenberg; +Cc: util-linux, Phil Auld, Thijs Raymakers
In-Reply-To: <2c111844-b6fa-42cc-8333-eec4d7bb4a49@telfort.nl>
On Thu, Apr 03, 2025 at 11:55:12AM +0200, Benno Schulenberg wrote:
>
> Op 03-04-2025 om 10:11 schreef Karel Zak:
> > On Mon, Mar 31, 2025 at 11:44:42AM +0200, Benno Schulenberg wrote:
> > > - fputsln(_("Manage core scheduling cookies for tasks."), stdout);
> > > + fputsln(_("Manage core-scheduling cookies for tasks."), stdout);
>
> > > - fputsln(_(" get retrieve the core scheduling cookie of a PID"),
> > > + fputsln(_(" get retrieve the core-scheduling cookie of a PID"), stdout);
>
>
> > There is a comment from Thijs that kernel docs does not use hyphen, it
> > means "core scheduling" rather than "core-scheduling". Maybe it would
> > be better to follow kernel.
>
> When speaking of the scheduling itself, it is indeed "core scheduling",
> but when using this compound word as an adjective, then it is much
> clearer to hyphenate it, to avoid the impression that it is talking
> about a _core_, deep, central scheduling cookie.
OK, merged :-)
Karel
--
Karel Zak <kzak@redhat.com>
http://karelzak.blogspot.com
^ permalink raw reply
* Re: [PATCH 09/10] coresched: reduce excessive whitespace and verbosity in usage text
From: Benno Schulenberg @ 2025-04-03 9:55 UTC (permalink / raw)
To: Karel Zak; +Cc: util-linux, Phil Auld, Thijs Raymakers
In-Reply-To: <cztqfu3prb4v2urpxrujq5wqqdclnxwsny4h5ejbml7d7kll2n@yj3dgreqhtrl>
[-- Attachment #1.1: Type: text/plain, Size: 1141 bytes --]
Op 03-04-2025 om 10:11 schreef Karel Zak:
> On Mon, Mar 31, 2025 at 11:44:42AM +0200, Benno Schulenberg wrote:
>> - fputsln(_("Manage core scheduling cookies for tasks."), stdout);
>> + fputsln(_("Manage core-scheduling cookies for tasks."), stdout);
>> - fputsln(_(" get retrieve the core scheduling cookie of a PID"),
>> + fputsln(_(" get retrieve the core-scheduling cookie of a PID"), stdout);
> There is a comment from Thijs that kernel docs does not use hyphen, it
> means "core scheduling" rather than "core-scheduling". Maybe it would
> be better to follow kernel.
When speaking of the scheduling itself, it is indeed "core scheduling",
but when using this compound word as an adjective, then it is much
clearer to hyphenate it, to avoid the impression that it is talking
about a _core_, deep, central scheduling cookie.
> https://www.kernel.org/doc/html/latest/admin-guide/hw-vuln/core-scheduling.html
In that first paragraph, I would write "Core-scheduling support...".
https://www.grammarly.com/blog/punctuation-capitalization/hyphen-with-compound-modifiers/
Benno
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 840 bytes --]
^ permalink raw reply
* Re: [PATCH 09/10] coresched: reduce excessive whitespace and verbosity in usage text
From: Karel Zak @ 2025-04-03 8:11 UTC (permalink / raw)
To: Benno Schulenberg; +Cc: util-linux, Phil Auld, Thijs Raymakers
In-Reply-To: <20250331094443.9619-9-bensberg@telfort.nl>
On Mon, Mar 31, 2025 at 11:44:42AM +0200, Benno Schulenberg wrote:
> Also, use semicolons instead of periods in option descriptions.
>
> And consistently use an uppercased "PID" in feedback messages.
>
> CC: Phil Auld <pauld@redhat.com>
> CC: Thijs Raymakers <thijs@raymakers.nl>
> Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
> ---
> schedutils/coresched.c | 33 +++++++++++++--------------------
> 1 file changed, 13 insertions(+), 20 deletions(-)
>
> diff --git a/schedutils/coresched.c b/schedutils/coresched.c
> index 9d8be3e12..7634d988c 100644
> --- a/schedutils/coresched.c
> +++ b/schedutils/coresched.c
> @@ -80,31 +80,24 @@ static void __attribute__((__noreturn__)) usage(void)
> program_invocation_short_name);
>
> fputs(USAGE_SEPARATOR, stdout);
> - fputsln(_("Manage core scheduling cookies for tasks."), stdout);
> + fputsln(_("Manage core-scheduling cookies for tasks."), stdout);
>
> fputs(USAGE_FUNCTIONS, stdout);
> - fputsln(_(" get retrieve the core scheduling cookie of a PID"),
> - stdout);
> - fputsln(_(" new assign a new core scheduling cookie to an existing\n"
> - " PID or execute a program with a new cookie"),
> - stdout);
> - fputsln(_(" copy copy the core scheduling cookie from an existing PID\n"
> - " to another PID, or execute a program with that\n"
> - " copied cookie"),
> - stdout);
> + fputsln(_(" get retrieve the core-scheduling cookie of a PID"), stdout);
There is a comment from Thijs that kernel docs does not use hyphen, it
means "core scheduling" rather than "core-scheduling". Maybe it would
be better to follow kernel.
https://www.kernel.org/doc/html/latest/admin-guide/hw-vuln/core-scheduling.html
https://github.com/util-linux/util-linux/pull/3500
Karel
--
Karel Zak <kzak@redhat.com>
http://karelzak.blogspot.com
^ permalink raw reply
* Re: [PATCH 01/10] enosys: add the missing arguments of -s and -i to the usage text
From: Karel Zak @ 2025-04-02 11:11 UTC (permalink / raw)
To: Benno Schulenberg; +Cc: util-linux
In-Reply-To: <20250331094443.9619-1-bensberg@telfort.nl>
PR for all patches, except the last one (--dest-type rename), on
GitHub: https://github.com/util-linux/util-linux/pull/3500.
It will be merged if it passes the relevant tests.
Thanks!
Karel
--
Karel Zak <kzak@redhat.com>
http://karelzak.blogspot.com
^ permalink raw reply
* Re: [PATCH 05/10] irqtop: improve several more option descriptions, and align them all
From: Karel Zak @ 2025-04-02 10:58 UTC (permalink / raw)
To: Benno Schulenberg; +Cc: Joe Jin, util-linux, Zhenwei Pi
In-Reply-To: <3b638c6f-e304-4771-b952-3f7172779966@telfort.nl>
On Tue, Apr 01, 2025 at 11:17:47AM +0200, Benno Schulenberg wrote:
>
> Op 31-03-2025 om 18:12 schreef Joe Jin:
> > > > Why remove the "Q"?
> > >
> > > It looks ugly. And why would the user want to hold Shift before pressing q,
> > > when just pressing q will do? Holding Shift has no extra effect.
> >
> > Then should it be removed from parse_input() as well?
>
> No, there it should stay, to accommodate users that for some reason
> have CapsLock engaged.
>
> I would propose the opposite change: to accept also the uppercase I,
> T, D, and N for sorting the table on the corresponding column.
I prefer your current version of the patch (keep Q usable for backward
compatibility, but don't announce it in the docs/help). I don't think
we need to extend support for uppercase letters. The letters are rare, so
save them for the future :-)
Karel
--
Karel Zak <kzak@redhat.com>
http://karelzak.blogspot.com
^ permalink raw reply
* Re: [PATCH 10/10] coresched: rename option '--dest-type' to just '--type'
From: Karel Zak @ 2025-04-01 12:20 UTC (permalink / raw)
To: Benno Schulenberg; +Cc: Phil Auld, util-linux, Thijs Raymakers
In-Reply-To: <a281e4be-2cd9-4d22-be86-502395556005@telfort.nl>
On Tue, Apr 01, 2025 at 11:25:40AM +0200, Benno Schulenberg wrote:
>
> Op 01-04-2025 om 10:35 schreef Karel Zak:
> > On Mon, Mar 31, 2025 at 07:09:02AM -0400, Phil Auld wrote:
> > > but this could break users. There
> > > may not be that many yet anyway, of course.
> >
> > It's already released, so it is truly a backward-incompatible change.
>
> Users of a brand-new tool really should expect some iterations in the
> next versions to improve the feel of it. So I don't see a problem in
> correcting a poor choice for a long-option name.
We've already discussed this, and --dest-type was chosen because
there's --source <pid> and --dest <pid>. We wanted to ensure users
understand the type relates to --dest. It's just an option name, so
let's not get into bike-shedding, please ;-)
Karel
--
Karel Zak <kzak@redhat.com>
http://karelzak.blogspot.com
^ permalink raw reply
* Re: [PATCH 10/10] coresched: rename option '--dest-type' to just '--type'
From: Benno Schulenberg @ 2025-04-01 9:25 UTC (permalink / raw)
To: Karel Zak, Phil Auld; +Cc: util-linux, Thijs Raymakers
In-Reply-To: <tvh2bppxcinonxmyjrrgghgsylnaz6mkcrqr5ifxfqxvw54jym@iirtylnnzx4h>
[-- Attachment #1.1: Type: text/plain, Size: 477 bytes --]
Op 01-04-2025 om 10:35 schreef Karel Zak:
> On Mon, Mar 31, 2025 at 07:09:02AM -0400, Phil Auld wrote:
>> but this could break users. There
>> may not be that many yet anyway, of course.
>
> It's already released, so it is truly a backward-incompatible change.
Users of a brand-new tool really should expect some iterations in the
next versions to improve the feel of it. So I don't see a problem in
correcting a poor choice for a long-option name.
Benno
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 840 bytes --]
^ permalink raw reply
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox