On 07/28/14 07:26 PM, Garrett D'Amore via illumos-developer wrote:
I'd like to propose that we "cleanup" certain things in man pages.
1. For section 7D pages, I'd like to remove the FILES section, or at
least any references to driver binaries. The location of driver
binaries is architecture, and in some cases distribution-, specific,
and offers little useful value. I think even documenting driver.conf
location is rather pointless, since driver.conf covers it.
So, driver.conf should be in the SEE ALSO section.
2. For NIC drivers, I want to remove the entire APPLICATION
PROGRAMMING INTERFACE that describes the various DLPI parameters.
Instead, the page should document that the driver is an ethernet
driver, and include a reference to dlpi(7p).
Fine if they are all the same. Max frame size should be mentioned (and
probably also explicitly mention support for jumbo frames, or not).
Likewise, the various ethernet-generic driver.conf properties ought
to be removed from documentation -- the correct way to configure
properties is via dladm instead of driver.conf.
Are they all configurable via dladm?
Personally I would prefer that information remains, but also states
dladm is now the preferred interface where that is the case.
3. For class wide drivers (e.g. ethernet), maybe we should also remove
the /dev/igb* (or whatever) notation from FILES. Again, DLPI is the
right way to access these, not by accessing the /dev node directly.
(And again, the /dev node can vary based upon vanity naming, style 1
vs style 2 DLPI, etc.)
DLPI API requires that the vendor specifies the device node to open.
4. Each driver doesn't need to include a reference to the WDD, STREAMS
Programming guide, etc. That is covered in Intro(7), and the driver
pages can just list that in SEE ALSO.
Yes, but you probably exceeded the max link count a human will follow,
thus obscuring the information.
--
Andrew Gabriel
-------------------------------------------
illumos-discuss
Archives: https://www.listbox.com/member/archive/182180/=now
RSS Feed: https://www.listbox.com/member/archive/rss/182180/21175430-2e6923be
Modify Your Subscription:
https://www.listbox.com/member/?member_id=21175430&id_secret=21175430-6a77cda4
Powered by Listbox: http://www.listbox.com
