Prefered manpage idioms?

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

Prefered manpage idioms?

Stephen Gregoratto
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:

1. Manpage

Is it:
  man page
  man-page
  manpage
  reference
  manual
  UNIX™ Programmers Manual
    ...on second thought, maybe not

2. Standard output

Is it:
  Print to standard output/error
    tee(1)
  Print to the standard output/error
    cat(1), echo(1)
  Print to stdout/stderr
    bzcat(1)

Bonus Round:
  Print to ...
  Write to ...
  Print on ...
    readlink(1)

3. Program arguments

Is it:
  Argument
    echo(1)
  Operand
    printf(1), also echo(1)?
--
Stephen Gregoratto
PGP: 3FC6 3D0E 2801 C348 1C44 2D34 A80C 0F8E 8BAB EC8B

Reply | Threaded
Open this post in threaded view
|

Re: Prefered manpage idioms?

Andreas Kusalananda Kähäri-4
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



--
Kusalananda
Sweden

Reply | Threaded
Open this post in threaded view
|

Re: Prefered manpage idioms?

Jason McIntyre-2
In reply to this post by Stephen Gregoratto
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:
>

hi.

> 1. Manpage
>
> Is it:
>   man page
>   man-page
>   manpage
>   reference
>   manual
>   UNIX??? Programmers Manual
>     ...on second thought, maybe not
>

i think any of man page, manual page, or manual is fine.

> 2. Standard output
>
> Is it:
>   Print to standard output/error
>     tee(1)
>   Print to the standard output/error
>     cat(1), echo(1)
>   Print to stdout/stderr
>     bzcat(1)
>

these are all fine, i think.

> Bonus Round:
>   Print to ...
>   Write to ...
>   Print on ...
>     readlink(1)
>
> 3. Program arguments
>
> Is it:
>   Argument
>     echo(1)
>   Operand
>     printf(1), also echo(1)?

also fine.

i think we just have to accept that there's more than one way to write
things. we try to keep things consistent where it makes sense, but i
think we need to allow for some variation too.

jmc

Reply | Threaded
Open this post in threaded view
|

Re: Prefered manpage idioms?

Marc Espie-2
On Thu, May 30, 2019 at 07:29:55PM +0100, Jason McIntyre wrote:

> i think any of man page, manual page, or manual is fine.
>
> > 2. Standard output
> >
> > Is it:
> >   Print to standard output/error
> >     tee(1)
> >   Print to the standard output/error
> >     cat(1), echo(1)
> >   Print to stdout/stderr
> >     bzcat(1)
> >
>
> these are all fine, i think.

IMO, these are highly contextual.

"End user commands" will tend to say standard output or error.

stdout and stderr *are* programmer's idioms, so I would be surprised
to see them in less technical commands.

Reply | Threaded
Open this post in threaded view
|

Re: Prefered manpage idioms?

Jason McIntyre-2
On Thu, May 30, 2019 at 09:09:58PM +0200, Marc Espie wrote:

> On Thu, May 30, 2019 at 07:29:55PM +0100, Jason McIntyre wrote:
> > i think any of man page, manual page, or manual is fine.
> >
> > > 2. Standard output
> > >
> > > Is it:
> > >   Print to standard output/error
> > >     tee(1)
> > >   Print to the standard output/error
> > >     cat(1), echo(1)
> > >   Print to stdout/stderr
> > >     bzcat(1)
> > >
> >
> > these are all fine, i think.
>
> IMO, these are highly contextual.
>

agreed.

> "End user commands" will tend to say standard output or error.
>
> stdout and stderr *are* programmer's idioms, so I would be surprised
> to see them in less technical commands.
>

i'm pretty sure you'll find stdout/stderr scattered all over userland
docs. the post itself quoted bzcat.

i don;t think we can (or should) attempt to police this.

jmc

Reply | Threaded
Open this post in threaded view
|

Re: Prefered manpage idioms?

Theo de Raadt-2
Jason McIntyre <[hidden email]> wrote:

> i don;t think we can (or should) attempt to police this.

Ouch, that typo really triggered my ADD, let's hope you don't make
similar errors in our manual pages.

Reply | Threaded
Open this post in threaded view
|

Re: Prefered manpage idioms?

Marc Espie-2
On Thu, May 30, 2019 at 01:37:41PM -0600, Theo de Raadt wrote:
> Jason McIntyre <[hidden email]> wrote:
>
> > i don;t think we can (or should) attempt to police this.
>
> Ouch, that typo really triggered my ADD, let's hope you don't make
> similar errors in our manual pages.

Yep, let's stick to seperate or implimentation as admissible typos.

Reply | Threaded
Open this post in threaded view
|

Re: Prefered manpage idioms?

Ingo Schwarze
In reply to this post by Andreas Kusalananda Kähäri-4
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