pkg man pages

[Warren Block <wblock@wonkity.com>]

You have probably heard about the pkg project, FreeBSD's rework of the 
package database.  Well, we've been looking at the man pages for those 
commands.  It's clear the synopsis sections need work, but less clear 
which way is the best, clearest way to format those sections in mdoc.

Since you guys are the experts, I'd like to ask your opinion.

As an example, consider pkg-check.8:
https://github.com/freebsd/pkg/blob/master/docs/pkg-check.8

   pkg check [-Bdsr] [-nqvy] [-a | -Cgix pattern]

There are four main commands, [-Bdsr].  I don't think these are 
actually optional.

There are some optional options, -nqvy.

Then there is [-a | -Cgix pattern], to operate on all packages or a 
pattern match for package name.  The options on the pattern make it 
possible to be case sensitive and so on.

Then there are GNU-style double-dash duplicate variants for all of the 
above.  I find the way these are currently shown to be confusing:

[--{shlibs,dependencies,checksums,recompute}]

meaning --shlibs or --dependencies and so on.  The options will not fit 
on a single line, so the [] markers are kind of difficult to see.


The other pkg commands have very similar options, so it would be nice to 
get it right before changing any of them.

I'd say the first part of the synopsis should look something like this 
(less markup):

   pkg check -B|-d|-s|-r [-nqvy] [-a|-Cgix pattern]

Then a second version could be shown with the long options.  But when 
some commands get to be this complicated, they sometimes go to a generic 
form:

   pkg check command [options] [packages]

   Where "command" is

     -B or --shlibs is used to...
     -d or --dependencies does something...
     -s or --checksums checks checksums...
     -r or --recompute recomputes...

   And "options" are...

Can you recommend examples of the right way to do this?

Thanks!
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv