From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-01-web.scc.kit.edu (scc-mailout-kit-01-web.scc.kit.edu [129.13.231.93]); by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 4c045cd1; for ; Tue, 21 Jul 2015 00:44:48 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-01.scc.kit.edu with esmtps (TLS1.2:DHE_RSA_AES_256_CBC_SHA256:256) (envelope-from ) id 1ZHQM7-0003Em-BH; Tue, 21 Jul 2015 07:44:44 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1ZHQiC-0005yw-ON; Tue, 21 Jul 2015 08:07:32 +0200 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.80) (envelope-from ) id 1ZHQM6-0004nX-GW; Tue, 21 Jul 2015 07:44:43 +0200 Received: from localhost (1031@localhost [local]); by localhost (OpenSMTPD) with ESMTPA id 49252af9; Tue, 21 Jul 2015 07:44:42 +0200 (CEST) Date: Tue, 21 Jul 2015 07:44:42 +0200 From: Ingo Schwarze To: Warren Block Cc: discuss@mdocml.bsd.lv, wblock@FreeBSD.org Subject: Re: pkg man pages Message-ID: <20150721054442.GJ9062@athene.usta.de> References: X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.5.23 (2014-03-12) Hi Warren, Warren Block wrote on Mon, Jul 20, 2015 at 06:24:56PM -0600: > 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 Random things that spring to the eye: * The Copyright notice is missing. It doesn't even say who the author is. Technically, that means the license is ineffective, it is not free software, so you shouldn't have it in the tree. * .Sh NAME .Nm is inconsistent with the page name. * The DESCRIPTION ought to start with one or two sentences what the basic purpose of the tool is, in particular when running without arguments. * Then you should put the sentence "The options are as follows:" * Use .Bl for the options and sort them alphabetically. * .Sh OPTIONS is terrible style, delete that. * Don't do .Cm --all, make that .Fl -all. * ... > 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. I would argue that all GNU-style double-dash options ought to be deleted from the SYNOPSIS outright, without any replacement. The whole point of the SYNOPSIS is to provide a concise overview of the user interface. GNU-style options, by definition, are not concise, so they shouldn't be in the SYNOPSIS. They are nothing but a distraction and a nuisance. You might make an exception when a GNU-style option doesn't have a proper one-character alternative - it might be better to sacrifice conciseness than completeness of the SYNOPSIS. > 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] NEVER do that. Terrible style. It completely defeats the purpose of the SYNOPSIS which is to concisely show the options. > 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? .Sh SYNOPSIS .Nm .Fl B | d | s | r .Op Fl nqvy .Op Fl a | Cgix Ar pattern .Sh DESCRIPTION Yours, Ingo P.S. I'd go one step further and say that GNU-style options are a clear indicator of bad design in the first place. If you have a user interface of reasonable size and simplicity, you don't need them, the fifty options you can have with single letters is *WAY* more than any reasonable interface can have. So they are just bloat, redundancy, needless complication and wordiness. So consider deleting them outright before users start using them. If you must keep them, make sure you always mention the proper one letter options FIRST and only mention the GNU-stuff at most once, as a discouraged alternative. They still encumber the documentation, but this is the best way to minimize the detrimental effect. -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv