@ferdnyc commented on this pull request.
> +Typographic conventions:
+- Put option aliases on separate lines
+- Put option arguments with pre-determined values into <> (see below)
+
+*-d*
+*--do-this*
+ Do Y instead of default action.
+
+*-o* _ARG_,
+*--output*=_ARG_
+ Use file _ARG_ for output.
+
+*--format*=<*aa*|*bb*>
+ Use format *aa* or *bb* for output.
+
+*--compress*=<_method_>
\*nod\* There are two conventions that I find pretty expressive, in different
contexts:
### The placeholder is treated as a _type_
...At least to the extent possible, and possibly working in concert with the
option name to fully describe the parameter. e.g.:
* `--comment=STRING`
* `--fps=FLOAT` or `--fps=FRACTION` or `--fps=RATIO` (which probably all
warrant some additional detail regarding syntax; even `FLOAT` is only really
self-evident to programmers, not lay users)
* `--artist=STRING`, `--title=STRING`, `--release-year=YEAR`, `--track=NUMBER`,
`--length=TIME` (where only `TIME` requires further documentation of its syntax)
That style is handy because, if the argument name is sufficiently expressive,
you often don't need any additional explanation. (All of the `STRING`s, the
`NUMBER`, and the `YEAR` fall into that category, when coupled with their
option name.)
### The placeholder names the symbol that will hold the assigned value
It may implicitly give some hints as to value-type, as well. like:
* `--prefix=PREFIX`
* `--libdir=LIBDIR`
* `--bindir=BINDIR`
* `-c CONFIG_FILE` or `--config=CONFIG_FILE`
* `-o OUTPUT_DIR` or `--output=OUTPUT_DIR`
* etc.
I have no evidence for this, but I strongly suspect this convention was either
started or championed by autoconf. It features heavily in `configure`-type
scripting, and there's a nice symmetry because typically whatever value is
supplied for each `PLACEHOLDER` will end up getting set as a `#define` of that
same name, in the build system and/or `config.h`. (So, using all-caps isn't
just an argument convention, but a more fundamental programming convention
looping back around and influencing the argument style.)
### Meson
Interestingly, in both its man page and `--help` output Meson uses the second
placeholder form, coupled with a curly-brace syntax for "enum" type arguments.
It seems to borrow from Bourne Shell expansions (`ls
rpm/{src,lib,plugins,docs}/`) and/or Python sets:
* **`--cmake-prefix-path CMAKE_PREFIX_PATH`**
* **`--install-umask INSTALL_UMASK`**
* **`--optimization {plain,0,g,1,2,3,s}`**
* **`--default-library {shared,static,both}`**
Always bolded, never underlined(/italics) -- they do use underlines in the man
page, but only for positional args, never for named options. So it'll be:
<pre><code>
<b>meson wrap <</b> <i>command</i> <b>> [</b> <i>options</i> <b>]</b>
<b>Commands:</b>
<b>list</b> list all available projects
<b>search</b> search projects by name
<b>options:</b>
<b>--workdir WORKDIR, -w WORKDIR</b>
<b>--dump-format {sh,export,vscode}</b>
</code></pre>
### CMake
CMake, OTOH, mixes both in its help output. `cmake --help` includes this:
```text
--log-level=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE>
= Set the verbosity of messages from CMake
files. --loglevel is also accepted for
backward compatibility reasons.
```
while `cmake --build` (which displays its help, with no other arguments)
includes this:
```text
--resolve-package-references={on|only|off}
= Restore/resolve package references during build.
```
In the man page, those become:
<pre><code>
<b>--log-level=<level></b>
Set the log <level>.
The <i>message()</i> command will only output messages of the specified
log level or higher. The valid log levels are <b>ERROR</b>,
<b>WARNING</b>,
<b>NOTICE</b>, <b>STATUS</b> (default), <b>VERBOSE</b>, <b>DEBUG</b>, or
<b>TRACE</b>.
<b>--resolve-package-references=<value></b>
Added in version 3.23.
Resolve remote package references from external package managers
(e.g. NuGet) before build. When <b><value></b> is set to
<b>on</b> (default),
packages will be restored before building a target. When
<b><value></b>
is set to <b>only</b>, the packages will be restored, but no build will
be performed. When <b><value></b> is set to <b>off</b>, no
packages will be
restored.
</code></pre>
The `--help` formatting seems very inconsistent, and probably reflects the fact
that the two options were created well over a decade apart (possibly two).
--
Reply to this email directly or view it on GitHub:
https://github.com/rpm-software-management/rpm/pull/3639#discussion_r2003590133
You are receiving this because you are subscribed to this thread.
Message ID: <rpm-software-management/rpm/pull/3639/review/[email protected]>_______________________________________________
Rpm-maint mailing list
[email protected]
https://lists.rpm.org/mailman/listinfo/rpm-maint
