@dmnks 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
> Part of the problem here is the ambiguity between a template and a guideline
> doc.
Yep, that's exactly what I had in mind, thanks for putting that down to words
:smile:
> And, I'm not entirely convinced how this all should be presented, really.
Me neither but I'd say, simplicity is key. Mixing "template" with "guidelines"
in one man page is a nice minimal way to provide a starting point for writing
man pages.
> The overall issue is that we have these subcommand like modes in pretty much
> all our commands, and that just doesn't fit the general man-page format that
> well. 🤔
And yep, this is a good point. Maybe it makes sense to clarify *that* (e.g.
have a separate section for MODES).
--
Reply to this email directly or view it on GitHub:
https://github.com/rpm-software-management/rpm/pull/3639#discussion_r1984781239
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
