#31387 closed defect (fixed)

Cosmetic update in building the pdf docs

Reported by: strogdon Owned by:
Priority: minor Milestone: sage-9.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:

Status badges

Description

With the current 9.3.beta7 devel version there is

(/usr/share/texmf-dist/tex/latex/xcite/xcite.sty
Package: xcite 2020/01/21 v16383.99998 eXternal Citations (EG)

(/usr/share/texmf-dist/tex/latex/tools/xr.sty
Package: xr 2019/07/22 v5.05 eXternal References (DPC)
))
(/usr/share/texmf-dist/tex/latex/hyperref/xr-hyper.sty
Package: xr-hyper 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 strogdon

I'm not sure why index:aagmrz2019 is the only reference that is multiply defined unless it is because it is the first reference in src/doc/en/reference/references/index.rst - the labels are imported twice. The following seems to get rid of the warnings

  • 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..be60aefdb1 100644
    a b latex_elements['hyperref'] = r""" 
    7070\usepackage{xcite}
    7171\usepackage{xr-hyper}
    7272\externaldocument[../references/]{../references/references}
    73 \externalcitedocument[../references/]{../references/references}
    7473% Include hyperref last.
    7574\usepackage{hyperref}
    7675% Fix anchor placement for figures with captions.

I believe the xr-hyper package aliases \externalcitedocument to \externaldocument. I haven't thoroughly tested this to determine if references are OK, but the multiply defined warnings are not present.

Last edited 16 months ago by strogdon (previous) (diff)

comment:2 Changed 16 months ago by strogdon

  • Cc jhpalmieri added

comment:3 Changed 16 months ago by strogdon

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.

Last edited 16 months ago by strogdon (previous) (diff)

comment:4 follow-up: Changed 16 months ago by gh-DaveWitteMorris

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 xr-hyper, 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 xr-hyper (7.00j 2021-02-10), or, at least, a newer version than 2019/10/03 v6.1.

comment:5 Changed 16 months ago by strogdon

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 follow-up: Changed 16 months ago by jhpalmieri

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 strogdon

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 jhpalmieri

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 strogdon

Replying to gh-DaveWitteMorris:

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 xr-hyper, 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 xr-hyper (7.00j 2021-02-10), 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 = [ 
    6767]
    6868
    6969latex_elements['hyperref'] = r"""
    70 \usepackage{xcite}
    71 \usepackage{xr-hyper}
     70\usepackage{xr}
    7271\externaldocument[../references/]{../references/references}
    73 \externalcitedocument[../references/]{../references/references}
    7472% Include hyperref last.
    7573\usepackage{hyperref}
    7674% 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 follow-up: Changed 16 months ago by gh-DaveWitteMorris

I thought xr-hyper 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:

%% xr-hyper 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:installation-guide' on page 6 undefined o
local/share/doc/sage/latex/en/installation/installation.log:LaTeX Warning: Hyper reference `index:installation-guide' on page 35 undefined 

I will test on MacOS 10.15.

comment:11 in reply to: ↑ 6 ; follow-up: Changed 16 months ago by gh-DaveWitteMorris

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, xr-hyper.sty and hyperref.sty that are reported in the TeX log?

comment:12 Changed 16 months ago by gh-DaveWitteMorris

Also, I wonder whether we are using the same commands to make the documentation. I did:

make doc-clean
./configure
make doc-pdf

Should I be doing something else?

comment:13 in reply to: ↑ 10 Changed 16 months ago by strogdon

Replying to gh-DaveWitteMorris:

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?

Last edited 16 months ago by strogdon (previous) (diff)

comment:14 in reply to: ↑ 11 Changed 16 months ago by jhpalmieri

Replying to gh-DaveWitteMorris:

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, xr-hyper.sty and hyperref.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/texmf-dist/tex/latex/tools/xr.sty
Package: xr 2020-05-10 v5.06 eXternal References (DPC)

/usr/local/texlive/2020/texmf-dist/tex/latex/hyperref/xr-hyper.sty
package: xr-hyper 2021-02-07 v7.00h eXternal References (DPC)

/usr/local/texlive/2020/texmf-dist/tex/latex/hyperref/hyperref.sty
Package: hyperref 2021-02-07 v7.00h Hypertext links for LaTeX

I do

make doc-clean
make doc # sometimes I include this, sometimes not, make no difference
make doc-pdf

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 gh-DaveWitteMorris

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 xr-hyper. I will try the unpatched conf_sub.py on my mac.

My packages are:

/usr/local/texlive/2020/texmf-dist/tex/latex/tools/xr.sty
Package: xr 2019/07/22 v5.05 eXternal References (DPC)

/usr/local/texlive/2020/texmf-dist/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 gh-DaveWitteMorris

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 jhpalmieri

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.14159265-2.6-1.40.21 (TeX Live 2020) (preloaded format=pdflatex)
 restricted \write18 enabled.
entering extended mode
(./junk.tex
LaTeX2e <2020-10-01> patch level 4
L3 programming layer <2021-02-06>

comment:18 follow-up: Changed 16 months ago by gh-DaveWitteMorris

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 2021-02-10 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.14159265-2.6-1.40.21 (TeX Live 2020) (preloaded format=pdflatex)
 restricted \write18 enabled.
entering extended mode
(./test.tex
LaTeX2e <2020-02-02> patch level 5
L3 programming layer <2020-03-06>

I will try to upgrade to the latest version.

comment:19 Changed 16 months ago by jhpalmieri

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 strogdon

Replying to gh-DaveWitteMorris:

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 gh-DaveWitteMorris

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:23 Changed 16 months ago by jhpalmieri

comment:24 Changed 16 months ago by jhpalmieri

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 strogdon

  • Branch set to u/strogdon/trac_31387

comment:26 Changed 16 months ago by strogdon

  • Authors set to Steven Trogdon
  • Commit set to c9b1d279fe791b8246e6df0efcf11a74375119f7
  • Status changed from new to needs_review

I will address the undefined references on another ticket.


New commits:

c9b1d27cosmetic update to building the pdf docs

comment:27 Changed 16 months ago by strogdon

The undefined references are now addressed on #31398.

comment:28 Changed 16 months ago by gh-DaveWitteMorris

  • 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 vbraun

  • Branch changed from u/strogdon/trac_31387 to c9b1d279fe791b8246e6df0efcf11a74375119f7
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.