From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=0.2 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED autolearn=no autolearn_force=no version=3.4.4 Received: (qmail 13205 invoked from network); 20 Jul 2021 04:10:49 -0000 Received: from bsd.lv (HELO mandoc.bsd.lv) (66.111.2.12) by inbox.vuxu.org with ESMTPUTF8; 20 Jul 2021 04:10:49 -0000 Received: from fantadrom.bsd.lv (localhost [127.0.0.1]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 1d338bfc for ; Mon, 19 Jul 2021 23:10:46 -0500 (EST) Received: from wout4-smtp.messagingengine.com (wout4-smtp.messagingengine.com [64.147.123.20]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 9300dc1f for ; Mon, 19 Jul 2021 23:10:45 -0500 (EST) Received: from compute6.internal (compute6.nyi.internal [10.202.2.46]) by mailout.west.internal (Postfix) with ESMTP id 40873320093C; Tue, 20 Jul 2021 00:10:44 -0400 (EDT) Received: from mailfrontend2 ([10.202.2.163]) by compute6.internal (MEProxy); Tue, 20 Jul 2021 00:10:44 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sgregoratto.me; h=date:from:to:cc:subject:message-id:references:mime-version :content-type:content-transfer-encoding:in-reply-to; s=fm3; bh=T onUcaGL49vIqZT7oyeTqoAXEjdMIABSj9QzX4V9u9k=; b=jf24N9h9FEU2Jef0W fA8cLz2S9PTtkDT0oNoUol3B2pssBVp+WsSQZXU/BWG3ImdsuQoXxinU47YKuD4c duY841taeAkbkEoMlRxxgqur4bnPNxti5v5zXsctwgc6b3b3gbTXjNDoSqul0xwB hhG72dmiLTqGQALhcVsL5598nYwSBDdlU2j89hbuJVnkx+ihtmxDTfGkYyZ6GTzN VO9UwZVs16BtofrmkwiFKNoVxHIEVTlxGIqVbHKnSv2U9Yek28PyQAUq93AgbijX zxqQRsD1PO9n01zSbiOySKmb48SDAvqjAb5IcHOCIjLryHe1VTaHanIdqM4m7zad 5FhZA== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-transfer-encoding:content-type :date:from:in-reply-to:message-id:mime-version:references :subject:to:x-me-proxy:x-me-proxy:x-me-sender:x-me-sender :x-sasl-enc; s=fm3; bh=TonUcaGL49vIqZT7oyeTqoAXEjdMIABSj9QzX4V9u 9k=; b=bVINYMtRagHpp1h9xz1LSE21wIl44kIlr0EgISx0lTZ0gnDOVBk/hu8+x njANNHfnZzEyebJ8UMFhO4oIwHIYJiivTpTIFTxmABhRhcSfrEJ2trbliLAwtAjW FLb2naa9KTflwajXcFj9u5oFDQtytl6Da9hG49dgJosxzFckvbZr+Wxqd1OOfsQf 2qU6qsStuNkTH36Pugxb192vrMByzZXayG9EF3qfEPzQqZZSj9lrSlhfda0ddAju 9xnya4NaGr35T6lQVJcxHgVXtv8zfuDNfUgMGG3Dl+iSrRYbQ6XGbIg9GbqJ6mKi EvHW2yttWCLwFZhN8topwxY3IeJSg== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedvtddrfedugdejfecutefuodetggdotefrodftvf curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu uegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmdenuc fjughrpeffhffvuffkfhggtggugfgjsehtkeertddttdejnecuhfhrohhmpefuthgvphhh vghnucfirhgvghhorhgrthhtohcuoeguvghvsehsghhrvghgohhrrghtthhordhmvgeqne cuggftrfgrthhtvghrnhepveefgeefheegjedvudelkedtkeeiieegffejvdeiieejveff veektdejgfetgffgnecuffhomhgrihhnpehgihhthhhusgdrtghomhdprghgvgdqvghntg hrhihpthhiohhnrdhorhhgnecuvehluhhsthgvrhfuihiivgeptdenucfrrghrrghmpehm rghilhhfrhhomhepuggvvhesshhgrhgvghhorhgrthhtohdrmhgv X-ME-Proxy: Received: by mail.messagingengine.com (Postfix) with ESMTPA; Tue, 20 Jul 2021 00:10:42 -0400 (EDT) Date: Tue, 20 Jul 2021 14:10:38 +1000 From: Stephen Gregoratto To: Ingo Schwarze Cc: Stephen Gregoratto , discuss@mandoc.bsd.lv Subject: Re: mdoc synopsis style for more than one mandatory, mutually exclusive options? Message-ID: <20210720041038.3k5pt4q2r4lzlhec@BlackBox> Mail-Followup-To: Ingo Schwarze , Stephen Gregoratto , discuss@mandoc.bsd.lv References: <20210719224854.hrmf3ez2oynitfe3@BlackBox> <20210720003457.GB7771@athene.usta.de> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <20210720003457.GB7771@athene.usta.de> 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