@pmatilai commented on this pull request.
> +*rpmcmd* [options] [_ARGUMENT_] ...
+
+# DESCRIPTION
+Describe what *rpmcmd* command does in detail.
+
+Put distinct operational modes to their own subsections.
+
+Typographic conventions:
+- Use bold for literal values such as command name and options:
+*cmd* does X, with option *--do-this* does Y instead
+- Use underline uppercase to denote user arguments: _ARGUMENT_
+- Use underline for literal file names: _hello-1.0-1.noarch.rpm_
+- Put an empty line before a new section/option/etc
+- Put text immediately below a section/option/etc (ie without an empty line)
+- Put optional elements into [] brackets
+- Put one-of-many choices into <val1|val2|val3> lists
Good, I was kinda counting on you to spot the curly brace elephant :grin: I
actually find the curly braces an alien notation for indicating mandatory
choice. Well okay, IIRC we only ever use them to indicate short/long aliases of
the same mandatory options, and because a mandatory option is not really an
option :sweat_smile: Maybe we should just call it a *mode* indicator where
relevant, because that could actually be helpful (and offer an excuse to just
let them be...)
For optional choice, `[--foo|--bar]` is correct, although that seems pretty
rare. But neither of these are quite what I intended, I just didn't describe it
very well. There's an example of it further down though:
```
--compress=<gzip|zstd>
```
I don't quite know where it comes from, but I just "know" `<>` is how deity
intended mandatory to be indicated :smile: This goes way, way back. So far
back, I think it may have been something I learned at school. man-pages(7)
doesn't seem to know anything about it.
Looking around a bit, I see that used in eg curl and git-add man page to
indicate a mandatory option argument, eg `--output=<file>` style. Something
that gives me that warm fuzzy "this is proper" feeling :laughing:
Rpm man pages don't use <> for anything atm but it does seem useful to me as it
makes the mandatoryness really stand out, and allows indicating the different
variants like whether the argument is a one-from-many choice literal like above
or just a user-speficied arg eg that `--output=<file>` case.
--
Reply to this email directly or view it on GitHub:
https://github.com/rpm-software-management/rpm/pull/3639#discussion_r1984476723
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
