Hardware notes

[Bruce A. Mah]

If memory serves me right, Simon L. Nielsen wrote:
> On 2003.08.09 02:02:31 +0200, Simon L. Nielsen wrote:
> > 
> > [Bruce wants to simplify the hardware notes, and mainly make the
> > hardware notes references to the section 4 manual pages]
> > 
> > I have been thinking a bit about the hardware notes today, and I got a
> > crazy idea...  If each section 4 manual page listed the supported
> > devices in some machine parseable way (e.g. in a seperate section?), the
> > device list could actually be extracted from the manual pages and used
> > in the release notes.  Then the actual list would only be one place for
> > each driver.  While it might sound a bit crazy, I actually think it
> > could work.  Of course it would require some work in the manual pages,
> > but it shouldn't be too hard.
> 
> It was suggested that I should do a proof of concept, so I did.

Sorry for the delay.

Wow.  Thanks for giving this a shot.  This is actually pretty clever.

> I actually think it works pretty well, but I'm still not really sure if
> I think this is the way to go, since manual pages were not really made
> for this.

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).

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

3.  Only half an objection, but building the hardware notes now
    requires an up-to-date checked-out copy of the manpage sources.

That having been said, your solution definitely goes a long way
towards grep-able hardware notes without cut-n-pasted text.

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?)  But we should discuss this.  Also, I'd
like to hear what others think.

Regardless, thanks for working on this!

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/4335bf0f/attachment.sig>