Requesting guidance - correct use of backtick formatting in manpage titles/links

Question

This question makes two references to the veth(4) manpage.

• The first one links to veth(4) but does not use inline formatting for the manpage title.

• The second one does not link, but does use inline formatting for veth(4).

The impression I generally get from unix.SE is that inline backtick formatting should be used for manpage titles like veth(4), and that one instance of the title should if possible link to an online copy of the manpage, but I could be wrong.

Can you clarify:

1. Whether backtick formatting should be used for manpage titles, and
2. How many instances of the manpage title in a given post should link to a copy of the manpage?

Answer 1

As one of the site's frequent editors, I can't say that I remember guidance that's this specific. Off the cuff, my personal preferences would be:

1. Links for manpage references should not use code formatting, although I wouldn't bother editing posts just to remove that formatting.
2. I would prefer that the first manpage instance (per command) be a link and have the subsequent ones just refer to "the man page". Having multiple links would make me wonder if those links went to different locations, and wouldn't add any value if they linked to the same location.

Answer 2

Another personal preference datapoint:

I use code formatting in two ways:

1. When multiple sections might have the manpage and there is a high chance of confusion, I write out the man command, and I format the entire command: "See man 2 readlink for details ...".
2. When it's only in one section, or the default section is likely to be the same for everyone, I only mention the manpage name, and format just the name: "Check the sudo manpage ...".

I personally prefer to avoid using the name(section) notation, as it is objectively less useful than spelling out the command. Not all man commands support man foo(N) (man-db man does, but macOS man doesn't, for example). But man N foo is pretty much universal. Even where it is supported, you will pretty much always have to quote foo(N): man 'foo(N)', as ( and ) are metacharacters in many shells and you'll get a syntax error otherwise.

And with online manpages, while Debian's manpage repository or FreeBSD's support foo(N), Ubuntu's manpage repository supports only foo.N.