@dmnks commented on this pull request.
Some random nitpicks inline. Overall, LGTM and it's good to have some kind of
conventions. We can always improve them as we go.
> +*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
This is actually not what we do right now in existing man pages, we use curly
braces :sweat_smile:
That said, I think none of these should be used - because what if you wanted to
have an optional choice:
```
rpmcmd [--foo|--bar]
```
> +- 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
+Describe common options and in this section.
+
+Typographic conventions:
These seem to be just repeat the general conventions from above, except perhaps
the first one. Maybe drop them from the above list and keep it here?
> +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
Is this section meant to always be present and be called OPTIONS? (As in,
*general* options?)
> +Put options common to more than one mode into a subsection of its own.
+
+# ENVIRONMENT
+Describe environment variables affecting program execution.
+
+# EXIT STATUS
+Describe exit codes of the command.
+
+# EXAMPLES
+Add at least one example for each major functionality of the command.
+
+```
+rpmcmd --do-this package-1.0-1.noarch.rpm
+```
+
+# SEE ALSO
I think we should also have a FILES section somewhere (for config files and
such).
> +- 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
+Describe common options and in this section.
+
+Typographic conventions:
How about adding also:
```
- List both the long and short variant, in that order
```
--
Reply to this email directly or view it on GitHub:
https://github.com/rpm-software-management/rpm/pull/3639#pullrequestreview-2665011533
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
