bdrewery
commented
2 years ago I like where you are going with this. The current naming scheme is a disaster of inconsistency and confusing. Maybe "flags" instead of "options".
Do you know the mdoc manpage syntax? It's easier to learn than you might think. man mdoc for reference. Then you can modify a manpage and do man path/to/file.1 to render it. The only weird gotcha that I can't explain is that any sentence ending in a period (.) should be followed by a newline.
Otherwise someone might find time to work on this, but I encourage you to give it a try.
grahamperrin
Prerequisites
Hi there,
Thank you for developing poudriere!
Here are my suggestions for the poudriere man-pages, as copied from my message on the FreeBSD forum: make.conf for poudriere: confusion
Because it doesn't seem possible to produce colored text here, please refer to my message at the FreeBSD forum if you wish to see the colored text.
I realise that my remark about the naming convention of the command options (as used in poudriere-options(8)), more specifically replacing it with another term instead of that command (for example useopts) probably has backwards compatibilty issues.
Kind regards, Eric
<hr ->
At poudriere-options(8) there is a part that is mentioned in the section SYNOPSIS: [poudriere-options] but, it is not described in that man-page (see ?-1, in the image above of poudriere-options(8)).
Also, you have to realise that at the SYNOPSIS section of poudriere-options(8) the string options is not a placeholder but an actual string that has to be typed in literally. This is because poudriere-options(8) is an incarnation of the general poudriere(8) format for one specific command, namely the options command as specified at poudriere(8) in its SYNOPSIS section by the placeholder command. Compare that with pkg(8), there the placeholder in the SYNOPSIS section is designated in a much cleaner way by: \
IMO, it can also be unclear that in the NAME section of poudriere-options(8) the following string is written as: poudriere-options This is not the actual command that is to be typed in. Compare for example:
Because of the (complex) syntax of poudriere(8), its man-pages are split into several man-pages and you have to use a unique name for a man-page; however, this gives rise to ?-2 ambiguity in the image of poudriere-options(8)(*) above. pkg(8) faces similar difficulties and is also split up. That might have something to do with the naming conventions or limitations of man-pages.
Firstly, however, note that with pkg(8) there is a subtle but significant difference. pkg(8) is also split up into seperate man-pages, for example for the incarnation pkg‑info(8) (as mentioned in the SEE ALSO section of pkg(8)). The man-page of pkg‑info(8) is tagged by the string "pkg-info" but, at the NAME section of pkg‑info(8) it correctly uses the string pkg info (note: no dash between the two words), which string (=pkg info) is also used in that exact same way in all other sections.
Secondly, compare with pkg-static at the NAME section of pkg(8) as an alternative name. pkg-static functions as an exact synonym of pkg. Here the dash between the two words is mandatory.
At the SYNOPSIS section of poudriere(8) there is a part poudriere-options These options are not described by a similar name in subsequent sections. They appear to be described in the section GLOBAL OPTIONS (see ?-3, in the image of poudriere(8) above). If this is the case, why are are such different terms used to indicate the same item?
If I understand Jose's description correctly, at poudriere-options(8) in the section SYNOPSIS the string [poudriere-options] (note: the presence of the two "[" & "]") is not described in poudriere-options(8) but is described in the section GLOBAL OPTIONS of poudriere(8). If this is indeed the case, I do not find that self-evident. The name change into "GLOBAL OPTIONS" does not help. I have not seen any other man-pages where you have to cross reference to find a description of a certain item for which there is not an expliciet cross-reference present. I may be wrong; if so, I'd appreciate examples where that is the case.
It seems that the use of the word argument(s) of a command is not in line with the usage elsewhere in man-pages. With the command poudriere of poudriere(8) the first (optional) argument is [poudriere-options]. The second argument is command. In the COMMANDS section of poudriere(8) this is described as:
This could be reworded as: \ must be one of the following list:
This also begs the question if, instead of the command/argument options, something like useopts or portoptions would not have been a more apropriate term, not clashing with the terminology option(s) used pervasively in man-pages.
<hr ->
Perhaps this (differences highlighted) is clearer:
<hr ->
Added: (*) The sub-man-pages of poudriere (in the SEE ALSO section of poudriere(8) ) are all consistently documented: they have the dash in their denotations in the NAME section, while the actual command has not (inconsistent with pkg‑info(8) ).
Most sub-man-pages of poudriere have in their SYNOPSIS section a [poudriere-options] denotation; those that have probably all refer to the section GLOBAL OPTIONS of poudriere(8).