[v3,0/2] man-pages: add documentation for statmount/listmount

Message

Josef Bacik June 26, 2024, 6:21 p.m. UTC

V2: https://lore.kernel.org/linux-fsdevel/[e-mail]/
V1: https://lore.kernel.org/linux-fsdevel/[e-mail]/

v2->v3:
- Removed a spurious \t comment in listmount.2 (took me a while to figure out
  why it was needed in statmount.2 but not listmount.2, it's because it lets you
  know that there's a TS in the manpage).
- Fixed some unbalanced " in both pages
- Removed a EE in the nf section which is apparently not needed

v1->v2:
- Dropped the statx patch as Alejandro already took it (thanks!)
- Reworked everything to use semantic newlines
- Addressed all of the comments on the statmount.2 man page

Got more of the checks to run so found more issues, fixed those up, but no big
changes.  Thanks,

Josef

Josef Bacik (2):
  statmount.2: New page describing the statmount syscall
  listmount.2: New page describing the listmount syscall

 man/man2/listmount.2 | 111 +++++++++++++++++
 man/man2/statmount.2 | 285 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 396 insertions(+)
 create mode 100644 man/man2/listmount.2
 create mode 100644 man/man2/statmount.2

Comments

Alejandro Colomar June 26, 2024, 6:48 p.m. UTC | #1

Hi Josef,

On Wed, Jun 26, 2024 at 02:21:38PM GMT, Josef Bacik wrote:
> V2: https://lore.kernel.org/linux-fsdevel/[e-mail]/
> V1: https://lore.kernel.org/linux-fsdevel/[e-mail]/
> 
> v2->v3:
> - Removed a spurious \t comment in listmount.2 (took me a while to figure out
>   why it was needed in statmount.2 but not listmount.2, it's because it lets you
>   know that there's a TS in the manpage).

Yep; here's the Makefile relevant rule:

$ grepc -x mk -tr _LINT_man_tbl share/mk/
share/mk/lint/man/tbl.mk:$(_LINT_man_tbl): %.lint-man.tbl.touch: % $(MK) | $$(@D)/
	$(info	$(INFO_)GREP		$@)
	$(HEAD) -n1 <$< \
	| if $(GREP) '\\" t$$' >/dev/null; then \
		$(CAT) <$< \
		| if ! $(GREP) '^\.TS$$' >/dev/null; then \
			>&2 $(ECHO) "$<:1: spurious '\\\" t' comment:"; \
			>&2 $(HEAD) -n1 <$<; \
			exit 1; \
		fi; \
	else \
		$(CAT) <$< \
		| if $(GREP) '^\.TS$$' >/dev/null; then \
			>&2 $(ECHO) "$<:1: missing '\\\" t' comment:"; \
			>&2 $(HEAD) -n1 <$<; \
			exit 1; \
		fi; \
	fi
	$(TAIL) -n+2 <$< \
	| if $(GREP) '\\" t$$' >/dev/null; then \
		>&2 $(ECHO) "$<: spurious '\\\" t' not in first line:"; \
		>&2 $(GREP) -n '\\" t$$' $< /dev/null; \
		exit 1; \
	fi
	$(TOUCH) $@

Maybe I should expand those error messages to be a little bit more
clear.

> - Fixed some unbalanced " in both pages
> - Removed a EE in the nf section which is apparently not needed

You need to do:

.nf
foo
.fi
.EX
bar
.EE

You cannot nest them.  The following code is wrong (I discovered that
recently):

.nf
foo
.EX
bar
.EE
.fi

See this commit:

<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=a911df9e88dedc801bed50eb92c26002729af9c0>
commit a911df9e88dedc801bed50eb92c26002729af9c0
Author: Alejandro Colomar <[e-mail]>
Date:   Mon Jun 17 01:18:39 2024 +0200

    man/, share/mk/: Fix nested EX/EE within nf/fi
    
    EX/EE can't be nested within nf/ni.  The mandoc(1) reports weren't
    spurious.
    
    Re-enable the mandoc(1) warnings, and fix the code.
    
    Fixes: 31203a0c8dbf ("share/mk/: Globally disable two spurious mandoc(1) wa>
    Link: <https://lists.gnu.org/archive/html/groff/2024-06/msg00019.html>
    Reported-by: Douglas McIlroy <[e-mail]>
    Cc: "G. Branden Robinson" <[e-mail]>
    Signed-off-by: Alejandro Colomar <[e-mail]>


> v1->v2:
> - Dropped the statx patch as Alejandro already took it (thanks!)
> - Reworked everything to use semantic newlines
> - Addressed all of the comments on the statmount.2 man page
> 
> Got more of the checks to run so found more issues, fixed those up, but no big
> changes.  Thanks,

Thanks.  I'll review the patches soon, hopefully.

Have a lovely night!
Alex

> 
> Josef
> 
> Josef Bacik (2):
>   statmount.2: New page describing the statmount syscall
>   listmount.2: New page describing the listmount syscall
> 
>  man/man2/listmount.2 | 111 +++++++++++++++++
>  man/man2/statmount.2 | 285 +++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 396 insertions(+)
>  create mode 100644 man/man2/listmount.2
>  create mode 100644 man/man2/statmount.2
> 
> -- 
> 2.43.0
> 
>