From mboxrd@z Thu Jan  1 00:00:00 1970
Received: from wonkity.com (wonkity.com [67.158.26.137]);
	by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id c4c1adbe;
	for <discuss@mdocml.bsd.lv>;
	Mon, 20 Jul 2015 19:25:04 -0500 (EST)
Received: from wonkity.com (localhost [127.0.0.1])
	by wonkity.com (8.15.2/8.14.9) with ESMTPS id t6L0OwnN075859
	(version=TLSv1.2 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO);
	Mon, 20 Jul 2015 18:24:58 -0600 (MDT)
	(envelope-from wblock@wonkity.com)
Received: from localhost (wblock@localhost)
	by wonkity.com (8.15.2/8.14.9/Submit) with ESMTP id t6L0OuE6075786;
	Mon, 20 Jul 2015 18:24:58 -0600 (MDT)
	(envelope-from wblock@wonkity.com)
Date: Mon, 20 Jul 2015 18:24:56 -0600 (MDT)
From: Warren Block <wblock@wonkity.com>
To: discuss@mdocml.bsd.lv
cc: wblock@FreeBSD.org
Subject: pkg man pages
Message-ID: <alpine.BSF.2.20.1507201758190.61628@wonkity.com>
User-Agent: Alpine 2.20 (BSF 67 2015-01-07)
X-Mailinglist: mdocml-discuss
Reply-To: discuss@mdocml.bsd.lv
MIME-Version: 1.0
Content-Type: text/plain; format=flowed; charset=US-ASCII
X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3 (wonkity.com [127.0.0.1]); Mon, 20 Jul 2015 18:24:58 -0600 (MDT)

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