Re: [PATCH kmod] man: silence autoconf warnings

From: Lucas De Marchi <lucas.demarchi@intel.com>
To: <emil.l.velikov@gmail.com>
Cc: <linux-modules@vger.kernel.org>
Subject: Re: [PATCH kmod] man: silence autoconf warnings
Date: Tue, 20 Feb 2024 15:56:38 -0600	[thread overview]
Message-ID: <63an63knqvcxyxh5ejx64bsxgpooikbba5inrd2kzbxuhuuenc@nk644hvv5j2p> (raw)
In-Reply-To: <20240217-autoconf-manpage-warns-v1-1-e1570cfc286e@gmail.com>

On Sat, Feb 17, 2024 at 04:01:26PM +0000, Emil Velikov via B4 Relay wrote:
>From: Emil Velikov <emil.l.velikov@gmail.com>
>
>Currently we have a pattern rule, which effective states that two output
>files are produced - %.5 and %.8. Although that's not the case in
>practise, since each input xml will be generated to a single manual
>page.
>
>Add the manpage section as part of the xml filename and tweak the
>pattern (match) rule, accordingly.
>
>Signed-off-by: Emil Velikov <emil.l.velikov@gmail.com>
>---
>Noticed, while wondering if I should add sanitizer support to the
>autoconf build.
>
>A few, random questions:
> - are there any objections to adding sanitizers support?

no

> - would a meson.build be acceptable? Giving us sanitizers, coverage,
>   scan-build, etc out of the box

yes. A few years ago we converted to meson but I think a few things were
not working properly and we never finished that. If you few like adding
that for the next version, feel free to use that as base:

https://github.com/falconindy/kmod.git meson

> - writing xml is fiddly, would people be OK if we convert them to
>   scdoc? here are some examples of the raw file [1] vs the man [2]

first time I hear about scdoc. syntax seems simple, but I do wonder how
common it is in distros compared to e.g. pandoc or other options to
produce manpages.

I know mkosi writes markdown and converts that to a manpage
(https://github.com/systemd/mkosi) and dim uses rst2man
(https://gitlab.freedesktop.org/drm/maintainer-tools.git)

Any of those options seems better than writing xml, so I won't oppose to
scdoc if it's available in multiple distros out of the box in a version
that is sufficient for us.

Lucas De Marchi

>
>[1] https://gitlab.alpinelinux.org/alpine/apk-tools/-/raw/master/doc/apk-add.8.scd?ref_type=heads
>[2] https://man.archlinux.org/man/extra/apk-tools/apk-add.8.en
>---
> man/Makefile.am                            | 11 +++++++++--
> man/{depmod.xml => depmod.8.xml}           |  0
> man/{depmod.d.xml => depmod.d.5.xml}       |  0
> man/{insmod.xml => insmod.8.xml}           |  0
> man/{kmod.xml => kmod.8.xml}               |  0
> man/{modinfo.xml => modinfo.8.xml}         |  0
> man/{modprobe.xml => modprobe.8.xml}       |  0
> man/{modprobe.d.xml => modprobe.d.5.xml}   |  0
> man/{modules.dep.xml => modules.dep.5.xml} |  0
> man/{rmmod.xml => rmmod.8.xml}             |  0
> 10 files changed, 9 insertions(+), 2 deletions(-)

it seems you forgot to rename lsmod.xml so it fails to build.
I fixed that up and pushed.

thanks
Lucas De Marchi

>
>diff --git a/man/Makefile.am b/man/Makefile.am
>index f550091..d62ff21 100644
>--- a/man/Makefile.am
>+++ b/man/Makefile.am
>@@ -13,10 +13,10 @@ dist_man_MANS = $(MAN5) $(MAN8) $(MAN_STUB)
> modules.dep.bin.5: modules.dep.5
> endif
>
>-EXTRA_DIST = $(MAN5:%.5=%.xml) $(MAN8:%.8=%.xml)
>+EXTRA_DIST = $(MAN5:%.5=%.5.xml) $(MAN8:%.8=%.8.xml)
> CLEANFILES = $(dist_man_MANS)
>
>-%.5 %.8: %.xml
>+define generate_manpage
> 	$(AM_V_XSLT)if [ '$(distconfdir)' != '/lib' ] ; then \
> 		sed -e 's|@DISTCONFDIR@|$(distconfdir)|g' $< ; \
> 	else \
>@@ -29,3 +29,10 @@ CLEANFILES = $(dist_man_MANS)
> 		--stringparam man.output.quietly 1 \
> 		--param funcsynopsis.style "'ansi'" \
> 		http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl -
>+endef
>+
>+%.5: %.5.xml
>+	$(generate_manpage)
>+
>+%.8: %.8.xml
>+	$(generate_manpage)
>diff --git a/man/depmod.xml b/man/depmod.8.xml
>similarity index 100%
>rename from man/depmod.xml
>rename to man/depmod.8.xml
>diff --git a/man/depmod.d.xml b/man/depmod.d.5.xml
>similarity index 100%
>rename from man/depmod.d.xml
>rename to man/depmod.d.5.xml
>diff --git a/man/insmod.xml b/man/insmod.8.xml
>similarity index 100%
>rename from man/insmod.xml
>rename to man/insmod.8.xml
>diff --git a/man/kmod.xml b/man/kmod.8.xml
>similarity index 100%
>rename from man/kmod.xml
>rename to man/kmod.8.xml
>diff --git a/man/modinfo.xml b/man/modinfo.8.xml
>similarity index 100%
>rename from man/modinfo.xml
>rename to man/modinfo.8.xml
>diff --git a/man/modprobe.xml b/man/modprobe.8.xml
>similarity index 100%
>rename from man/modprobe.xml
>rename to man/modprobe.8.xml
>diff --git a/man/modprobe.d.xml b/man/modprobe.d.5.xml
>similarity index 100%
>rename from man/modprobe.d.xml
>rename to man/modprobe.d.5.xml
>diff --git a/man/modules.dep.xml b/man/modules.dep.5.xml
>similarity index 100%
>rename from man/modules.dep.xml
>rename to man/modules.dep.5.xml
>diff --git a/man/rmmod.xml b/man/rmmod.8.xml
>similarity index 100%
>rename from man/rmmod.xml
>rename to man/rmmod.8.xml
>
>---
>base-commit: b29704cd448aaa455dba4e656fc0f0d3c686df3f
>change-id: 20240217-autoconf-manpage-warns-0eeb0fa627cf
>
>Best regards,
>-- 
>Emil Velikov <emil.l.velikov@gmail.com>
>