sphinx-doc
LaTeX: Link to `#` doesn't work
Describe the bug
I'm not sure if that's expected to work, but since #something seems to work, maybe # should work as well?
In HTML output, both work, but there is a different problem (#11335).
How to Reproduce
index.rst:
Title
=====
`link to subsection <#a-subsection>`_
A Subsection
------------
`link to top <#>`_
conf.py:
# empty
Run:
python -m sphinx . _build -b latex
cd _build
latexmk -pv
Note that link to subsection has turned into a working link, while link to top is just a passive little piece of text.
The Sphinx run doesn't produce any errors or warnings, but LaTeX reports this:
LaTeX Warning: Hyper reference `index:' on page 3 undefined on input line 94.
Environment Information
Platform: linux; (Linux-6.1.0-6-amd64-x86_64-with-glibc2.36)
Python version: 3.11.2 (main, Mar 13 2023, 12:18:29) [GCC 12.2.0])
Python implementation: CPython
Sphinx version: 6.2.0+/0fb6716f3
Docutils version: 0.19.1b.dev
Jinja2 version: 3.1.2
Pygments version: 2.14.0
Sphinx extensions
No response
Additional context
This is related to https://github.com/spatialaudio/nbsphinx/issues/664, which was originally reported by @jfbu.
The first link works because A Subsection creates a label named index:a-subsection. When using #a-subsection, it seems that it prefixes index: to a-subsection and everything works well. However, the LaTeX output does not create a label at the top of the document whereas HTML implicitly interprets anchor # as the top.
EDIT: After reconsidering what I said in https://github.com/sphinx-doc/sphinx/issues/11335#issuecomment-1512761898, I think it is reasonable to modify the LaTeX writer in order to incorporate a top-level label. The question being: should it be at the top of the section? the subsection? visual page?
EDIT 2: Any thoughts on that @jfbu ?
The question being: should it be at the top of the section? the subsection? visual page?
Neither?
I think it should point to the beginning of the "document". This seems the closest to the HTML behavior to me, isn't it?
In my alternative implementation https://github.com/spatialaudio/nbsphinx/pull/725 (which I would prefer not having to use!), instead of defining a new label I'm using a :doc:`current-document` link (with sphinx.addnodes.pending_xref(reftype='doc', ...).
I don't know what's most meaningful when implementing this in Sphinx itself, though.
I think it should point to the beginning of the "document". This seems the closest to the HTML behavior to me, isn't it?
The closest to the HTML behavior is to go to the top of the section (perhaps we have a misunderstanding about the term "document" but that would be just after \begin{document}). But now that I think about it, going to a subsection is stupid and we just should go to the beginning of the reST document (perhaps that's what you were referring to).
Yes, I meant what Sphinx calls a "document". That's what I was trying to clarify with pending_xref(reftype='doc', ...), which will generate a link to the top of a given "document".
In LaTeX, the two references are represented as \href{\#a-subsection}{link to subsection} and \href{\#}{link to top}
While the first reference is converted to an active link, it does not work as expected:
The pdfTeX compiler writes the warning:
pdfTeX warning (dest): name{a-subsection} has been referenced but does not exist, replaced by a fixed one
Clicking at the link in a PDF viewer zooms out to show the complete sample document.
The second link gets a different warning:
Package hyperref Warning: Suppressing link with empty target on input line 46.
Conclusion:
Both, #something and # don't work as expected. However they
fail differently.
In addition, the interpreation of # as "go to the top of the document" is ambiguous: Should this lead to the top of the complete Sphinx project or the top of the individual input files in the project.
Setting an explicit hypertarget at the top in rST is easy:
.. _top:
Title
=====
Link to title_ and link to top_.
I'd call the current behaviour a known LaTeX limitation rather than a bug.
