Man writer: hyperlinks

[van-de-bugger]

Currently man writer renders links as text:

$ cat ./test.md
SEE ALSO
========

*   [pandoc](https://pandoc.org)


$ pandoc -f markdown -t man ./test.md
.SH SEE ALSO
.IP \[bu] 2
pandoc (https://pandoc.org)

There are special groff macros to format links:

$ man man-pages
<...>
   Hyperlinks
       For hyperlinks, use the .UR/.UE macro pair (see groff_man(7)).  This produces proper hyperlinks that can be used in a web browser, when rendering a page with, say:

           BROWSER=firefox man -H pagename
<...>

.UR/.UE usage:

.UR url
[label]
.UE [punctuation]

Brackets denote optionality, punctuation will be written afther the link with no interleaving space.

BTW, there are similar macros for email links: .MT and .ME. See more details in groff_man (search for "Hyperlink macros").

It would be nice if man writer uses these groff macros.

[jgm]

If these are groff-specific, that might be a reason to avoid them.
Also, how do these render on the terminal? Does the URL get displayed as we do currently?

[jgm]

I don't see these macros being used in the man pages on my system. I don't think we should use them.

[van-de-bugger]

I don't see these macros being used in the man pages on my system.

What is your system?

Ubuntu 20.04, released in 2020, has number of man pages with .UR macro:

$ find /usr/share/man -type f -name '*.gz' | \
    while read f; do \
        if zcat "$f" | grep -qEe '^\.UR '; then \
            echo "$f"; \
        fi; \
    done | wc -l
127

Ubuntu 14.04, released in 2014, has 58 man pages with .UR macro too.

I found NomadBSD, a FreeSBD-based OS. They provide Live image, so I was able to download and run it without installation. NomadBSD does not have man pages with .UR/.UE macros, but their man understands these macros anyway:

# uname -a
FreeBSD NomadBSD 13.1-RELEASE-p5 FreeBSD 13.1-RELEASE-p5 NOMADBSD amd64

# cat ./test.man
.SH SEE ALSO
.UR https://pandoc.org
pandoc
.UE

# man ./test.man | cat
()                                                                         ()

SEE ALSO
       pandoc <https://pandoc.org>

                                October 5, 2023                            ()

BTW, they man is not GNU one: NomadBSD's man does not accept --version option:

# man --version
Illegal option --
Usage: <...>

I think even if NomadBSD (read "FreeBSD") man recognizes .UR/.UE macros, using these macros in man pages is pretty safe.

Also, how do these render on the terminal? Does the URL get displayed as we do currently?

How NomadBSD renders links using less-than or more-than signs, as shown above.

Linux renders them similar:

SEE ALSO
       • pandoc ⟨https://pandoc.org⟩

But uses Unicode angle brackets instead of less-than and more-than signs.

However, rendering is not so important. More importantly that pandoc loses information when converting from markdown to man: in markdown we have link, in man we only have text, not a link.

BTW, pandoc's man reader recognizes .UR/.UE macros. Look:

$ cat test.man 
.SH SEE ALSO
.IP \[bu] 2
.UR https://pandoc.org
pandoc
.UE

$ pandoc -f man -t markdown ./test.man
# SEE ALSO

-   [pandoc](https://pandoc.org)

You see, than converting from man to markdown correctly converts a link, but conversion in opposite direction does not.

[jgm]

I think I was mistaken; there are some .URs on my system (macOS), e.g. ggrep. When I do man ggrep it gives me a warning that the manpage is not compatible and might display incorrectly, but the links do appear correctly, so maybe it's something else it doesn't like...

Anyway, I will reopen this for further comment, but the question is whether it is best practice for portable man pages to produce these groff-specific macros. Maybe @g-branden-robinson (who helped with some other man page issues) could weigh in on this?

[g-branden-robinson]

I think I was mistaken; there are some .URs on my system (macOS), e.g. ggrep. When I do man ggrep it gives me a warning that the manpage is not compatible and might display incorrectly, but the links do appear correctly, so maybe it's something else it doesn't like...

I'm curious to know what's issuing warnings and what they say. What provides your system's man command? I'm guessing either mandb or mandoc.

Here's what I get for each implementation.

$ man --version
man 2.9.4
$ mman --version
mman: invalid option -- '-'
mman: invalid option -- 'v'
mman: invalid option -- 'e'
mman: invalid option -- 'r'
usage: man [-acfhklw] [-C file] [-M path] [-m path] [-S subsection]
           [[-s] section] name ...

Anyway, I will reopen this for further comment, but the question is whether it is best practice for portable man pages to produce these groff-specific macros. Maybe @g-branden-robinson (who helped with some other man page issues) could weigh in on this?

It appears to me that GNU grep is ensuring that it can use UR and other macros by defining them itself.

https://git.savannah.gnu.org/cgit/grep.git/tree/doc/grep.in.1?h=v3.11#n58

As extensions to the man macro language go, UR and UE are reasonably portable; they've been in stable release in groff for nearly 15 years. There are of course other implementations to consider.

• mandoc(1) has supported them since 1.12.3, released on December 31, 2013.
• Heirloom Doctools troff has supported them since its 160217 (February 2016) release.

I don't actually know that that many people use Heirloom behind a man pager, but figured I should include it for completeness.

Can you tell me what sorts of factors would help you decide whether support for groff extensions is prevalent enough for pandoc to employ them?

Regards,
Branden

[jgm]

I get

/usr/bin/man: illegal option -- -
Usage:
 man [-adho] [-t | -w] [-M manpath] [-P pager] [-S mansect]
     [-m arch[:machine]] [-p [eprtv]] [mansect] page [...]
 man -f page [...] -- Emulates whatis(1)
 man -k page [...] -- Emulates apropos(1)

The message:

This manpage is not compatible with mandoc(1) and might display incorrectly.

Can you tell me what sorts of factors would help you decide whether support for groff extensions is prevalent enough for pandoc to employ them?

I'm really not sure. If the man implementations commonly found on macOS, linux, and BSD systems can all handle these macros, then I think it should be fine? I didn't know if there were any standard guidelines for producing portable man pages.

[g-branden-robinson]

Hi John,

I get

/usr/bin/man: illegal option -- -
Usage:
 man [-adho] [-t | -w] [-M manpath] [-P pager] [-S mansect]
     [-m arch[:machine]] [-p [eprtv]] [mansect] page [...]
 man -f page [...] -- Emulates whatis(1)
 man -k page [...] -- Emulates apropos(1)

Huh. That doesn't look like man-db man or mandoc man.

But today I learned there are several macOS users complaining about a change in Ventura (1, 2).

The users say macOS's new man(1) is a shell script. So is FreeBSD's, so it may be that Apple adopted that one. Or forked it.

The message:

This manpage is not compatible with mandoc(1) and might display incorrectly.

Yikes. That is not very helpful, and with respect to UR and UE macro usage, not even accurate.

It might take some sleuthing to figure out what exactly about the page is provoking that diagnostic. The GNU grep(1) page does, as I implied before, do some fairly sophisticated things (conditional tests and definitions) that ultra-portable pages don't attempt.

Can you tell me what sorts of factors would help you decide whether support for groff extensions is prevalent enough for pandoc to employ them?

I'm really not sure. If the man implementations commonly found on macOS, linux, and BSD systems can all handle these macros, then I think it should be fine? I didn't know if there were any standard guidelines for producing portable man pages.

There is no standard, and never has been. In the 6 years I've been working on groff I've added a lot of historical information to the groff_man(7) document to help people out with these matters. More importantly, in groff 1.23.0, the groff_man_style(7) page has a section on "Portability", to which Ingo Schwarze and I have given a lot of attention.

So what I would do is read up about the macros documented in groff_man(7) as extensions, decide which formatters you want to support, and proceed from there. groff of course supports its own extensions, and mandoc supports them all except for the brand-new-to-1.23.0 MR.

Let me know if/how I can help here.

Regards,
Branden

[jgm]

Thanks - I decided to support them.