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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Hi Josef,

On Wed, Jun 26, 2024 at 02:21:38PM GMT, Josef Bacik wrote:
> V2: https://lore.kernel.org/linux-fsdevel/cover.1719417184.git.josef@xxxxxxxxxxxxxx/
> V1: https://lore.kernel.org/linux-fsdevel/cover.1719341580.git.josef@xxxxxxxxxxxxxx/
> 
> 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 <alx@xxxxxxxxxx>
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 <douglas.mcilroy@xxxxxxxxxxxxx>
    Cc: "G. Branden Robinson" <branden@xxxxxxxxxx>
    Signed-off-by: Alejandro Colomar <alx@xxxxxxxxxx>


> 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
> 
> 

-- 
<https://www.alejandro-colomar.es/>

Attachment: signature.asc
Description: PGP signature


[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux