Format-agnostic hyperlinks

[John Gardner]

Hey folks,

Recent discussion on this list about PDF and HTML links galvanised an
earlier attempt of mine to implement hyperlinks in Troff in a device- and
package-agnostic manner: It's still very much a W.I.P., but

.[ "here's what I've done so far" ](
https://github.com/Alhadis/Mono/commit/f363ed40d ) ,


and that right there is an example of how it looks. I chose a Markdown-ish
syntax not just because it's immediately familiar to most developers, but
it provides an easy way to specify different links:

.[ "1. URL" ]( https://github.com ) ,

.[ "2. Anchor/Bookmark" ][ internal-id ] ,

.[ "3. Anchor with auto-selected ID" ] .


For HTML output, this produces:

<a href="https://github.com";>1. URL</a>,

<a href="#internal-id">2. Anchor/Bookmark</a>,

<a href="#id-1">3. Anchor with auto-selected ID</a>.


For PDF, well... the expected output should be obvious. For all other
formats, a printed and/or purely text-based medium is assumed. Only URLs
are printed; anchors are (logically) ignored:

1. URL (*https://url/ <https://url/>*),

2. Anchor/Bookmark,

3. Anchor with auto-selected ID.


If finer control is needed over the URL's printed representation, a more
verbose syntax is provided:

.[ Text ]( before-url URL after-url ) optional-affix


For example this:

.[ "API reference" ]( ": " *https://docs.github.com/
<https://docs.github.com/>* "" ) .


will show up in printed/non-interactive mediums as:


API reference: *https://docs.github.com/ <https://docs.github.com/>*.


Yet HTML output remains the same as the shorter syntax:


<a href="*https://docs.github.com/ <https://docs.github.com/>*">API
reference</a>.

This is admittedly a hack, but I couldn't think of a more elegant-looking
way to customise the format of printed URLs. I considered adding footnote
support, but felt it'd be feature creep.

*Anchors*
As for bookmarks/anchors? The syntax is:

.# "Text" internal-id optional-affix

.# "Text with auto-selected ID"

.# "Text with user-supplied ID" internal-id

.# \& hidden-anchor


Here, "ID" refers to the identifier of a named destination (for PDF) or to
a fragment identifier (for sections within an HTML document). For anything
else, .# just degrades sensibly to its textual representation.

I've rambled too much (and I seriously need sleep), so I'll wrap this up
and leave you folks to provide feedback. Remember it's still a W.I.P (I
just didn't want to lose a month of work to a hard-drive failure or
something).

— John\c
.[ @Alhadis ]( https://github.com/Alhadis )
.ex

*PS:* Oh yeah, to make things extra challenging for myself, I'm using only
CSTR-54 compatible Roff features. That means no GNU extensions (unless
Groff is clearly identified as the running Roff interpreter), and all
macros need to be compatible with legacy *roffs (or at least degrade
gracefully in a manner best adapted to the environment's limitations).

Funnily enough, mandoc is more of a headache than the original Osanna troff
is… ;-) Not that anybody uses mandoc for halfway-decent typesetting.