[illumos-Developer] webrev: man fixes, new man pages

[Garrett D'Amore]

On Sat, 2011-03-19 at 02:42 -0400, Richard Lowe wrote:
> Generally:  We should, at some point, use a table separator other than
> ^G.  It doesn't show in webrevs.

See my PS below.  At some point I'd like to revisit man pages in
general.. some of this markup is *really* ugly, and I think a lot of
logical structure has been lost in this markup.  (I.e. this markup is
purely physical rather than logical.)

> 
> audioctl.1:
>   You're supposed to actually fill in the copyright notices... :)

Doh!  Thanks.

> 
>   Don't think you need an Architecture line in Attributes for a
> command unless it's not on both.

Good point.  I'll remove it.

> 
> usr/src/pkg/manifests/driver-audio-audiocmihd.mf:
> 
>   There's no reason to $(i386_ONLY) the 32bit driver.  The entire
> package is i386-specific.

For now. :-)  The binary audiocmihd could probably be made to work on
SPARC pretty trivially if someone wanted to test and was willing to fix
any minor things in the driver.  I tried to make sure the driver is
portable in the code, but I didn't test the driver because I didn't see
any demand for it on that hardware and little point in delivering it
there.

Anyway, I'd like to leave the $(i386_ONLY) there for now.  One less
thing to change later if someone wants it on SPARC.  (Right now the only
thing needed to make it work SPARC should be to add a
sparc/audiocmihd/Makefile, reference it in sparc/Makefile.sparc.common,
and then add move the package name to the sparc stanza in
usr/src/pkg/Makefile.  Should be that simple. :-)

> 
> usr/src/prototypes/prototype.man:1
> 
>   The 't' here controls whether man(1) runs tbl.  If you're going to
> suggest it in the prototype, consider 'te', to run eqn as well.
>   Be prepared for 90% of people to leave them there regardless of
> their use of tbl or eqn, however.

I did consider 'te', but decided against.

Few enough people use eqn that I didn't think it worth adding.  But
*everyone* uses tbl because of the ATTRIBUTES table.  (And forcing
another process pipe on everyone that would only rarely be used seemed
not a good thing. :-)

	- Garrett

PS: After going into this, I'm starting to see some merit in moving
towards mandoc, or enhancing our man macros with some "standard" macros
to make this stuff cleaner/better.  I shouldn't have to say "SunOS"
anywhere, for example.