Re: [PATCH] filesystems.5, erofs.5: add erofs documentation

[Alejandro Colomar <alx.manpages@gmail.com>]

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

Hi наб!

On 4/9/23 19:16, наб wrote:
> Modelled after tmpfs(5) ‒ there's a listing of mount options,
> and a summary of limitations. The feature flags are described in
> mkfs.erofs, and they're versioned and maintained upstream quite well
> there, so no need to duplicate those, since you only care on image
> creation.
> 
> The real value add is the mount options, but I cannot figure out
> how device_id and fsid interact with the system at large,
> so I just noted they're there.
> 
> State as of 6.3-rc5.
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>

Applying: filesystems.5, erofs.5: add erofs documentation
/home/alx/src/linux/man-pages/man-pages/.bare.git/worktrees/master/rebase-apply/patch:65: trailing whitespace.
Must be given as many times and in the same order as 
warning: 1 line adds whitespace errors.

> ---
>  man5/erofs.5       | 84 ++++++++++++++++++++++++++++++++++++++++++++++
>  man5/filesystems.5 |  6 ++++
>  2 files changed, 90 insertions(+)
>  create mode 100644 man5/erofs.5
> 
> diff --git a/man5/erofs.5 b/man5/erofs.5
> new file mode 100644
> index 000000000..de5b56121
> --- /dev/null
> +++ b/man5/erofs.5
> @@ -0,0 +1,84 @@
> +.\" Copyright (c) 2016 by Michael Kerrisk <mtk.manpages@gmail.com>
> +.\"
> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> +.\"
> +.TH erofs 5 (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +erofs \- the Enhanced Read-Only File System
> +.SH DESCRIPTION
> +.B erofs
> +is a create-once read-only filesystem,
> +with support for compression and a multi-device backing store.
> +.PP
> +There are two inode formats:
> +32-byte compact with 16-bit UID/GID, 32-bit file size, and no file times,
> +and 64-byte extended with 32-bit UID/GID, 64-bit file size,
> +and a modification time
> +.RI ( st_mtim ).

The above is a bit difficult to parse due to the ands and commas.
How about a list (.IP \[bu] 3) with the two entries or something
like that?

> +.\" See fs/erofs/super.c:shmem_parse_options for options it supports.
> +.SS Mount options
> +.TP
> +.BR user_xattr / nouser_xattr
> +Controls whether
> +.I user
> +extended attributes are exposed.
> +Defaults to yes
> +.TP
> +.BR acl / noacl
> +Controls whether POSIX
> +.BR acl (5)s
> +are exposed.
> +Defaults to yes.
> +.TP
> +.BR cache_strategy = disabled | readahead | readaround
> +Cache allocation for compressed files:
> +never, if reading from start of file, regardless of position.
> +Defaults to
> +.BR readaround .
> +.TP
> +.BR dax ", " dax = always | never
> +Direct Access control.
> +If
> +.B always
> +and the source device supports DAX, uncompressed non-inlined files
> +will be read directly, without going through the page cache.
> +.B dax
> +is a synonym for
> +.BR always .
> +Defaults to unset, which is equivalent to
> +.BR never .
> +.TP
> +.BR device = \fIblobdev\fP
> +Add extra device holding some of the data.
> +Must be given as many times and in the same order as 
> +.B \-\-blobdev
> +was to
> +.BR mkfs.erofs (8).
> +.\" Nominally there's a device_table feature and it somehow scans(?) for them,
> +.\" cf. super.c:erofs_scan_devices(), but I haven't gotten it to work
> +.TP
> +.BR domain_id = \fIdid\fP ", " fsid = \fIid\fP

You could use .TQ:

.TP
.BR domain_id = \fIdid\fP
.TQ
.BR fsid = \fIid\fP

(similarly above in dax, acl, and user_xattr)


That helps searching with
/    <opt-name>

> +Control CacheFiles on-demand read support.
> +To be documented.
> +.RE
> +.IP
> +.SH VERSIONS
> +.B erofs
> +images are versioed through the use of feature flags;

s/ioe/ione/

> +these are listed in the
> +.B \-E
> +section of
> +.BR mkfs.erofs (1),
> +.SH NOTES

You could use the CONFIGURATION section for this.  :)
Check man-pages(7).

> +The kernel must be configured with the
> +.B CONFIG_EROFS_FS
> +option to mount EROFS filesystems.
> +There are sub-configuration items that restrict the availability
> +of some of the parameters above.
> +.SH SEE ALSO
> +.BR mkfs.erofs (1),
> +.BR fsck.erofs (1),
> +.BR dump.erofs (1)
> +.PP
> +.I Documentation/filesystems/erofs.txt
> +in the kernel source.

I prefer saying Linux rather than kernel.

> diff --git a/man5/filesystems.5 b/man5/filesystems.5
> index 3c15f14da..c9b0bf695 100644
> --- a/man5/filesystems.5
> +++ b/man5/filesystems.5
> @@ -48,6 +48,12 @@ filesystems in the Linux kernel.
>  See the kernel documentation for a comprehensive
>  description of all options and limitations.
>  .TP 10

Bruh, still have pages that specify the indentation...
Would you mind sending a patch that removes these in fs(5),
or in all the pages you feel like, if you want?

Cheers,
Alex

> +.B erofs
> +is the Enhanced Read-Only File System, stable since Linux 5.4.
> +.\" commit 47e4937a4a7ca4184fd282791dfee76c6799966a moves it out of staging
> +See
> +.BR erofs (5).
> +.TP
>  .B ext
>  is an elaborate extension of the
>  .B minix

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

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