style.mdoc: add subsection for cross-references

[mhorne]

Summary

In particular, to give advice on referencing man pages that are provided
by ports. The linked pages may not be present after a fresh install, so
it is useful to give the name of the port which provides it.

Codify the existing precedent for this.

[ziaee]

I really like this notation because it's so clear, but we should discuss this with @bapt, he said pkg categories are not stable and we shouldn't do this.

*Sigh* Phabricator on mobile cannot deselect accept revision once fat fingered, even after allegedly switching to the desktop site -.-

share/man/man5/style.mdoc.5

310

For this bullet point, I think this applies really to everything in this page. mdoc(7) is the spec, and this page is our style guide for applying it. If this isn't obvious, maybe we should refactor this to the second sentence at the top of the page?

[bapt]

origin is not a good way to reference a package, I know people are used to it, because at somepoint it was the only to get a unique name which reference a package, but it is not the case anymore, with flavors or even with subpackages.

Another issue pkg can actually come from 2 different path: ports-mgmt/pkg and ports-mgmt/pkg-devel.

[mhorne]

In D50330#1148832, @bapt wrote:

origin is not a good way to reference a package, I know people are used to it, because at somepoint it was the only to get a unique name which reference a package, but it is not the case anymore, with flavors or even with subpackages.

So what do you suggest instead, a specific package name?

As noted this is a reaction to a preexisting pattern in the src tree. Whatever style policy we define here should be forward-thinking, of course, but let us also be clear of the current reality.

Another issue pkg can actually come from 2 different path: ports-mgmt/pkg and ports-mgmt/pkg-devel.

The specific example cited here can be changed to some other common/well-known program e.g. gcc(1).

share/man/man5/style.mdoc.5

310

A general statement to this effect can be added near the top, sure. But the point here is to direct the reader to the relevant parts of that (long) page.

If you think this point is not useful at all, I will simply drop it.

[bapt]

I think we should just specify the package name and nothing more. so a user can do pkg search pkgname

[ziaee]

That introduces a regression in building from src :(