[PATCH 3/5] erofs-utils: man: mkfs.erofs: wording/formatting touchups

[Gao Xiang]

On 2023/4/9 19:56, Ahelenia Ziemiańska wrote:
> Some things that gave me pause or were weirdly formatted.
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli at nabijaczleweli.xyz>

Thanks, it looks much better than the current status.

Reviewed-by: Gao Xiang <hsiangkao at linux.alibaba.com>

Thanks,
Gao Xiang

> ---
>   man/mkfs.erofs.1 | 100 +++++++++++++++++++++++++++--------------------
>   1 file changed, 57 insertions(+), 43 deletions(-)
> 
> diff --git a/man/mkfs.erofs.1 b/man/mkfs.erofs.1
> index 82ef138..1cfde28 100644
> --- a/man/mkfs.erofs.1
> +++ b/man/mkfs.erofs.1
> @@ -20,25 +20,25 @@ mkfs.erofs is used to create such EROFS filesystem \fIDESTINATION\fR image file
>   from \fISOURCE\fR directory.
>   .SH OPTIONS
>   .TP
> -.BI "\-z " compression-algorithm " [" ",#" "]" " [:" " ... " "]"
> +.BI "\-z " compression-algorithm \fR[\fP, # \fR][\fP: ... \fR]\fP
>   Set a primary algorithm for data compression, which can be set with an optional
>   compression level (1 to 12 for LZ4HC, 0 to 9 for LZMA and 100 to 109 for LZMA
>   extreme compression) separated by a comma.  Alternative algorithms could be
>   specified and separated by colons.
>   .TP
>   .BI "\-C " max-pcluster-size
> -Specify the maximum size of compress physical cluster in bytes. It may enable
> -big pcluster feature if needed (Linux v5.13+).
> +Specify the maximum size of compress physical cluster in bytes.
> +This may cause the big pcluster feature to be enabled (Linux v5.13+).
>   .TP
>   .BI "\-d " #
>   Specify the level of debugging messages. The default is 2, which shows basic
>   warning messages.
>   .TP
>   .BI "\-x " #
> -Specify the upper limit of an xattr which is still inlined. The default is 2.
> -Disable storing xattrs if < 0.
> +Limit how many xattrs will be inlined. The default is 2.
> +Disables storing xattrs if < 0.
>   .TP
> -.BI "\-E " extended-option " [,...]"
> +.BI "\-E " extended-option \fR[\fP, ... \fR]\fP
>   Set extended options for the filesystem. Extended options are comma separated,
>   and may take an extra argument using the equals ('=') sign.
>   The following extended options are supported:
> @@ -51,29 +51,30 @@ it may take an argument as the pcluster size of the packed inode in bytes.
>   .TP
>   .BI dedupe
>   Enable global compressed data deduplication to minimize duplicated data in
> -the filesystem. It may be used with \fI-Efragments\fR option together to
> -further reduce image sizes. (Linux v6.1+)
> +the filesystem. May further reduce image size when used with
> +.BR -E\ fragments .
> +(Linux v6.1+)
>   .TP
>   .BI force-inode-compact
> -Forcely generate compact inodes (32-byte inodes) to output.
> +Force generation of compact (32-byte) inodes.
>   .TP
>   .BI force-inode-extended
> -Forcely generate extended inodes (64-byte inodes) to output.
> +Force generation of extended (64-byte) inodes.
>   .TP
>   .BI force-inode-blockmap
> -Forcely generate inode chunk format in 4-byte block address array.
> +Force generation of inode chunk format as a 4-byte block address array.
>   .TP
>   .BI force-chunk-indexes
> -Forcely generate inode chunk format in 8-byte chunk indexes (with device id).
> +Forcely generate inode chunk format as an 8-byte chunk index (with device ID).
>   .TP
> -.BI fragments
> -Pack the tail part (pcluster) of compressed files or the whole files into a
> +.BI fragments\fR[\fP= size \fR]\fP
> +Pack the tail part (pcluster) of compressed files, or entire files, into a
>   special inode for smaller image sizes, and it may take an argument as the
>   pcluster size of the packed inode in bytes. (Linux v6.1+)
>   .TP
>   .BI legacy-compress
> -Drop "inplace decompression" and "compacted indexes" support, which is used
> -to generate compatible EROFS images for Linux v4.19 - 5.3.
> +Disable "inplace decompression" and "compacted indexes",
> +for compatibility with Linux pre-v5.4.
>   .TP
>   .BI noinline_data
>   Don't inline regular files to enable FSDAX for these files (Linux v5.15+).
> @@ -89,8 +90,8 @@ Set the volume label for the filesystem to
>   The maximum length of the volume label is 16 bytes.
>   .TP
>   .BI "\-T " #
> -Set all files to the given UNIX timestamp. Reproducible builds requires setting
> -all to a specific one.
> +Set all files to the given UNIX timestamp. Reproducible builds require setting
> +all to a specific one. By default, the source file's modification time is used.
>   .TP
>   .BI "\-U " UUID
>   Set the universally unique identifier (UUID) of the filesystem to
> @@ -102,64 +103,77 @@ like this: "c1b9d5a2-f162-11cf-9ece-0020afc76f16".
>   Make all files owned by root.
>   .TP
>   .BI "\-\-blobdev " file
> -Specify another extra blob device to store chunk-based data.
> +Specify an extra blob device to store chunk-based data.
>   .TP
>   .BI "\-\-chunksize " #
>   Generate chunk-based files with #-byte chunks.
>   .TP
>   .BI "\-\-compress-hints " file
> -If the optional
> -.BI "\-\-compress-hints " file
> -argument is given,
> -.B mkfs.erofs
> -uses it to apply the per-file compression strategy. Each line is defined by
> +Apply a per-file compression strategy. Each line in
> +.I file
> +is defined by
>   tokens separated by spaces in the following form.  Optionally, instead of
> -the given primary algorithm, alternative algorithms could be specified with
> -\fIalgorithm-index\fR by hand:
> +the given primary algorithm, alternative algorithms can be specified with
> +\fIalgorithm-index\fR explicitly:
>   .RS 1.2i
> -<pcluster-in-bytes> [algorithm-index] <match-pattern>
> +<pcluster-size-in-bytes> [algorithm-index] <match-pattern>
>   .RE
> +.IR match-pattern s
> +are extended regular expressions, matched against absolute paths within
> +the output filesystem, with no leading /.
>   .TP
>   .BI "\-\-exclude-path=" path
>   Ignore file that matches the exact literal path.
> -You may give multiple `--exclude-path' options.
> +You may give multiple
> +.B --exclude-path
> +options.
>   .TP
>   .BI "\-\-exclude-regex=" regex
> -Ignore files that match the given regular expression.
> -You may give multiple `--exclude-regex` options.
> +Ignore files that match the given extended regular expression.
> +You may give multiple
> +.B --exclude-regex
> +options.
>   .TP
>   .BI "\-\-file-contexts=" file
> -Specify a \fIfile_contexts\fR file to setup / override selinux labels.
> +Read SELinux label configuration/overrides from \fIfile\fR in the
> +.BR selinux_file (5)
> +format.
>   .TP
>   .BI "\-\-force-uid=" UID
> -Set all file uids to \fIUID\fR.
> +Set all file UIDs to \fIUID\fR.
>   .TP
>   .BI "\-\-force-gid=" GID
> -Set all file gids to \fIGID\fR.
> +Set all file GIDs to \fIGID\fR.
>   .TP
>   .BI "\-\-gid-offset=" GIDOFFSET
> -Add \fIGIDOFFSET\fR to all file gids.
> -When this option is used together with --force-gid, the final file gids are
> +Add \fIGIDOFFSET\fR to all file GIDs.
> +When this option is used together with
> +.BR --force-gid ,
> +the final file gids are
>   set to \fIGID\fR + \fIGID-OFFSET\fR.
>   .TP
>   .B \-\-help
> -Display this help and exit.
> +Display help string and exit.
>   .TP
>   .B "\-\-ignore-mtime"
> -File modification time is ignored whenever it would cause \fBmkfs.erofs\fR to
> +Ignore the file modification time whenever it would cause \fBmkfs.erofs\fR to
>   use extended inodes over compact inodes. When not using a fixed timestamp, this
> -can reduce total metadata size.
> +can reduce total metadata size. Implied by
> +.BR "-E force-inode-compact" .
>   .TP
>   .BI "\-\-max-extent-bytes " #
> -Specify maximum decompressed extent size # in bytes.
> +Specify maximum decompressed extent size in bytes.
>   .TP
>   .B "\-\-preserve-mtime"
> -File modification time is preserved whenever \fBmkfs.erofs\fR decides to use
> -extended inodes over compact inodes.
> +Use extended inodes instead of compact inodes if the file modification time
> +would overflow compact inodes. This is the default. Overrides
> +.BR --ignore-mtime .
>   .TP
>   .BI "\-\-uid-offset=" UIDOFFSET
> -Add \fIUIDOFFSET\fR to all file uids.
> -When this option is used together with --force-uid, the final file uids are
> +Add \fIUIDOFFSET\fR to all file UIDs.
> +When this option is used together with
> +.BR --force-uid ,
> +the final file uids are
>   set to \fIUID\fR + \fIUIDOFFSET\fR.
>   .SH AUTHOR
>   This version of \fBmkfs.erofs\fR is written by Li Guifu <blucerlee at gmail.com>,