Re: mdoc synopsis style for more than one mandatory, mutually exclusive options?

[Ingo Schwarze <schwarze@usta.de>]

Hi Stephen,

Stephen Gregoratto wrote on Tue, Jul 20, 2021 at 08:48:54AM +1000:

> I am working on a utility that takes input from different sources:
> 
> 1. Arguments after options parsing (i.e., after --).
> 2. From the named file after the `-R` flag.
> 3. From the named file after the `-I` flag.
> 
> The program will quit if input == 0, so at least one of these options
> must be used. And there can be multiple instances of each (i.e., -R and
> -I can be specified more than once).
> 
> My question is: how can I format this in the synopsis without it being
> overwhelming? Semantically, .Op is out because it isn't optional.

Don't over-think the SYNOPSIS.  It cannot express everything.
If something cannot be fully expressed in the SYNOPSIS, write the
SYNOPSIS such that it isn't wrong and then explain the additional
constraints in the DESCRIPTION.

From what you say above, it is clear you need at least this:

.Nm
.Op Fl I ifile
.Op Fl R rfile
.Op Ar argument ...

Do not use ifile, rfile, and argument for the placeholders;
use expressive names instead.  I cannot suggest any because i do
not know ehat the two kinds of files contain and what the arguments
mean.

Then, in the DESCRIPTION, after explaining what the basic purpose
of the utility is, say something like

  At least one source of input, i.e. at least one
  .Fl I
  option,
  .Fl R
  option, or
  .Ar argument
  is required.

If it matters, add a sentence like this one here:

  Input sources are processed in the order given on the command line.

At the end of .It Fl I , say something like

  Multiple
  .Fl I
  options can be provided

And if that matters and you did not already say it earlier, something like:

  and are processed in the given order.


All that said, also consider command line user interface design;
difficulty in writing a manual can be a symptom of missed opportunities
of making the UI simpler or more uniform.

For example:

 * Many utilities optionally taking input and output file names
   as option arguments read from stdin and write to stdout by
   default, to allow using them in pipelines.  Would that be
   beneficial for your program?  Is it really necessary that
   the program does nothing useful unless it is given at least
   one option or argument?

 * If "ifile" and "argument" serve a similar purpose, why is one
   and option argument and the other an argument proper?
   Would the UI become easier to understand by choosing another
   option letter and making "argument" an option argument, too?
   That would also allow to first process a file, then an argument,
   then another file.
   For example, sed(1) supports both "-f command_file" and
   "-e command".  Whether supporting both "sed command file"
   and "sed -e command file" was a good idea (syntactic sugar)
   or a bad one (needless variation causing complexity) is another
   question; for sed(1), it may be warranted because "sed command file"
   is really the dominant use case and -e and -f are needed more rarely.
   But the dominant use case may be different for your utility.
   For example, i think supporting "man -s 2 pledge" would have
   been enough; that "man 2 pledge" also works is useless UI bloat
   because the dominant use case is just "man pledge" and in those
   few cases where the section needs to be specified, typing "-s"
   wouldn't have been annoying.

> I've seen other utilities use something like
> 
>   (a | -F b)...
> 
> instead, but I've never seen this form in a manpage before.

Using parentheses for alternatives isn't unusual in GNU manuals,
but you won't find it in OpenBSD manuals because it's an attempt
to express complexity that can't really be expressed very well in
the SYNOPSIS, and also because it almost always conflicts with the
rule to list options without arguments first in alphabetical order,
followed by options with arguments in alphabetical order, followed
by positional arguments.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv