Can I force hyperref to use a custom driver?

Question

As part of a project to get LaTeX to output something useful, I found myself wanting to write a new hyperref driver for the desired format. The documentation explains what a driver needs to do, but it doesn't explain how to get hyperref to load the new driver instead of its given one. Looking through the code, I can't see an obvious hook but I may well be missing something. At the moment, I load the driver file using the \AtBeginDocument hook, but it worries me that this might not be very robust.

So, can I get hyperref to load a custom driver without modifying hyperref.sty? If not, are there any dangers from manually loading it myself at the start of the actual document?

Answer 1

I got notified about this thread and have now added option customdriver in hyperref 6.83f. From its README:

Option `customdriver'
---------------------
  The value of option `customdriver' is the name of an external
  driver file without extension `.def'. The file must have
  \ProvidesFile with a version date and number that match the
  date and number of `hyperref', otherwise a warning is given.

  Because the interface, what needs to be defined in the driver,
  is not well defined and quite messy, the option is mainly intended
  to ease developing, testing, debugging the driver part.

Answer 2

You could use a hyperref.cfg with the line \def\Hy@driver{myhdriver}. This will load a myhdriver.def. But it will work only with LaTeX (means dvi output) and not with pdfLaTeX (pdf output). With pdfoutput hyperref will force the use of the hpdftex.def.

Answer 3

The patch below seems to do the trick. Declare the option customdriver to store its key in \HyOpt@CustomDriver. If that's nonempty then clobber \Hy@driver just before loading the driver file. EDIT: added context for the diff, as requested by Andrew Stacey.

*** hyperref-original.sty
--- hyperref-modified.sty
***************
*** 2861,2866 ****
--- 2861,2870 ----
      }%
    \fi
  }
+ \let\HyOpt@CustomDriver\ltx@empty
+ \define@key{Hyp}{customdriver}{%
+   \def\HyOpt@CustomDriver{#1}%
+ }
  \define@key{Hyp}{hyperfigures}[true]{%
    \Hy@boolkey[hyperfigures]{figures}{#1}%
  }
***************
*** 4206,4211 ****
--- 4210,4219 ----
        \fi
      \fi
    \fi
+   \ifx\HyOpt@CustomDriver\ltx@empty
+   \else
+     \let\Hy@driver\HyOpt@CustomDriver
+   \fi
    \Hy@Message{Driver\HyOpt@DriverType: \Hy@driver}%
    \chardef\Hy@VersionChecked=0 %
    \input{\Hy@driver.def}%

Used as

\documentclass{article}
\usepackage[customdriver={foo}]{hyperref}
\begin{document}
   \href{foo}{bar}
\end{document}