Reserve certain options for certain functions #71

New Issue

Open

opened 2024-02-20 17:57:01 +00:00 by trinity · 3 comments

trinity commented

2024-02-20 17:57:01 +00:00

Owner

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.

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.

trinity added the

enhancement

label 2024-02-20 17:57:01 +00:00

emma commented

2024-02-22 00:40:59 +00:00

Owner

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 22:36:15 +00:00

Author

Owner

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-24 06:27:05 +00:00

Owner

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.