Latex issue when is included a citation in the caption of a table or figure

[fcolahuerta]

When is included a cite in the caption of a table or figure.
The generation in latex of the list of figures or tables is failing.

Are the citation labels added with the \protected label?

\protect\citeA[

[4] (structuraloptimizationgenerativedesign.lot Runaway argument? {\numberline {3.1.1}{\ignorespaces Summary of optimization objectives\ETC. ! Paragraph ended before \contentsline was complete. <to be read again> \par l.5 ...erved@a \relax \let \reserved@d =[\def \par }}{6}{table.3.1.0.0.0.1}% ? r

[mcmtroffaes]

This is a documented issue: https://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html#latex-backend-fails-with-citations-in-figure-captions Does the workaround documented there still work?

[fcolahuerta]

No it does not work. It still given the same error, on the captions with a cite.
In fact the version installed it does not seem to generate \phantomsection labels.

[mcmtroffaes]

Ah, good to know. Something must have changed in sphinx. Looking at the error, I'm not sufficiently skilled in TeX wizardry to see a simple immediate solution. If there would be a way to adjust something in the preamble to make it work, similar to the old solution, that would be fantastic. Ideas welcome.

[fcolahuerta]

I have been looking this and it seems that if is added the term \protect before the \hyperlink{} citation method inside a the tables or figures captions \sphinxcaption{} the list of tables is generated correctly without errors

The following give error in LATEX, when generated by SPHINX with sphinxcontrib-bibtex,
\sphinxcaption{Summary of optimization objectives {[}\hyperlink{cite.0_Bibliography:id120}{1}{]}, {[}\hyperlink{cite.0_Bibliography:id113}{9}{]}}\label{\detokenize{structures:optimization-objective}} \sphinxaftertopcaption

The following does not give error,
\sphinxcaption{Summary of optimization objectives {[}\protect\hyperlink{cite.0_Bibliography:id120}{1}{]}, {[}\protect\hyperlink{cite.0_Bibliography:id113}{9}{]}}\label{\detokenize{3_1_building_structures:optimization-objective}} \sphinxaftertopcaption

The same for figures cases, the following does not give error, with the \protect term before \hyperlink,
\noindent\sphinxincludegraphics[scale=0.7]{{smoothin_result}.png} \caption{Current smoothing result {[}\protect\hyperlink{cite.0_Bibliography:id126}{35}{]}}\label{\detokenize{structures:smoothin-result}}\end{figure}

However, I do not know how to add this term \protect in runtime while the sphinx LATEX generation.

Reference,
https://tex.stackexchange.com/questions/522524/using-hyperrefs-hyperlink-command-inside-caption-in-figure-environment

[mcmtroffaes]

Many thanks for doing some research on this. Glad to see there's a solution in principle. Adding \protect before every \hyperlink is a very easy thing to do from the extension (a one line patch, really). However, do you know whether it would be safe to have \protect\hyperlink in all places (not just captions)? Or would that break some things where \protect isn't strictly needed now?

[mcmtroffaes]

Haven't tested yet but I wonder if something like this could work in conf.py:

latex_elements = {
 'preamble': r'''
     \usepackage{etoolbox}
     \AtBeginEnvironment{figure}{\pretocmd{\hyperlink}{\protect}{}{}}
 '''
}

[fcolahuerta]

In latex files where the issue has been check it does not harm adding \protect before every \hyperlink
In fact the solution that works for me is modifying the domain.py function with this feature. Or just doing a manual replace all \hyperlink for \protect\hyperlink
In the develop branch it seems has changed

def render(self, backend: "BaseBackend"): assert isinstance(backend, pybtex_docutils.Backend), \ "SphinxReferenceText only supports the docutils backend" info = self.info[0] if info.builder.name == 'latex': key = f'cite.{info.todocname}:{info.citation_id}' return ( [raw_latex(f'\\protect\\hyperlink{{{key}}}{{')]

Adding the solution to the preamble is less general, and does not work in my case. For the figures, code-blocks and tables might work if are generated with the standard latex labels. But for example in my case the tables are generated using \sphinxcaption and in this cases does not work.

[mcmtroffaes]

Thanks for the feedback, I've been thinking about this, will eventually try to come up with some solution (I'm just super busy for a few weeks).

[SunbrightShinobi]

Just checking if there was an estimation when the protect would be added to attempt to fix this. Just came across this issue today when updating my sphinx environment and troubleshooting it to find that it was already written up :)

[mcmtroffaes]

I'm wary of adding a blanket \protect to every \hyperlink out of fear of breaking other things. Perhaps it won't - if someone here is a TeX wizard and can explain to me why this fix won't break anything, that would be great! For now, I'd prefer to have this fix localized somehow, e.g. via

\usepackage{etoolbox}
\AtBeginEnvironment{figure}{\pretocmd{\hyperlink}{\protect}{}{}}

but apparently this doesn't work, and I don't know why. Some advice would be deeply appreciated.

[partofthething]

but apparently this doesn't work, and I don't know why. Some advice would be deeply appreciated.

FWIW this fix does work for me perfectly with a xelatex build. Thanks!

[mcmtroffaes]

but apparently this doesn't work, and I don't know why. Some advice would be deeply appreciated.

FWIW this fix does work for me perfectly with a xelatex build. Thanks!

Thanks for letting me know. I'm amazed this random untested code actually worked! Unfortunately, I still couldn't make it work on pdflatex.