Using hyperref in iucr package will trigger some errors.

[hongyi-zhao]

Currently, I'm using the iucr package to write a paper, but I find the following setting with hyperref will trigger a compile error:

\usepackage[unicode=true,
 bookmarks=true,bookmarksnumbered=false,bookmarksopen=false,
 breaklinks=false,pdfborder={0 0 0},pdfborderstyle={},backref=false,colorlinks=true]
 {hyperref}

The error is as follows:

ERROR: LaTeX Error: Missing \begin{document}.

--- TeX said ---

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.32 
     
--- HELP ---
LaTeX produced printed output before encountering a \begin{document}
command. Either you forgot the \begin{document} command or there is
something wrong in the preamble. The problem may be a stray character
or an error in a declaration---for example, omitting the braces around
an argument or forgetting the \ in a command name.

But if I use it as follows, the error will disappear:

\usepackage{hyperref}

Any tips for fixing the problem with more options?

Regards,
Zhao

[davidcarlisle]

please provide a complete example and show your full log.

this gives no error with pdflatex or latex in texlive 2023

\documentclass{iucr}
\usepackage[unicode=true,
 bookmarks=true,bookmarksnumbered=false,bookmarksopen=false,
 breaklinks=false,pdfborder={0 0 0},pdfborderstyle={},backref=false,colorlinks=true]
 {hyperref}
\begin{document}

\end{document}

[u-fischer]

you are probably already loading hyperref before (with other options).

[hongyi-zhao]

@davidcarlisle For your example, the same error still occurs in my case:

$ cat test.tex 
\documentclass{iucr}
\usepackage[unicode=true,
 bookmarks=true,bookmarksnumbered=false,bookmarksopen=false,
 breaklinks=false,pdfborder={0 0 0},pdfborderstyle={},backref=false,colorlinks=true]
 {hyperref}
\begin{document}

 This is a test!

\end{document}

$ pdflatex test.tex 
This is pdfTeX, Version 3.141592653-2.6-1.40.25 (TeX Live 2023) (preloaded format=pdflatex)
 restricted \write18 enabled.
entering extended mode
(./test.tex
LaTeX2e <2022-11-01> patch level 1
L3 programming layer <2023-04-20> (./iucr.cls
Document Class: iucr 2021/03/05 IUCr article/chapter class
(/opt/texlive/2023/texmf-dist/tex/latex/tools/multicol.sty)
(/opt/texlive/2023/texmf-dist/tex/latex/psnfss/times.sty)
(/opt/texlive/2023/texmf-dist/tex/latex/graphics/graphics.sty
(/opt/texlive/2023/texmf-dist/tex/latex/graphics/trig.sty)
(/opt/texlive/2023/texmf-dist/tex/latex/graphics-cfg/graphics.cfg)
(/opt/texlive/2023/texmf-dist/tex/latex/graphics-def/dvips.def))
(/opt/texlive/2023/texmf-dist/tex/latex/float/float.sty)
(/opt/texlive/2023/texmf-dist/tex/latex/tools/tabularx.sty
(/opt/texlive/2023/texmf-dist/tex/latex/tools/array.sty))
(/opt/texlive/2023/texmf-dist/tex/generic/dvips/colordvi.tex)
(/opt/texlive/2023/texmf-dist/tex/latex/base/article.cls
Document Class: article 2022/07/02 v1.4n Standard LaTeX document class
(/opt/texlive/2023/texmf-dist/tex/latex/base/size10.clo))
(/opt/texlive/2023/texmf-dist/tex/latex/harvard/harvard.sty
(/opt/texlive/2023/texmf-dist/tex/latex/base/ifthen.sty)
(/opt/texlive/texmf-local/tex/latex/html/html.sty
(/opt/texlive/2023/texmf-dist/tex/latex/hyperref/hyperref.sty
(/opt/texlive/2023/texmf-dist/tex/generic/ltxcmds/ltxcmds.sty)
(/opt/texlive/2023/texmf-dist/tex/generic/iftex/iftex.sty)
(/opt/texlive/2023/texmf-dist/tex/generic/pdftexcmds/pdftexcmds.sty
(/opt/texlive/2023/texmf-dist/tex/generic/infwarerr/infwarerr.sty))
(/opt/texlive/2023/texmf-dist/tex/latex/graphics/keyval.sty)
(/opt/texlive/2023/texmf-dist/tex/latex/kvsetkeys/kvsetkeys.sty)
(/opt/texlive/2023/texmf-dist/tex/generic/kvdefinekeys/kvdefinekeys.sty)
(/opt/texlive/2023/texmf-dist/tex/generic/pdfescape/pdfescape.sty)
(/opt/texlive/2023/texmf-dist/tex/latex/hycolor/hycolor.sty)
(/opt/texlive/2023/texmf-dist/tex/latex/letltxmacro/letltxmacro.sty)
(/opt/texlive/2023/texmf-dist/tex/latex/auxhook/auxhook.sty)
(/opt/texlive/2023/texmf-dist/tex/latex/hyperref/nameref.sty
(/opt/texlive/2023/texmf-dist/tex/latex/refcount/refcount.sty)
(/opt/texlive/2023/texmf-dist/tex/generic/gettitlestring/gettitlestring.sty
(/opt/texlive/2023/texmf-dist/tex/latex/kvoptions/kvoptions.sty)))
(/opt/texlive/2023/texmf-dist/tex/latex/etoolbox/etoolbox.sty)
(/opt/texlive/2023/texmf-dist/tex/latex/hyperref/pd1enc.def)
(/opt/texlive/2023/texmf-dist/tex/generic/intcalc/intcalc.sty)
(/opt/texlive/2023/texmf-dist/tex/latex/hyperref/puenc.def)
(/opt/texlive/2023/texmf-dist/tex/latex/url/url.sty)
(/opt/texlive/2023/texmf-dist/tex/generic/bitset/bitset.sty
(/opt/texlive/2023/texmf-dist/tex/generic/bigintcalc/bigintcalc.sty))
(/opt/texlive/2023/texmf-dist/tex/latex/base/atbegshi-ltx.sty))
(/opt/texlive/2023/texmf-dist/tex/latex/hyperref/hpdftex.def
(/opt/texlive/2023/texmf-dist/tex/latex/base/atveryend-ltx.sty)
(/opt/texlive/2023/texmf-dist/tex/latex/rerunfilecheck/rerunfilecheck.sty
(/opt/texlive/2023/texmf-dist/tex/generic/uniquecounter/uniquecounter.sty)))))
FONT WARNINGS CAN USUALLY BE IGNORED. IF YOU EXPERIENCE
PROBLEMS WITH FONTS, USE THE [preprint] OPTION
(/opt/texlive/2023/texmf-dist/tex/latex/psnfss/ot1ptmcm.fd)
(/opt/texlive/2023/texmf-dist/tex/latex/psnfss/omlptmcm.fd)
(/opt/texlive/2023/texmf-dist/tex/latex/psnfss/ot1ptm.fd))

! LaTeX Error: Missing \begin{document}.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.6 \begin
          {document}
? 

[muzimuzhi]

$ cat test.tex 
\documentclass{iucr}
\usepackage[unicode=true,
 bookmarks=true,bookmarksnumbered=false,bookmarksopen=false,
 breaklinks=false,pdfborder={0 0 0},pdfborderstyle={},backref=false,colorlinks=true]
 {hyperref}
\begin{document}

 This is a test!

\end{document}

I can't reproduce the error with latest iucr.cls (2.1.16, 2021-11-03, downloaded from https://www.iucr.org/__data/iucr/ftp/templates/latex/iucr.cls). Notice that your stdout contains

(/opt/texlive/texmf-local/tex/latex/html/html.sty
(/opt/texlive/2023/texmf-dist/tex/latex/hyperref/hyperref.sty
...

but in latest iucr.cls, html is not loaded, hence hyperref is not loaded by the class.

%% iucr.cls, lines 730--734
%% 
% ================ load additional required packages =========================
% (harvard.sty loads html.sty if present, which uses counters defined in
%  article.cls)
% \RequirePackage{html}
\RequirePackage{harvard}

From the changelog found in beginning lines in iucr.cls, one can also see

%   2.0beta8                                                                 %
%          2002-04-11  Backed out RequirePackage{html}: not reqd in TeXLive6 %
%          ...
%   2.0beta7                                                                 %
%          ...
%   2.0beta6                                                                 %
%          2001-10-25  Added RequirePackage{html} ahead of                   %
%                      RequirePackage{harvard} to cure dependency problems   %
%                      of these two packages that call each other            %

[u-fischer]

Either use a newer version of the class, or use \PassOptionsToPackage{....}{hyperref} before loading the class to pass additional options.

[hongyi-zhao]

@muzimuzhi

(/opt/texlive/texmf-local/tex/latex/html/html.sty
(/opt/texlive/2023/texmf-dist/tex/latex/hyperref/hyperref.sty
...

Thank you for your valuable clues. The texmf-local directory was not removed during the TeXLive update process. However, after removing this directory, the problem disappeared.

werner@X10DAi:/opt/texlive$ sudo rm -fr texmf-local/

werner@X10DAi:~/Desktop/iucr/latex$ cat test.tex 
\documentclass{iucr}
\usepackage[unicode=true,
  bookmarks=true,bookmarksnumbered=false,bookmarksopen=false,
  breaklinks=false,pdfborder={0 0 0},pdfborderstyle={},backref=false,colorlinks=true]
  {hyperref}
\begin{document}

\end{document}


werner@X10DAi:~/Desktop/iucr/latex$ pdflatex test.tex 
This is pdfTeX, Version 3.141592653-2.6-1.40.25 (TeX Live 2023) (preloaded format=pdflatex)
 restricted \write18 enabled.
entering extended mode
(./test.tex
LaTeX2e <2022-11-01> patch level 1
L3 programming layer <2023-04-20> (./iucr.cls
Document Class: iucr 2021/03/05 IUCr article/chapter class
(/opt/texlive/2023/texmf-dist/tex/latex/tools/multicol.sty)
(/opt/texlive/2023/texmf-dist/tex/latex/psnfss/times.sty)
(/opt/texlive/2023/texmf-dist/tex/latex/graphics/graphics.sty
(/opt/texlive/2023/texmf-dist/tex/latex/graphics/trig.sty)
(/opt/texlive/2023/texmf-dist/tex/latex/graphics-cfg/graphics.cfg)
(/opt/texlive/2023/texmf-dist/tex/latex/graphics-def/dvips.def))
(/opt/texlive/2023/texmf-dist/tex/latex/float/float.sty)
(/opt/texlive/2023/texmf-dist/tex/latex/tools/tabularx.sty
(/opt/texlive/2023/texmf-dist/tex/latex/tools/array.sty))
(/opt/texlive/2023/texmf-dist/tex/generic/dvips/colordvi.tex)
(/opt/texlive/2023/texmf-dist/tex/latex/base/article.cls
Document Class: article 2022/07/02 v1.4n Standard LaTeX document class
(/opt/texlive/2023/texmf-dist/tex/latex/base/size10.clo))
(/opt/texlive/2023/texmf-dist/tex/latex/harvard/harvard.sty
(/opt/texlive/2023/texmf-dist/tex/latex/base/ifthen.sty))
FONT WARNINGS CAN USUALLY BE IGNORED. IF YOU EXPERIENCE
PROBLEMS WITH FONTS, USE THE [preprint] OPTION
(/opt/texlive/2023/texmf-dist/tex/latex/psnfss/ot1ptmcm.fd)
(/opt/texlive/2023/texmf-dist/tex/latex/psnfss/omlptmcm.fd)
(/opt/texlive/2023/texmf-dist/tex/latex/psnfss/ot1ptm.fd))
(/opt/texlive/2023/texmf-dist/tex/latex/hyperref/hyperref.sty
(/opt/texlive/2023/texmf-dist/tex/generic/ltxcmds/ltxcmds.sty)
(/opt/texlive/2023/texmf-dist/tex/generic/iftex/iftex.sty)
(/opt/texlive/2023/texmf-dist/tex/generic/pdftexcmds/pdftexcmds.sty
(/opt/texlive/2023/texmf-dist/tex/generic/infwarerr/infwarerr.sty))
(/opt/texlive/2023/texmf-dist/tex/latex/graphics/keyval.sty)
(/opt/texlive/2023/texmf-dist/tex/latex/kvsetkeys/kvsetkeys.sty)
(/opt/texlive/2023/texmf-dist/tex/generic/kvdefinekeys/kvdefinekeys.sty)
(/opt/texlive/2023/texmf-dist/tex/generic/pdfescape/pdfescape.sty)
(/opt/texlive/2023/texmf-dist/tex/latex/hycolor/hycolor.sty)
(/opt/texlive/2023/texmf-dist/tex/latex/letltxmacro/letltxmacro.sty)
(/opt/texlive/2023/texmf-dist/tex/latex/auxhook/auxhook.sty)
(/opt/texlive/2023/texmf-dist/tex/latex/hyperref/nameref.sty
(/opt/texlive/2023/texmf-dist/tex/latex/refcount/refcount.sty)
(/opt/texlive/2023/texmf-dist/tex/generic/gettitlestring/gettitlestring.sty
(/opt/texlive/2023/texmf-dist/tex/latex/kvoptions/kvoptions.sty)))
(/opt/texlive/2023/texmf-dist/tex/latex/etoolbox/etoolbox.sty)
(/opt/texlive/2023/texmf-dist/tex/latex/hyperref/pd1enc.def)
(/opt/texlive/2023/texmf-dist/tex/generic/intcalc/intcalc.sty)
(/opt/texlive/2023/texmf-dist/tex/latex/hyperref/puenc.def)
(/opt/texlive/2023/texmf-dist/tex/latex/url/url.sty)
(/opt/texlive/2023/texmf-dist/tex/generic/bitset/bitset.sty
(/opt/texlive/2023/texmf-dist/tex/generic/bigintcalc/bigintcalc.sty))
(/opt/texlive/2023/texmf-dist/tex/latex/base/atbegshi-ltx.sty))
(/opt/texlive/2023/texmf-dist/tex/latex/hyperref/hpdftex.def
(/opt/texlive/2023/texmf-dist/tex/latex/base/atveryend-ltx.sty)
(/opt/texlive/2023/texmf-dist/tex/latex/rerunfilecheck/rerunfilecheck.sty
(/opt/texlive/2023/texmf-dist/tex/generic/uniquecounter/uniquecounter.sty)))
(/opt/texlive/2023/texmf-dist/tex/latex/l3backend/l3backend-pdftex.def)
No file test.aux.
Beginning to process article (iucr) 
(/opt/texlive/2023/texmf-dist/tex/latex/graphics/color.sty
(/opt/texlive/2023/texmf-dist/tex/latex/graphics-cfg/color.cfg)
(/opt/texlive/2023/texmf-dist/tex/latex/graphics-def/pdftex.def
(/opt/texlive/2023/texmf-dist/tex/context/base/mkii/supp-pdf.mkii
[Loading MPS to PDF converter (version 2006.09.02).]
)) (/opt/texlive/2023/texmf-dist/tex/latex/graphics/mathcolor.ltx))
(/opt/texlive/2023/texmf-dist/tex/latex/epstopdf-pkg/epstopdf-base.sty
(/opt/texlive/2023/texmf-dist/tex/latex/latexconfig/epstopdf-sys.cfg))
Finished processing article
(/opt/texlive/2023/texmf-dist/tex/latex/psnfss/ot1ppl.fd)
Underfull \vbox (badness 10000) has occurred while \output is active
Overfull \vbox (18.0pt too high) has occurred while \output is active
Overfull \vbox (25.37831pt too high) has occurred while \output is active
Overfull \hbox (1.90002pt too wide) has occurred while \output is active
 []
[1
Non-PDF special ignored!
<special> papersize=614.295pt,794.96999pt
{/opt/texlive/2023/texmf-var/fonts/map/pdftex/updmap/pdftex.map}{/opt/texlive/2
023/texmf-dist/fonts/enc/dvips/base/8r.enc}] (./test.aux)

Package rerunfilecheck Warning: File `test.out' has changed.
(rerunfilecheck)                Rerun to get outlines right
(rerunfilecheck)                or use package `bookmark'.

 )
(see the transcript file for additional information)</opt/texlive/2023/texmf-di
st/fonts/type1/public/amsfonts/cm/cmsy7.pfb></opt/texlive/2023/texmf-dist/fonts
/type1/urw/palatino/uplb8a.pfb></opt/texlive/2023/texmf-dist/fonts/type1/urw/pa
latino/uplr8a.pfb>
Output written on test.pdf (1 page, 30789 bytes).
Transcript written on test.log.

[hongyi-zhao]

Now, I try to test the official iucr template.ltx and a new problem ! LaTeX Error: \caption outside float occurs. See the attached files for more information.

template.zip

[muzimuzhi]

Both hyperref and iucr redefines \caption. iucr also redefines float environments (figure and table) which only work with its own \caption. You can add

\usepackage{etoolbox}
\csdef{hyper@nopatch@caption}{}

before loading hyperref to suppress the redefinition of \caption on hyperref's side. Note by doing this references to (labels to) captions will create broken internal links.

It seems iucr wants to be compatible with hyperref, but its \caption and float environments (re)implementations break conditions which are held for at least standard document classes. I'm not sure if hyperref is a must when using iucr.

BTW I recommend uploading log instead of stdout. Log file contains more info.

Explanation on the error ! LaTeX Error: \caption outside float.

In standard document classes, \@captype is only defined in float environments. Once defined, it holds the float type, initially either figure or table. Then \caption checks if \@captype is defined. If not, error ! LaTeX Error: \caption outside float. is thrown to warn user \caption is designed to be used only inside float environments. If defined, the value of \@captype is used to step corresponding counter and compose the caption title.

iucr redefines figure and table environments and \caption in a way that \@captype is never defined and used. But when hyperref is loaded, \caption is redefined back to a variant using \@captype, which results in the error.

[hongyi-zhao]

Note by doing this references to (labels to) captions will create broken internal links.

If so, what's the function of your suggested workaround?

I wonder whether there is a way to completely replace the original implementation in the package without revising its source code, aka, a monkey patching like solution.

BTW I recommend uploading log instead of stdout. Log file contains more info.

Updated.

Explanation on the error ! LaTeX Error: \caption outside float.

How to fix the problem from the perspective of the package files?

[hongyi-zhao]

Another problem I noticed that is the fig1.ps file doesn't get embedded in the out PDF file at all:

template.pdf

[u-fischer]

Sorry but the hyperref bug tracker is not the right place to debug a journal class. Please contact the authors of the class.

[hongyi-zhao]

For the sake of completeness of this discussion, I would like to forward the reply from the package developer here:

Dear Zhao

Thank you very much for the link to the discussion on github, which
is very useful. I have now been able to reproduce the problem with
a fresh installation of texlive-2023.

iucr.cls is now a very old package, and was originally designed
before PDF became the usual final document format. The hyperlinking
options introduced by pdflatex and hyperref conflict with some
of the earliest design decisions when the class file was written
(as you have discovered) and the continuing development of hyperref
can introduce new conflicts.

We do not actually use LaTeX for typesetting the journals.
Input LaTeX files are converted to SGML (a publishing industry standard)
which is used in our typesetting process. During this conversion, some
of the features supported by LaTeX are lost. Active hyperlinking is one
of these; so hyperref is not needed.

However, here is one possible workaround:

\documentclass{iucr}

\let\IUCrcaption\caption
\usepackage[unicode=true,
bookmarks=true,bookmarksnumbered=false,bookmarksopen=false,
breaklinks=false,pdfborder={0 0
0},pdfborderstyle={},backref=false,colorlinks=true]
{hyperref}
\let\caption\IUCrcaption

\begin{document}

This has the effect of temporarily storing the definition of \caption
in a new macro (which we call \IUCrcaption), and then restoring it
after the redefinition that occurs when hyperref is loaded.

I hope this helps.

Kind regards
Brian

(Note also that pdflatex uses a different processing engine from latex,
which is why .ps files are not embedded. pdflatex supports graphics in
jpg, tiff, png or pdf formats.)