Troubleshooters.Com®, Linux Library and Litt's LyX Library Present:
Colored and Clickable Wrapping URLs in LaTeX and LyX
Copyright © 2021 by Steve Litt
See the Troubleshooters.Com Bookstore.
CONTENTS
Life shouldn't be this hard. All you want is to be able to put colored, clickable, wrapping URLs in your LyX document, so that when you click them, a browser shows the contents of the URL, they're colored to show they're not just more text, and instead of walking off the right side of the paper, they wrap pretty much as other text would wrap. But nooooo!
And what makes it worse is many of your friends say they have no problem doing this --- what's wrong with you?
No problem, you go online to find an answer. And then your problems start multiplying, big time. As you experiment, sometimes your URL wraps but won't bring up the URL if you click it. Sometimes it clicks just fine but walks right off the right side of the paper. Sometimes it wraps, with some of the lines clickable and others not. Sometimes it doesn't compile at all. And once in a blue moon, when the stars align exactly right, it's clickable, wrapable and colored. If that ever happens, save a copy and make it read-only, so you can go back to it.
What caused all this seeming intermittence is your choice of which Internet advice combination you followed. The advice is plentiful: Use the url package. No, use the xurl package. Use the hyperref package. Well, yes, use hyperref but don't set colorlinks=true! No wait, instead of colorlinks=true use some other package. Use the hyperref package with breaklinks=true. No, don't do that, it makes different lines non-clickable! Use \sloppy. No, don't use \sloppy. Somebody even suggests installing package burl, which you can't even find in CTAN.
Meanwhile, as you begin to tear your hair out, your friends imply that you must be stupid or something.
STOP THE MADNESS!
If you use Linux with the TeXLive version of LaTeX, this document shows you an easy route to colored, clickable and correctly wrapping URLs in your PDF document. This route is built upon a few key distinctions...
NOTE:
The examples and shellscripts in this document use program mupdf to view PDF files. I'd recommend you use mupdf too, because it easily pulls up web pages from PDF URLs. But if you decide to use a different PDF viewer, substitute that viewer's filename for "mupdf".
Here are the key distinctions:
You must use either pdflatex or lualatex to compile the document. If you try using latex to convert to .dvi, and then convert to .pdf, you'll lose enough essentials that you can't make clickable, wrapable colored URLs, at least without an insane amount of kludge. As far as xetex, I'm not even going to discuss that. Why use xetex in 2021?
The hyperref package is what enables clickable links in PDFs, including URLs. I've found no way to make clickable PDFs without using package hyperref, or else a package that brings in hyperref by inclusion.
If you want your URL (and other clickable links and references) a different color, so it's obvious they're clickable, you need to use colorlinks=true. If, and only if, you need to use breaklinks=true in order to make other kinds of references wrap, you can do so, without breaking your URLs, as long as you follow the other key distinctions.
Oh man, I can hear some of my friends howling in outrage when I suggest compiling with a shellscript instead of using LyX' built-in compilation method. But a compile shellscript is my story, and I'm sticking to it. Here's why...
I'm an Elder in the Church of the Known State. I want to know exactly what's happening during compilation, instead of relying on LyX' current compilation setting using, for instance, pdftex to compile. Because sure as the next season follows this one, sooner or later you'll need to change one of those LyX settings, and as far as I know those settings are LyX wide, not per-document. So when you change it for one document, that can break the compile of others.
And even if there's a way to make those settings per-document, the file in which those settings are kept will be too hard to find and too easy to accidentally erase.
Meanwhile, if every large document you have has a file called compilebook.sh in the document's directory, things are obvious, and that shellscript even serves as documentation for how to compile it.
Best of all, nothing about using a shellscript to compile in any way hurts your ability to compile with built-in LyX settings for small and simple documents. The shellscript is only for tricky, complex, or big documents.
If you adhere to these key distinctions, making clickable, wrappable and colored URLs will usually work the first time, and if not, troubleshooting will be easy.
Create the following LaTeX file, called example.latex, which includes two instances of a long URL:
\documentclass{book} \textwidth=3in \parindent=0pt \usepackage[colorlinks=true]{hyperref} \begin{document} \rule{\linewidth}{0.2ex} Here's the URL: \url{https://www.briggsandstratton.com/na/en_us/support/videos/browse/4-stroke-theory.html}. The next URL is on a line of its own. \url{https://www.briggsandstratton.com/na/en_us/support/videos/browse/4-stroke-theory.html} \end{document}
Now you need a shellscript to compile the preceding. Create the following shellscript, called compile.sh:
#!/bin/sh rm example.pdf pdflatex example.latex #lualatex example.latex mupdf example.pdf
After you've created example.latex and compile.sh, running compile.sh produces a PDF with two colored, clickable, wrapping links.
You'll notice that compile.sh uses pdflatex to compile the document. If you instead want to use lualatex, just comment out pdflatex and uncomment lualatex. Be aware that when you use lualatex, you must install the LaTeX package called luainputenc, or your compile fails.
Follow these instructions to create a tiny LyX example of clickable, wrappable, colored URLs:
That's it, you've created the LyX file. Now just create the compile shellscript, called lyxcompile.sh, as follows:
#!/bin/sh rm lyxexample.tex rm lyxexample.pdf lyx -e pdflatex lyxexample.lyx pdflatex lyxexample.tex mupdf lyxexample.pdf
Finally, use the chmod command to mark lyxcompile.sh executable, and perform the following command:
./lyxcompile.sh
If you've done everything as described in this section, a PDF file pops up. Its text looks something like what you see in the following square:
In researching wrapping, clickable URLs, you'll doubtlessly come upon people recommending the xurl package, saying it will solve all your problems. Don't believe it. The xurl package was created to solve a different problem, and usually won't help. Let me explain...
The techniques described earlier in this document create colored, wrappable, clickable URLs in almost every case, because they are able to break on dots and slashes. The only time the xurl package is needed is when a URL has strings between such breakable characters that exceed the text width of the document. When does this happen? In most cases, it happens when the web designer decides to pass ginormous variable values within the URL. The following paragraph has an example:
http://troubleshooters.com/fixbench?id=kOasdfjk21 xx23v2kjv 92ajdlsvo23j4 jf042jvj20djabakan183adown 238naxwk01jmv0a3x23 jmv21xx23v2kjv92a jdlsvowajwlxo3bnam30sx jkiuz123adfkweijv8aOe21xx2 3v2kjv92ajdlsvo82fQE
Ugh! When you run into one of those, add the following to your Document->Settings-Local Layout:
#\usepackage{xurl}%
Then test and troubleshoot as necessary.
I market about eight LyX-authored books. For every one of them, no existing Document Class met my needs. So for each book, I created my own Document Class, most of them based on the existing LaTeX Book Document Class. Doing this has given me almost infinite adjustment of the presentation of the books. In fact, my book Key To Everyday Excellence goes so far as to put a date marker on each page's header, so the reader keeps his or her bearings as the story zooms from current to backstory and back again over most of the 21st century. If there's a current document class or LaTeX package offering this feature, I sure haven't heard of it.
If you use make own document class, you'll do so with a layout file. Layout files are way beyond the scope of this document, but are partially covered elsewhere in Litt's LyX Library.
Here are some tips for clickable, wrappable colored links in a document using a layout file:
When all you want is a colored, wrapping, clickable URL and it just won't happen, things go downhill fast, because there's so much ambiguous and contradictory advice for this problem on the Internet. If you use either pdflatex or lualatex, you've solved the major problem, and the rest is probably easy to handle.
Is this document just another ambiguous and contradictory piece of web advice? All I can say is that on 5/2/2021 I tech edited it, and everything worked, and I did enough experimentation to know which variables had what effects. But I couldn't check every edge case. So if you find errors or edge cases in this document, please email me, and I'll fix what's necessary.
[ Training | Troubleshooters.Com | Email Steve Litt ]