Opened 16 months ago
Closed 15 months ago
#31387 closed defect (fixed)
Cosmetic update in building the pdf docs
Reported by:  strogdon  Owned by:  

Priority:  minor  Milestone:  sage9.3 
Component:  documentation  Keywords:  
Cc:  jhpalmieri  Merged in:  
Authors:  Steven Trogdon  Reviewers:  Dave Morris 
Report Upstream:  N/A  Work issues:  
Branch:  c9b1d27 (Commits, GitHub, GitLab)  Commit:  c9b1d279fe791b8246e6df0efcf11a74375119f7 
Dependencies:  Stopgaps: 
Description
With the current 9.3.beta7
devel version there is
(/usr/share/texmfdist/tex/latex/xcite/xcite.sty Package: xcite 2020/01/21 v16383.99998 eXternal Citations (EG) (/usr/share/texmfdist/tex/latex/tools/xr.sty Package: xr 2019/07/22 v5.05 eXternal References (DPC) )) (/usr/share/texmfdist/tex/latex/hyperref/xrhyper.sty Package: xrhyper 2019/10/03 v6.1 eXternal References (DPC) ) Package xr Info: IMPORTING LABELS FROM ../references/references.aux on input li ne 66. Package xr Info: IMPORTING LABELS FROM ../references/references.aux on input li ne 68. LaTeX Warning: Label `../references/index:aagmrz2019' multiply defined.
when building the pdf docs. This appears in every latex generated .log
file.
Change History (29)
comment:1 Changed 16 months ago by
comment:2 Changed 16 months ago by
 Cc jhpalmieri added
comment:3 Changed 16 months ago by
No, perhaps the warnings are to be tolerated. At a very minimum local/share/doc/sage/pdf/en/reference/cryptography/cryptography.pdf
has undefined references with the change.
comment:4 followup: ↓ 9 Changed 16 months ago by
What happens if you delete \usepackage{xcite}
? (In addition to deleting \externalcitedocument
.) There is no reason to import this package:
The package xcite is no longer necessary, because its functionality has been taken over by xr, so this final version is just a stub that loads xr. (from https://ctan.org/pkg/xcite)
There is no reason to load both xr
and xrhyper
, because they both do the same thing. I do not understand why only one reference would be multiply defined, but maybe the problem is an incompatibility between these two packages.
It may also help to update to the latest version of xrhyper
(7.00j 20210210), or, at least, a newer version than 2019/10/03 v6.1.
comment:5 Changed 16 months ago by
Certainly not intended but even without addressing the multiply defined
warnings there are undefined references.
$ grep r "LaTeX Warning: Citation" local/share/doc/sage/latex/ local/share/doc/sage/latex/en/reference/coding/coding.log:LaTeX Warning: Citation `../graphs/../combinat/sage/combinat/matrices/hadamard_ local/share/doc/sage/latex/en/reference/algebras/algebras.log:LaTeX Warning: Citation `../graphs/../combinat/sage/combinat/sf/macdonald:macdo local/share/doc/sage/latex/en/reference/graphs/graphs.log:LaTeX Warning: Citation `../combinat/sage/combinat/matrices/hadamard_matrix:bh1 local/share/doc/sage/latex/en/reference/graphs/graphs.log:LaTeX Warning: Citation `../combinat/sage/combinat/matrices/hadamard_matrix:bh1 local/share/doc/sage/latex/en/reference/graphs/graphs.log:LaTeX Warning: Citation `../combinat/sage/combinat/matrices/hadamard_matrix:bh1 local/share/doc/sage/latex/en/reference/graphs/graphs.log:LaTeX Warning: Citation `../combinat/sage/combinat/matrices/hadamard_matrix:cp1 local/share/doc/sage/latex/en/reference/graphs/graphs.log:LaTeX Warning: Citation `../combinat/sage/combinat/designs/database:designhandb local/share/doc/sage/latex/en/reference/graphs/graphs.log:LaTeX Warning: Citation `../combinat/sage/combinat/matrices/hadamard_matrix:bh1 local/share/doc/sage/latex/en/reference/graphs/graphs.log:LaTeX Warning: Citation `../combinat/sage/combinat/matrices/hadamard_matrix:bh1 local/share/doc/sage/latex/en/reference/graphs/graphs.log:LaTeX Warning: Citation `../combinat/sage/combinat/matrices/hadamard_matrix:bh1 local/share/doc/sage/latex/en/reference/graphs/graphs.log:LaTeX Warning: Citation `../combinat/sage/combinat/matrices/hadamard_matrix:bh1 local/share/doc/sage/latex/en/reference/graphs/graphs.log:LaTeX Warning: Citation `../combinat/sage/combinat/matrices/hadamard_matrix:bh1 local/share/doc/sage/latex/en/reference/graphs/graphs.log:LaTeX Warning: Citation `../combinat/sage/combinat/matrices/hadamard_matrix:bh1 local/share/doc/sage/latex/en/reference/arithmetic_curves/arithmetic_curves.log:LaTeX Warning: Citation `../graphs/../combinat/sage/combinat/dyck_word:cha2005' local/share/doc/sage/latex/en/reference/categories/categories.log:LaTeX Warning: Citation `../graphs/../combinat/sage/combinat/root_system/hecke
comment:6 followup: ↓ 11 Changed 16 months ago by
A more serious problem is that the pdf docs don't build for me: I get an error in reference/stats
. From local/share/docs/sage/latex/en/reference/stats/stats.log
:
Chapter 8. ! TeX capacity exceeded, sorry [input stack size=5000]. \non@alpherr #1>\@latex@error {\string #1 allowed only in math mode}\@ehd l.2922 ...Samplers for \protect\(\ZZ[x]\protect\)} If you really absolutely need more capacity, you can ask a wizard to enlarge me.
comment:7 Changed 16 months ago by
reference/stats/stats.tex
does produce stats.pdf
here. I don't know what controls the stack size nor how to change it. From stats.log
I have
Here is how much of TeX's memory you used: 15408 strings out of 482818 241885 string characters out of 5956944 529798 words of memory out of 5000000 30147 multiletter control sequences out of 15000+600000 588142 words of font info for 119 fonts, out of 8000000 for 9000 37 hyphenation exceptions out of 8191 38i,13n,49p,908b,642s stack positions out of 5000i,500n,10000p,200000b,80000s
comment:8 Changed 16 months ago by
It doesn't build for me on two different OS X machines (one running Catalina 10.15, one running Big Sur 11.2), for what that's worth.
comment:9 in reply to: ↑ 4 Changed 16 months ago by
Replying to ghDaveWitteMorris:
What happens if you delete
\usepackage{xcite}
? (In addition to deleting\externalcitedocument
.) There is no reason to import this package:The package xcite is no longer necessary, because its functionality has been taken over by xr, so this final version is just a stub that loads xr. (from https://ctan.org/pkg/xcite)There is no reason to load both
xr
andxrhyper
, because they both do the same thing. I do not understand why only one reference would be multiply defined, but maybe the problem is an incompatibility between these two packages.It may also help to update to the latest version of
xrhyper
(7.00j 20210210), or, at least, a newer version than 2019/10/03 v6.1.
This performs much better for me. Of course I'm able to build things.

src/doc/en/reference/conf_sub.py
diff git a/src/doc/en/reference/conf_sub.py b/src/doc/en/reference/conf_sub.py index 28c95c69e4..eef8721bdd 100644
a b latex_documents = [ 67 67 ] 68 68 69 69 latex_elements['hyperref'] = r""" 70 \usepackage{xcite} 71 \usepackage{xrhyper} 70 \usepackage{xr} 72 71 \externaldocument[../references/]{../references/references} 73 \externalcitedocument[../references/]{../references/references}74 72 % Include hyperref last. 75 73 \usepackage{hyperref} 76 74 % Fix anchor placement for figures with captions.
There are no multiply defined
references and the references in local/share/doc/sage/pdf/en/reference/cryptography/cryptography.pdf
look correct. I still see the undefined references above which is another issue. My distro (gentoo) provides
xr.sty 2019/07/22 v5.05 eXternal References (DPC)
and
hyperref.sty 2020/01/14 v7.00d Hypertext links for LaTeX
comment:10 followup: ↓ 13 Changed 16 months ago by
I thought xrhyper
would be better, because it is distributed with hyperref
, and is therefore less likely to have a version clash, but xr
is probably more stable:
%% xrhyper package (beta release) ... %% This is a modified version of the xr package from the Standard LaTeX %% tools distribution. ... %% If no problems are reported the version in the tools distribution %% will be updated to match this at the next LaTeX release.
So using xr
is probably a good idea.
I tested the patch of comment:9 on Ubuntu 20.04 (CoCalc
) and had the good results, just the same 15 undefined references as in comment:5. I noticed that some Japanese fonts are missing (not surprising), and I also had 2 other LaTeX Warnings:
local/share/doc/sage/latex/en/installation/installation.log:LaTeX Warning: Hyper reference `index:installationguide' on page 6 undefined o local/share/doc/sage/latex/en/installation/installation.log:LaTeX Warning: Hyper reference `index:installationguide' on page 35 undefined
I will test on MacOS 10.15.
comment:11 in reply to: ↑ 6 ; followup: ↓ 14 Changed 16 months ago by
Replying to jhpalmieri:
A more serious problem is that the pdf docs don't build for me: ...
! TeX capacity exceeded, sorry [input stack size=5000]
...
In my experience, this error is almost always due to an infinite loop (such as \def\foo{\foo}
).
Did these results use a patch to conf_sub.py
? What are the versions of xr.sty
, xrhyper.sty
and hyperref.sty
that are reported in the TeX log?
comment:12 Changed 16 months ago by
Also, I wonder whether we are using the same commands to make the documentation. I did:
make docclean ./configure make docpdf
Should I be doing something else?
comment:13 in reply to: ↑ 10 Changed 16 months ago by
Replying to ghDaveWitteMorris:
I tested the patch of comment:9 on Ubuntu 20.04 (
CoCalc
) and had the good results, just the same 15 undefined references as in comment:5. I noticed that some Japanese fonts are missing (not surprising), and I also had 2 other LaTeX Warnings:
I believe I know how to deal with the 15 undefined references in comment:5. Additional references need to be added to src/doc/en/reference/references/index.rst
. But perhaps this should be another ticket?
comment:14 in reply to: ↑ 11 Changed 16 months ago by
Replying to ghDaveWitteMorris:
Replying to jhpalmieri:
A more serious problem is that the pdf docs don't build for me: ...
! TeX capacity exceeded, sorry [input stack size=5000]
...In my experience, this error is almost always due to an infinite loop (such as
\def\foo{\foo}
).Did these results use a patch to
conf_sub.py
? What are the versions ofxr.sty
,xrhyper.sty
andhyperref.sty
that are reported in the TeX log?
I've seen in on several machines with different branches, and I'm not patching anything.
/usr/local/texlive/2020/texmfdist/tex/latex/tools/xr.sty Package: xr 20200510 v5.06 eXternal References (DPC) /usr/local/texlive/2020/texmfdist/tex/latex/hyperref/xrhyper.sty package: xrhyper 20210207 v7.00h eXternal References (DPC) /usr/local/texlive/2020/texmfdist/tex/latex/hyperref/hyperref.sty Package: hyperref 20210207 v7.00h Hypertext links for LaTeX
I do
make docclean make doc # sometimes I include this, sometimes not, make no difference make docpdf
The complaint comes from the line
l.2922 ...Samplers for \protect\(\ZZ[x]\protect\)}
If I change this (for example, to "...Samplers for ZZ[x]", removing the math mode, the error goes away.
comment:15 Changed 16 months ago by
Please try the patch of comment:9. It worked for me on MacOS 10.15 (although I do get those same 15 missing citations). The original conf_sub.py
file is out of date, since it was written when xcite
was still needed, and it may be that xr
is conflicting with xrhyper
. I will try the unpatched conf_sub.py
on my mac.
My packages are:
/usr/local/texlive/2020/texmfdist/tex/latex/tools/xr.sty Package: xr 2019/07/22 v5.05 eXternal References (DPC) /usr/local/texlive/2020/texmfdist/tex/latex/hyperref/hyperref.sty Package: hyperref 2020/01/14 v7.00d Hypertext links for LaTeX
If the patch doesn't work for you, I will update xr
and hyperref
, to see if I get the same error as you, because the problem could be a bug in one of those packages. Hyperref is certainly active in that line.
comment:16 Changed 16 months ago by
The unpatched conf_sub.py
file worked for me on MacOS 10.15 (but I got the multiply defined label that was the original issue on this ticket). I will see what happens when I upgrade xr.sty
and hyperref.sty
.
I forgot to ask: what version of xcite.sty
do you have? I think mine is 2020/01/21 v16383.99998
comment:17 Changed 16 months ago by
Running pdflatex
on this file produces the same error for me:
\documentclass{report} \usepackage{hyperref} \newcommand{\ZZ}{\Bold{Z}} \newcommand{\Bold}[1]{\mathbf{#1}} \begin{document} \chapter{Discrete Gaussian Samplers for \protect\(\ZZ[x]\protect\)} testing \end{document}
More version information:
This is pdfTeX, Version 3.141592652.61.40.21 (TeX Live 2020) (preloaded format=pdflatex) restricted \write18 enabled. entering extended mode (./junk.tex LaTeX2e <20201001> patch level 4 L3 programming layer <20210206>
comment:18 followup: ↓ 20 Changed 16 months ago by
Thanks! That's very helpful (much faster to test than running a whole docbuild). The test file works for me, even after upgrading hyperref. (However, the upgrade of hyperref gave me hyperref 20210210 v7.00j
, which is not quite the same as yours.) The only issue (which is expected) is that the math in the chapter title gives a hyperref warning:
Package hyperref Warning: Token not allowed in a PDF string (Unicode): (hyperref) removing `math shift' on input line 8.
I assume that removing \usepackage{hyperref}
eliminates the error for you, so we know that the problem has something to do with hyperref. Please try changing the chapter
line to each of the following three variations:
\chapter{Discrete Gaussian Samplers for \texorpdfstring{\protect\(\ZZ[x]\protect\)}{Z[x]}}
\chapter{Discrete Gaussian Samplers for \(\ZZ[x]\)}
\chapter{Discrete Gaussian Samplers for $\ZZ[x]$}
My version info:
This is pdfTeX, Version 3.141592652.61.40.21 (TeX Live 2020) (preloaded format=pdflatex) restricted \write18 enabled. entering extended mode (./test.tex LaTeX2e <20200202> patch level 5 L3 programming layer <20200306>
I will try to upgrade to the latest version.
comment:19 Changed 16 months ago by
Switching between $
and \(
makes no difference, nor do the \protect
statements. Using \texorpdfstring
works, though. This works:
\documentclass{report} \usepackage{hyperref} \begin{document} \chapter{Testing \texorpdfstring{\(\mathbf{y}=4\)}{blah}} test \chapter{Testing \(\mathbf{x}=3\)} test \end{document}
This does not:
{{{ \documentclass{report} \usepackage{hyperref} \begin{document} \chapter{Testing \(\mathbf{x}=3\)} test \chapter{Testing \texorpdfstring{\(\mathbf{y}=4\)}{blah}} test \end{document} }}}
comment:20 in reply to: ↑ 18 Changed 16 months ago by
Replying to ghDaveWitteMorris:
Package hyperref Warning: Token not allowed in a PDF string (Unicode): (hyperref) removing `math shift' on input line 8.
I see the above as well with
hyperref.sty 2020/01/14 v7.00d Hypertext links for LaTeX
comment:21 Changed 16 months ago by
Now that I've upgraded Latex, I'm getting the results that jhpalmieri reported in comment:19. Changing the order of the chapters makes a difference, but I have no idea why.
comment:22 Changed 16 months ago by
comment:23 Changed 16 months ago by
And proposed as a bug at https://github.com/latex3/latex2e/issues/501
comment:24 Changed 16 months ago by
Anyway, I have no opinions on the subject of this ticket. I've created #31397 for the errors in building the PDF documents. Let's keep this ticket focused on the original cosmetic issues; sorry for derailing it in the first place.
comment:25 Changed 16 months ago by
 Branch set to u/strogdon/trac_31387
comment:26 Changed 16 months ago by
 Commit set to c9b1d279fe791b8246e6df0efcf11a74375119f7
 Status changed from new to needs_review
I will address the undefined references on another ticket.
New commits:
c9b1d27  cosmetic update to building the pdf docs

comment:27 Changed 16 months ago by
The undefined references
are now addressed on #31398.
comment:28 Changed 16 months ago by
 Priority changed from major to minor
 Reviewers set to Dave Morris
 Status changed from needs_review to positive_review
Thanks for fixing this.
comment:29 Changed 15 months ago by
 Branch changed from u/strogdon/trac_31387 to c9b1d279fe791b8246e6df0efcf11a74375119f7
 Resolution set to fixed
 Status changed from positive_review to closed
I'm not sure why
index:aagmrz2019
is the only reference that is multiply defined unless it is because it is the first reference insrc/doc/en/reference/references/index.rst
 the labels are imported twice. The following seems to get rid of the warningssrc/doc/en/reference/conf_sub.py
\externalcitedocument[../references/]{../references/references}I believe the
xrhyper
package aliases\externalcitedocument
to\externaldocument
. I haven't thoroughly tested this to determine if references are OK, but themultiply defined
warnings are not present.