Re: [patch] rename tbl man pages
On Thu, Jul 07, 2022 at 03:42:27PM +0200, Ingo Schwarze wrote:
> Hi Daniel,
>
> Daniel Dickman wrote on Thu, Jul 07, 2022 at 12:03:18AM -0400:
>
> > Over a decade ago there was some work in bsd.man.mk to build tbl pages
> > with mandoc. For example this commit from 2010:
> >
> >
> > revision 1.32
> > date: 2010/10/17 22:47:08; author: schwarze; state: Exp; lines: +8 -18;
> > Build tbl(1) pages with mandoc(1), not groff.
> > Xenocara build checked myself, base build also by jmc@, thanks!
> > "don't wait for me" deraadt@
> >
> > Pages in base using tbl mostly look good already except for the
> > rare .T{ macros; there may still be a few formatting issues
> > in xenocara, please speak up when you run into them.
> > Eventually, mandoc will catch up.
>
> Today, the tbl(7) formatting of all the pages you are touching
> is byte-by-byte identical between groff(1) and mandoc(1) -
> with one minor exception in infocmp(1) where groff(1) renders
> a few horizontal lines incorrectly due to a bug in groff(1).
>
> >
> >
> > Back then there was some special infrastructure to build these man pages
> > if they were named something like *.6tbl.
> >
> > That convention is a local OpenBSD convention, it does not exist outside
> > of our tree.
> >
> > At this point the special naming for these man pages is no longer needed:
>
> That is completely correct.
>
> > * games/phantasia/phantasia.6tbl
> > * gnu/usr.sbin/mkhybrid/src/mkhybrid.8tbl
> > * share/man/man4/man4.hppa/cpu.4tbl
> > * share/man/man4/wi.4tbl
> > * share/man/man4/man4.hppa/cpu.4tbl
> > * usr.bin/infocmp/infocmp.1tbl
> > * usr.bin/tic/captoinfo.1tbl
> >
> > The benefits are:
> > - The affected Makefiles are shortened by 3+ lines
> > - diffing external software like mkhybrid against the original sources
> > results in less noise
> > - remove an unnecessary cp step doing the build
>
> The price to pay is relatively minor: making it slightly harder to
> inspect commit history of these manual pages. But these are not
> edited often anyway, so that's not a big deal.
>
> > ok on the diff below? (I've left out the man page renames from the diff
> > for brevity)
>
> I don't have a strong opinion either way. If you think it's worth it,
> i do not object.
>
> From visual inspection, the diff looks correct to me. I also tested
> building and installing in the affected directories and noticed no
> issues. I did not run a complete make build / make release cycle
> though, but i trust you to not break that.
>
> Yours,
> Ingo
>
>
for me it's a good move:
- easier to find(1) our pages within the source tree
- there are so few of them it just looks inconsistent
- simpler
but i hate losing easy access to cvs history too. so i also have no
strong opinions.
jmc
Re: [patch] rename tbl man pages
Hi Daniel,
Daniel Dickman wrote on Thu, Jul 07, 2022 at 12:03:18AM -0400:
> Over a decade ago there was some work in bsd.man.mk to build tbl pages
> with mandoc. For example this commit from 2010:
>
>
> revision 1.32
> date: 2010/10/17 22:47:08; author: schwarze; state: Exp; lines: +8 -18;
> Build tbl(1) pages with mandoc(1), not groff.
> Xenocara build checked myself, base build also by jmc@, thanks!
> "don't wait for me" deraadt@
>
> Pages in base using tbl mostly look good already except for the
> rare .T{ macros; there may still be a few formatting issues
> in xenocara, please speak up when you run into them.
> Eventually, mandoc will catch up.
Today, the tbl(7) formatting of all the pages you are touching
is byte-by-byte identical between groff(1) and mandoc(1) -
with one minor exception in infocmp(1) where groff(1) renders
a few horizontal lines incorrectly due to a bug in groff(1).
>
>
> Back then there was some special infrastructure to build these man pages
> if they were named something like *.6tbl.
>
> That convention is a local OpenBSD convention, it does not exist outside
> of our tree.
>
> At this point the special naming for these man pages is no longer needed:
That is completely correct.
> * games/phantasia/phantasia.6tbl
> * gnu/usr.sbin/mkhybrid/src/mkhybrid.8tbl
> * share/man/man4/man4.hppa/cpu.4tbl
> * share/man/man4/wi.4tbl
> * share/man/man4/man4.hppa/cpu.4tbl
> * usr.bin/infocmp/infocmp.1tbl
> * usr.bin/tic/captoinfo.1tbl
>
> The benefits are:
> - The affected Makefiles are shortened by 3+ lines
> - diffing external software like mkhybrid against the original sources
> results in less noise
> - remove an unnecessary cp step doing the build
The price to pay is relatively minor: making it slightly harder to
inspect commit history of these manual pages. But these are not
edited often anyway, so that's not a big deal.
> ok on the diff below? (I've left out the man page renames from the diff
> for brevity)
I don't have a strong opinion either way. If you think it's worth it,
i do not object.
>From visual inspection, the diff looks correct to me. I also tested
building and installing in the affected directories and noticed no
issues. I did not run a complete make build / make release cycle
though, but i trust you to not break that.
Yours,
Ingo
> Index: games/phantasia/Makefile
> ===
> RCS file: /cvs/src/games/phantasia/Makefile,v
> retrieving revision 1.18
> diff -u -p -u -r1.18 Makefile
> --- games/phantasia/Makefile 24 Nov 2015 03:10:10 - 1.18
> +++ games/phantasia/Makefile 7 Jul 2022 01:24:22 -
> @@ -6,7 +6,7 @@ CFLAGS+=-DTERMIOS
> DPADD= ${LIBM} ${LIBCURSES}
> LDADD= -lm -lcurses
> MAN= phantasia.6
> -CLEANFILES+=map setup setup.o phantglobs.o.bld phantasia.6
> +CLEANFILES+=map setup setup.o phantglobs.o.bld
>
> all: setup phantasia
>
> @@ -19,9 +19,6 @@ phantglobs.o.bld: phantglobs.c
> setup: phantglobs.o.bld setup.o monsters.asc ${DPADD}
> ${HOSTCC} ${CFLAGS} ${LDFLAGS} ${LDSTATIC} -o ${.TARGET} \
> phantglobs.o.bld setup.o ${LDADD}
> -
> -phantasia.6: phantasia.6tbl
> - cp ${.ALLSRC} ${.TARGET}
>
> beforeinstall:
> ./setup -m ${.CURDIR}/monsters.asc
> Index: gnu/usr.sbin/mkhybrid/mkhybrid/Makefile
> ===
> RCS file: /cvs/src/gnu/usr.sbin/mkhybrid/mkhybrid/Makefile,v
> retrieving revision 1.7
> diff -u -p -u -r1.7 Makefile
> --- gnu/usr.sbin/mkhybrid/mkhybrid/Makefile 9 Sep 2015 20:02:31 -
> 1.7
> +++ gnu/usr.sbin/mkhybrid/mkhybrid/Makefile 7 Jul 2022 01:24:22 -
> @@ -8,7 +8,6 @@
> PROG=mkhybrid
> MAN= mkhybrid.8
> BINDIR= /usr/sbin
> -CLEANFILES+= mkhybrid.8
> .PATH: ${.CURDIR}/../src ${.CURDIR}/../src/libhfs_iso
> ${.CURDIR}/../src/libfile
>
> SRCS=data.c block.c low.c lfile.c btree.c node.c record.c lvolume.c \
> @@ -20,8 +19,5 @@ CFLAGS+=-DSYSTEM_ID_DEFAULT=\"OpenBSD\"
> -I${.CURDIR}/../src -I${.CURDIR}/../src/include \
> -I${.CURDIR}/../src/libhfs_iso \
> -I${.CURDIR}/../src/libfile
> -
> -mkhybrid.8: mkhybrid.8tbl
> - cp ${.ALLSRC} ${.TARGET}
>
> .include
> Index: share/man/man4/man4.hppa/Makefile
> ===
> RCS file: /cvs/src/share/man/man4/man4.hppa/Makefile,v
> retrieving revision 1.29
> diff -u -p -u -r1.29 Makefile
> --- share/man/man4/man4.hppa/Makefile 30 Mar 2016 06:38:44 - 1.29
> +++ share/man/man4/man4.hppa/Makefile 7 Jul 2022 01:24:22 -
> @@ -6,9 +6,5 @@ MAN+= harmony.4 ie.4 intro.4 io.4 lasi.4
> MAN+=phantomas.4 power.4 runway.4 ssio.4 uturn.4 wax.4
> # tir.4 xbar.4 mcx.4
> MANSUBDIR=hppa
> -CLEANFILES+= cpu.4
> -
> -cpu.4: cpu.4tbl
> - cp ${.ALLSRC} ${.TARGET}
>
> .include
> Index: share/man/man4/Makefile
Re: [patch] rename tbl man pages
On Thu, Jul 07, 2022 at 12:03:18AM -0400, Daniel Dickman wrote:
> Over a decade ago there was some work in bsd.man.mk to build tbl pages
> with mandoc. For example this commit from 2010:
>
>
> revision 1.32
> date: 2010/10/17 22:47:08; author: schwarze; state: Exp; lines: +8 -18;
> Build tbl(1) pages with mandoc(1), not groff.
> Xenocara build checked myself, base build also by jmc@, thanks!
> "don't wait for me" deraadt@
>
> Pages in base using tbl mostly look good already except for the
> rare .T{ macros; there may still be a few formatting issues
> in xenocara, please speak up when you run into them.
> Eventually, mandoc will catch up.
>
>
> Back then there was some special infrastructure to build these man pages
> if they were named something like *.6tbl.
>
> That convention is a local OpenBSD convention, it does not exist outside
> of our tree.
>
> At this point the special naming for these man pages is no longer needed:
>
> * games/phantasia/phantasia.6tbl
> * gnu/usr.sbin/mkhybrid/src/mkhybrid.8tbl
> * share/man/man4/man4.hppa/cpu.4tbl
> * share/man/man4/wi.4tbl
> * share/man/man4/man4.hppa/cpu.4tbl
> * usr.bin/infocmp/infocmp.1tbl
> * usr.bin/tic/captoinfo.1tbl
>
> The benefits are:
> - The affected Makefiles are shortened by 3+ lines
> - diffing external software like mkhybrid against the original sources
> results in less noise
> - remove an unnecessary cp step doing the build
>
> ok on the diff below? (I've left out the man page renames from the diff
> for brevity)
>
>
hi.
if we can do it without issue, it would definitely be preferrable. i'm
pretty sure this is a question for ingo, though.
jmc
>
> Index: games/phantasia/Makefile
> ===
> RCS file: /cvs/src/games/phantasia/Makefile,v
> retrieving revision 1.18
> diff -u -p -u -r1.18 Makefile
> --- games/phantasia/Makefile 24 Nov 2015 03:10:10 - 1.18
> +++ games/phantasia/Makefile 7 Jul 2022 01:24:22 -
> @@ -6,7 +6,7 @@ CFLAGS+=-DTERMIOS
> DPADD= ${LIBM} ${LIBCURSES}
> LDADD= -lm -lcurses
> MAN= phantasia.6
> -CLEANFILES+=map setup setup.o phantglobs.o.bld phantasia.6
> +CLEANFILES+=map setup setup.o phantglobs.o.bld
>
> all: setup phantasia
>
> @@ -19,9 +19,6 @@ phantglobs.o.bld: phantglobs.c
> setup: phantglobs.o.bld setup.o monsters.asc ${DPADD}
> ${HOSTCC} ${CFLAGS} ${LDFLAGS} ${LDSTATIC} -o ${.TARGET} \
> phantglobs.o.bld setup.o ${LDADD}
> -
> -phantasia.6: phantasia.6tbl
> - cp ${.ALLSRC} ${.TARGET}
>
> beforeinstall:
> ./setup -m ${.CURDIR}/monsters.asc
> Index: gnu/usr.sbin/mkhybrid/mkhybrid/Makefile
> ===
> RCS file: /cvs/src/gnu/usr.sbin/mkhybrid/mkhybrid/Makefile,v
> retrieving revision 1.7
> diff -u -p -u -r1.7 Makefile
> --- gnu/usr.sbin/mkhybrid/mkhybrid/Makefile 9 Sep 2015 20:02:31 -
> 1.7
> +++ gnu/usr.sbin/mkhybrid/mkhybrid/Makefile 7 Jul 2022 01:24:22 -
> @@ -8,7 +8,6 @@
> PROG=mkhybrid
> MAN= mkhybrid.8
> BINDIR= /usr/sbin
> -CLEANFILES+= mkhybrid.8
> .PATH: ${.CURDIR}/../src ${.CURDIR}/../src/libhfs_iso
> ${.CURDIR}/../src/libfile
>
> SRCS=data.c block.c low.c lfile.c btree.c node.c record.c lvolume.c \
> @@ -20,8 +19,5 @@ CFLAGS+=-DSYSTEM_ID_DEFAULT=\"OpenBSD\"
> -I${.CURDIR}/../src -I${.CURDIR}/../src/include \
> -I${.CURDIR}/../src/libhfs_iso \
> -I${.CURDIR}/../src/libfile
> -
> -mkhybrid.8: mkhybrid.8tbl
> - cp ${.ALLSRC} ${.TARGET}
>
> .include
> Index: share/man/man4/man4.hppa/Makefile
> ===
> RCS file: /cvs/src/share/man/man4/man4.hppa/Makefile,v
> retrieving revision 1.29
> diff -u -p -u -r1.29 Makefile
> --- share/man/man4/man4.hppa/Makefile 30 Mar 2016 06:38:44 - 1.29
> +++ share/man/man4/man4.hppa/Makefile 7 Jul 2022 01:24:22 -
> @@ -6,9 +6,5 @@ MAN+= harmony.4 ie.4 intro.4 io.4 lasi.4
> MAN+=phantomas.4 power.4 runway.4 ssio.4 uturn.4 wax.4
> # tir.4 xbar.4 mcx.4
> MANSUBDIR=hppa
> -CLEANFILES+= cpu.4
> -
> -cpu.4: cpu.4tbl
> - cp ${.ALLSRC} ${.TARGET}
>
> .include
> Index: share/man/man4/Makefile
> ===
> RCS file: /cvs/src/share/man/man4/Makefile,v
> retrieving revision 1.817
> diff -u -p -u -r1.817 Makefile
> --- share/man/man4/Makefile 18 Jan 2022 07:53:39 - 1.817
> +++ share/man/man4/Makefile 7 Jul 2022 01:24:22 -
> @@ -113,9 +113,4 @@ SUBDIR= man4.alpha man4.amd64 man4.arm64
> man4.hppa man4.i386 man4.landisk man4.loongson man4.luna88k \
> man4.macppc man4.octeon man4.powerpc64 man4.riscv64 man4.sparc64
>
> -CLEANFILES+= wi.4
> -
> -wi.4: wi.4tbl
> - cp ${.ALLSRC} ${.TARGET}
> -
> .include
> Index: share/man/man4/man4.hppa/Makefile
>
[patch] rename tbl man pages
Over a decade ago there was some work in bsd.man.mk to build tbl pages
with mandoc. For example this commit from 2010:
revision 1.32
date: 2010/10/17 22:47:08; author: schwarze; state: Exp; lines: +8 -18;
Build tbl(1) pages with mandoc(1), not groff.
Xenocara build checked myself, base build also by jmc@, thanks!
"don't wait for me" deraadt@
Pages in base using tbl mostly look good already except for the
rare .T{ macros; there may still be a few formatting issues
in xenocara, please speak up when you run into them.
Eventually, mandoc will catch up.
Back then there was some special infrastructure to build these man pages
if they were named something like *.6tbl.
That convention is a local OpenBSD convention, it does not exist outside
of our tree.
At this point the special naming for these man pages is no longer needed:
* games/phantasia/phantasia.6tbl
* gnu/usr.sbin/mkhybrid/src/mkhybrid.8tbl
* share/man/man4/man4.hppa/cpu.4tbl
* share/man/man4/wi.4tbl
* share/man/man4/man4.hppa/cpu.4tbl
* usr.bin/infocmp/infocmp.1tbl
* usr.bin/tic/captoinfo.1tbl
The benefits are:
- The affected Makefiles are shortened by 3+ lines
- diffing external software like mkhybrid against the original sources
results in less noise
- remove an unnecessary cp step doing the build
ok on the diff below? (I've left out the man page renames from the diff
for brevity)
Index: games/phantasia/Makefile
===
RCS file: /cvs/src/games/phantasia/Makefile,v
retrieving revision 1.18
diff -u -p -u -r1.18 Makefile
--- games/phantasia/Makefile24 Nov 2015 03:10:10 - 1.18
+++ games/phantasia/Makefile7 Jul 2022 01:24:22 -
@@ -6,7 +6,7 @@ CFLAGS+=-DTERMIOS
DPADD= ${LIBM} ${LIBCURSES}
LDADD= -lm -lcurses
MAN= phantasia.6
-CLEANFILES+=map setup setup.o phantglobs.o.bld phantasia.6
+CLEANFILES+=map setup setup.o phantglobs.o.bld
all: setup phantasia
@@ -19,9 +19,6 @@ phantglobs.o.bld: phantglobs.c
setup: phantglobs.o.bld setup.o monsters.asc ${DPADD}
${HOSTCC} ${CFLAGS} ${LDFLAGS} ${LDSTATIC} -o ${.TARGET} \
phantglobs.o.bld setup.o ${LDADD}
-
-phantasia.6: phantasia.6tbl
- cp ${.ALLSRC} ${.TARGET}
beforeinstall:
./setup -m ${.CURDIR}/monsters.asc
Index: gnu/usr.sbin/mkhybrid/mkhybrid/Makefile
===
RCS file: /cvs/src/gnu/usr.sbin/mkhybrid/mkhybrid/Makefile,v
retrieving revision 1.7
diff -u -p -u -r1.7 Makefile
--- gnu/usr.sbin/mkhybrid/mkhybrid/Makefile 9 Sep 2015 20:02:31 -
1.7
+++ gnu/usr.sbin/mkhybrid/mkhybrid/Makefile 7 Jul 2022 01:24:22 -
@@ -8,7 +8,6 @@
PROG= mkhybrid
MAN= mkhybrid.8
BINDIR=/usr/sbin
-CLEANFILES+= mkhybrid.8
.PATH: ${.CURDIR}/../src ${.CURDIR}/../src/libhfs_iso ${.CURDIR}/../src/libfile
SRCS= data.c block.c low.c lfile.c btree.c node.c record.c lvolume.c \
@@ -20,8 +19,5 @@ CFLAGS+=-DSYSTEM_ID_DEFAULT=\"OpenBSD\"
-I${.CURDIR}/../src -I${.CURDIR}/../src/include \
-I${.CURDIR}/../src/libhfs_iso \
-I${.CURDIR}/../src/libfile
-
-mkhybrid.8: mkhybrid.8tbl
- cp ${.ALLSRC} ${.TARGET}
.include
Index: share/man/man4/man4.hppa/Makefile
===
RCS file: /cvs/src/share/man/man4/man4.hppa/Makefile,v
retrieving revision 1.29
diff -u -p -u -r1.29 Makefile
--- share/man/man4/man4.hppa/Makefile 30 Mar 2016 06:38:44 - 1.29
+++ share/man/man4/man4.hppa/Makefile 7 Jul 2022 01:24:22 -
@@ -6,9 +6,5 @@ MAN+= harmony.4 ie.4 intro.4 io.4 lasi.4
MAN+= phantomas.4 power.4 runway.4 ssio.4 uturn.4 wax.4
# tir.4 xbar.4 mcx.4
MANSUBDIR=hppa
-CLEANFILES+= cpu.4
-
-cpu.4: cpu.4tbl
- cp ${.ALLSRC} ${.TARGET}
.include
Index: share/man/man4/Makefile
===
RCS file: /cvs/src/share/man/man4/Makefile,v
retrieving revision 1.817
diff -u -p -u -r1.817 Makefile
--- share/man/man4/Makefile 18 Jan 2022 07:53:39 - 1.817
+++ share/man/man4/Makefile 7 Jul 2022 01:24:22 -
@@ -113,9 +113,4 @@ SUBDIR= man4.alpha man4.amd64 man4.arm64
man4.hppa man4.i386 man4.landisk man4.loongson man4.luna88k \
man4.macppc man4.octeon man4.powerpc64 man4.riscv64 man4.sparc64
-CLEANFILES+= wi.4
-
-wi.4: wi.4tbl
- cp ${.ALLSRC} ${.TARGET}
-
.include
Index: share/man/man4/man4.hppa/Makefile
===
RCS file: /cvs/src/share/man/man4/man4.hppa/Makefile,v
retrieving revision 1.29
diff -u -p -u -r1.29 Makefile
--- share/man/man4/man4.hppa/Makefile 30 Mar 2016 06:38:44 - 1.29
+++ share/man/man4/man4.hppa/Makefile 7 Jul 2022 01:24:22 -
@@ -6,9 +6,5 @@ MAN+= harmony.4 ie.4 intro.4 io.4 lasi.4
MAN+= phantomas.4 power.4 runway.4 ssio.4 uturn.4 wax.4
# tir.4 xbar.4 mcx.4
