README for hyperref bundle, 2007/01/25 TABLE OF CONTENTS ================= 1 Introduction 2 Download 3 Installation 4 Additional Packages 5 New Features 6 Package Compatibility 7 Limitations 8 Hints 9 Authors/Maintainers 10 Bug Reports 11 Known Problems 12 ToDo 1 INTRODUCTION ============== This package is used to emend cross-referencing commands in LaTeX to produce some sort of \special commands; there are backends for the \special set defined for HyperTeX dvi processors, for embedded pdfmark commands for processing by Acrobat Distiller (dvips and dvipsone), for dviwindo, for pdfTeX, for dvipdfm, for TeX4ht, and for VTEX's pdf and HTML backends. Included are: a) `backref' a package by David Carlisle to provide links back from bibliography to the main text; these are hypertext links after using hyperref. b) nameref' a package to allow reference to the *names* of sections rather than their numbers. 2 DOWNLOAD ========== `hyperref' is available on CTAN: CTAN:macros/latex/contrib/hyperref/ Also a ZIP file is provided that contains the files, already sorted in a TDS tree: CTAN:macros/latex/contrib/hyperref/hyperref-tds.zip or CTAN:install/macros/latex/contrib/hyperref.zip `CTAN:' means one of the `Comprehensive TeX Archive Network' nodes or one of its mirrors. This is explained in http://www.tex.ac.uk/cgi-bin/texfaq2html?label=archives The files are organized in three, sometimes four directories: ./ Root directory that contains `README', `.dtx', and `.ins' files. doc/ Directory for documentation files. test/ Directory for some test files. The main repository of hyperref is located at the server of the international `TeX User Group' (TUG). The hyperref directory at the TUG server http://www.tug.org/applications/hyperref/ contains the following files: hyperref.zip hyperref-doc.zip hyperref-test.zip manual.html manual2.html manual.css HTML version of the quite old hyperref manual in `doc/manual.pdf'. The CTAN stuff will be mirrored automatically from the ftp server, so ftp://ftp.tug.org/pub/tex/hyperref/ corresponds to CTAN:macros/latex/contrib/hyperref/ 3 INSTALLATION ============== Installation with ZIP file in TDS format ---------------------------------------- The ZIP file `hyperref-tds.zip' contains the files sorted in a TDS tree. Thus you can directly unpack the ZIP file inside a TDS tree. (See CTAN:tds.zip for an explanation of TDS.) Example: cd /...somewhere.../texmf unzip /...downloadpath.../hyperref-tds.zip Do not forget to refresh the file name database of this TDS tree, Example: texhash /...somewhere.../texmf Manual installation ------------------- a) Download the hyperref files from CTAN or the TUG server. If necessary, unpack them. b) If directory `beta' exists, replace the files by the counterparts in this directory, if you want to use the latest versions. c) Generate the package and driver files: tex hyperref.ins d) Install the files `*.sty', `*.def', and `*.cfg' in your TDS tree: cp *.sty *.def *.cfg TDS:tex/latex/hyperref/ Replace `TDS:' by the prefix of your TDS tree (texmf directory). The exception is bmhydoc.sty, it belongs to the source files (TDS:source/latex/hyperref/). e) Copy the documentation files to "TDS:doc/latex/hyperref/": manual.pdf, README, README.pdf, ChangeLog, ChangeLog.pdf, slides.pdf, paper.pdf, options.pdf, hyperref.pdf, backref.pdf, nameref.pdf (Also the HTML version of the manual can be put there.) f) Update the databases if necessary, eg. for teTeX: mktexlsr .../texmf 4 ADDITIONAL PACKAGES ===================== Depending on the driver, hyperref loads other packages apart from nameref and backref: * url.sty CTAN:macros/latex/contrib/other/misc/url.sty * keyval.sty, color.sty: CTAN:macros/latex/required/graphics/ * pdftex.def: CTAN:macros/pdftex/graphics/pdftex.def * kvoptions.def: CTAN:macros/latex/contrib/oberdiek/kvoptions.pdf * refcount.sty (loaded by nameref) CTAN:macros/latex/contrib/oberdiek/refcount.pdf 5 NEW FEATURES ============== Starred form of \autoref ------------------------ \autoref* generates a reference without link as \ref* or \pageref*. Link border style ----------------- Links can be underlined instead of the default rectangle or options "colorlinks", "frenchlinks". This is done by option pdfborderstyle={/S/U/W 1} Some remarks: * AR7/Linux seems to have a bug, that don't use the default value "1" for the width, but zero, thus that the underline is not visible without "/W 1". The same applies for dashed boxes, eg.: pdfborderstyle={/S/D/D[3 2]/W 1} * The syntax is described in the PDF specification, look for "border style", eg. Table 8.13 "Entries in a border style dictionary" (specification for version 1.6) * The border style is removed by pdfborderstyle={} This is automatically done if option colorlinks is enabled. * Be aware that not all PDF viewers support this feature, not even Acrobat Reader itself: Some support: * AR7/Linux: "underline" and "dashed", but the border width must be given. * xpdf 3.00: "underline" and "dashed" Unsupported: * AR5/Linux * ghostscript 8.50 Option "bookmarksdepth" ----------------------- The depth of the bookmarks can be controlled by the new option "bookmarksdepth". The option acts globally and distinguishes three cases: * "bookmarksdepth" without value Then hyperref uses the current value of counter "tocdepth". This is the compatible behaviour and the default. * "bookmarksdepth=", the value is number (also negative): The depth for the bookmarks are set to this number. * "bookmarksdepth=" The is a document division name (part, chapter, ...). It must not start with a digit or minus to avoid mixing up with the number case. Internally hyperref uses the value of macro "\toclevel@". Examples: \hypersetup{bookmarksdepth=paragraph} \hypersetup{bookmarksdepth=4} % same as before \hypersetup{bookmarksdepth} % counter "tocdepth" is used Option "pdfescapeform" ---------------------- There are many places where arbitrary strings end up as PS or PDF strings. The PS/PDF strings in parentheses form require the protection of some characters, e.g. unmatched left or right parentheses need escaping or the escape character itself (backslash). Since 2006/02/12 v6.75a the PS/PDF driver should do this automatically. However I assume a problem with compatibility, especially regarding the form part where larger amounts of JavaScript code can be present. It would be a pain to remove all the escaping, because an additional escaping layer can falsify the code. Therefore a new option pdfescapeform was introduced: * pdfescapeform=false Escaping for the formulars are disabled, this is the compatibility behaviour, therefor this is the default. * pdfescapeform=true Then the PS/PDF drivers do all the necessary escaping. This is the logical choice and the recommended setting. For example, the user writes JavaScript as JavaScript and do not care about escaping characters for PS/PDF output. Default driver setting ---------------------- (hyperref >= 6.72s) If no driver is given, hyperref tries its best to guess the most suitable driver. Thus it loads "hpdftex", if pdfTeX is detected running in PDF mode. Or it loads the corresponding VTeX driver for VTeX's working modes. Unhappily many driver programs run after the TeX compiler, so hyperref does not have a chance (dvips, dvipdfm, ...). In this case driver "hypertex" is loaded that supports the HyperTeX features that are recognized by xdvi for example. This behaviour, however, can easily be changed in the configuration file "hyperref.cfg": \providecommand*{\Hy@defaultdriver}{hdvips} for dvips, or \providecommand*{\Hy@defaultdriver}{hypertex} for the default behaviour of hyperref. Backref entries --------------- Alternative interface for formatting of backref entries, example: \documentclass[12pt,UKenglish]{article} \usepackage{babel} \usepackage[pagebackref]{hyperref} % Some language options are detected by package backref. % This affects the following macros: % \backrefpagesname % \backrefsectionsname % \backrefsep % \backreftwosep % \backreflastsep \renewcommand*{\backref}[1]{ % default interface % #1: backref list % % We want to use the alternative interface, % therefore the definition is empty here. } \renewcommand*{\backrefalt}[4]{% % alternative interface % #1: number of distinct back references % #2: backref list with distinct entries % #3: number of back references including duplicates % #4: backref list including duplicates \par #3 citation(s) on #1 page(s): #2,\par \ifnum#1=1 % \ifnum#3=1 % 1 citation on page % \else #3 citations on page % \fi \else #3 citations on #1 pages % \fi #2,\par \ifnum#3=1 % 1 citation located at page % \else #3 citations located at pages % \fi #4.\par } \begin{document} \section{Hello} \cite{ref1, ref2, ref3, ref4} \section{World} \cite{ref1, ref3} \newpage \section{Next section} \cite{ref1} \newpage \section{Last section} \cite{ref1, ref2} \newpage \pdfbookmark[1]{Bibliography}{bib} \begin{thebibliography}{99} \bibitem{ref1} Dummy entry one. \bibitem{ref2} Dummy entry two. \bibitem{ref3} Dummy entry three. \bibitem{ref4} Dummy entry four. \end{thebibliography} \end{document} \phantomsection --------------- Set an anchor at this location. It is often used in conjunction with \addcontentsline for sectionlike things (index, bibliography, preface). \addcontentsline refers to the latest previous location where an anchor is set. \cleardoublepage \phantomsection \addcontentsline{toc}{chapter}{\indexname} \printindex Now the entry in the table of contents (and bookmarks) for the index points to the start of the index page, not to a location before this page. \hypercalcbp ------------ See manual. 6 PACKAGE COMPATIBILITY ======================= Currently only package loading orders are available: Note: hyperref loads package "nameref" at \begin{document}. Sometimes this is too late, thus this package must be loaded earlier. algorithm --------- \usepackage{float} \usepackage{hyperref} \usepackage[chapter]{algorithm}% eg. amsmath ------- The environments equation and eqnarray are not supported too well. For example, there can be spacing problems. Consider using the environments that package amsmath provide, e.g. gather for equation. The environment equation can even redefined to use gather: \usepackage{amsmath} \let\equation\gather \let\endequation\endgather arydshln, longtable --------,---------- Package longtable must be put before hyperref and arydshln, hyperref after arydshln generates an error, thus the resulting package order is then: \usepackage{longtable} \usepacakge{hyperref} \usepackage{arydshln} babel/magyar.ldf ---------------- Unsupported. magyar.ldf's redefinitions of many LaTeX internals conflict with hyperref's redefinitions of these commands. bibentry -------- Workaround: \makeatletter \let\saved@bibitem\@bibitem \makeatother \usepackage{bibentry} \usepackage{hyperref} \begin{document} \begingroup \makeatletter \let\@bibitem\saved@bibitem \nobibliography{database} \endgroup cite ---- This is from Mike Shell: > cite.sty cannot currently be used with hyperref. > However, I can do a workaround via: > > \makeatletter > \def\NAT@parse{\typeout{This is a fake Natbib command to fool Hyperref.}} > \makeatother > > \usepackage[hypertex]{hyperref} > > so that hyperref will not redefine any of the biblabel stuff - so cite.sty > will work as normal - although the citations will not be hyperlinked, of > course (But this may not be an issue for many people). dblaccnt -------- pd1enc.def or puenc.def should be loaded before: \usepackage{hyperref} \usepackage{dblaccnt} or see entry for "vietnam". easyeqn ------- Not compatible, breaks. ellipsis -------- This packages redefines \textellipsis, thus it has to be loaded after package hyperref (pd1enc.def/puenc.def should be loaded before): \usepackage{hyperref} \usepackage{ellipsis} float ----- \usepackage{float} \usepackage{hyperref} * Several \caption commands are not supported inside one float object. * Anchor are set at top of the float object, if its style is controlled by float.sty. foiltex ------- Version 2002/10/29 v2.1.4a forgets adding \HyPL@EveryPage to the code that is executed each page. This sabotages the page labels (option pdfpagelabels) and a rerun warning can be shown (depends on the used driver). Workaround: \documentclass{foils} \usepackage{hyperref} \makeatletter \ifHy@pageanchor \g@addto@macro\@hyperfixhead{\HyPL@EveryPage}% \fi \makeatother footnote -------- This package is not supported, you have to disable hyperref's footnote support by using option "hyperfootnotes=false". IEEEtran.cls ------------ version >= V1.6b (because of \@makecaption, see ChangeLog) index ----- version >= 1995/09/28 v4.1 (because of \addcontentsline redefinition) lastpage -------- Compatible. linguex ------- \usepackage{hyperref} \usepackage{linguex} ltabptch -------- \usepackage{longtable} \usepackage{ltabptch} \usepackage{hyperref} minitoc-hyper ------------- This package is obsolete, use the uptodate original package minitoc instead. multind ------- \usepackage{multind} \usepackage{hyperref} natbib ------ \usepackage{natbib} \usepackage{hyperref} nomencl ------- * Example for introducing links for the page numbers: \renewcommand*{\pagedeclaration}[1]{\unskip, \hyperpage{#1}} * For equations the following might work: \renewcommand*{\eqdeclaration}[1]{% \hyperlink{equation.#1}{(Equation~#1)}% } But the mapping from the equation number to the anchor name is not available in general. prettyref --------- %%% example for prettyref %%% \documentclass{article} \usepackage{prettyref} \usepackage[pdftex]{hyperref} %\newrefformat{FIG}{Figure~\ref{#1}}% without hyperref \newrefformat{FIG}{\hyperref[{#1}]{Figure~\ref*{#1}}} \begin{document} This is a reference to \prettyref{FIG:ONE}. \newpage \begin{figure} \caption{This is my figure} \label{FIG:ONE} \end{figure} \end{document} %%% example for prettyref %%% ntheorem -------- ntheorem-hyper.sty is an old patched version of ntheorem.sty. Newer versions of ntheorem know the option hyperref: \usepackage{hyperref} \usepackage[hyperref]{ntheorem} But there are still unsolved problems (options thref, ...). setspace -------- \usepackage{setspace} \usepackage{hyperref} sidecap ------- Before 2002/05/24 v1.5h: \usepackage{nameref} \usepackage{hyperref} \usepackage{sidecap} subfigure --------- 1995/03/06 v2.0: \usepackage{subfigure} \usepackage{hyperref} % hypertexnames is set to false. v2.1: \usepackage{nameref} \usepackage{subfigure} \usepackage{hyperref} or \usepackage{hyperref} \usepackage{subfigure} v2.1.2: please update v2.1.3: \usepackage{hyperref} \usepackage{subfigure} or vice versa? titleref -------- \usepackage{nameref} \usepackage{titleref}% without usetoc \usepackage{hyperref} titlesec -------- "nameref" supports titlesec, but hyperref does not (unsolved is the anchor setting, missing with unnumbered section, perhaps problems with page breaks with numbered ones). varioref -------- \usepackage{nameref} \usepackage{varioref} \usepackage{hyperref} Some babel versions (eg. 2005/05/21 v3.8g) contain a patch for varioref that breaks the hyperref support for varioref. Thus with babel v3.8g varioref cannot be used with hyperref. Also unsupported: * \Ref, \Vref do not uppercase the first letter. * \vpageref[]{...} On the same page a previous space is not suppressed. verse ----- Version 2005/08/22 v2.22 contains support for hyperref. For older versions see example from de.comp.text.tex (2005/08/11, slightly modified): \documentclass{article} % package order does not matter \usepackage{verse} \usepackage{hyperref} \makeatletter % make unique poemline anchors \newcounter{verse@env} \setcounter{verse@env}{0} \let\org@verse\verse \def\verse{% \stepcounter{verse@env}% \org@verse } \def\theHpoemline{\arabic{verse@env}.\thepoemline} % add anchor for before \addcontentsline in \@vsptitle \let\org@vsptitle\@vsptitle \def\@vsptitle{% \phantomsection \org@vsptitle } \makeatother \begin{document} \poemtitle{Poem 1} \begin{verse} An one-liner. \end{verse} \newpage \poemtitle{Poem 2} \begin{verse} Another one-liner. \end{verse} \end{document} vietnam ------- % pd1enc.def should be loaded before package dblaccnt: \usepackage[PD1,OT1]{fontenc} \usepackage{vietnam} \usepackage{hyperref} 7 LIMITATIONS ============= * Wrapped/broken link support Only few drivers support automatically wrapped/broken links, e.g. pdftex, dvipdfm, hypertex. Other drivers lack this feature, e.g. dvips, dvipsone. Workarounds: * For long section or caption titles in the table of contents or list of figures/tables option "linktocpage" can be used. Then the page number will be a link, and the overlong section title is not forced into an one line link with overvull \hbox warning. * "\url"s are caught by package "breakurl". * The option "breaklinks" is intended for internal use. But it can be used to force link wrapping, e.g. when printing a document. However, when such a document is converted to PDF and viewed with a PDF viewer, the active link area will be misplaced. Another limitation: some penalties are "optimized" by TeX, thus there are missing break points, especially within \url. (See thread "hyperref.sty, breaklinks and url.sty 3.2" in comp.text.tex 2005-09). 8 HINTS ======= Index with makeindex -------------------- * Package hyperref adds \hyperpage commands by the encap mechanism (see documentation of Makeindex), if option hyperindex is set (default). \hyperpage uses the page anchors that are set by hyperref at each page (default). However in the default case page numbers are used in anchor names in arabic form. If the page numbers in other formats are used (book class with \frontmatter, \romannumbering, ...), then the page anchors are not unique. Therefore option "plainpages=false" is recommended. * The encap mechanism of Makeindex allows to use one command only (see documentation of Makeindex). If the user sets such a command, hyperref suppresses its \hyperpage command. With logical markup this situation can easily be solved: \usepackage{makeidx} \makeindex \usepackage[hyperindex]{hyperref} \newcommand*{\main}[1]{\textbf{\hyperpage{#1}}} ... \index{Some example|main} * Other encap characters can be set by option "encap". Example for use of "?": \usepackage[encap=?]{hyperref} * An other possibility is the insertion of \hyperpage by a style file for makeindex. For this case, hyperref's insertion will be disabled by "hyperindex=false". \hyperpage will be defined regardless of setting of hyperindex. %%% cut %%% hyperindex.ist %%% cut %%% delim_0 ", \\hyperpage{" delim_1 ", \\hyperpage{" delim_2 ", \\hyperpage{" delim_n "}, \\hyperpage{" delim_t "}" encap_prefix "}\\" encap_infix "{\\hyperpage{" encap_suffix "}" %%% cut %%% hyperindex.ist %%% cut %%% Warning "bookmark level for unknown defaults to 0" ----------------------------------------------------------- Getting rid of it: \makeatletter \providecommand*{\toclevel@}{0} \makeatother Link anchors in figures ----------------------- The caption command increments the counter and here is the place where hyperref set the corresponding anchor. Unhappily the caption is set below the figure, so the figure is not visible if a link jumps to a figure. In this cases, try package "hypcap.sty" that implements a method to circumvent the problem. Additional unicode characters in bookmarks and pdf information entries: ----------------------------------------------------------------------- \documentclass[pdftex]{article} \usepackage[unicode]{hyperref} % Support for additional unicode characters: % % Example: \.{a} and \d{a} % % 1. Get a list with unicode data, eg: % http://www.unicode.org/Public/UNIDATA/UnicodeData.txt % % 2. Identify the characters (\.{a}, \d{a}): % % 0227;LATIN SMALL LETTER A WITH DOT ABOVE;... % 1EA1;LATIN SMALL LETTER A WITH DOT BELOW;... % % 3. Calculate the octal code: % The first characters of the line in the file are % hex values, convert each byte and prepend them % with a backslash. (This will go into the PDF file.) % % 0227 -> \002\047 % 1EA1 -> \036\241 % % 4. Transform into a form understood by hyperref: % % Hyperref must know where the first byte starts, % this is marked by "9" (8 and 9 cannot occur in % octal numbers): % % \002\047 -> \9002\047 % \036\241 -> \9036\241 % % Optional: "8" is used for abbreviations: % \900 = \80, \901 = \81, \902 = \82, ... % % \9002\047 -> \82\047 % % 5. Declare the character with LaTeX: % \DeclareTextCompositeCommand{\.}{PU}{a}{\82\047} \DeclareTextCompositeCommand{\d}{PU}{a}{\9036\241} \begin{document} \section{\={a}, \d{a}, \'{a}, \.{a}} \end{document} Footnotes --------- The footnote support is rather limited. It is beyond the scope to use \footnotemark and \footnotetext out of order or reusing \footnotemark. Here you can either disable hyperref's footnote support by "hyperfootnotes=false" or fiddle with internal macros, nasty example: \documentclass{article} \usepackage{hyperref} \begin{document} \makeatletter A% \footnotemark \let\saved@Href@A\Hy@footnote@currentHref % remember link name B% \footnotemark \let\saved@Href@B\Hy@footnote@currentHref b% \addtocounter{footnote}{-1}% \addtocounter{Hfootnote}{-1}% generate the same anchor \footnotemark C% \footnotemark \let\saved@Href@C\Hy@footnote@currentHref \addtocounter{footnote}{-2}% \let\Hy@footnote@currentHref\saved@Href@A \footnotetext{AAAA}% \addtocounter{footnote}{1}% \let\Hy@footnote@currentHref\saved@Href@B \footnotetext{BBBBB}% \addtocounter{footnote}{1}% \let\Hy@footnote@currentHref\saved@Href@C \footnotetext{CCCC}% \end{document} 9 AUTHORS/MAINTAINERS ===================== * Sebastian Rahtz * Heiko Oberdiek 10 BUG REPORTS ============== A bug report should contain: * Comprehensive problem description. This includes error or warning messages. * \errorcontextlines=\maxdimen can be added in the TeX code to get more informations in TeX error messages. * Minimal test file that shows the problem, but does not contain any unnecessary packages and code. * Used drivers/programs. * Version information about used packages and programs. * If you are using LaTeX, then add "\listfiles". Then a list of version informations is printed at the end of the LaTeX run. * Please no other files than the minimal test file. The other files .log, .dvi, .ps, .pdf are seldom necessary, so send them only on request. Bug address: Heiko Oberdiek Vietnamese part --------------- Responsible for the Vietnamese translations of the \autoref names and puvnenc.def are: Han The Thanh Reinhard Kotucha Arabic part ----------- Responsible for the additions to PU encoding for Arabi is Youssef Jabri 11 KNOWN PROBLEMS ================= * (half-done) hyper images (link from thumbnail in text) * Relative links are not sorted out or documented well. For PDF generation: * With baseurl: all links are considered relative to this URL. * Without baseurl: a relative link without "file:" can be achieved by: \begingroup \hypersetup{linkfileprefix={}}% \href{../foo/bar.html}{bar.html} \endgroup * ... 12 TODO ======= * modules * bookmark organisation * documentation * PDF threads * more for PDF forms * per object setting * vary gap between text and box * PostScript driver: the current implementation doesn't relly support nested links. The start positions should be remembered in a stack, but there are complications with page breaks. * ...