sphinx-doc / sphinx-doc/sphinx
Write \hypertarget for labels to allow external linking to a destination within a PDF
@jfbu is already working on this.
Since Jan 31, 2021.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
PDFs have the concept of "named targets" that can be used by an external application to jump directly to a part of the document. This is very useful to link to a specific part of a long document.
Let's say a document doc.pdf has a section with a named target "my-target", then PDF viewers can jump directly to that section by opening the url http://example.com/doc.pdf#nameddest=my-target. Some PDF viewers also support the (non-standard) short form http://example.com/doc.pdf#my-target.
This works in Firefox (with pdf.js), Chrome, Sumatra, Evince, Adobe Acrobat Reader and probably others.
It is possible to create a named destination in LaTeX by using the \hypertarget command from the hyperref package (example on Stack Overflow)
This could be supported by Sphinx if it would generate a \hypertarget around a \label.
Example input:
.. _this-is-label-two:
Heading 2
=========
Current output:
\chapter{Heading 2}
\label{\detokenize{index:heading-2}}\label{\detokenize{index:this-is-label-two}}
Proposed output:
\chapter{Heading 2}
\label{\detokenize{index:heading-2}}\hypertarget{this-is-label-two}{\label{\detokenize{index:this-is-label-two}}}
A PDF viewer can now jump directly to this section by opening http://example.com/doc.pdf#nameddest=this-is-label-two.
Note that I've removed the index: prefix in the hypertarget label. An external document can know the label to link to, but it is unlikely to know the original rst doc name (index in this case).
With this feature it would even be possible to have Intersphinx support linking between PDF files, rather than always pointing to HTML.
P.S. On my TexLive 2016, this works fine with pdflatex, but not with XeLaTeX. This is easily fixed by adding \special{dvipdfmx:config C 0x0010} to the preamble. See bug reports for Xetex and MikTex.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.