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
   during import.

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.
      i386/fontedit.1
     i386/vt220keys.1
        i386/vttest.1
          vax/crash.8
         vax/format.8
   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.

cheers,
Danny Thomas