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. 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). 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. 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.) 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. 6. ARCHITECTURE should be removed for most drivers, unless the driver is somehow intrinsic to an architecture. For example, nxge lists both SPARC and x86. For what purpose? That's highly distribution specific as well. Arguably a few cases where it only makes sense for a driver to support a specific architecture exist -- e.g. nv_sata can only ever exist on x86 since its on Nvidia motherboards, or cvc(7D) which only exists on Sun E10K and SF15K servers (do such things ever run illumos distros?) But in general I'd like to eliminate the extra pointless ARCHITECTURE section unless something meaningful can be said there. 7. SYNOPSIS. I'm thinking that the /dev/* synopsis for drivers is often incorrect or useless (e.g. tapes show up at /dev/rmt/*, and busses often have no /dev link whatsoever. Vanity naming makes /dev/e1000gX kind of unreliable too!) Some pages workaround this by supplying a page that describes a bus address (e.g. "st"), but even that's not necessarily correct. So given this, I'm inclined to just remove the synopsis altogether. Instead, we should indicate that the device is of type "x" (e.g. a disk, or a tape device, or whatever), and include a cross reference to a page that gives information on how to locate such devices in the system. (E.g. dkio(7d) should give some information about the fact that disk devices are generally found under /dev/dsk/* and /dev/rdsk/* ... or perhaps Intro(7) could cover this content?) Thanks. - Garrett ------------------------------------------- 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
