8.x grudges

[Jeremy Chadwick]

On Thu, Jul 08, 2010 at 02:46:16PM -0700, Freddie Cash wrote:
> On Thu, Jul 8, 2010 at 2:36 PM, Lucas Holt <luke at foolishgames.com> wrote:
> > On 07/08/10 17:06, Peter Jeremy wrote:
> >>
> >> On 2010-Jul-07 14:22:22 -0400, "Mikhail T."<mi+thun at aldan.algebra.com>
> >>  wrote:
> >>
> >>>
> >>> In no particular order:
> >>>
> >>>   1.
> >>>      A picture, that one of the systems was displaying at boot (and
> >>>      then used as a screen-saver),  stopped showing properly. The
> >>>      colors are right, but the picture is distorted beyond recognition.
> >>>      The relevant part of loader.conf is:
> >>>
> >>>          splash_pcx_load="YES"
> >>>          vesa_load="YES"
> >>>          bitmap_load="YES"
> >>>          bitmap_name="/boot/187426-9-quokka-dreaming.pcx"
> >>>
> >>
> >> It's a bit difficult to provide any useful input without some idea
> >> of what the picture should and does look like.  Can you please post
> >> the actual bitmap as well as a picture of your screen showing the
> >> problem.
> >>
> >>
> >>>
> >>>   3.
> >>>      Likewise, having "device ugen" breaks config(8) -- another
> >>>      undocumented incompatibility.
> >>>
> >>
> >> Can you please advise where it is documented that "device ugen"
> >> is valid in a FreeBSD-8 config file?
> >>
> > NAME
> >     ugen -- USB generic device support
> >
> > SYNOPSIS
> >     To compile this driver into the kernel, place the following line in your
> >     kernel configuration file:
> >
> >           device ugen
> >
> >     Alternatively, to load the driver as a module at boot time, place the
> >     following line in loader.conf(5):
> >
> >           ugen_load="YES"
> >
> > DESCRIPTION
> >     The ugen driver provides support for all USB devices that do not have a
> >     special driver.  It supports access to all parts of the device, but not
> >     in a way that is as convenient as a special purpose driver.
> >
> >     There can be up to 127 USB devices connected to a USB bus.  Each USB
> >     device can have up to 16 endpoints.  Each of these endpoints will commu-
> > <snip>
> >
> > uname -a
> > FreeBSD lholt-desktop.primemediaanalysis.com 8.0-RELEASE-p3 FreeBSD
> > 8.0-RELEASE-p3 #0: Tue May 25 20:54:11 UTC 2010
> > root at amd64-builder.daemonology.net:/usr/obj/usr/src/sys/GENERIC  amd64
> >
> > I'm not going to argue in favor of any points in this rant, but it is in the
> > man page.
> 
> Looks like you found a bug.  :)
> 
> ugen is not listed in any of the NOTES files, and is not a valid
> device entry for a 8.x kernel config file.  Maybe that man page got
> skipped in the USB stack upgrade?
> 
> Should definitely add a PR for this man page to be updated for the new
> USB stack.  Maybe even do an audit of the rest of the USB devices to
> make sure the man pages for those are correct as well.

In this specific case it's a bug -- someone didn't remove ugen.4 from
the build tree.

But be careful when it comes to relying on "man" to indicate a feature
existing.

Some older users may remember how catman pages could (can?  It may still
happen -- though my quick dig through periodic's 330.catman indicates
catman(1)'s -r flag is now used, so things SHOULD be in sync at all
times now) get out of sync.

With regards to "leftover man pages" in /usr/share/man/manX, I believe
mergemaster now handles clean-up of those, and probably catX too.  Can't
remember (I've been up for 22 hours, cut me some slack :-) ).

I will take a moment to mention periodic(8)'s "weekly_catman_enable"
variable, which is wonderful except for the fact that tons of our man
pages don't play nice with "nroff -man" so you'll see tons of warnings
every week -- with no filenames emitted to track down the offender.
Frustrating!  Maybe catman(1)'s -v flag emits the filename it's handing
off to nroff?  Not sure.  Either way, highly frustrating.

So for rebuilding catman pages, I recommend folks do it manually.
Run /etc/periodic/weekly/330.catman by hand (with the periodic.conf
variable set to "yes" of course), enjoy the warnings, then disable the
variable in the conf once more.

Man pages!!!  *shakes fist angrily*

-- 
| Jeremy Chadwick                                   jdc at parodius.com |
| Parodius Networking                       http://www.parodius.com/ |
| UNIX Systems Administrator                  Mountain View, CA, USA |
| Making life hard for others since 1977.              PGP: 4BD6C0CB |