@pmatilai commented on this pull request.
> +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
+- Do not emphasize separators like ",", "=", "[]", "|"
+
+When in doubt, consult *man-pages*(7).
+
+# OPTIONS
Poked around this and realized rpm(8) and rpmbuild(8) at least already follow a
relatively neat pattern here. We don't need to reinvent the wheel, maybe just
fine-tune a bit. The following assumes operational modes, where that's not the
case it's all simple anyhow and dont need these subsections:
The `DESCRIPTION` gives an overall description of what the command does and
deals with, and lists the available modes. (this is already the case)
The `# OPTIONS` section lists options that are common between two or more
modes, using subsections if needed. And then we have `# FOO MODE OPTIONS` to
separate from the more generic ones. For example the main rpm(8) page would
have:
```
# OPTIONS
## General options
...
## Select options
# INSTALL AND UPGRADE MODE OPTIONS
Describe the install mode invocation syntax and operation
- describe
- all
- the
- install
- options
# QUERY MODE OPTIONS
Describe the query mode operation and invocation
- describe
- all
- the
- query
- options
...
That's quite close to what we already have, the main difference is grouping the
non-mode options under the same OPTIONS umbrella and talking about MODE OPTIONS
for the rest. Thoughts?
--
Reply to this email directly or view it on GitHub:
https://github.com/rpm-software-management/rpm/pull/3639#discussion_r1984935858
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
