Subject: summary of changes about to be submitted for 60+ man-pages
To: None <firstname.lastname@example.org>
From: Danny Thomas <D.Thomas@vthrc.uq.edu.au>
Date: 11/02/1999 01:30:09
I thought I'd get some feedback before submitting patches to 63 manpages
and Makefiles. Here's the summary - consider each to be a statement
advanced for correction.
I noticed these in the warnings produced from my perl script which can
convert a document tree (man, pod, html, postscript) into a single
bookmarked PDF arranged in a meaningful order. In this case the NetBSD
/usr/share/man converts into a 8M, 3,293 page PDF which makes the whole
document not very useful. The process is really meant for packages like
bind and ntp4.
Often a man-page will exist under several names, perhaps even in different
sections. Including all these would have doubled the size of the PDF, so a
man-page is only included under the preferred name (.TH or .Dt) as in the
BSD4.4 reference manuals. However the other names are also included amongst
the bookmarks, so that means alias, bg ... for csh(1). It is the
determination of these bookmarks and the preferred name which involves
cross-checking of document titles, sections and volumes (aka machine) and
filenames and paths.
I've had a brief look at .Xr cross-references, which don't seem too bad.
0) purely as a convenience to my script, I've changed the first line
of these to start with a 'magic' sequence (atalk(4) had empty line)
so ''' got changed to .\"
cu(1), uucp(1), uustat(1), uux(1), atalk(4), uucico(8), uuxqt(8)
1) I assume that the title of the man-page corresponds to the name
of the source man-page. MLINKS can be used to create other names
as hard-links in /usr/share/man. I don't check the name of the
file as it's position under /usr/src is not known. I do check that
one of the filenames to a man-page does match the title, so
2) I assume every page in a machine sub-directory
* should include the machine in the title
eg ".Dt msconfig 1 atari"
* that means .Dt must be used
since .TH doesn't allow volume, aka machine
3) in mdoc, .Dt titles had to be upper-case for "due to troff limitations"
Many are in lower case. I'm assuming this is now OK. With the sole
exception of getNAME(8), I lower-case all names anyway.
4) the file _exit.2 has a .Dt title of "EXIT 2". Is that historical
or can't titles have leading underscores ? I'd rather see it
bookmarked as both _exit(2) & exit(2)
5) there are a few cases when the title does not match the filename
greconfig.8 changed title from grectrl 8 -> greconfig 8
dhcp-options.5 changed title from dhcpd-options 5 -> dhcp-options 5
x68k/boot.8 changed title from boot_x68k 8 -> boot 8
arm32/es.4 changed title from eh 4 -> es 4
i386/console.4:changed title from cons 4 -> console 4
newfs_lfs.8 changed title from newlfs 8 -> newfs_lfs 8
NB the last one was done by perseant after the July snapshot
i386/vt220keys.1: didn't know whether to change title to vt220keys
or the filename to i386/vt220.1
6) there were somes case when the section in the title didn't match
the manX directory. In general I preferred to change the title
section instead of putting the file under different manX directory
tcpdump.8 changed title from tcpdump 1 -> tcpdump 8
mailstats.8 changed title from mailstats 1 -> mailstats 8
praliases.8 changed title from praliases 1 -> praliases 8
i386/ispcvt.8 changed title from ispcvt 1 -> ispcvt 8
7) in two cases, the machine part of the title was misspelled
atari/floppy.4 & atari/ms.4 both used 'Atari'
8) there are a few cases when a machine-specific page is not in the
appropriate sub-directory; dbsym(8), grfconfig(8), mbr(8).
I could imagine the latter being of some use on other architectures
as background reading should DOS disks get attached. But for now
I moved them under the appropriate machine sub-directory
9) in the title for fgen(1), the volume is given as PRM
no other page does so. I removed it, but maybe it could return
if other pages used it consistently, eg the manless gspa
A) fea(4) had three .Dt (probably the last, EYA, being a tyop)
I don't think that's a good idea. Multiple .Nm is fine, though.
B) cpio(1), fixmount(8) & wire-test(8) had an 'L' (library) suffix
to the section. I removed this which presumably didn't get removed
C) Of the 41 pages in machine sub-directories not including the machine
in the title, in 5 cases that's because the title was given by .TH.
The first three probably need addition of the NetBSD copyright block
D) dunno whether I've screwed up, but it seems host(1) included in
the july tarball, hasn't been fully processed
.Dt HOST @CMD_EXT_U@
E) another PR describes a fix so gawk(1) gets hard-linked to awk(1)
[the main problem is with bsd.info.mk not handling MLINK]
F) One question about .Xr cross-refs. There's numerous uses of ioctl
with no section. Now there's ioctl(9), I assuming these should all
get 2 added. However the real question - should the section always
be specified in an .Xr ?
[I came across PR 5562 after writing this]
PS these are from the man-pages a few weeks ago and suspect the glitches
nearly all remain.