Hardware notes

Simon L. Nielsen simon at FreeBSD.org
Tue Aug 12 18:54:13 UTC 2003


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.

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

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

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

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

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

-- 
Simon L. Nielsen
FreeBSD Documentation Team
-------------- 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/5f670c1d/attachment.sig>


More information about the freebsd-doc mailing list