Skip site navigation (1)Skip section navigation (2)
Date:      Tue, 12 Aug 2003 20:54:10 +0200
From:      "Simon L. Nielsen" <simon@FreeBSD.org>
To:        "Bruce A. Mah" <bmah@FreeBSD.org>
Cc:        Ruslan Ermilov <ru@FreeBSD.org>
Subject:   Re: Hardware notes
Message-ID:  <20030812185410.GA7418@FreeBSD.org>
In-Reply-To: <20030812152843.GA64916@intruder.kitchenlab.org>
References:  <Pine.LNX.4.44.0308081232001.28480-100000@pancho> <200308082326.h78NQpmh056949@intruder.kitchenlab.org> <20030809000230.GA53916@FreeBSD.org> <20030810000622.GF396@FreeBSD.org> <20030812152843.GA64916@intruder.kitchenlab.org>

next in thread | previous in thread | raw e-mail | index | archive | help

--T4sUOijqQbZv57TR
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

On 2003.08.12 08:28:43 -0700, Bruce A. Mah wrote:
>=20
> I'm not totally convinced either.  With my "devil's advocate" hat on:
>=20
> 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)?

--=20
Simon L. Nielsen
FreeBSD Documentation Team

--T4sUOijqQbZv57TR
Content-Type: application/pgp-signature
Content-Disposition: inline

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.2 (FreeBSD)

iD8DBQE/OTfSh9pcDSc1mlERAtYyAJ46VFnrD1gmtOcGU2CvwdMz23UJFQCfRFcn
QZdRt6/56vuwFJ9nsO+b9VU=
=sTU8
-----END PGP SIGNATURE-----

--T4sUOijqQbZv57TR--



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20030812185410.GA7418>