Rework pkg-set.8 #2076
Rework pkg-set.8 #2076
Conversation
- Reorganize synopsis to pair short and long options - Mark exclusive options as such - Add missing --vital synonym for -v - Reorder sections to pacify mandoc -T lint - Copyedit and fix markup throughout
|
Planning to go over all manual pages. Will mark as mergeable when done. |
|
Hey Pau Amma, thanks for working on the manual pages. I’d like to suggest dropping the long options from the synopsis entirely for readability. See #2027. This way it would also be less editing work for you. |
|
I'm not even sure if there is any useful outcome of just listing all possible options and arguments (especially optional ones) in the same place. Short options only are totally useless as they provide no information about what they do. Long options are, indeed, messy... So a format like |
| .Dt PKG-SET 8 | ||
| .Os | ||
| .Sh NAME | ||
| .Nm "pkg set" | ||
| .Nd modify information in the installed database | ||
| .Nd modify information in the installed packages database |
There was a problem hiding this comment.
| .Nd modify information in the installed packages database | |
| .Nd modify information in the installed package database |
| @@ -14,32 +14,23 @@ | |||
| .\" | |||
| .\" @(#)pkg.8 | |||
| .\" | |||
| .Dd November 18, 2016 | |||
| .Dd October 5, 2022 | |||
| .Dt PKG-SET 8 | |||
| .Os | |||
| .Sh NAME | |||
| .Nm "pkg set" | |||
There was a problem hiding this comment.
| .Nm "pkg set" | |
| .Nm pkg-set |
| This affects the operation of | ||
| .Xr pkg-autoremove 8 . | ||
| .It Fl a , Cm --all | ||
| .It Fl a , Fl -all |
| Match | ||
| .Ar pkg-name | ||
| as a regular expression according to the "modern" or "extended" syntax of | ||
| as a regular expression using the modern or extended syntax of |
There was a problem hiding this comment.
| as a regular expression using the modern or extended syntax of | |
| using an extended regular expression as documented in |
Extended regular expression is the standardized definition of this. "Modern" is vague and doesn't age well, and this syntax has existed longer than I've been alive.
| See | ||
| .Xr pkg.conf 5 | ||
| for further description. | ||
| .Bl -tag -width ".Ev CASE_SENSITIVE_MATCH" |
There was a problem hiding this comment.
| .Bl -tag -width ".Ev CASE_SENSITIVE_MATCH" | |
| .Bl -tag -width "CASE_SENSITIVE_MATCH" |
Using macros in list widths is an undefined behavior, which notably renders as -1 space in some implementations.
I really love moving sections into standard order! I think it makes it more predictable!
| .Sh FILES | ||
| See | ||
| .Xr pkg.conf 5 . | ||
| .Sh EXAMPLES | ||
| Change a package from automatic to non-automatic, which will prevent | ||
| Change a package from automatic to non-automatic, which will keep |
There was a problem hiding this comment.
No, prevent was better grammar.
| .Xr re_format 7 . | ||
| .It Fl v Ar 01 | ||
| .It Fl v Ar 0|1 , Fl -vital Ar 0|1 |
There was a problem hiding this comment.
In style.mdoc, we do say that that the preferred syntax for "x | y" is without a space, however the vast majority of the time we do use a space, and so does the rest of the industry. The other day I even found this syntax with a space describing sauces available with chicken wings.
| matching against | ||
| .Ar pkg-name | ||
| case insensitive. | ||
| case-insensitive. | ||
| This is the default, unless modified by setting | ||
| .Ev CASE_SENSITIVE_MATCH | ||
| to true in | ||
| .Pa pkg.conf . |
There was a problem hiding this comment.
| .Pa pkg.conf . | |
| .Xr pkg.conf 5 . |
I think xrefs take highest priority when there are multiple appropriate macros since they're clickable in most implementations.
Reorganize synopsis to pair short and long options
Mark exclusive options as such
Add missing --vital synonym for -v
Reorder sections to pacify mandoc -T lint
Copyedit and fix markup throughout