.mso doc.tmac
.mso www.tmac
.mso pdfmark.tmac
.Dd July 1, 2020
.Dt GROFFLINKS 6
.Os UNIX
.\" 
.\" If generating a PDF, give some metadata
.pdfinfo /Title    A test of Groff Hyperlinking
.pdfinfo /Author   hackerb9@member.fsf.org
.pdfinfo /Subject  Groff hypertext in pdf and nroff
.pdfinfo /Keywords Hotlinks, weiners, brats, bangers, snausages
.\" To generate pdf, use groff like so
.\"    groff -Tpdf -P-e -P-pletter ywww.6 > ywww.pdf	
.\" 
.Sh NAME
.\" 
.Nm Hypertext
.Nd can one macro work for both nroff and PDF?
.Ss YES! USE .URL 
hackerb9 modified the www.tmac package so that
.Li .URL
uses pdfmark to create hyperlinks when generating PDF output. 
This document exists as a test file to make sure everything works.
HTML links already worked for www.tmac and that is unchanged. Nearly
unchanged is functionality for output formats that do not support
hypertext (nroff, postscript): as before, the link text is shown in
blue, if possible, and then the URI is printed in angle brackets. The
one minor change is that if the output is to a tty or device without
color, then the text will be differentiated by underlining (nroff),
italics (b&w postscript), or a dotted box (b&w pdf).
.
.Ss .LINK: omit URL if a link is not possible
Also added is a new
.Li .LINK
macro that works like
.Li .URL
on output devices that can link (PDF & HTML), but renders as
normal text, with no URL, on devices that cannot (TTY, PS).
.Sh TESTS
.Ss Basic test
Here is the most basic test of
.Li .URL
which simply links a word to a URL:
.URL "https://scholarspace.manoa.hawaii.edu/handle/10125/53707"  Hello !
.Pp
Note that in PDF and HTML output the URL should \fInot\fR be shown
above, but in nroff and postscript output it should.
This
.LINK "https://en.wikipedia.org/wiki/Persistent_uniform_resource_locator" \
      "sentence is an example"
of using
.Li .LINK
which creates links when it can, but simply omits the URL when hypertext
is unavailable.
.Pp
.Ss \&In a sentence (with punctuation surrounding)
Testing
.Li .URL
in
.URL "https://www.amazon.com/Groff-book-continuing-saga/dp/B0006RO6LQ" \
     "the middle" ) (
of this sentence with parentheses around the linked text.
.Pp
.Ss Bare URL
Testing
.Li .URL
with just a bare URL, no descriptive text: 
.URL "https://groff.org" 
.Pp
Empty string for link text, with punctuation afterward:
.URL "https://groff.org" "" .
.Pp
.Ss Inline in a paragraph
Now, let's try using the
.Li .URL
command in a paragraph to make sure
it is not adding spurious newlines or colons. 
In 2009, the 6809 assembly code was documented by
.URL http://computerarcheology.com/CoCo/MadnessMinotaur/ \
     "Chris Cantrell of Computer Archaeology" .
In 2015 John M. Layman used that documentation to create
a port to Intel's 32-bit CPU architecture (\fIx86\fP).
.Ss MTO (mailto) test
.Pp
This is a link to send mail to
.mailto hackerb9@member.fsf.org "hackerb9" .
Here is a bare mailto address: 
.MTO groff@gnu.org
.Pp
.Sh ABNORMAL CONDITIONS
.Ss Overly long bare URL (no link text provided)
Bare URLs (no description) should wrap at / (slash).
.URL "https://www.columbiabasinherald.com/news/2020/mar/02/district-unveils-mascot-colors/"
.Pp
.Ss Splitting URLs on symbols
Groff's WWW package doesn't
.LINK https://en.wikipedia.org/wiki/Clean_URL yet
handle splitting long URLs on
other symbols like ?, _, %, or &.
.Pp
.URL "https://open.spotify.com/album/32aa0867XRy3hylZWsYiKN?fbclid=IwAR3nqvaSmELmEWZuUYdq4-N--oZ2jkEHqY2krB_erAsbT8DMYYjkGl7GDDg&_php=1"
.Pp
.Ss Overly long link text
Descriptive text should wrap to more then one output line as needed.
.Pp
.URL "https://www.reddit.com/r/NetflixSexEducation/comments/exw4n5/mrs_groff_is_highly_underrated_i_love_how_she/" \
     "Mrs. Groff is highly underrated. I love how she learns to value herself and take control of her dull life. Her beginning to feel young again is so heartwarming."
.Pp
.Ss Insufficient arguments
It is an error to use
.Li .URL ,
.Li .LINK ,
or
.Li .MTO
with no arguments.
When processed with groff, this document produces three error messages
to the terminal like this:
.Bd -literal
usage: .URL <URI> [descriptive-text [affix-text [prefix-text]]]
usage: .LINK <URI> [descriptive-text [affix-text [prefix-text]]]
usage: .MTO <email> [name [after [before]]]
.Ed
.tmc TEST: 
.URL
.tmc TEST: 
.LINK
.tmc TEST: 
.MTO