Hi, while these technicalities do exist in POSIX, it is better if understanding a manual page does not require paying attentions to them. In my opinion, the idiom that is simplest too understand is just
the .Ar foo argument and the .Fl x option and then it is usually obvious from the context (from the item head in an option list or from the SYNOPSIS) whether "foo" is an option-argument or an operand. In the unusual case where confusion between option-arguments and operands is likely to arise and to cause users to construct a command incorrectly, using the term "option-argument" is probably sufficient to make it clear that the argument cannot be given without the option, because the term is somewhat self-explanatory. On the other hand, merely talking about an "operand" when the misconception could arise that the argument is an option-argument is probably not sufficient because the official term is somewhat non-obvious. Such (rare) cases likely need a more explicit wording, but that depends on the individual situation. That said, i agree with Jason that there is no need to change existing uses of "operand" (like in echo(1)) or to complain when people use the term in a manual page, even though i probably wouldn't use it. Yours, Ingo Andreas Kusalananda Kaehaeri wrote on Thu, May 30, 2019 at 02:32:00PM +0200: > On Thu, May 30, 2019 at 10:16:12PM +1000, Stephen Gregoratto wrote: >> When I'm writing new manpages, I like to draw inspiration from the >> documentation of similar programs. The problem is that many manpages >> have different ways of saying the same thing, probably due to their >> authors and time period they were written in. >> >> So, I'd like to ask what your preferred choice is of the following >> common idioms I keep finding: >[cut] >> 3. Program arguments >> >> Is it: >> Argument >> echo(1) >> Operand >> printf(1), also echo(1)? > An argument to a command can be one of three things: > > 1. An option > 2. An option-argument > 3. An operand > > An option is an argument that starts with a dash. An option-argument is > an argument to an option that takes an argument. An operand is an > argument that is not an option or an option-argument. > > Example: > > man -M path ls > > * -M is an option > * path is an option-argument to the -M option > * ls is an operand since it's neither an option nor an option-argument. > > POSIX: > > Argument: "In the shell command language, a parameter passed to a > utility as the equivalent of a single string in the argv array created > by one of the exec functions. An argument is one of the options, > option-arguments, or operands following the command name." > > Option: "An argument to a command that is generally used to specify > changes in the utility's default behavior." > > Option-argument: "A parameter that follows certain options. In some > cases an option-argument is included within the same argument string as > the option-in most cases it is the next argument." > > Operand: "An argument to a command that is generally used as an object > supplying information to a utility necessary to complete its processing. > Operands generally follow the options in a command line." > > > https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html
