# Fixing JAIR style

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 appear to be nearly twenty years old, and breaks horribly, for instance when trying to use hyperref, possibly due to problems with the shipped theapa styles on which it appears to rely.

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.
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.
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 already do.

-
Imho it isn't worth to patch theapa. Better switch to biblatex and reimplement the bibliography styles and commands with its tools. Beside solving the hyperref issues it will also give you better unicode/utf8 support (with biber). –  Ulrike Fischer Feb 3 '12 at 14:04
@UlrikeFischer: Moving to Biblatex would be awesome, but decrease the odds of an update being accepted. It's still new, and there are an awful lot of old TeX distributions out there. If both were made available... –  qubyte Feb 3 '12 at 14:34
Have you tried loading the natbib package as well? It might provide just enough functionality to keep hyperref from blowing up. –  Mico Feb 3 '12 at 15:24
Such old TeX-system will also contain quite old hyperref version. Do you want to support them too? Btw: you could also try either to load theapa after hyperref or to use the trick mentioned in readme.pdf to get the cite package to work. But both will disable links for cite commands. –  Ulrike Fischer Feb 3 '12 at 15:24
@UlrikeFischer: Look at this from the perspective of a volunteer-run journal. Adding new technologies that, let's face it, a good fraction of authors will not have installed immediately hurts you. These backwards authors can't compile their work, and will a) ask for help (volunteer run remember) and/or b) take their manuscript somewhere else. It's fine to update packages and technologies, but there must be a latency. –  qubyte Feb 3 '12 at 15:57

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
citecolor=black,       % color of links to bibliography
filecolor=black,        % color of file links
urlcolor=purple,        % color of external links
}
\usepackage{jair, theapa, rawfonts}

\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.

-
When I add hyperref with these options to the sample file, the first run of pdflatex succeeds, but the second run (when the citation names are actually inserted into the document) fails. So this doesn't look like a solution. –  András Salamon Jul 28 '12 at 16:50

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
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}

\usepackage{ifthen}

%new citation commands. Add more as needed, using the existing ones as templates

\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.

-

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.

-
Hello. I have a similar problem but with using biblatex-apa package instead of theapa.sty (my document has nothing to do with JAIR and doesn't uses its style files). I tried to change the order I call biblatex and hyperref, and also tried to use implicit=false, but the problem remains. I know this is not the proper way for asking this, but, please, could you tell me what els could I try?? This is awful. Even if I don't call hyperref, I get the same error (Use of \reserved@a doesn't match its definition). –  Vicent Nov 2 '12 at 12:15