Troubleshooters.Com®, Linux Library and Litt's LyX Library Present:

Colored and Clickable Wrapping URLs in LaTeX and LyX

Copyright © 2021 by Steve Litt

CONTENTS

Introduction

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".

Key Distinctions

Here are the key distinctions:

You must use pdflatex or lualatex to compile the document.

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?

You must use package hyperref in order to have clickable links.

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.

You must use the correct options for package hyperref.

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.

Compile your document with a shellscript

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.

A Simple LaTeX Example

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.

A Simple LyX Example

Follow these instructions to create a tiny LyX example of clickable, wrappable, colored URLs:

  1. In an empty directory, create and save a brand new LyX document whose document class is "book".
  2. In the screen brought up by Document->settings->Page Layout, do the following:
    1. Set Format to "US Letter"
    2. Set orientation to "Portrait"
    3. Set Page style to "Default"
    4. Click the Apply button
    5. Save the document
  3. In the screen brought up by Document->settings->PDF properties, do the following:
    1. Check the box labeled "Use Hyperref Support"
    2. Click the Hyperlinks tab
    3. Click the Apply button
    4. Save the document
  4. In the screen brought up by Document->settings->Page Margins, do the following:
    1. Uncheck the box labeled "Default margins"
    2. Set top margin at 1cm
    3. Set bottom margin at 1cm
    4. Set inner margin at 8cm
    5. Set outer margin at 8cm
    6. Click the Apply button
    7. Save the document
  5. Save the document.
  6. In LyX' editor window, write "Begin clickable, wrappable, colored URL example", without the quotes, and press the Enter key.
  7. From the top menu, Insert->URL
    • Note that a LyX URL inset is created, with the cursor in the area to contain the URL.
  8. Into the inset, type "https://www.briggsandstratton.com/na/en_us/support/videos/browse/4-stroke-theory.html", without the quotes, of course.
  9. Move the cursor past the end of the inset, and press the Enter key.
  10. On the new line just created, write "End clickable, wrappable, colored URL example", without the quotes.
  11. Save the document as lyxexample.lyx.

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:

Screenshot of the created PDF file, showing the colored, wrapped and clickable links.

When to Use xurl

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.

When You Use a Real Layout File

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:

Wrap Up

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 ]