should there be a manpage for every device? every kernel configuration interface attribute?

I often see names that don't have corresponding manual pages
like "ra".

I think there should be a man page for every device.

I think there should be a man page for every kernel
configuration 
interface attribute (I don't know if that is the right term,
but I will 
show examples below.)

What do you think?

 m=`uname -m` ; dmesg |  egrep "^[^ ]+ at " |
 cut -d " " -f 1,3 | tr -d ":" | fmt 1
|
 sed -e 's,[0-9]$,,g' | sort -u | while read d ; do
  [ -e "/usr/share/man/man4/$d.4" ] ||
  [ -e "/usr/share/man/man4/$m/$d.4" ] || echo
"$d needed" ; done

output on vax 4.0:

ibus needed
mscpbus needed
mtc needed
ra needed
rl needed
rlc needed
rx needed
uba needed

on amd64 HEAD:

cpu needed
hpet needed
ioapic needed
pcib needed

and on i386 3.1:

cpu needed
pcib needed


And another example:

cat /usr/src/sys/arch/i386/conf/GENERIC | tr -d '#' | egrep
"^[^ ]+ at " | 
cut -d " " -f 1,3 | tr -d "?" |
fmt 1 | sed -e 's,[0-9]$,,g' |
sort -u | while read d ; do
          [ -e "/usr/share/man/man4/$d.4" ] ||
          [ -e "/usr/share/man/man4/$m/$d.4" ] ||
echo "$d needed" ; done

results in:

addcom needed
adt7463c needed
amdpcib needed
cpu needed
elansc needed
gcscehci needed
gcscpcib needed
geodecntr needed
geodegcb needed
geodewdog needed
gscpcib needed
iic needed
ioapic needed
p64h2apic needed
root needed
satlink needed
stuirda needed
vald needed
viapcib needed
weasel needed




So should many of the above be documented or what?

I can make the beginning of webpages as needed.

  Jeremy C. Reed

On Thu, Mar 20, 2008 at 05:42:27PM -0500, Jeremy C. Reed
wrote:
 > I often see names that don't have corresponding manual
pages like "ra".
 > 
 > I think there should be a man page for every device.

Yes.

(Would you like to have cron run that mail the results here
once a
month or so? That would probably help get it done in the
long run.)

-- 
David A. Holland
dhollandnetbsd.org

On Fri, 21 Mar 2008, David Holland wrote:
> > I often see names that don't have corresponding
manual pages like "ra".
> >
> > I think there should be a man page for every
device.
>
> Yes.

seconded


> (Would you like to have cron run that mail the results
here once a
> month or so? That would probably help get it done in
the long run.)

Cron job is a nice idea...
I wonder if src/sys/dev/DEVNAMEs can be of any help ...


  - Hubert

> (Would you like to have cron run that mail the results
here once a
> month or so? That would probably help get it done in
the long run.)

Also for /dev files too.

So in addition to my other two scripts, here's another:

 m=`uname -m` ; find /dev -type c -o -type b | xargs -n 1
basename |
 tr -d '.' | sed -E -e 's,[0-9][a-z]+$,,g' -e 's,[0-9]+$,,g'
|
 egrep -v '^pty|^dty|tty|^$' | sort -u |  while read d ; do
   [ -e "/usr/share/man/man4/$d.4" ] ||
   [ -e "/usr/share/man/man4/$m/$d.4" ] || echo
"$d needed" ; done

So on my amd64 HEAD plus my notes added:

(this includes "r" raw devices too.)

afm needed
altq needed
audioctl needed -- link to audio.4
blue needed -- link to altq.4 (when ready)
cbq needed -- link to altq.4 (when ready)
cdnr needed -- link to altq.4 (when ready)
cfs needed
console needed (curious: how do you know what console you
are using?)
cpuctl needed
ctyU needed  -- I didn't exclude these as no cty man page!
ctyY needed
drvctl needed
enrst needed -- link to st.4
enss needed -- link to ss.4
enst needed -- maybe link to st.4?
erst needed -- link to st.4
est needed -- maybe link to st.4?
fifoq needed -- link to altq.4 (when ready)
hfsc needed -- link to altq.4 (when ready)
ipauth needed -- link to ipf.4
iplookup needed
ipscan needed
ipstate needed -- link to ipf.4
ipsync needed
isdnteld needed
klog needed
kmem needed -- blame that amd64 manpages bug
localq needed -- link to altq.4 (when ready)
lockstat needed
lpa needed -- link to lpt.4
lpt needed -- also amd64 manpages bug
mem needed -- also amd64 manpages bug
nrst needed -- link to st.4
nrwt needed -- link to wt.4  ** also looks like typos in wt4
that refer to
				st instead of wt??
nss needed -- link to ss.4
nst needed -- maybe link to st.4?
nwt needed -- maybe link to wt.4?
power needed
priq needed -- link to altq.4 (when ready)
ptmx needed -- link to ptm.4
putter needed
random needed -- link to rnd(4)?
rccd needed -- 
rcd needed -- link to cd.4
rcgd needed -- link to cgd.4
red needed -- link to altq.4 (when ready)
rfd needed -- floppy.4 needed?
rfss needed -- link to fss.4
rio needed -- link to altq.4 (when ready)
rld needed -- link to ld.4
rmcd needed -- link to mcd.4
rmd needed -- link to md.4
rraid needed -- link to raid.4
rsd needed -- link to sd.4
rst needed -- link to st.4?
rvnd needed -- link to vnd.4
rwd needed -- link to wd.
rwt needed -- link to wt.4
rxbd needed -- link to 
satlink needed
sysmon needed
systrace needed
tuner needed -- link to bktr.4?
ulpn needed -- link to ulpt.4
urandom needed -- link to rnd(4)?
vbi needed -- link to bktr.4
watchdog needed
wfq needed -- link to altq.4 (when ready)
wsmuxctl needed -- link to wsmux.4
xbd needed
xencons needed


On Fri, 21 Mar 2008, Hubert Feyrer wrote:
> I wonder if src/sys/dev/DEVNAMEs can be of any help
...

That will help too.

> console needed (curious: how do you know what console
you are using?)

It is there. Just not on amd64!

I have committed seven links (MLINKS) for man pages based on
my lists. I 
have many, many to go. And many man pages need to be
written.

As another way to check is looking at .Xr references in
manpages. This is 
hard because some manpages are dynamic.

Anyways, here is a start of another list. Either the
manpages should exist 
or the original manpages should not reference them.

ae
aed
altq
asc
awacs
battery
bm
bwtwo
cgsix
cgthree
cosc
csc
ct
envstat
ie
iic
ioctl
ipcomp
kbd
magma
ms
mt
ns
nvram
obio
p2p
pfsync
phantomas
pnozz
polling
ppi
ptmx
ptsc
rd
sci
scif
sppp
tcx
viapm
vidcaudio
wdog
zx

  Jeremy C. Reed