Introduce MAKEDEV.man*, an equivalent of MAKEDEV.mi and MAKEDEV.sub

designed to output mdoc rather than shell script, and use them to produce
much better MAKEDEV.8 manual pages.

Note that MAKEDEV.man relies upon BSD m4 behaviour, which all m4 binaries
might not follow.

mdoc help and comments jmc@, disabused ok deraadt@

3 files changed, 235 insertions, 6 deletions

diff --git a/etc/MAKEDEV.man b/etc/MAKEDEV.man
new file mode 100644
index 00000000000..2dd59dbfacc
--- /dev/null
+++ b/etc/MAKEDEV.man
@@ -0,0 +1,94 @@
+define(COMM,`.\"')dnl
+include(MAKEDEV.mansub)dnl
+dnl
+vers(a, {-$OpenBSD: MAKEDEV.man,v 1.1 2004/02/16 19:03:30 miod Exp $-})dnl
+dnl
+define(quote,{-.Dq $1
+-})dnl
+include(MAKEDEV.common)dnl
+dnl
+__devtitle(make,{-Special device names-})dnl
+__devitem({-all-},{-all-},dnl
+{-Creates special files for all devices on MACHINE-})dnl
+__devitem(std,{-std-},dnl
+{-Creates the
+.Sq standard
+devices (console, drum, klog, kmem, ksyms, mem, null,
+stderr, stdin, stdout, tty, zero)
+which are absolutely necessary for the system to function properly-})dnl
+__devitem(local,local,dnl
+{-Creates configuration-specific devices, by invoking the shell file
+.Pa MAKEDEV.local .-})dnl
+define({-_std-},)dnl
+divert(1)dnl
+dnl send md shell fragments to the bit bucket...
+define(__mddivert,11)dnl
+include(etc.MACHINE/MAKEDEV.md)dnl
+dnl
+.El
+divert(0)dnl
+.\" ${--}OpenBSD{--}$
+.\"
+.\" THIS FILE AUTOMATICALLY GENERATED.  DO NOT EDIT.
+.\" generated from:
+.\"
+show_vers()dnl <-- now that all files are included, show versions
+.\"
+.\" Copyright (c) 2004, Miodrag Vallat
+.\" Copyright (c) 2001-2004 Todd T. Fries <todd@OpenBSD.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd esyscmd({-date +"%B %e, %Y"-})dnl
+.Dt MAKEDEV 8 MACHINE
+.Os
+.Sh NAME
+.Nm MAKEDEV
+.Nd create system and device special files
+.Sh SYNOPSIS
+.Nm MAKEDEV
+.Ar name
+.Op Ar ...
+.Sh DESCRIPTION
+The shell script
+.Nm ,
+found in the
+.Pa /dev
+directory, is used to create various special files.
+See
+.Xr intro 4
+for a more complete discussion of special files.
+.Pp
+.Nm
+takes any number of device names as arguments, where the names are
+the common abbreviation for the device or group of devices.
+.Pp
+Where a device name is followed by a star
+.Sq * ,
+the star must be replaced by a unit number.
+If units are expected for a device but not provided,
+.Nm
+will supply the standard numbers in most cases.
+.Pp
+The MACHINE supports the following devices:
+.Pp
+divert(9)dnl
+.Sh FILES
+.Bl -tag -width /dev -compact
+.It Pa /dev
+The special file directory.
+.El
+.Sh SEE ALSO
+.Xr intro 4 ,
+.Xr config 8 ,
+.Xr mknod 8
diff --git a/etc/MAKEDEV.mansub b/etc/MAKEDEV.mansub
new file mode 100644
index 00000000000..535a6edee4b
--- /dev/null
+++ b/etc/MAKEDEV.mansub
@@ -0,0 +1,128 @@
+dnl	$OpenBSD: MAKEDEV.mansub,v 1.1 2004/02/16 19:03:30 miod Exp $
+dnl
+dnl Copyright (c) 2004, Miodrag Vallat
+dnl Copyright (c) 2001-2004 Todd T. Fries <todd@OpenBSD.org>
+dnl
+dnl Permission to use, copy, modify, and distribute this software for any
+dnl purpose with or without fee is hereby granted, provided that the above
+dnl copyright notice and this permission notice appear in all copies.
+dnl
+dnl THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+dnl WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+dnl MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+dnl ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+dnl WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+dnl ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+dnl OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+dnl
+dnl This file is an m4 file, really. It's a clone of MAKEDEV.sub, then
+dnl adapted to mdoc output. This means, mostly removed from any non-trivial
+dnl content...
+dnl
+dnl o First, a change of quote to make shell statements like: `command`
+dnl   possible
+dnl
+changequote(`{-', `-}')dnl
+dnl
+dnl o version info must be stripped of $ so we can say 'generated from' below
+dnl
+dnl  If we just use the version string how are we going to know what arch
+dnl  'MAKEDEV.md,v' came from?
+dnl
+dnl  Thus, I have used the below to create a version string looking like
+dnl  'OpenBSD: etc.sparc/MAKEDEV.inc,v...' which works, although requires
+dnl  some attention if ported to another Id string setup.
+dnl
+dnl
+dnl Initialize the stacks stored in _m4_*
+dnl
+undefine({-_m4_cvs_ver-})dnl
+pushdef({-_m4_cvs_ver-}, {-done-})dnl
+dnl
+undefine({-_m4_devs-})dnl
+pushdef({-_m4_devs-}, {-done-})dnl
+dnl
+undefine({-_m4_disks-})dnl
+undefine({-_m4_disks2-})dnl
+pushdef({-_m4_disks-}, {-done-})dnl
+pushdef({-_m4_disks2-}, {-done-})dnl
+dnl
+dnl define stack 'add to' functions, only unique names queued
+dnl
+define({-ver_q-}, {-ifelse(index($1_ver, y), 0, ,
+{-pushdef({-_m4_cvs_ver-}, {-$2-})define({-$1_ver-}, {-y-})-})-})dnl ver_q
+dnl
+define({-dev_q-}, {-ifelse(index(_q_$1_dev, :), 0,
+{-errprint({-duplicated dev id: $1 at -}__file__{-:-}__line__ originally at _q_$1_dev)-},
+{-pushdef({-_m4_devs-}, {-$1-})dnl
+define({-_q_$1_dev-}, {-:-}__file__{-:-}__line__)-})-})dnl dev_q
+dnl
+define({-disk_q-}, {-ifelse(index(_q_$1_disk, :), 0,
+{-errprint({-duplicated disk id: $1 at -}__file__{-:-}__line__ originally at _q_$1_disk)-}, {-pushdef({-_m4_disks-}, {-$1-})dnl
+pushdef({-_m4_disks2-}, {-$1-})dnl
+define({-_q_$1_disks-}, {-:-}__file__{-:-}__line__)-})-})dnl disk_q
+dnl
+dnl store a version string for 'this' file
+dnl
+dnl vers ( uniqueidstring, versionstring, subdir )
+dnl
+dnl example1: vers(__file__, {-$OpenBSD: MAKEDEV.mansub,v 1.1 2004/02/16 19:03:30 miod Exp $-})
+dnl example2: vers(__file__, {-$OpenBSD: MAKEDEV.mansub,v 1.1 2004/02/16 19:03:30 miod Exp $-}, etc.MACHINE)
+dnl
+dnl if subdir is defined, prepend it to the filename in the version string
+dnl
+define({-vers-},
+{-ifelse({-$3-}, {--},
+{-ver_q(hstcl({-$1-}), {-translit({-{-$2-}-}, {-$-}, {--})-})-},
+{-ver_q(hstcl({-$1-}), {-_addsubdir({-{-$2-}-}, $3)-})-})-})dnl
+dnl
+dnl Version info for this file:
+dnl
+vers(__file__, {-$OpenBSD: MAKEDEV.mansub,v 1.1 2004/02/16 19:03:30 miod Exp $-})dnl
+dnl
+dnl
+define({-_addsubdir-},
+{-patsubst({-$1-}, {-\$(OpenBSD:) ([^\$]*)\$-}, {-\1 $2/\2-})-})dnl
+dnl
+dnl do the 'showing' of the version info
+dnl
+define({-do_vers-}, {-COMM	$1-})dnl
+dnl
+dnl show version function, to be called at the place when all versions are
+dnl   queued, and it is time to show all of them
+dnl
+define({-show_vers-},
+{-ifelse(_m4_cvs_ver, {-done-}, {--},
+{-do_vers(_m4_cvs_ver)
+popdef({-_m4_cvs_ver-})dnl
+show_vers()dnl
+-})-})dnl
+dnl
+dnl
+dnl _devitem(pattern, description)
+dnl
+define({-_devitem-},{-.It Ar $1
+$2.-})dnl
+dnl
+dnl _devtitle(name,description)
+dnl
+define({-_devtitle-},{-ifelse($1,make,,{-.El
+-}).Pp
+.Sy $2
+.Bl -tag -width tenletters -compact-})dnl
+dnl
+dnl _DEV(name, [character major], [block major])
+dnl
+define({-_DEV-}, {-$1_dev{--}dnl
+define({-$1__DEV-}, {-Y-})-})dnl
+dnl
+define({-_MKDEV-}, {-$1_mkdev-})dnl
+define({-_TITLE-}, {-$1_title-})dnl
+define({-__devitem-}, {-define($1_dev, {-_devitem($2,$3)-})$4-})dnl
+define({-__devtitle-}, {-define($1_title, {-_devtitle($1,$2)-})-})dnl
+define({-_mkdev-})dnl
+define({-_mcdev-})dnl
+define({-_cdev-})dnl
+define({-__mkdev-})dnl
+define({-target-})dnl
+define({-twrget-})dnl
diff --git a/etc/Makefile b/etc/Makefile
index a42efc55c1a..15bd5e1198d 100644
--- a/etc/Makefile
+++ b/etc/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.198 2004/02/13 14:14:52 miod Exp $
+#	$OpenBSD: Makefile,v 1.199 2004/02/16 19:03:30 miod Exp $
 
 TZDIR=		/usr/share/zoneinfo
 LOCALTIME=	Canada/Mountain
@@ -351,17 +351,24 @@ cleandir:
 	cd ${.CURDIR}; for m in ${MAKEDEVARCHS}; do \
 	    ${MAKE} MACHINE=$$m clean; done
 
+MAKEDEVSRC=	MAKEDEV.mi MAKEDEV.sub MAKEDEV.common
+MAKEDEVDOC=	MAKEDEV.man MAKEDEV.mansub MAKEDEV.common
 m4: etc.${M}/MAKEDEV
+man: ${.CURDIR}/../share/man/man8/man.${M}/MAKEDEV.8
 
-etc.${M}/MAKEDEV: MAKEDEV.sub MAKEDEV.mi etc.${M}/MAKEDEV.md
-	echo "==> etc.${M}/MAKEDEV"
+etc.${M}/MAKEDEV: ${MAKEDEVSRC} etc.${M}/MAKEDEV.md
+	@echo "==> etc.${M}/MAKEDEV"
 	m4 -DMACHINE=${M} MAKEDEV.mi > etc.${M}/.MAKEDEV.tmp && \
 	    mv etc.${M}/.MAKEDEV.tmp etc.${M}/MAKEDEV || \
 	    rm etc.${M}/.MAKEDEV.tmp
 
-allarchs: MAKEDEV.sub MAKEDEV.mi
+${.CURDIR}/../share/man/man8/man.${M}/MAKEDEV.8: ${MAKEDEVDOC} etc.${M}/MAKEDEV.md
+	m4 -DMACHINE=${M} MAKEDEV.man > \
+	    ${.CURDIR}/../share/man/man8/man8.${M}/MAKEDEV.8
+
+allarchs: ${MAKEDEVSRC} ${MAKEDEVDOC}
 	cd ${.CURDIR}; for m in ${MAKEDEVARCHS}; do \
-	    ${MAKE} M=$$m m4; done
+	    ${MAKE} M=$$m m4 man; done
 
 distrib:
 	cd ${.CURDIR}/../distrib && \
@@ -370,7 +377,7 @@ distrib:
 DHSIZE=1024 1536 2048 3072 4096
 update-moduli:
 	( \
-		echo '#    $$OpenBSD: Makefile,v 1.198 2004/02/13 14:14:52 miod Exp $$'; \
+		echo '#    $$OpenBSD: Makefile,v 1.199 2004/02/16 19:03:30 miod Exp $$'; \
 		echo '# Time Type Tests Tries Size Generator Modulus'; \
 		( for i in ${DHSIZE}; do \
 			ssh-keygen -b $$i -G /dev/stdout; \