Re: pkg man pages

[Ingo Schwarze <schwarze@usta.de>]

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