Links in man pages don't always work

[magikid]

The links in the man pages to specific sections don't always work. Specifically, when the section being linked to is on a different man page, the link doesn't work.

For example, under the DESCRIPTION section of the rcrc.5.html page is a link to EXCLUDE_PATTERN which should point to the EXCLUDE_PATTERN section of the lsrc(1) page but instead it is linking to the EXCLUDE_PATTERN section on the rcrc page which doesn't exist.

[magikid]

After reading through mandoc documentation for Xr, it doesn't seem possible to use that macro to link the pages.

It may be possible through the Lk macro since that generates links to arbitrary pages but I can't get mandoc to generate reasonable ids for the links. So far the only link ids I can get mandoc to generate look like x4449524543544f5259204c41594f5554 for the section labeled EXCLUDE_PATTERN.

[mike-burns]

This might require patches to the mandoc HTML generator. Something around here, I suspect:

https://github.com/openbsd/src/blob/a44f9822a98f5f92d75e4231acd17435c1f03729/usr.bin/mandoc/mdoc_html.c#L919

Or it might need a new extension to mandoc. It does look like I'm violating .Sx already: "Reference a section or subsection in the same manual page" (emphasis mine).

[mat-m]

@mike-burns : so a quick fix is to replace all .Sx out-of-page links with Emphasis on subsection and .Xr on page ? Something like

• Phrase all links to other pages' subsections with see command, SECTION structure
• And update format so "see lsrc(1), EXCLUDE PATTERN" will give

see 
.Xr lsrc 1 ,
.Em EXCLUDE PATTERN

Lk is for external URLs in man pages. I would prefer an upgrade of Xr (Cross-Ref) to support a third parameter for the subsection of the page.

[mike-burns]

@mat-m I like that use of .Em. That makes sense to me.