Brian Utterback wrote: > So, in any case, we need a "best practice" kind of rule around FOSS man > pages. Should the team attempt to deliver as close as possible to the > original page in the package, or should it reflect the capabilities of > what is actually delivered, or something in between? It was already > pointed out that an "Attributes" section almost certainly must be added. > In this particular case, it also seems likely that the synopsis needs to > be changed to reflect the renamed deliverables, no? These two cases > must be decided before this case goes forward. And in general, I > believe that we require some kind of man page even if the original > package didn't have one, right?
I can't speak to the common practices followed in other consolidations, but in the X consolidation, we patch the upstream man pages where applicable to document Solarism's such as our SMF manifests and Secure-by-Default settings, and to note our different paths. (Since we have one major upstream source, X.Org, that produces most of the hundreds of upstream packages we build and integrate, it was not hard to write a script to do some modifications automatically, like adding /usr/X11/bin to command synopses, and -L/-l flags to library synopses, and the required attributes section, while things like describing the SMF manifests are done in patches.) Some examples of our man page patches, to see what we change: http://src.opensolaris.org/source/xref/fox/fox-gate/XW_NV/open-src/lib/libpciaccess/scanpci.man.patch - Add RBAC profile notes to scanpci(1) man page http://src.opensolaris.org/source/xref/fox/fox-gate/XW_NV/open-src/xserver/xorg/sun-manpage.patch - Add SMF, SBD, dtlogin, Xsun, etc. notes to Xserver(1) man page. and the script that modifies man pages, based on flags in the Makefile for each upstream package: http://src.opensolaris.org/source/xref/fox/fox-gate/XW_NV/open-src/common/suntouch-manpages.pl -- -Alan Coopersmith- alan.coopersmith at sun.com Sun Microsystems, Inc. - X Window System Engineering
