Set LaTeX bibitem id to citation node id

[jnothman]

Subject: LaTeX writer uses \bibitem[label]{label} when it should use \bibitem[id]{label}

Feature or Bugfix

• Bugfix

Purpose

In the unusual case that the textual label differs from the ID, the ID should be preferred. This comes up in a proposed change to numpydoc.

These IDs are not currently used for referencing within sphinx-produced TeX documents, as sphinx explicitly adds a \label to reference text.

[jnothman]

I could add a test, but it might involve hacking doctrees.

[tk0miya]

It seems the labels of \cite are not changed. Is this really correct?

[tk0miya]

oh, sorry. Please forget my comment above.

[tk0miya]

Please add a test for this. in addition, please rebase this to stable branch.

[jnothman]

test will have to be over a modified doctree. I'll try get to it... Sphinx doesn't use these ids to reference. It uses a separate \label etc. but TeX expects them to have certain properties.

[jfbu]

This can not be merged, as bi[3] has already been normalized (converted to lowercase, stripped of diacritics (é becomes e), ...) hence although indeed the link works, this normalizes too much the look of the reference tag in the bibliography in an unexpected by user way.

[jfbu]

@jnothman for background could you add a comment here with a link to numpydoc relevant thread?

[jnothman]

Sorry, perhaps I got this backwards. In [] should be the display text, i.e. bi[0], and in {} the ID? Does that make sense to you, @jfbu?

This relates to numpy/numpydoc#136

[jfbu]

Sorry, perhaps I got this backwards. In [] should be the display text, i.e. bi[0], and in {} the ID? Does that make sense to you, @jfbu?

Yes it is \bibitem[citeKey]{citeID} actual bibliographic reference. It will print out in bibliography as

[citeKey] actual bibliographic reference

and the [citeKey] will also be used and be a link in the document text.

I observe that Sphinx

• encloses in braces the actual bibliographic reference which appears unneeded,

• does not use the \cite command, a citeID is produced (self.idescape(bi[0])) but not used. In a normal LaTeX document one would see \cite{citeID} to match \bibitem[citeKey]{citeID}.

a priori, this looks sub-optimal.

In bi[3] there is a Sphinx citeid which is used to produced a label which serves as target for an hyperlink located at reference location in document. It is not same thing as the citeID above which is escaped from bi[0].

The bi[0] which ends up in \bibitem[self.encode(bi[0])] gives the printed citeKey in LaTeX document, it undergoes a TeX-escaping which I think boils down only to replacement of the underscore _ which is allowed in reST citations into \_ for LaTeX, because other allowed characters need no LaTeX-escaping.

[jfbu]

@tk0miya I have started to work on getting LaTeX to use standard \cite command. This is at https://github.com/jfbu/sphinx/tree/latex_use_cite and currently has two commits (on tip of stable). It works in simple test, but I needed to hack into _resolve_citation_xref of standard domain. I can't work on this in near future, but I mention it here in case you have an opinion whether this might be worthwile. For example

Lorem ipsum [RefTTT_éé]_ dolor sit amet.

.. [RefTTT_éé] Book or article reference, URL or whatever.

now generates in latex file:

Lorem ipsum \cite{\detokenize{RefTTT__xe9_xe9}} dolor sit amet.

and

\begin{sphinxthebibliography}{RefTTT\_éé}
\bibitem[RefTTT\_éé]{\detokenize{RefTTT__xe9_xe9}}
Book or article reference, URL or whatever.

\end{sphinxthebibliography}

which is much lighter mark-up than in current Sphinx, with same functionality.

[tk0miya]

@jfbu +1

[jfbu]

@jnothman any other proposal on this PR? for reasons explained it can not be merged as is.

FYI, I will refactor latex writer to use standard LaTeX \cite command at some point in future; if using \cite helps in your problem it could be merged into 1.7.x series as bugfix; else it will go into 1.8.

[jnothman]

Sorry, I've not had much attention for this one. If you have an alternative fix, feel free to put one in.

[jfbu]

@jnothman thanks for update, issue is that I don't know what is to fix from your point of view. As mentioned it is planned for LaTeX writer to use \cite as it looks the reasonable thing to do and may ease up further customizations on user side. But I have no a priori idea whether this will help solve numpy/numpydoc#136, which sounds related to some specific handling of references done at numpy.

[tk0miya]

Finally, in #4904, I replaced \hyperref with \cite.
As a result, this is also resolved.

Thanks,