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

[Stephen Gregoratto <dev@sgregoratto.me>]

Hi Ingo,

Thanks for your recommendations. The program I'm working on is an
implementation of age[1], a encryption program. It's supposed to act as
just another UNIX-style filter that just works™.

My implementation is different in that I'm not strictly following the
reference's style of arguments, as I find them too complicated for my
tastes. It commits the "sin" of arguments taking on different meanings
in different contexts. You make a good point about needless complexity,
and I've tried to structure my implementation to reduce this as much as
possible, mainly by using subcommands.


Here's the full synopsis of the previous scenario, in context:

  zage encrypt [-a] [-i file] [-o file] \
    -R recipient-file -I identity-file recipients ...
  zage encrypt [-a] [-i file] [-o file] -p

Here "recipients" are public keys, in two forms: age X25519 keys and
OpenSSH Ed25519 keys. They're short enough that it's reasonable to
expect users to paste them in as arguments. -R denotes files
containing these recipient types, one per line. This means that users
can pass their authorized_keys file, and encrypt to any ssh-ed25519 key
in said file. I kept going back and forth between having -R only
specified once or more than, but I decided to stick with the latter
since it leads to cute invocations like:

-R ~/.ssh/id_ed25519.pub -R <(curl -s https://github.com/ischwarze.keys)

-I is similar to -R, except it reads secret keys, and thus has to
compute the public key of each. This one is a holdover from the
reference implementation, and I'm not so sure about keeping it around.

-i and -o are the usual input and output files, defaulting to stdin/out
if not given. -a is for PEM/ASCII armour, and -p is a special case for
password encryption.

Hope that clears things up. I think I'll stick to your advice about
keeping the SYNOPSIS simple, and explain in detail later on (probably in
a subheading to keep things neat).

[1] https://age-encryption.org/v1
-- 
Stephen Gregoratto
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv