diff --git a/share/man/man5/style.mdoc.5 b/share/man/man5/style.mdoc.5 --- a/share/man/man5/style.mdoc.5 +++ b/share/man/man5/style.mdoc.5 @@ -304,6 +304,44 @@ .Va critical_filesystems_ Ns Ar type .Ed .El +.Ss Cross-References +.Bl -dash -width "" +.It +For general information on references between man pages consult the +.Xr mdoc 7 +page; +specifically, the paragraphs describing +.Sq \&.Xr +and +.Sx SEE ALSO . +.It +It is sometimes necessary to reference programs, libraries, or other +documentation from outside of the +.Fx +base system; that is, man pages provided by +.Xr ports 7 . +Such cross-references should be formatted as: +.Bd -literal -offset indent +\&.Xr pkg 8 Pq Pa ports/ports-mgmt/pkg +.Ed +.Pp +which renders as: +.Bd -filled -offset indent +.Xr pkg 8 Pq Pa ports/port-mgmt/pkg +.Ed +.Pp +This way, the user is provided a link to relevant and potentially useful +information, but they will not be confused when +.Xr man 1 +informs them that the page cannot be found. +In fact, they will know exactly where to obtain it. +.Pp +If a page is referenced several times in this manner, it is acceptable to +omit the port's path for subsequent instances. +The complete reference must be provided with the first occurance and in the +.Sx SEE ALSO +section. +.El .Sh SEE ALSO .Xr man 1 , .Xr mandoc 1 ,