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.0 required=5.0 tests=UNPARSEABLE_RELAY autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 20177 invoked from network); 20 Jul 2021 00:35:09 -0000 Received: from bsd.lv (HELO mandoc.bsd.lv) (66.111.2.12) by inbox.vuxu.org with ESMTPUTF8; 20 Jul 2021 00:35:09 -0000 Received: from fantadrom.bsd.lv (localhost [127.0.0.1]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 9dad7341 for ; Mon, 19 Jul 2021 19:35:03 -0500 (EST) Received: from scc-mailout-kit-02.scc.kit.edu (scc-mailout-kit-02.scc.kit.edu [129.13.231.82]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id a5c2166d for ; Mon, 19 Jul 2021 19:35:02 -0500 (EST) Received: from hekate.asta.kit.edu ([141.3.145.153] helo=hekate.usta.de) by scc-mailout-kit-02.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1m5diu-0007Zc-Bk; Tue, 20 Jul 2021 02:35:01 +0200 Received: from donnerwolke.asta.kit.edu ([141.3.145.61] helo=donnerwolke.usta.de) by hekate.usta.de with esmtp (Exim 4.92.2) (envelope-from ) id 1m5dis-0008D5-1e; Tue, 20 Jul 2021 02:34:58 +0200 Received: from athene.asta.kit.edu ([141.3.145.60] helo=athene.usta.de) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1m5dir-0001IU-Ty; Tue, 20 Jul 2021 02:34:58 +0200 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id ca45e6fb; Tue, 20 Jul 2021 02:34:57 +0200 (CEST) Date: Tue, 20 Jul 2021 02:34:57 +0200 From: Ingo Schwarze To: Stephen Gregoratto Cc: discuss@mandoc.bsd.lv Subject: Re: mdoc synopsis style for more than one mandatory, mutually exclusive options? Message-ID: <20210720003457.GB7771@athene.usta.de> References: <20210719224854.hrmf3ez2oynitfe3@BlackBox> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20210719224854.hrmf3ez2oynitfe3@BlackBox> User-Agent: Mutt/1.12.2 (2019-09-21) 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