| Message ID | 20240217-autoconf-manpage-warns-v1-1-e1570cfc286e@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [kmod] man: silence autoconf warnings | expand |
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> >
On Tue, 20 Feb 2024 at 21:56, Lucas De Marchi <lucas.demarchi@intel.com> wrote: > > 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. > Neat, thanks for the input and pointers. Will do some digging and provide a summary wrt scdoc/rst2man -Emil
On Fri, Feb 23, 2024 at 11:05:24AM GMT, Emil Velikov wrote: >On Tue, 20 Feb 2024 at 21:56, Lucas De Marchi <lucas.demarchi@intel.com> wrote: >> >> 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. >> > >Neat, thanks for the input and pointers. Will do some digging and >provide a summary wrt scdoc/rst2man did you get a chance to try those? TIL igt also uses rst2man for its tools (https://gitlab.freedesktop.org/drm/igt-gpu-tools/-/tree/master/man?ref_type=heads) so I think it would be the preferred one. thanks Lucas De Marchi > >-Emil
On Mon, 29 Apr 2024 at 22:45, Lucas De Marchi <lucas.demarchi@intel.com> wrote: > > On Fri, Feb 23, 2024 at 11:05:24AM GMT, Emil Velikov wrote: > >On Tue, 20 Feb 2024 at 21:56, Lucas De Marchi <lucas.demarchi@intel.com> wrote: > >> > >> 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. > >> > > > >Neat, thanks for the input and pointers. Will do some digging and > >provide a summary wrt scdoc/rst2man > > did you get a chance to try those? TIL igt also uses rst2man for its > tools > (https://gitlab.freedesktop.org/drm/igt-gpu-tools/-/tree/master/man?ref_type=heads) > > so I think it would be the preferred one. > I have been mostly AFK the last few months, so I didn't pick on this. My main concern with rst2man is regarding the state of the python ecosystem. Python 3.12 was released circa Oct 2023 and it landed in Arch just this week. From casual observations - hundreds of tools are not adhering to the deprecation warnings and thus might be broken as python 3.13 comes out. Admittedly all that is somewhat tangential. Will play around with both tools and provide something less hand-wavy in the next few days. -Emil
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