Fixing JAIR style

Question

According to the Eigenfactor ranking of journals, the Journal of Artificial Intelligence Research (JAIR) is a leading open-access journal in AI. Unfortunately, the JAIR style files are twenty years old and break horribly when trying to use hyperref. This particular error seems due to the shipped theapa styles which jair.sty depends on.

I have spent several hours trying to understand and fix the errors, but this seems to require a higher skill level of LaTeX hacking than I have attained. To replicate the problem, add \usepackage{hyperref} to the preamble of the provided sample.tex input file, then run LaTeX, BibTeX, LaTeX; the next and final run of LaTeX (to resolve the dangling references) then fails with

! Undefined control sequence.  
\hyper@@link ->\let \Hy@reserved@a   
                                   \relax \@ifnextchar [{\hyper@link@ }{\hyp...  
l.65 ...d graph partitioning problems \cite{papad}  
                                                  .  

at the very first place in the file where \cite{} is used. Note that if hyperref is not used, then these errors go away; packages like url or tikz work fine. If the bibliography commands are removed, then the error also goes away. A similar error occurs when changing \bibliographystyle{theapa} to standard bibliography styles, such as short:

! Use of \@year@ doesn't match its definition.
\Y@papad ->\@year@ J
                    PY
l.65 ...d graph partitioning problems \cite{papad}
                                                  .

Finally, if one removes the \usepackage{theapa} from the document preamble, then the problem goes away (except that \shortcite{} and other theapa macros are now undefined). I have even tried to use a different version of theapa.sty from the custom one that is shipped with jair.sty but this seems to give the same problems.

Does anyone have ideas about what to change in the jair.sty style file to avoid this problem? If we can track down the issue then I would be happy to work on a patch to submit to JAIR. It would be nice to help this volunteer-run journal to support bibliographies with internal links and hyperlinks to articles in the bibliography, as publishers like Elsevier do.

Answer 1

You can get a bit of the functionality you want by inserting the hyperref package as shown in the minimal below (these settings worked with the sample2e.tex example file in the JAIR folder).

\documentclass[jair,twoside,11pt,theapa]{article}
\usepackage[bookmarks=true]{hyperref}
\hypersetup{%
    bookmarks=false,    % show bookmarks bar?
    pdftitle={TeX and friends hackers manual},    % title
    pdfauthor={Yiannis Lazarides},                     % author
    pdfsubject={TeX and LaTeX},                        % subject of the document
    pdfkeywords={TeX, LaTeX, graphics, images}, % list of keywords
    colorlinks=true,       % false: boxed links; true: colored links
    linkcolor=blue,       % color of internal links
    citecolor=black,       % color of links to bibliography
    filecolor=black,        % color of file links
    urlcolor=purple,        % color of external links
    linktoc=page            % only page is linked
}
\usepackage{jair, theapa, rawfonts}

\jairheading{1}{1993}{1-15}{6/91}{9/91}
\ShortHeadings{Minimizing Conflicts: A Heuristic Repair Method}
{Minton, Philips, Johnston, \& Laird}
\firstpageno{25}

\begin{document}
\section{One}\label{sec:one}
\section{Three}
  In Section \ref{sec:one}, we referenced \ldots
\section{Four}
  Some more text.
\end{document}

However, as you correctly pointed out the class files are in need of an overhaul for screen viewing. In print the style offers an outstanding style for a journal article. I would suggest the following approach.

1. Copy the basic .cls into a .dtx file so that you can document the changes.
2. Aim for immediate functionality first without any bibliography and citations.
3. Declare an option 'oldclass' or similar to switch on the old style files for backward compatibility.
4. Ensure everything works without any errors up to this point.
5. Upgrade the class to BiblateX, so that the class will survive another possibly 20 years, which by that time AI would have advanced enough to take over from that point onward!

The advantage of this approach, you will ensure backwards compatibility and you can make incremental improvements in a better way. Budget 1-2 weeks full time work, if you fairly well versed with LaTeX.

Answer 2

I have suffered the same compatibility problems when writing a JAIR article. It turns out that theapa can be made mostly compatible with hyperref with a little effort in your preamble:

• The loading order is important: first hyperref, then refstyle (or your cross reference package of choice, which may require to be loaded before hyperref), and last jair and theapa. In this way, we can enable hyperref support for hyperlinks, hyperlinked cross references, bookmarks, PDF attributes and PDF layout:

%use this command unless it is already invoked earlier in the preamble
\makeatletter

\usepackage[implicit=true,unicode=true,
 bookmarks=true,bookmarksnumbered=true,bookmarksopen=true]
 {hyperref}
\hypersetup{
  pdftitle={my title},
  pdfauthor={my name},
  pdfsubject={my subject},
  pdfkeywords={my keywords},
  %all links are black to preserve the appearance of a printed paper
  colorlinks=true,
  allcolors=black,
  pdfpagelayout=OneColumn,
  pdfnewwindow=true,
}

\usepackage{refstyle}

%we also use the package rawfonts because this this is copied verbatim
%from the JAIR author kit (http://www.jair.org)
\usepackage{jair, theapa, rawfonts}

• After loading these packages, we still have not hyperlink support for the citations. We have to redefine an internal command from theapa, and define new commands equivalent to the citation commands of theapa:

%load this package unless you have loaded it earlier
\usepackage{ifpdf}

%only the pdflatex driver can handle hyperlinks that break across lines
%(as citations often do) so we define them only when using pdflatex
\ifpdf

  %we add hyperref support with the commands \hyper@natanchorstart and \hyper@natanchorend
  \def\@lbibitem[#1]#2{\def\BBA{\BBAA}\item[\hyper@natanchorstart{#2}\@biblabel{#1}\hyper@natanchorend]\if@filesw
        { \def\BBA{\string\BBA}%
          \def\protect##1{\string ##1\space}\immediate
          \write\@auxout{\string\bibcite{#2}{#1}}%
    \def\BBA{\BBAA}}\fi\ignorespaces}

  %load this package unless you have loaded it earlier
  \usepackage{ifthen}

  %new citation commands. Add more as needed, using the existing ones as templates
  %hyperref support is added by using the commands \hyper@natlinkstart and \hyper@natlinkend
  \newcommand{\mshortcite}[2][]{\hyper@natlinkstart{#2}\ifthenelse{\equal{#1}{}}{\shortcite{#2}}{\shortcite[#1]{#2}}\hyper@natlinkend}
  \newcommand{\mshortciteA}[2][]{\hyper@natlinkstart{#2}\ifthenelse{\equal{#1}{}}{\shortciteA{#2}}{\shortciteA[#1]{#2}}\hyper@natlinkend}
  \newcommand{\mfullciteA}[2][]{\hyper@natlinkstart{#2}\ifthenelse{\equal{#1}{}}{\fullciteA{#2}}{\fullciteA[#1]{#2}}\hyper@natlinkend}
  \newcommand{\mshortciteR}[2][]{\hyper@natlinkstart{#2}\ifthenelse{\equal{#1}{}}{\shortciteR{#2}}{\shortciteR[#1]{#2}}\hyper@natlinkend}
  \newcommand{\mciteyear}[2][]{\hyper@natlinkstart{#2}\ifthenelse{\equal{#1}{}}{\citeyear{#2}}{\citeyear[#1]{#2}}\hyper@natlinkend}
  \newcommand{\mciteyearR}[2][]{\hyper@natlinkstart{#2}\ifthenelse{\equal{#1}{}}{\citeyearR{#2}}{\citeyearR[#1]{#2}}\hyper@natlinkend}
  \newcommand{\mshortciteS}[2][]{\hyper@natlinkstart{#2}\ifthenelse{\equal{#1}{}}{\shortciteS{#2}}{\shortciteS[#1]{#2}}\hyper@natlinkend}
  \newcommand{\mshortciteauthor}[1]{\hyper@natlinkstart{#1}\shortciteauthor{#1}\hyper@natlinkend}
  \newcommand{\mfullciteauthor}[1]{\hyper@natlinkstart{#1}\fullciteauthor{#1}\hyper@natlinkend}

\else

  %default definitions when not using pdflatex
  \let\mcite\shortcite
  \let\mcitea\shortciteA
  \let\mcitear\fullciteA
  \let\mciter\shortciteR
  \let\mciteyear\citeyear
  \let\mciteyearr\citeyearR
  \let\mcites\shortciteS
  \let\mciteauthor\shortciteauthor
  \let\mciteauthorr\fullciteauthor
  \let\mcitetable\mciter

\fi

%use this command unless it is already invoked later in the preamble
\makeatother

And that's it!

Using these code snippets in your preamble will enable almost full hyperref support in your JAIR articles. Beware that some theapa functionality is missing in the new citation commands, such as optional arguments in angle brackets, or citing more than one reference with a single citation command.

If you just want to use theapa without jair, just substitute

\usepackage{jair, theapa, rawfonts}

by

\usepackage{theapa}

UPDATE: It has been brought to my attention that this solution only worked with pdflatex, but not for producing DVI->PS, because the DVI driver is unable to handle links in citations that break across lines. The solution is to enable the new citation commands only for pdflatex using ifpdf. The code has been updated accordingly.

Answer 3

It turns out that

\usepackage[implicit=false]{hyperref}

is enough to stop hyperref and the JAIR styles from stomping on each other. This is even with JAIR's BibTeX style file modified by urlbst to support DOI fields and inline hyperlinked URLs.

Option implicit=false prevents the hyperref package from redefining some LaTeX internals, according to the documentation. With implicit=false the hyperlinks within the document also seem to be omitted, but that is not so important for me.

Answer 4

I got this problem when using apacite package and hyperref package simultaneously. With the error message

! Undefined control sequence.  
\hyper@@link ->\let \Hy@reserved@a   
                                   \relax \@ifnextchar [{\hyper@link@ }{\hyp...  
l.65 ...d graph partitioning problems \cite{xxxx}

It turned out that I had put \usepackage{apacite} before \usepackage{hyperref}. I just moved \usepackage{hyperref} before \usepackage{apacite} and everything works for me now.