latex3 / latex3/hyperref

Confused about reserved characters in the `\url` macro

Open
#411 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TeX
Stars
205
Forks
41
PR merge metrics
No merged PRs in 30d

Description

As the title says, I am very confused about how hyperref (and also the url package) handle escaping in the argument. The documentation says that hyperref "makes use of the url package", with an important difference: "[m]ost importantly the hyperref \url expands commands." To me that sounds good, but I am quite baffled about using the core LaTeX escaping commands in the argument. Here's an approximately minimal working example (where "working" means "successfully compiling"):

\documentclass{article}
\usepackage[hidelinks]{hyperref}

\begin{document}

\noindent\raggedright \url{https://example.org/foo/{}bar} \break
\url{https://example.org/\{leftbrace} \break
\url{https://example.org/\}rightbrace} \break
\url{https://example.org/\$dollar1} \break
\url{https://example.org/$dollar2} (Only the unescaped dollar sign works?) \break 
\url{https://example.org/\&ampersand1} \break
\url{https://example.org/&ampersand2} (Both ampersands work?) \break
\url{https://example.org/%percent1} (Not a line-ending comment?) \break
\url{https://example.org/\%percent2} \break
\url{https://example.org/\^{}circumflex} \break
\url{https://example.org/^circumflex} (Both circumflexes work?) \break
\url{https://example.org/\~{}tilde} \break
\url{https://example.org/~tilde} (... but only the unescaped tilde works?) \break
\url{https://example.org/\textbackslash{}backslash} \break
\url{https://example.org/\backslash} \break
\url{https://example.org/\tilde} \break
%\url{https://example.org/\s} (Uncommenting this line causes compilation to fail.) \break
\url{https://example.org/\\backslash} (Both unescaped and strangely-escaped backslash work, and also some other weird things are happening here.) \break

\end{document}

With this result:

Image

I don't really know exactly how hyperref expects to process each of these input cases, but the cases seem quite inconsistent with each other and the documentation I quoted above. Could someone help me understand how these cases should work, and whether any of them indicate a bug in this package? In addition to these cases, if you uncomment the line starting with %\url{https://example.org/\s}, compilation fails.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by compiling the supplied minimal example with hyperref and compare each escaped-character case against the hyperref and url documentation. Record which inputs should compile and render as intended; done means a documented expected behavior and, if a package defect is confirmed, a focused reproducible test or issue.

Written by the indexing model from the issue text.

Assessment

Tech stack
latex, tex
Domain
backend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.