Fix usage text #126

New Issue

2024-06-26T15:59:19-06:00

emma commented

2024-06-26 15:59:19 -06:00

The usage text in utilities and manpages is all over the place and needs a sense of cohesiveness. So far, the CONDUCT file has specified the NetBSD coding standards as the Bonsai coding standards. This is a discussion thread on this issue.

	/*
	 * [...]
	 *
	 * Usage statements should look like the manual pages.
	 * Options w/o operands come first, in alphabetical order
	 * inside a single set of braces, upper case before lower case
	 * (AaBbCc...).  Next are options with operands, in the same
	 * order, each in braces.  Then required arguments in the
	 * order they are specified, followed by optional arguments in
	 * the order they are specified.  A bar (`|') separates
	 * either/or options/arguments, and multiple options/arguments
	 * which are specified together are placed in a single set of
	 * braces.
	 *
	 * [...]
	 *
	 * "usage: f [-aDde] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\n"
	 * "usage: f [-a | -b] [-c [-de] [-n number]]\n"
	 */

The usage text in utilities and manpages is all over the place and needs a sense of cohesiveness. So far, the CONDUCT file has specified the NetBSD coding standards as the Bonsai coding standards. This is a discussion thread on this issue. ``` /* * [...] * * Usage statements should look like the manual pages. * Options w/o operands come first, in alphabetical order * inside a single set of braces, upper case before lower case * (AaBbCc...). Next are options with operands, in the same * order, each in braces. Then required arguments in the * order they are specified, followed by optional arguments in * the order they are specified. A bar (`|') separates * either/or options/arguments, and multiple options/arguments * which are specified together are placed in a single set of * braces. * * [...] * * "usage: f [-aDde] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\n" * "usage: f [-a | -b] [-c [-de] [-n number]]\n" */ ```

emma added the bug question labels 2024-06-26 15:59:19 -06:00

emma pinned this 2024-06-26 15:59:28 -06:00

trinity commented

2024-06-28 09:20:03 -06:00

My usage text guidelines are as follows:

Mandatory positional arguments are noted with brackets like [description].
Optional positional arguments are noted with parens like (description).
For the purpose of notation here are no mandatory options, even when one of a selection of options must be specified.
Option arguments are usually not optional, so they follow the form (-n [argument]).

When you put it together you can get usages like Usage: util (-abc) (-d [arg]) [argument] (argument) that give you an idea of what your program invocation is missing without distracting with syntax.

I like the NetBSD guidelines but I have found these to be clearer.

My usage text guidelines are as follows: - Mandatory positional arguments are noted with brackets like `[description]`. - Optional positional arguments are noted with parens like `(description)`. - For the purpose of notation here are no mandatory options, even when one of a selection of options must be specified. - Option arguments are usually not optional, so they follow the form `(-n [argument])`. When you put it together you can get usages like `Usage: util (-abc) (-d [arg]) [argument] (argument)` that give you an idea of what your program invocation is missing without distracting with syntax. I like the NetBSD guidelines but I have found these to be clearer.

emma commented

2024-06-28 09:51:08 -06:00

I dislike the nested brackets; plus, they make it look like arguments are optional.

emma commented

2024-06-28 11:21:04 -06:00

NetBSD’s is very clear:
usage: f [-aDde] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\n

Yours is noisy when options have arguments and seem to imply that they are optional (since they are in brackets, though it’s not entirely clear):
usage: f (-aDde) (-b [b_arg]) (-m [m_arg]) [req1] [req2] (opt1 (opt2))\n

I like the way this looks, though:
usage: f (-aDde) (-b b_arg) (-m m_arg) req1 req2 (opt1 (opt2))\n

NetBSD’s is very clear: `usage: f [-aDde] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\n` Yours is noisy when options have arguments and seem to imply that they are optional (since they are in brackets, though it’s not entirely clear): `usage: f (-aDde) (-b [b_arg]) (-m [m_arg]) [req1] [req2] (opt1 (opt2))\n` I like the way this looks, though: `usage: f (-aDde) (-b b_arg) (-m m_arg) req1 req2 (opt1 (opt2))\n`

sashakoshka commented

2024-06-28 16:37:09 -06:00

It is a well established convention that square brackets mean something is optional. Breaking that would cause much confusion for users, especially if it isn't explained to them.

This is one of the many cases where the principle of least astonishment is very applicable.

It is a well established convention that square brackets mean something is optional. Breaking that would cause much confusion for users, especially if it isn't explained to them. This is one of the many cases where the principle of least astonishment is very applicable.

trinity commented

2024-06-28 18:27:53 -06:00

Count me in to NetBSD style.

emma closed this issue

2024-06-29 17:26:30 -06:00

emma unpinned this 2024-06-29 17:26:33 -06:00

trinity commented

2024-07-01 09:03:03 -06:00

I failed to elaborate on one of my thoughts; while parens are nice, l think deferring to NetBSD's judgement unmodified is wiser. Then we can simply refer people to their documentation for option syntax.

I still prefer my proposed option syntax but I think principle of least astonishment trumps my opinion. Also, NetBSD is a >30 year old project with impeccable code quality and one of the most polite and helpful development communities on the Internet.

I failed to elaborate on one of my thoughts; while parens are nice, l think deferring to NetBSD's judgement unmodified is wiser. Then we can simply refer people to their documentation for option syntax. I still prefer my proposed option syntax but I think principle of least astonishment trumps my opinion. Also, NetBSD is a >30 year old project with impeccable code quality and one of the most polite and helpful development communities on the Internet.

Sign in to join this conversation.

3 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: bonsai/harakit#126