Reserve -h #71

New Issue

trinity · 2024-02-20T10:57:01-07:00

trinity commented

2024-02-20 10:57:01 -07:00

-h should always be an invalid command that prints basic usage information.

I used to think this, but I see now I was wrong:

There are a number of conventions I think we should explicate or establish:

-0 ("zero") sets the delimiter to the nul byte ('\0'), in applicable programs

-! (boolean Not) negates the function of the program, in applicable programs

-d("delimiter") sets an arbitrary delimiter, in applicable programs

-f ("force") forces the program's function, rather than warning the user when they may need to be particularly mindful

-h ("help") always shows the program usage synopsis

-i ("input") sets a program input, in applicable programs

-o ("output") sets a program output, in applicable programs

-q ("quiet") silences diagnostic messages, in applicable programs. It can be used multiple times (e.g. "-qq") to indicate multiple levels of silence.

-v ("verbose") makes the program output extra diagnostic messages, in applicable programs. It can be used multiple times (e.g. "-vv") to indicate multiple levels of verbosity.

-w ("whitespace" or "word") sets the delimiter used to any whitespace, in applicable programs.

Many of those options, as Emma says below, are entirely unnecessary, and the others are at best contextual.

`-h` should always be an invalid command that prints basic usage information. I used to think this, but I see now I was wrong: > There are a number of conventions I think we should explicate or establish: > > - `-0` ("zero") sets the delimiter to the nul byte (`'\0'`), in applicable programs > - `-!` (boolean Not) negates the function of the program, in applicable programs > - `-d`("delimiter") sets an arbitrary delimiter, in applicable programs > - `-f` ("force") forces the program's function, rather than warning the user when they may need to be particularly mindful > - `-h` ("help") always shows the program usage synopsis > - `-i` ("input") sets a program input, in applicable programs > - `-o` ("output") sets a program output, in applicable programs > - `-q` ("quiet") silences diagnostic messages, in applicable programs. It can be used multiple times (e.g. `"-qq"`) to indicate multiple levels of silence. > - `-v` ("verbose") makes the program output extra diagnostic messages, in applicable programs. It can be used multiple times (e.g. `"-vv"`) to indicate multiple levels of verbosity. > - `-w` ("whitespace" or "word") sets the delimiter used to any whitespace, in applicable programs. Many of those options, as Emma says below, are entirely unnecessary, and the others are at best contextual.

trinity added the

enhancement

label 2024-02-20 10:57:01 -07:00

emma commented

2024-02-21 17:40:59 -07:00

I’m not sure I’m a fan of this. I think we should aim for consistency but we can’t account for all tools, right?

I also think it would be okay to use -h for something if it made sense for the option.

I’m not sure I’m a fan of this. I think we should aim for consistency but we can’t account for all tools, right? I also think it would be okay to use `-h` for something if it made sense for the option.

trinity commented

2024-02-22 15:36:15 -07:00

They're less prescription and more suggestion; certainly exceptions can and will exist, though I do think that -h should only print the program usage. There should be a known incorrect usage for the utilities so that someone can (faster than a manual lookup) get a refresher on what options can be used with a given utility.

"Reserve" was a strong word that does not quite match my meaning; "establishing conventions" was a better expression. When justified unconventionality is perfectly fine. The idea is to be consistent enough to give the user an intuition for how our tools are used and make them more confident in using utilities for the first time.

They're less prescription and more suggestion; certainly exceptions can and will exist, though I do think that `-h` should *only* print the program usage. There should be a known incorrect usage for the utilities so that someone can (faster than a manual lookup) get a refresher on what options can be used with a given utility. "Reserve" was a strong word that does not quite match my meaning; "establishing conventions" was a better expression. When justified unconventionality is perfectly fine. The idea is to be consistent enough to give the user an intuition for how our tools are used and make them more confident in using utilities for the first time.

emma commented

2024-02-23 23:27:05 -07:00

I don’t know that we should formalize this, but it would make sense to always be aware of the conventions we set. We could probably add this sentiment to CONTRIBUTING.

emma commented

2024-12-16 15:46:02 -07:00

Since this was made, verbosity and debug level options (-d, -q, -v) have been dropped from dj(1), and I believe that this functionality is not necessary in system utilities: they should simply output all available information to stderr (there will not be much in simple programs like this).

Since this was made, verbosity and debug level options (`-d`, `-q`, `-v`) have been dropped from `dj(1)`, and I believe that this functionality is not necessary in system utilities: they should simply output all available information to stderr (there will not be much in simple programs like this).

emma commented

2024-12-16 15:46:39 -07:00

-r would be the reversing-functionality flag I would grok the best. -! is weird and I have never seen it before.

`-r` would be the reversing-functionality flag I would grok the best. `-!` is weird and I have never seen it before.

trinity commented

2025-03-21 14:40:59 -06:00

I've changed my mind. -h should never be used, and that's my only opinion on the matter - except, also, that programs should take advice from the design of other programs.

I've changed my mind. `-h` should never be used, and that's my only opinion on the matter - except, also, that programs should take advice from the design of other programs.

trinity changed title from ~~Reserve certain options for certain functions~~ to Reserve `-h`

2025-03-21 14:43:32 -06:00

emma commented

2025-03-26 08:32:43 -06:00

Strong agree.

Sign in to join this conversation.