Hardware notes

[Bruce A. Mah]

If memory serves me right, Simon L. Nielsen wrote:
> On 2003.08.12 08:28:43 -0700, Bruce A. Mah wrote:
> > 
> > I'm not totally convinced either.  With my "devil's advocate" hat on:
> > 
> > 1.  The manpages you wrote up (dc/asr/twe) seem to be some of the
> >     better-maintained manpages in the tree.  Examples of manpages that
> >     aren't quite ready for this yet are an(4) and ahc(4).
> 
> Yes, there will certainly be some pages which require some work before
> they can be used this way, but I think that should be a doable task.

I admit I don't have a good handle on the magnitude of the work that'd
be involved.

> > 2.  If we do this, I'd definitely like the option to turn off the
> >     lists of devices and just keep the descriptions.  One concern I
> 
> Yes, I also think this should be fairly simple to do if the lists
> extracted from the manual pages are used in the Hardware notes as SGML
> entities.  We could just generate some dummy empty entities for a
> hardware list without the details.

Sounds good.

> >     have about the hardware notes is that they're too long, and it's
> >     really hard to get an overall feel for what we support.
> 
> Perhaps both the full hardware notes and the brief version could both be
> generated, and linked to each other, like the single/split HTML files.

Hmmm...that's a thought.

> > 3.  Only half an objection, but building the hardware notes now
> >     requires an up-to-date checked-out copy of the manpage sources.
> 
> AFAIR it currently requires the doc/ tree, so I don't see this as much
> of a problem to also require src/share/man/man4.

Well, I said it was only half of an objection.  It would change my
operating procedures, and the Web site build scripts would work
differently.

> > So my first inclination would be to hold off on this, at least for the
> > first pass of a cleanup plan.  (Maybe we could add the device lists as
> > a build-time option later?)
> 
> I actuall think it would be simpler to do this if the hardware notes
> aren't as "cluddered" with the device lists, so waiting should be no
> problem.

OK.

> BTW, I noticed that the hardware notes for some drivers actually
> contained more supported devices than the manual pages, so somebody
> should probably try to update the manual pages with the missing devices.
> (A task on http://www.freebsd.org/docproj/current.html perhaps)?

Sure, sounds good.  Besides the hardware notes, possible places to
troll for supported device information include the source code for the
drivers themselves (looking for the probe/attach messages) and
src/sys/dev/usb/usbdevs.  Also bugging the driver maintainers has been
known to work.  :-)

Bruce.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20030812/461cd5ab/attachment.sig>