I'm not completely sure about .It Va, but the Va macro is not documented in mandoc(7) and only appears in some openbsd mandoc.samples man-page which doesn't seem to be connected to their or our build, where it's referenced as a variable.
.Ql also isn't documented in mandoc(7), however it's a quoted literal according to groff_mdoc(7) from textproc/groff, so I think it's fine.

You also need to attach an actual reviewer, as I'm just a stand-in. ;)

share/man/man7/ports.7
395	Should be .It Va
397	Should also be .It Va
401	Should also be .It Va

LGTM!

Just a note for your consideration: I wonder if we should mention there, that people often use set SU_CMD to use sudo (I do at least):

.if exists(/usr/local/bin/sudo)
SU_CMD= /usr/local/bin/sudo -E sh -c
.endif

This revision is now accepted and ready to land.Jun 26 2020, 9:04 PM

0mp added inline comments.Jun 26 2020, 9:05 PM

share/man/man7/ports.7
395	Actually, `It` is not necessary here. `It` is for list items.

What I did is I think consistent with the rest of the file, for example

.It Cm fetch
Fetch all of the files needed to build this port from the sites
listed in
.Va MASTER_SITES
and
.Va PATCH_SITES .
See
.Va FETCH_CMD , MASTER_SITE_OVERRIDE
and
.Va MASTER_SITE_BACKUP .

Well, an actual doc persons opinion is more valuable than mine, so I defer :)

In D25433#562467, @debdrup wrote:

I'm not completely sure about .It Va, but the Va macro is not documented in mandoc(7) and only appears in some openbsd mandoc.samples man-page which doesn't seem to be connected to their or our build, where it's referenced as a variable.
.Ql also isn't documented in mandoc(7), however it's a quoted literal according to groff_mdoc(7) from textproc/groff, so I think it's fine.

You also need to attach an actual reviewer, as I'm just a stand-in. ;)

Va is defined in mdoc(7)! So is Ql :)

In D25433#562475, @0mp wrote:
Just a note for your consideration: I wonder if we should mention there, that people often use set SU_CMD to use sudo (I do at least):
.if exists(/usr/local/bin/sudo)
SU_CMD= /usr/local/bin/sudo -E sh -c
.endif

As we all know, sudo is a port itself and not necessary to utilize SU_CMD (as portmaster.8 seems to claim, the way I read it). I'd omit sudo from ports.7 entirely on the basis that it doesn't have any advantage over su(1), but that would be incorrect - it's at least more convenient to not have to type in the password all the time. I could mention it here, but I think there are not too many people who use su(1) on a daily basis and not know about sudo. If they know, they will easily decide whether to use su or sudo.

In D25433#562495, @pstef wrote:
In D25433#562475, @0mp wrote:
Just a note for your consideration: I wonder if we should mention there, that people often use set SU_CMD to use sudo (I do at least):
.if exists(/usr/local/bin/sudo)
SU_CMD= /usr/local/bin/sudo -E sh -c
.endif
As we all know, sudo is a port itself and not necessary to utilize SU_CMD (as portmaster.8 seems to claim, the way I read it). I'd omit sudo from ports.7 entirely on the basis that it doesn't have any advantage over su(1), but that would be incorrect - it's at least more convenient to not have to type in the password all the time. I could mention it here, but I think there are not too many people who use su(1) on a daily basis and not know about sudo. If they know, they will easily decide whether to use su or sudo.