Proposal: Improve XeTeXLinkBox Support for Other dvipdfmx-Based Workflows

[HirokiHamaguchi]

Proposal: Improve \XeTeXLinkBox Support for Other dvipdfmx-Based Workflows

For hyperref package developers.

Hello, I am Hiroki Hamaguchi from Japan, and I sincerely appreciate the work of the hyperref package developers.

I am submitting this Pull Request (PR) to address issues around the \XeTeXLinkBox command.

Summary

• I would like to fix hyperlink-generation issues for images and similar objects that the current \XeTeXLinkBox command does not fully handle.
• I defined a new command, \HyperrefLinkBox, as a general-purpose implementation of this functionality so that these issues can be fixed while preserving backward compatibility.
• I believe this change affects many users, including those of the orcidlink package, and I would appreciate your review.

Background

First, I will explain the background of this PR based on my current understanding.

XeTeXLinkBox Command

The hyperref package provides a command called \XeTeXLinkBox, which is described as follows.

7.7 \XeTeXLinkBox
When XeTeX generates a link annotation, it does not look at the boxes (as the other drivers), but only at the character glyphs. If there are no glyphs (images, rules, ...), then it does not generate a link annotation. Macro \XeTeXLinkBox puts its argument in a box and adds spaces at the lower left and upper right corners. An additional margin can be specified by setting it to the dimen register \XeTeXLinkMargin. The default is 2pt.

(From the hyperref manual, v7.01p (2026-01-29))

This command and related logic are defined in the following location:

hyperref/hyperref.dtx

Line 7886 in d2eb2fa

\newcommand{\XeTeXLinkBox}[1]{%

Historically, this command appears to have been used as a workaround for cases where links were not generated for some objects when compiling with XeTeX. This seems to be related to a bug in dvipdfmx, which still has not been fixed. Since the issue can be handled relatively simply on the hyperref side, I submitted this PR.

(From StackExchange, last visited 2026-03-14)

Usage in orcidlink package

One major motivation for this PR is that this command is used by the orcidlink package, so the impact is likely significant. The orcidlink package is a useful package that makes it easy to create ORCID icons with hyperlinks.

(From CTAN, last visited 2026-03-14)

The hyperref package is used internally in the orcidlink package to generate links for ORCID icons. Since ORCID is widely used in academic publishing, and usage has grown in recent years, I consider this one of the important practical use cases.

Existing Problems

Next, this section explains the current problems.

The link-generation issue mentioned above also occurs when compiling with drivers other than XeTeX. However, the \XeTeXLinkBox command does not address these non-XeTeX cases.

I suspect that the KNONW PROBLEMS section in the hyperref README.md may be referring to this issue. The description is as follows. This issue appears to have been recognized by the community for at least eight years.

## KNOWN PROBLEMS

 * (half-done) hyper images (link from thumbnail in text)

(From hyperref README.md)

A similar discussion also seems to appear in this issue:

#16

In particular, for pLaTeX compilation, it is mentioned in posts such as the following:

https://tex.stackexchange.com/questions/559136/why-is-the-link-area-in-the-image-so-small

Problems similar to these occur with dvipdfmx-based workflows, including upLaTeX. The examples below show actual outputs. Using Python, I highlighted linked regions with red/blue boxes. When compiled with pdfTeX-family engines such as pdflatex and lualatex, links are correctly generated. In contrast, when compiled with dvipdfmx-based engines, some links on images are missing. I confirmed all of this on the latest TeX Live 2026.

In particular, links to ORCID icons generated by the orcidlink package are missing. Therefore, I think this is not merely an edge case, but an issue many users may encounter in practice.

Table: Raw engine outputs

latexmk pdflatex	lualatex	pdflatex	xelatex	xelatex xdvipdfmx

Table: DVI-to-PDF workflow outputs

platex dvipdfmx	ptex2pdf platex	ptex2pdf uplatex	uplatex dvipdfmx

Detailed reproduction steps and the PDF themselves are available in my GitHub repository. Running the Python script pdf2png.py generates all the results.

These results show that when compiling with dvipdfmx and related workflows, there are indeed cases that cannot be handled by \XeTeXLinkBox alone.

Since fixing the issue naturally also requires changes in the orcidlink package, I am planning to submit a PR there as well, but I believe it is necessary to first address this on the hyperref side.

Potential Bugs

Next, I describe potential bugs derived from the implementation of \XeTeXLinkBox.

The \XeTeXLinkBox command is documented as generating a link area by adding spaces, and in practice this is done by inserting 1sp spaces. Here, sp means “scaled point,” with 1sp = 1/65536 pt. However, this 1sp spacing causes problems with non-XeTeX drivers and became an obstacle to a fix. Specifically, when implementing a straightforward fix, the following error occurred.

pdfTeX error (arithmetic): divided by zero.
<argument> ...shipout:D \box_use:N \l_shipout_box \__shipout_drop_firstpage_...

There are also GitHub issues related to \XeTeXLinkBox that appear to point out problems originating from this 1sp spacing:

progit-ja/progit#8

Zettlr/Zettlr#209

! Font \XeTeXLink@font=pzdr at 0.00002pt not loadable:
Metric (TFM) file or installed font not found.

Proposed Solution

Based on the above background and issues, I propose the following solution.

• Define a \HyperrefLinkBox command, similar to \XeTeXLinkBox, for non-XeTeX drivers as well.
• Unlike the current \XeTeXLinkBox implementation, generate the link area by adding 1pt spacing instead of 1sp spacing.

Please see the PR code for details.

Compiled Results

Below are the compilation results after implementing this change. I also applied a minor change to the orcidlink package, assuming this change exists.
Specifically, the following change was made.

+ \newcommand{\@OrcidLinkBox}[1]{%
+ \ifcsname HyperrefLinkBox\endcsname%
+ \HyperrefLinkBox{#1}%
+ \else%
+ \XeTeXLinkBox{#1}%
+ \fi%
+ }

\newcommand{\orcidlogo}{%
\texorpdfstring{%
\setlength{\@curXheight}{\fontcharht\font`X}%
- \XeTexLinkBox{%
+ \@OrcidLinkBox{%
\@preventExternalization%
\begin{tikzpicture}[yscale=-\@OrigHeightRecip*\@curXheight,
xscale=\@OrigHeightRecip*\@curXheight,transform shape]
\pic{orcidlogo};
\end{tikzpicture}%
}}{}}

I compiled using almost the same method as shown in the Existing Problems section, except that I replaced \XeTeXLinkBox with \HyperrefLinkBox.

As you can see, links that were previously missing are now generated.

Table: Raw engine outputs

latexmk pdflatex succeeded	lualatex succeeded	pdflatex succeeded	xelatex succeeded	xelatex xdvipdfmx succeeded

Table: DVI-to-PDF workflow outputs

platex dvipdfmx succeeded	ptex2pdf platex succeeded	ptex2pdf uplatex succeeded	uplatex dvipdfmx succeeded

Impact Survey and Future Outlook

Impact Survey

To avoid unintended impact, I performed a lightweight survey of how this command and related functionality are used.

I am aware of the following issue, and I believe this change is broadly applicable and aligned with the direction discussed there.

#240

From a backward-compatibility perspective, I intentionally avoided changing the definition of \XeTeXLinkBox. For example, sites such as the following mention \XeTeXLinkMargin.

https://tex.stackexchange.com/questions/577314/xelatex-hyperref-bounding-box

That said, I personally think \XeTeXLinkBox could also be implemented via \HyperrefLinkBox, which may improve readability than the current PR implementation. If this way is preferred, I can change it.

The name \HyperrefLinkBox intentionally includes “Hyperref” to avoid macro name collisions. If there is a more appropriate naming convention, I can adopt it. At least through an exact-match Google search, I confirmed no apparent naming conflict.

Future Outlook

Here, I would like to discuss the future outlook of this change.

First, I would like maintainers to determine whether this PR is needed. If you already have another implementation direction in mind, I will withdraw this PR.

Also, if this PR is considered useful, it is still incomplete in the following respects, and I would like to discuss them.
If needed, I can implement these additional changes myself with proper guidance.

1. As noted above, I would like to discuss how \XeTeXLinkBox should be implemented, and whether the current \HyperrefLinkBox implementation is appropriate.
2. How should comments be written in hyperref.dtx? (For example, this file currently has entries like % \subsection{Link box support for XeTeX}, but I could not determine from searching where they are consumed. I wrote the PR based on a best-effort guess; I would appreciate guidance on the correct approach.)
3. Additional updates to doc/hyperref-doc.tex (I think we should add similar explanations and examples after \subsection{\textbackslash XeTeXLinkBox}).
4. Add tests (I am not yet fully sure how tests are run in this repository. Tests for other drivers may also be necessary.)
5. Add an entry to Changelog.txt (this seems straightforward).

Conclusion

Thank you for your time and effort. I would greatly appreciate your review.

[u-fischer]

sorry but could you please add one short example demonstrating the problem that you have with \XeTeXLinkBox (or that is not solved by it)? I got a bit lost in all the references.

[HirokiHamaguchi]

Reply 1

Thanks for the comment. The minimum working example (MWE) is to compile the following code with pLaTeX or upLaTeX.

\documentclass[12pt,dvipdfmx]{article}

\usepackage{hyperref}
\usepackage{orcidlink}
\usepackage{tikz}

\begin{document}

orcidlink icon: \href{https://orcid.org/0009-0005-7348-1356}{\orcidlink{0009-0005-7348-1356}}\\

TikZ figure wrapped by \texttt{\string\XeTeXLinkBox}:
\href{https://example.com}{%
    \XeTeXLinkBox{%
        \begin{tikzpicture}[scale=0.8]
            \draw[fill=blue!20] (0,0) circle (1);
            \draw[fill=red!40] (-0.7,-0.7) rectangle (0.7,0.7);
        \end{tikzpicture}%
    }%
}

\end{document}

The two objects (the ORCID icon and the TikZ figure) are wrapped by \XeTeXLinkBox, but do not work as hyperlinks. (mwe_platex.pdf)

[u-fischer]

ah ok. Well your fix is not the right one, as you are defining the command for all backends but we do not want this definition for pdftex and luatex. I will extend \XeTeXLinkBox to the dvipdfmx backends, then you can use that, see the branch pr142.