manpages should not render relative links

[juhp]

A follow on to #105

I was going to suggest adding --roff-no-rellinks, though I can't really think of situations where showing rellinks in manpages makes much sense: so I would argue the default behaviour should be not to render rellinks in roff output. But if you prefer to have it behind an option that is okay too.

See also https://github.com/kristapsdz/lowdown/issues/105#issuecomment-3551044425

with an example to reproduce the problem:

$ curl -s https://raw.githubusercontent.com/NixOS/nix/refs/heads/master/doc/manual/source/command-ref/nix-store.md | lowdown -T man | grep .md | wc -l 20

[juhp]

(Though one problem with nix's doc *.md is that they use [some text] (some comment) occasionally which is not intended to be a link but lowdown converts it to one anyway, but this may be a nix bug (I don't know the commonmark spec) - but can ask upstream.)

[devurandom]

(Though one problem with nix's doc *.md is that they use [some text] (some comment) occasionally which is not intended to be a link but lowdown converts it to one anyway, but this may be a nix bug (I don't know the commonmark spec) - but can ask upstream.)

The spec explicitly forbids this for links: https://spec.commonmark.org/0.31.2/#example-511

(i.e. lowdown should not render [some text] (some comment) as a link.)

[juhp]

(Sure - I will report that to nix later perhaps - anyway that part not so serious: there are only several of them)

But the main serious issue with rellinks in manpages remains (and nix has many (hundred(s)) of those)

[kristapsdz]

In these examples, [some text](some comment) should absolutely render as a link to some comment, which is a relative URI to the document named some comment.

For this reason, I've just added --roff-no-rellinks: like --term-no-rellinks, it inhibits printing the link address, so there's more control over this situation.

Unfortunately, the relationship between the "nolinks", "norellinks", and "shortlinks" is complicated for -tman due to being locked to how the macros are rendered by the roff formatter. Formatters will render UR macro links by showing the link address along with its content, if any. Links are not clickable, so the link shown alongside must be canonical. Thus, if a user asks for "nolink" or an applicable "norellink", the UR macro is not used and the system falls back to traditional mode of styling links, then omits the styled link if there's also text. "Shortlink" only has meaning if "nolink" or "norellink" is specified, because the link given to the UR macro should be well-formed.

For -tms it's better because the pdfhref macro will render links as clickable and not actually show the link itself. So things like "nolink", "norellink", and "shortlink" make more sense and Do The Right Thing.

All of this is in the repo right now and documented, and will be rolled into the next release. I'll close out this comment at that time, unless what you're seeing flies in the face of what makes sense.