From 5c46c751583a70d35e1f323c0d65b63c459d495b Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sun, 7 Feb 2021 21:54:30 +0000 Subject: hyperref (7feb21) git-svn-id: svn://tug.org/texlive/trunk@57665 c570f23f-e606-0410-a88d-b1316a301751 --- .../texmf-dist/source/latex/hyperref/backref.dtx | 4 +- .../texmf-dist/source/latex/hyperref/bmhydoc.sty | 6 +- .../texmf-dist/source/latex/hyperref/doc/fdl.tex | 422 --- .../source/latex/hyperref/doc/hyperref-doc.tex | 3816 ++++++++++++++++++++ .../source/latex/hyperref/doc/manual.tex | 3396 ----------------- .../texmf-dist/source/latex/hyperref/hluatex.dtx | 8 +- .../texmf-dist/source/latex/hyperref/hyperref.dtx | 20 +- .../texmf-dist/source/latex/hyperref/hyperref.ins | 2 +- .../texmf-dist/source/latex/hyperref/nameref.dtx | 6 +- 9 files changed, 3844 insertions(+), 3836 deletions(-) delete mode 100644 Master/texmf-dist/source/latex/hyperref/doc/fdl.tex create mode 100644 Master/texmf-dist/source/latex/hyperref/doc/hyperref-doc.tex delete mode 100644 Master/texmf-dist/source/latex/hyperref/doc/manual.tex (limited to 'Master/texmf-dist/source/latex/hyperref') diff --git a/Master/texmf-dist/source/latex/hyperref/backref.dtx b/Master/texmf-dist/source/latex/hyperref/backref.dtx index 2687a448dea..3fe08479a5e 100644 --- a/Master/texmf-dist/source/latex/hyperref/backref.dtx +++ b/Master/texmf-dist/source/latex/hyperref/backref.dtx @@ -3,7 +3,7 @@ %% Copyright (C) 1995-2000 David Carlisle, Sebastian Rahtz, Heiko Oberdiek %% 2001-2012 Heiko Oberdiek %% 2016-2019 Oberdiek Package Suport Group -%% 2019-2021 The LaTeX3 Project +%% 2019-2021 The LaTeX Project %% https://github.com/latex3/hyperref/issues %% %% This file is part of the `Hyperref Bundle'. @@ -19,7 +19,7 @@ %% %% This work has the LPPL maintenance status `maintained'. %% -%% The Current Maintainer of this work is The LaTeX3 Project. +%% The Current Maintainer of this work is The LaTeX Project. %% %% The list of all files belonging to the `Hyperref Bundle' is %% given in the file `manifest.txt'. diff --git a/Master/texmf-dist/source/latex/hyperref/bmhydoc.sty b/Master/texmf-dist/source/latex/hyperref/bmhydoc.sty index d25c4d6bf81..f41634002c5 100644 --- a/Master/texmf-dist/source/latex/hyperref/bmhydoc.sty +++ b/Master/texmf-dist/source/latex/hyperref/bmhydoc.sty @@ -1,7 +1,7 @@ %% Copyright %% 1995-2015 Heiko Oberdiek %% 2016-2019 Oberdiek Package Support Group -%% 2019-2020 LaTeX3 Project +%% 2019-2020 LaTeX Project %% https://github.com/latex3/hyperref/issues %% %% This file is part of the `Hyperref Bundle'. @@ -49,7 +49,7 @@ }% } \AtEndDocument{% - \@bmhydoc[open=false]{0}{manual.pdf}{Hyperref manual} + \@bmhydoc[open=false]{0}{hyperref-doc.pdf}{Hyperref manual} \@bmhydoc{1}{slides.pdf}{Bookmark talk, slides} \@bmhydoc{2}{paper.pdf}{Bookmark talk, paper} \@bmhydoc{1}{hyperref.pdf}{Sources: hyperref.dtx} @@ -78,7 +78,7 @@ \ignorespaces }% \begin{description} - \entry{manual.pdf}{\textbf{Manual}} + \entry{hyperref-doc.pdf}{\textbf{Manual}} The \textbf{USER MANUAL} (also available as HTML). \entry{ChangeLog.txt}{ChangeLog} This file records the version history. diff --git a/Master/texmf-dist/source/latex/hyperref/doc/fdl.tex b/Master/texmf-dist/source/latex/hyperref/doc/fdl.tex deleted file mode 100644 index 57f9b316217..00000000000 --- a/Master/texmf-dist/source/latex/hyperref/doc/fdl.tex +++ /dev/null @@ -1,422 +0,0 @@ -% This file is a chapter. It must be included in a larger document to work -% properly. - -\chapter{GNU Free Documentation License} - -Version 1.2, November 2002 - - - Copyright \copyright\ 2000,2001,2002 Free Software Foundation, Inc.\\ - 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA\\ - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - -\section*{PREAMBLE} - -The purpose of this License is to make a manual, textbook, or other -functional and useful document ``free'' in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of ``copyleft'', which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - - -\section{APPLICABILITY AND DEFINITIONS} -\label{applicability} - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The ``Document'', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as ``you''. You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A ``Modified Version'' of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A ``Secondary Section'' is a named appendix or a front-matter section of -the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall subject -(or to related matters) and contains nothing that could fall directly -within that overall subject. (Thus, if the Document is in part a -textbook of mathematics, a Secondary Section may not explain any -mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The ``Invariant Sections'' are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The ``Cover Texts'' are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A ``Transparent'' copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not ``Transparent'' is called ``Opaque''. - -Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, \LaTeX\ input format, SGML -or XML using a publicly available DTD, and standard-conforming simple -HTML, PostScript or PDF designed for human modification. Examples of -transparent image formats include PNG, XCF and JPG. Opaque formats -include proprietary formats that can be read and edited only by -proprietary word processors, SGML or XML for which the DTD and/or -processing tools are not generally available, and the -machine-generated HTML, PostScript or PDF produced by some word -processors for output purposes only. - -The ``Title Page'' means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, ``Title Page'' means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -A section ``Entitled XYZ'' means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as ``Acknowledgements'', -``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' -of such a section when you modify the Document means that it remains a -section ``Entitled XYZ'' according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - - -\section{VERBATIM COPYING} -\label{verbatim} - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in -section~\ref{copying}. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - - -\section{COPYING IN QUANTITY} -\label{copying} - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document's license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - - -\section{MODIFICATIONS} -\label{modifications} - -You may copy and distribute a Modified Version of the Document under -the conditions of sections~\ref{verbatim} and \ref{copying} above, -provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -\renewcommand{\labelenumi}{\Alph{enumi}.} -\begin{enumerate} -\item Use in the Title Page (and on the covers, if any) a title distinct - from that of the Document, and from those of previous versions - (which should, if there were any, be listed in the History section - of the Document). You may use the same title as a previous version - if the original publisher of that version gives permission. -\item List on the Title Page, as authors, one or more persons or entities - responsible for authorship of the modifications in the Modified - Version, together with at least five of the principal authors of the - Document (all of its principal authors, if it has fewer than five), - unless they release you from this requirement. -\item State on the Title page the name of the publisher of the - Modified Version, as the publisher. -\item Preserve all the copyright notices of the Document. -\item Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. -\item Include, immediately after the copyright notices, a license notice - giving the public permission to use the Modified Version under the - terms of this License, in the form shown in the Addendum below. -\item Preserve in that license notice the full lists of Invariant Sections - and required Cover Texts given in the Document's license notice. -\item Include an unaltered copy of this License. -\item Preserve the section Entitled ``History'', Preserve its Title, and add - to it an item stating at least the title, year, new authors, and - publisher of the Modified Version as given on the Title Page. If - there is no section Entitled ``History'' in the Document, create one - stating the title, year, authors, and publisher of the Document as - given on its Title Page, then add an item describing the Modified - Version as stated in the previous sentence. -\item Preserve the network location, if any, given in the Document for - public access to a Transparent copy of the Document, and likewise - the network locations given in the Document for previous versions - it was based on. These may be placed in the ``History'' section. - You may omit a network location for a work that was published at - least four years before the Document itself, or if the original - publisher of the version it refers to gives permission. -\item For any section Entitled ``Acknowledgements'' or ``Dedications'', - Preserve the Title of the section, and preserve in the section all - the substance and tone of each of the contributor acknowledgements - and/or dedications given therein. -\item Preserve all the Invariant Sections of the Document, - unaltered in their text and in their titles. Section numbers - or the equivalent are not considered part of the section titles. -\item Delete any section Entitled ``Endorsements''. Such a section - may not be included in the Modified Version. -\item Do not retitle any existing section to be Entitled ``Endorsements'' - or to conflict in title with any Invariant Section. -\item Preserve any Warranty Disclaimers. - -\end{enumerate} - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled ``Endorsements'', provided it contains -nothing but endorsements of your Modified Version by various -parties--for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - - -\section{COMBINING DOCUMENTS} -\label{combining} - -You may combine the Document with other documents released under this -License, under the terms defined in section~\ref{modifications} -above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled ``History'' -in the various original documents, forming one section Entitled -``History''; likewise combine any sections Entitled ``Acknowledgements'', -and any sections Entitled ``Dedications''. You must delete all sections -Entitled ``Endorsements''. - - -\section{COLLECTIONS OF DOCUMENTS} -\label{collections} - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - - -\section{AGGREGATION WITH INDEPENDENT WORKS} -\label{aggregation} - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an ``aggregate'' if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation's users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section~\ref{copying} is applicable to -these copies of the Document, then if the Document is less than one half -of the entire aggregate, the Document's Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - - -\section{TRANSLATION} -\label{translation} - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of -section~\ref{modifications}. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled ``Acknowledgements'', -``Dedications'', or ``History'', the requirement -(section~\ref{modifications}) to Preserve -its Title (section~\ref{applicability}) will typically require -changing the actual title. - - -\section{TERMINATION} -\label{termination} - -You may not copy, modify, sublicense, or distribute the Document except -as expressly provided for under this License. Any other attempt to -copy, modify, sublicense or distribute the Document is void, and will -automatically terminate your rights under this License. However, -parties who have received copies, or rights, from you under this -License will not have their licenses terminated so long as such -parties remain in full compliance. - - -\section{FUTURE REVISIONS OF THIS LICENSE} -\label{future} - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -http://www.gnu.org/copyleft/. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. - - -\section*{ADDENDUM: How to use this License for your documents} - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -\begin{quote} - Copyright \copyright\ YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. - A copy of the license is included in the section entitled ``GNU - Free Documentation License''. -\end{quote} - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the ``with...Texts.'' line with this: - - with the Invariant Sections being LIST THEIR TITLES, with the - Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. diff --git a/Master/texmf-dist/source/latex/hyperref/doc/hyperref-doc.tex b/Master/texmf-dist/source/latex/hyperref/doc/hyperref-doc.tex new file mode 100644 index 00000000000..f1e1895645c --- /dev/null +++ b/Master/texmf-dist/source/latex/hyperref/doc/hyperref-doc.tex @@ -0,0 +1,3816 @@ +% This is the manual for the LaTeX hyperref package. +% +% Copyright (C) 1998-2003 Sebastian Rahtz. +% Copyright (C) 2003 Steve Peter and Karl Berry +% Copyright (C) 2006-2012 Heiko Oberdiek. +% Copyright (C) 2017-2019 David Carlisle Ulrike Fischer +% Copyright (C) 2019-2020 The LaTeX3 Project +% +% Permission is granted to copy, distribute and/or modify this document +% under the terms of the GNU Free Documentation License, Version 1.1 or +% any later version published by the Free Software Foundation; with no +% Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +% Texts. A copy of the license is included in the section entitled +% ``GNU Free Documentation License.'' +% + +\def\mydate{January 2020} + +\RequirePackage{iftex} +\ifpdf % We are running pdfTeX in pdf mode +\ifx\directlua\undefinded +\documentclass[pdftex]{article} +\else +\documentclass[luatex]{article} +\fi +\else +\documentclass{article} +\fi + + +\usepackage{pifont} +\usepackage{calc} + +\usepackage{hologo} + +\def\OzTeX{O\kern-0.03em z\kern-0.15em \TeX} + +\newcommand*{\cs}[1]{% + \texttt{\textbackslash #1}% +} +\newcommand*{\xpackage}[1]{\textsf{#1}} +\newcommand*{\xoption}[1]{\textsf{#1}} + +% from doc.sty +\makeatletter +\ifx\l@nohyphenation\@undefined +\newlanguage\l@nohyphenation +\fi +\ifx\l@nohyphenation\@undefined + \newlanguage\l@nohyphenation +\fi +\DeclareRobustCommand\meta[1]{% + \ensuremath\langle + \ifmmode \expandafter \nfss@text \fi + {% + \meta@font@select + \edef\meta@hyphen@restore + {\hyphenchar\the\font\the\hyphenchar\font}% + \hyphenchar\font\m@ne + \language\l@nohyphenation + #1\/% + \meta@hyphen@restore + }% + \ensuremath\rangle +} +\def\meta@font@select{\ttfamily\itshape} +\makeatother + +% Page layout. +\advance\textwidth by 1.1in +\advance\oddsidemargin by -.55in +\advance\evensidemargin by -.55in +% +\advance\textheight by 1in +\advance\topmargin by -.5in +\advance\footskip by -.5in +% +\pagestyle{headings} +% +% Avoid some overfull boxes. +\emergencystretch=.1\hsize +\hbadness = 3000 + +% these are from lshort.sty, but lshort.sty pulls in so many other +% packages it seems cleaner to just include them here. +% +\newcommand{\bs}{\symbol{'134}}%Print backslash +\newcommand{\ci}[1]{\texttt{\bs#1}} + +\makeatletter +\@ifpackageloaded{tex4ht}{% + % separate definition for HTML case to avoid + % nasty borders with double horizontal lines with + % large gaps. + \newsavebox{\cmdsyntaxbox}% + \newenvironment{cmdsyntax}{% + \par + % \small + \addvspace{3.2ex plus 0.8ex minus 0.2ex}% + \vskip -\parskip + \noindent + \begin{lrbox}{\cmdsyntaxbox}% + \begin{tabular}{l}% + \rule{0pt}{1em}% + \ignorespaces + }{% + \end{tabular}% + \end{lrbox}% + \fbox{\usebox{\cmdsyntaxbox}}% + \par + \nopagebreak + \addvspace{3.2ex plus 0.8ex minus 0.2ex}% + \vskip -\parskip + }% +}{% + \newenvironment{cmdsyntax}{% + \par + \small + \addvspace{3.2ex plus 0.8ex minus 0.2ex}% + \vskip -\parskip + \noindent + \begin{tabular}{|l|}% + \hline + \rule{0pt}{1em}% + \ignorespaces + }{% + \\% + \hline + \end{tabular}% + \par + \nopagebreak + \addvspace{3.2ex plus 0.8ex minus 0.2ex}% + \vskip -\parskip + }% +} +\makeatother + +\usepackage{array,longtable} +\ifnum 0\ifluatex 1\else\ifxetex 1\fi\fi=0 % + \usepackage[T1]{fontenc}% + \usepackage{lmodern}% + \renewcommand*{\ttdefault}{lmvtt}% +\else + \usepackage{fontspec}% + \renewcommand*{\ttdefault}{lmvtt}% +\fi + +\newcommand*{\Quote}[1]{\textquotedblleft#1\textquotedblright} + +\def\Hanh{H\`an Th\^e\llap{\raise 0.5ex\hbox{\'{}}} Th\`anh} + +\ifpdf + \usepackage[% +% pdftex,% might be luatex, just allow automatic default + colorlinks,% + hyperindex,% + plainpages=false,% + bookmarksopen,% + bookmarksnumbered, + pdfusetitle,% + ]{hyperref} + %%?? \def\pdfBorderAttrs{/Border [0 0 0] } % No border arround Links +\else + \usepackage{hyperref} +\fi + +\makeatletter +\@ifpackageloaded{tex4ht}{% +\author{Sebastian Rahtz (deceased)\and + Heiko Oberdiek (inactive)\and + The \LaTeX3 Project (\url{https://github.com/latex3/hyperref/issues})} +}{% + \usepackage{bmhydoc}% +\author{Sebastian Rahtz\thanks{deceased}\and + Heiko Oberdiek\thanks{inactive}\and + The \LaTeX3 Project\thanks{\url{https://github.com/latex3/hyperref/issues}}} +} +\makeatother +\title{Hypertext marks in \hologo{LaTeX}: a manual for \xpackage{hyperref}} +\date{2021-02-07 v7.00h} + +\begin{document} + +% comes out too close to the toc, and we know it's page one anyway. +\thispagestyle{empty} +\maketitle +\tableofcontents +\setcounter{tocdepth}{2}% for bookmark levels + +\section{Introduction} + +The package derives from, and builds on, the work of the Hyper\hologo{TeX} +project, described at \texttt{http://xxx.lanl.gov/hypertex/}\footnote{Now: \url{https://ctan.org/tex-archive/support/hypertex/hypertex}}. It extends +the functionality of all the \hologo{LaTeX} cross-referencing commands +(including the table of contents, bibliographies etc) to produce +\cs{special} commands which a driver can turn into hypertext links; +it also provides new commands to allow the user to write \emph{ad hoc} +hypertext links, including those to external documents and URLs. + +The package is currently maintained at \url{https://github.com/latex3/hyperref/} and issues should +be reported there. + +This manual provides a brief overview of the \xpackage{hyperref} +package. For more details, you should read the additional documentation +distributed with the package, as well as the complete documentation by +processing \texttt{hyperref.dtx}. You should also read the chapter on +\xpackage{hyperref} in \textit{The \hologo{LaTeX} Web Companion}, where you will +find additional examples. + +The Hyper\hologo{TeX} specification\footnote{This is borrowed from an article +by Arthur Smith.} says that conformant viewers/translators must +recognize the following set of \cs{special} constructs: + +\begin{description} +\item[href:] \verb|html:| +\item[name:] \verb|html:| +\item[end:] \verb|html:| +\item[image:] \verb|html:| +\item[base\_name:] \verb|html:| +\end{description} + +The \emph{href}, \emph{name} and \emph{end} commands are used to do the +basic hypertext operations of establishing links between sections of +documents. The \emph{image} command is intended (as with current HTML +viewers) to place an image of arbitrary graphical format on the page in +the current location. The \emph{base\_name} command is be used to +communicate to the DVI viewer the full (URL) location of the current +document so that files specified by relative URLs may be retrieved +correctly. + +The \emph{href} and \emph{name} commands must be paired with an +\emph{end} command later in the \TeX\ file---the \TeX\ commands between +the two ends of a pair form an \emph{anchor} in the document. In the +case of an \emph{href} command, the \emph{anchor} is to be highlighted +in the \emph{DVI viewer}, and when clicked on will cause the scene to +shift to the destination specified by \emph{href\_string}. The +\emph{anchor} associated with a name command represents a possible +location to which other hypertext links may refer, either as local +references (of the form \verb|href="#name_string"| with the +\emph{name\_string} identical to the one in the name command) or as part +of a URL (of the form \emph{URL\#name\_string}). Here +\emph{href\_string} is a valid URL or local identifier, while +\emph{name\_string} could be any string at all: the only caveat is that +`$\verb|"|$' characters should be escaped with a backslash +($\backslash$), and if it looks like a URL name it may cause problems. + +However, the drivers intended to produce \emph{only} PDF use literal +PostScript or PDF \verb|\special| commands. The commands are defined in +configuration files for different drivers, selected by package options; +at present, the following drivers are supported: + +\begin{description} +\item[hypertex] DVI processors conforming to the Hyper\TeX\ guidelines (i.e.\ \textsf{xdvi}, \textsf{dvips} (with +the \textsf{-z} option), \textsf{\OzTeX}, and \textsf{Textures}) +\item[dvips] produces \verb|\special| commands tailored for \textsf{dvips} +\item[dvipsone] produces \verb|\special| commands tailored for \textsf{dvipsone} +\item[ps2pdf] a special case of output suitable for processing by earlier versions of Ghost\-script's +PDF writer; this is basically the same as that for \textsf{dvips}, but a few variations remained before version 5.21 +\item[tex4ht] produces \verb|\special| commands for use with \textsf{\TeX4ht} +\item[pdftex] pdf\TeX, \Hanh{}'s \TeX{} variant that writes PDF directly +\item[luatex] lua\TeX, Unicode \TeX{} variant that writes PDF directly +\item[dvipdfm] produces \verb|\special| commands for Mark Wicks' DVI to PDF driver \textsf{dvipdfm} +\item[dvipdfmx] produces \verb|\special| commands for driver + \textsf{dvipdfmx}, a successor of \textsf{dvipdfm} +\item[dviwindo] produces \verb|\special| commands that Y\&Y's Windows previewer interprets as hypertext jumps within the previewer +\item[vtex] produces \verb|\special| commands that MicroPress' HTML and + PDF-producing \TeX\ variants interpret as hypertext jumps within the + previewer +\item[textures] produces \verb|\special| commands that \textsf{Textures} interprets as hypertext jumps within the previewer +\item[xetex] produces \verb|\special| commands for Xe\TeX{} +\end{description} + +Output from \textsf{dvips} or \textsf{dvipsone} must be processed using +Acrobat Distiller to obtain a PDF file.\footnote{Make sure you turn off +the partial font downloading supported by \textsf{dvips} and +\textsf{dvipsone} in favor of Distiller's own system.} The result is +generally preferable to that produced by using the \textsf{hypertex} +driver, and then processing with \textsf{dvips -z}, but the DVI file is +not portable. The main advantage of using the Hyper\TeX\ \ci{special} +commands is that you can also use the document in hypertext DVI viewers, +such as \textsf{xdvi}. + +\begin{description} +\item[driverfallback] + If a driver is not given and cannot be autodetected, then use + the driver option, given as value to this option \textsf{driverfallback}. + Example: + \begin{quote} + \texttt{driverfallback=dvipdfm} + \end{quote} + Autodetected drivers (\textsf{pdftex}, \textsf{xetex}, \textsf{vtex}, + \textsf{vtexpdfmark}) are recognized from within \TeX\ and + therefore cannot be given as value to option \textsf{driverfallback}. + However a DVI driver program is run after the \TeX\ run is finished. + Thus it cannot be detected at \TeX\ macro level. Then package + \xpackage{hyperref} + uses the driver, given by \textsf{driverfallback}. If the driver + is already specified or can be autodetected, then option + \textsf{driverfallback} is ignored. +\end{description} + +\section{Implicit behavior} + +This package can be used with more or less any normal \LaTeX\ document +by specifying in the document preamble + +\begin{verbatim} +\usepackage{hyperref} +\end{verbatim} + +Make sure it comes \emph{last} of your loaded packages, to give it a +fighting chance of not being over-written, since its job is to redefine +many \LaTeX\ commands. Hopefully you will find that all cross-references +work correctly as hypertext. For example, \ci{section} commands will +produce a bookmark and a link, whereas \ci{section*} commands will only +show links when paired with a corresponding \ci{addcontentsline} +command. + +In addition, the \texttt{hyperindex} option (see below) attempts to make +items in the index by hyperlinked back to the text, and the option +\texttt{backref} inserts extra `back' links into the bibliography for +each entry. Other options control the appearance of links, and give +extra control over PDF output. For example, \texttt{colorlinks}, as its +name well implies, colors the links instead of using boxes; this is the +option used in this document. + + +\section{Package options} + +All user-configurable aspects of \xpackage{hyperref} are set using a +single `key=value' scheme (using the \xpackage{keyval} package) with the +key \texttt{Hyp}. The options can be set either in the optional argument +to the \cs{usepackage} command, or using the \cs{hypersetup} +macro. When the package is loaded, a file \texttt{hyperref.cfg} is read +if it can be found, and this is a convenient place to set options on a +site-wide basis. + +Note however that some options (for example \texttt{unicode}) can only be used as +package options, and not in \verb|\hypersetup| as the option settings are processed +as the package is read. + +As an example, the behavior of a particular file could be controlled by: +\begin{itemize} + +\item a site-wide \texttt{hyperref.cfg} setting up the look of links, +adding backreferencing, and setting a PDF display default: + +\begin{verbatim} +\hypersetup{backref, +pdfpagemode=FullScreen, +colorlinks=true} +\end{verbatim} + +\item A global option in the file, which is passed down to +\textsf{hyperref}: + +\begin{verbatim} +\documentclass[dvips]{article} +\end{verbatim} + +\item File-specific options in the \cs{usepackage} commands, which +override the ones set in \texttt{hyperref.cfg}: + +\begin{verbatim} +\usepackage[colorlinks=false]{hyperref} +\hypersetup{pdftitle={A Perfect Day}} +\end{verbatim} +\end{itemize} + +As seen in the previous example, information entries +(pdftitle, pdfauthor, \dots) should be set after the package is loaded. +Otherwise \LaTeX\ expands the values of these options prematurely. +Also \LaTeX\ strips spaces in options. Especially option `pdfborder' +requires some care. Curly braces protect the value, if given +as package option. They are not necessary in \verb|\hypersetup|. + +\begin{verbatim} +\usepackage[pdfborder={0 0 0}]{hyperref} +\hypersetup{pdfborder=0 0 0} +\end{verbatim} + +Package `kvoptions-patch' patches \LaTeX\ to make it aware +of key value options and to prevent premature value expansions. + +Some options can be given at any time, but many are restricted: before +\verb|\begin{document}|, only in \verb|\usepackage[...]{hyperref}|, +before first use, etc. + +In the key descriptions that follow, many options do not need a value, +as they default to the value true if used. These are the ones classed as +`boolean'. The values true and false can always be specified, however. + +\subsection{General options} + +Firstly, the options to specify general behavior and page size. + +\medskip +\begin{longtable}{>{\ttfamily}ll>{\itshape}ll} +draft & boolean & false & all hypertext options are turned off \\ +final & boolean & true & all hypertext options are turned on \\ +debug & boolean & false & extra diagnostic messages are printed in \\ + & & & the log file \\ +verbose & boolean & false & same as debug \\ +implicit & boolean & true & redefines \LaTeX\ internals \\ +setpagesize & boolean & true & sets page size by special driver commands +\end{longtable} + +\subsection{Options for destination names} + +Destinations names (also anchor, target or link names) are internal +names that identify a position on a page in the document. They +are used in link targets for inner document links or the bookmarks, +for example. + +Usually anchor are set, if \cs{refstepcounter} is called. +Thus there is a counter name and value. Both are used to +construct the destination name. By default the counter value +follows the counter name separated by a dot. Example for +the fourth chapter: +\begin{quote} + \verb|chapter.4| +\end{quote} +This scheme is used by: +\begin{description} +\item[\cs{autoref}] displays the description label for the + reference depending on the counter name. +\item[\cs{hyperpage}] is used by the index to get +page links. Page anchor setting (\verb|pageanchor|) must not +be turned off. +\end{description} + +It is very important that the destination names are unique, +because two destinations must not share the same name. +The counter value \cs{the} is not always unique +for the counter. For example, table and figures can be numbered +inside the chapter without having the chapter number in their +number. Therefore \xpackage{hyperref} has introduced \cs{theH} +that allows a unique counter value without messing up with +the appearance of the counter number. For example, the number +of the second table in the third chapter might be printed +as \texttt{2}, the result of \cs{thetable}. But the +destination name \texttt{table.2.4} is unique because it +has used \cs{theHtable} that gives \verb|2.4| in this case. + +Often the user do not need to set \cs{theH}. Defaults +for standard cases (chapter, \dots) are provided. And after \xpackage{hyperref} +is loaded, new counters with parent counters also define +\cs{theH} automatically, if \cs{newcounter}, \cs{@addtoreset} +or \cs{numberwithin} of package \xpackage{amsmath} are used. + +Usually problems with duplicate destination names can be solved +by an appropriate definition of \cs{theH}. If option +\texttt{hypertexnames} is disabled, then a unique artificial +number is used instead of the counter value. In case of page +anchors the absolute page anchor is used. With option \texttt{plainpages} +the page anchors use the arabic form. In both latter cases \cs{hyperpage} +for index links is affected and might not work properly. + +If an unnumbered entity gets an anchor (starred forms of +chapters, sections, \dots) or \cs{phantomsection} is used, +then the dummy counter name \texttt{section*} and an artificial +unique number is used. + +If the final PDF file is going to be merged with another file, than +the destination names might clash, because both documents might +contain \texttt{chapter.1} or \texttt{page.1}. Also \xpackage{hyperref} +sets anchor with name \texttt{Doc-Start} at the begin of the document. +This can be resolved by redefining \cs{HyperDestNameFilter}. +Package \xpackage{hyperref} calls this macro each time, it uses a +destination name. +The macro must be expandable and expects the destination name +as only argument. As example, the macro is redefined to add +a prefix to all destination names: +\begin{quote} +\begin{verbatim} +\renewcommand*{\HyperDestNameFilter}[1]{\jobname-#1} +\end{verbatim} +\end{quote} +In document \texttt{docA} the destination name \texttt{chapter.2} +becomes \texttt{docA-chapter.2}. + +Destination names can also be used from the outside in URIs(, if the +driver has not removed or changed them), for example: +\begin{quote} +\begin{verbatim} +http://somewhere/path/file.pdf#nameddest=chapter.4 +\end{verbatim} +\end{quote} +However using a number seems unhappy. If another chapter is added +before, the number changes. But it is very difficult to pass +a new name for the destination to the anchor setting process that +is usually deep hidden in the internals. The first name of +\cs{label} after the anchor setting seems a good approximation: +\begin{quote} +\begin{verbatim} + \section{Introduction} + \label{intro} +\end{verbatim} +\end{quote} +Option \texttt{destlabel} checks for each \cs{label}, if there is +a new destination name active and replaces the destination +name by the label name. Because the destination name is already in use +because of the anchor setting, the new name is recorded in the \texttt{.aux} +file and used in the subsequent \hologo{LaTeX} run. The renaming is done by +a redefinition of \cs{HyperDestNameFilter}. That leaves the old +destination names intact (e.g., they are needed for \cs{autoref}). +This redefinition is also available as \cs{HyperDestLabelReplace}, +thus that an own redefinition can use it. +The following example also adds a prefix for \emph{all} destination names: +\begin{quote} +\begin{verbatim} +\renewcommand*{\HyperDestNameFilter}[1]{% + \jobname-\HyperDestLabelReplace{#1}% +} +\end{verbatim} +\end{quote} +The other case that only files prefixed that do not have a corresponding +\cs{label} is more complicate, because \cs{HyperDestLabelReplace} needs +the unmodified destination name as argument. This is solved by an +expandable string test (\cs{pdfstrcmp} of \hologo{pdfTeX} +or \cs{strcmp} of \hologo{XeTeX}, package \xpackage{pdftexcmds} also supports +\hologo{LuaTeX}): +\begin{quote} +\begin{verbatim} +\usepackage{pdftexcmds} +\makeatletter +\renewcommand*{\HyperDestNameFilter}[1]{% + \ifcase\pdf@strcmp{#1}{\HyperDestLabelReplace{#1}} % + \jobname-#1% + \else + \HyperDestLabelReplace{#1}% + \fi +} +\makeatother +\end{verbatim} +\end{quote} + +With option \texttt{destlabel} destinations can also named manually, +if the destination is not yet renamed: +\begin{quote} +\verb|\HyperDestRename{|\meta{destination}\verb|}{|\meta{newname}\verb|}| +\end{quote} + +Hint: Anchors can also be named and set by \cs{hypertarget}. + +\medskip +\begin{longtable}{>{\ttfamily}ll>{\itshape}ll} +destlabel & boolean & false & destinations are named by first \cs{label}\\ + & & & after anchor creation\\ +hypertexnames & boolean & true & use guessable names for links \\ +naturalnames & boolean & false & use \LaTeX-computed names for links \\ +plainpages & boolean & false & Forces page anchors to be named by the Arabic form \\ + & & & of the page number, rather than the formatted form. \\ +\end{longtable} + +\subsection{Configuration options} + +\begin{longtable}{>{\ttfamily}ll>{\itshape}lp{9cm}} +raiselinks & boolean & true & In the hypertex driver, the height of links is normally calculated by the driver as + simply the base line of contained text; this options forces \verb|\special| commands to + reflect the real height of the link (which could contain a graphic) \\ +breaklinks & boolean & both & This option is in hyperref only used in the dviwindo driver, in all other cases it doesn't do anything sensible---it neither allows nor prevents links to be broken. The ocgx2 package +checks the state of the boolean.\\ +pageanchor & boolean & true & Determines whether every page is given an implicit anchor at the top left corner. If this + is turned off, \verb|\printindex| will not contain + valid hyperlinks. \\ +nesting & boolean & false & Allows links to be nested; no drivers currently support this. +\end{longtable} + +Note for option \verb|breaklinks|: +The correct value is automatically set according to the driver features. +It can be overwritten for drivers that do not support broken links. +However, at any case, the link area will be wrong and displaced. + +\subsection{Backend drivers} + +If no driver is specified, the package tries to find a driver in +the following order: +\begin{enumerate} +\item Autodetection, some \TeX\ processors can be detected at \TeX\ macro + level (pdf\TeX, Xe\TeX, V\TeX). +\item Option \textsf{driverfallback}. If this option is set, its value + is taken as driver option. +\item Macro \cs{Hy@defaultdriver}. The macro takes a driver file + name (without file extension). +\item Package default is \textsf{hypertex}. +\end{enumerate} +Many distributions are using a driver file \texttt{hypertex.cfg} that +define \cs{Hy@defaultdriver} with \texttt{hdvips}. This is recommended +because driver \textsf{dvips} provides much more features than +\textsf{hypertex} for PDF generation. + +\begin{longtable}{@{}>{\ttfamily}lp{.8\hsize}@{}} +driverfallback & Its value is used as driver option\\ + & if the driver is not given or autodetected.\\ +dvipdfm & Sets up \textsf{hyperref} for use with the \textsf{dvipdfm} driver.\\ +dvipdfmx & Sets up \textsf{hyperref} for use with the \textsf{dvipdfmx} driver.\\ +dvips & Sets up \textsf{hyperref} for use with the \textsf{dvips} driver. \\ +dvipsone & Sets up \textsf{hyperref} for use with the \textsf{dvipsone} driver. \\ +dviwindo & Sets up \textsf{hyperref} for use with the \textsf{dviwindo} Windows previewer. \\ +hypertex & Sets up \textsf{hyperref} for use with the Hyper\TeX-compliant drivers. \\ +latex2html & Redefines a few macros for compatibility with \textsf{latex2html}. \\ +nativepdf & An alias for \textsf{dvips} \\ +pdfmark & An alias for \textsf{dvips} \\ +pdftex & Sets up \textsf{hyperref} for use with the \textsf{pdftex} program.\\ +ps2pdf & Redefines a few macros for compatibility with + Ghostscript's PDF writer, otherwise identical to + \textsf{dvips}. \\ +tex4ht & For use with \textsf{\TeX4ht} \\ +textures & For use with \textsf{Textures} \\ +vtex & For use with MicroPress' \textsf{VTeX}; the PDF + and HTML backends are detected automatically. \\ +vtexpdfmark & For use with \textsf{VTeX}'s PostScript backend. \\ +xetex & For use with Xe\TeX\ (using backend for dvipdfm). +\end{longtable} +\smallskip + +If you use \textsf{dviwindo}, you may need to redefine the macro +\ci{wwwbrowser} (the default is \verb|C:\netscape\netscape|) to tell +\textsf{dviwindo} what program to launch. Thus, users of Internet +Explorer might add something like this to hyperref.cfg: + +\begin{verbatim} +\renewcommand{\wwwbrowser}{C:\string\Program\space + Files\string\Plus!\string\Microsoft\space + Internet\string\iexplore.exe} +\end{verbatim} + +\subsection{Extension options} +\begin{longtable}{@{}>{\ttfamily}ll>{\itshape}lp{8cm}@{}} +extension & text & & Set the file extension (e.g.\ \textsf{dvi}) which will be appended to file links + created if you use the \xpackage{xr} package. \\ +hyperfigures & boolean & & \\ +backref & text & false & Adds `backlink' text to the end of each item in the bibliography, as a list of + section numbers. This can only work properly \emph{if} there is a blank line after + each \verb|\bibitem|. Supported values are \verb|section|, \verb|slide|, \verb|page|, + \verb|none|, or \verb|false|. If no value is given, \verb|section| is taken as default.\\ +pagebackref & boolean & false & Adds `backlink' text to the end of each item in the bibliography, as a list of page + numbers. \\ +hyperindex & boolean & true & Makes the page numbers of index entries into hyperlinks. Relays on unique + page anchors (\verb|pageanchor|, \ldots) + \verb|pageanchors| and \verb|plainpages=false|. \\ +hyperfootnotes & boolean & true & Makes the footnote marks into hyperlinks to the footnote text. + Easily broken \ldots\\ +encap & & & Sets encap character for hyperindex \\ +linktoc & text & section & make text (\verb|section|), page number (\verb|page|), both (\verb|all|) or nothing (\verb|none|) be link on TOC, LOF and LOT \\ +linktocpage & boolean & false & make page number, not text, be link on TOC, LOF and LOT \\ +breaklinks & boolean & false & allow links to break over lines by making links over multiple lines into PDF links to + the same target \\ +colorlinks & boolean & false & Colors the text of links and anchors. The colors chosen depend on the the type of + link. At present the only types of link distinguished are citations, page references, + URLs, local file references, and other links. + Unlike colored boxes, the colored + text remains when printing.\\ +linkcolor & color & red & Color for normal internal links. \\ +anchorcolor & color & black & Color for anchor text. Ignored by most drivers. \\ +citecolor & color & green & Color for bibliographical citations in text. \\ +filecolor & color & cyan & Color for URLs which open local files. \\ +menucolor & color & red & Color for Acrobat menu items. \\ +runcolor & color & filecolor & Color for run links (launch annotations). \\ +urlcolor & color & magenta & Color for linked URLs. \\ +allcolors & color & & Set all color options (without border and field options).\\ +frenchlinks & boolean & false & Use small caps instead of color for links.\\ +hidelinks & & & Hide links (removing color and border). \\ +\end{longtable} \smallskip + +Note that all color names must be defined before use, following the +normal system of the standard \LaTeX\ \xpackage{color} package. + +\subsection{PDF-specific display options} +\begin{longtable}{@{}>{\ttfamily}ll>{\itshape}lp{7.6cm}@{}} +bookmarks & boolean & true & A set of Acrobat bookmarks are written, in a manner similar to the + table of contents, requiring two passes of \LaTeX. Some postprocessing + of the bookmark file (file extension \texttt{.out}) may be needed to + translate \LaTeX\ codes, since bookmarks must be written in PDFEncoding. + To aid this process, the \texttt{.out} file is not rewritten by \LaTeX\ + if it is edited to contain a line \verb|\let\WriteBookmarks\relax| \\ +bookmarksopen & boolean & false & If Acrobat bookmarks are requested, show them with all the subtrees + expanded. \\ +bookmarksopenlevel & parameter & & level (\ci{maxdimen}) to which bookmarks are open \\ +bookmarksnumbered & boolean & false & If Acrobat bookmarks are requested, include section numbers. \\ +bookmarkstype & text & toc & to specify which `toc' file to mimic \\ +CJKbookmarks & boolean & false & + This option should be used to produce CJK bookmarks. + Package \verb|hyperref| + supports both normal and preprocessed mode of the \xpackage{CJK} package; + during the creation of bookmarks, it simply replaces CJK's macros + with special versions which expand to the corresponding character + codes. Note that without the `unicode' option of hyperref you get + PDF files which actually violate the PDF specification because + non-Unicode character codes are used -- some PDF readers localized + for CJK languages (most notably Acroread itself) support this. + Also note that option `CJKbookmarks' cannot be used together + with option `unicode'. + + No mechanism is provided to translate non-Unicode bookmarks to + Unicode; for portable PDF documents only Unicode encoding should + be used.\\ +pdfhighlight & name & /I & How link buttons behave when selected; /I is for inverse (the default); + the other possibilities are /N (no effect), /O (outline), and /P (inset + highlighting). \\ +citebordercolor & RGB color & 0 1 0 & The color of the box around citations \\ +filebordercolor & RGB color & 0 .5 .5 & The color of the box around links to files \\ +linkbordercolor & RGB color & 1 0 0 & The color of the box around normal links \\ +menubordercolor & RGB color & 1 0 0 & The color of the box around Acrobat menu links \\ +urlbordercolor & RGB color & 0 1 1 & The color of the box around links to URLs \\ +runbordercolor & RGB color & 0 .7 .7 & Color of border around `run' links \\ +allbordercolors & & & Set all border color options \\ +pdfborder & & 0 0 1 & The style of box around links; defaults to a box with lines of 1pt thickness, + but the colorlinks option resets it to produce no border. +\end{longtable} + +Note that the color of link borders can be specified \emph{only} as 3 +numbers in the range 0..1, giving an RGB color. You cannot use colors +defined in \TeX. Since version 6.76a this is no longer true. +Especially with the help of package \xpackage{xcolor} the usual +color specifications of package \xpackage{(x)color} can be used. +For further information see description of package \xpackage{hycolor}. + +The bookmark commands are stored in a file called +\textit{jobname}\texttt{.out}. The files is not processed by \LaTeX\ so +any markup is passed through. You can postprocess this file as needed; +as an aid for this, the \texttt{.out} file is not overwritten on the +next \TeX\ run if it is edited to contain the line +\begin{verbatim} +\let\WriteBookmarks\relax +\end{verbatim} + +\subsection{PDF display and information options} +\begin{longtable}{@{}>{\ttfamily}l>{\raggedright}p{\widthof{key value}}>{\itshape}lp{7cm}@{}} +baseurl & URL & & Sets the base URL of the PDF document \\ +pdfpagemode & name & empty & Determines how the file is opening in Acrobat; the possibilities are + \verb|UseNone|, \verb|UseThumbs| (show thumbnails), \verb|UseOutlines| + (show bookmarks), \verb|FullScreen|, \verb|UseOC| (PDF 1.5), + and \verb|UseAttachments| (PDF 1.6). If no mode if explicitly chosen, but the + bookmarks option is set, \verb|UseOutlines| is used. \\ +pdftitle & text & & Sets the document information Title field \\ +pdfauthor & text & & Sets the document information Author field \\ +pdfsubject & text & & Sets the document information Subject field \\ +pdfcreator & text & & Sets the document information Creator field \\ +addtopdfcreator & text & & Adds additional text to the document information Creator field \\ +pdfkeywords & text & & Sets the document information Keywords field \\ +pdftrapped & name & empty & Sets the document information Trapped entry. Possible values are \verb|True|, \verb|False| and \verb|Unknown|. + An empty value means, the entry is not set.\\ +% +pdfinfo & key value list & empty & Alternative interface for setting the + document information.\\ +pdfview & name & XYZ & Sets the default PDF `view' for each link \\ +pdfstartpage & integer & 1 & Determines on which page the PDF file is opened. An empty value means, the entry is not set.\\ +pdfstartview & name & Fit & Set the startup page view \\ +pdfremotestartview & name & Fit & Set the startup page view of remote PDF files \\ +pdfpagescrop & n n n n & & Sets the default PDF crop box for pages. This should be a set of four numbers \\ +pdfcenterwindow & boolean & false & position the document window in the center of the screen \\ +pdfdirection & name & empty & direction setting. Possible values: \verb|L2R| (left to right) and + \verb|R2L| (right to left)\\ +pdfdisplaydoctitle & boolean & false & display document title instead of file name in title bar\\ +pdfduplex & name & empty & paper handling option for print dialog. Possible vatues are: + \verb|Simplex| (print single-sided), + \verb|DuplexFlipShortEdge| (duplex and flip on the short edge of the sheet), + \verb|DuplexFlipLongEdge| (duplex and flip on the long edge of the sheet)\\ + +pdffitwindow & boolean & false & resize document window to fit document size \\ +pdflang & name & relax & PDF language identifier (RFC 3066)\\ +pdfmenubar & boolean & true & make PDF viewer's menu bar visible \\ +pdfnewwindow & boolean & false & make links that open another PDF file start a new window \\ +pdfnonfullscreenpagemode + & name & empty & page mode setting on exiting full-screen mode. Possible values are + \verb|UseNone|, \verb|UseOutlines|, \verb|UseThumbs|, and \verb|UseOC|\\ +pdfnumcopies & integer & empty & number of printed copies \\ +pdfpagelayout & name & empty & set layout of PDF pages. Possible values: + \verb|SinglePage|, \verb|OneColumn|, + \verb|TwoColumnLeft|, \verb|TwoColumnRight|, + \verb|TwoPageLeft|, and \verb|TwoPageRight| \\ +pdfpagelabels & boolean & true & set PDF page labels \\ +pdfpagetransition & name & empty & set PDF page transition style. Possible values are + \verb|Split|, \verb|Blinds|, \verb|Box|, \verb|Wipe|, + \verb|Dissolve|, \verb|Glitter|, \verb|R|, + \verb|Fly|, \verb|Push|, + \verb|Cover|, \verb|Uncover|, + \verb|Fade|. + The default according to the PDF~Reference is \verb|R|, + which simply replaces the old page with the new one. \\ +pdfpicktraybypdfsize + & boolean & false & specify whether PDF page size is used to select input paper tray in print dialog \\ +pdfprintarea & name & empty & set /PrintArea of viewer preferences. Possible values are + \verb|MediaBox|, \verb|CropBox|, + \verb|BleedBox|, \verb|TrimBox|, and \verb|ArtBox|. + The dafault according to the PDF~Refence is \verb|CropBox| \\ +pdfprintclip & name & empty & set /PrintClip of viewer preferences. Possible values are + \verb|MediaBox|, \verb|CropBox|, + \verb|BleedBox|, \verb|TrimBox|, and \verb|ArtBox|. + The dafault according to the PDF~Refence is \verb|CropBox| \\ +pdfprintpagerange & n n (n n)* + & empty & set /PrintPageRange of viewer preferences\\ +pdfprintscaling & name & empty & page scaling option for print dialog + (option /PrintScaling of viewer + preferences, PDF 1.6); + valid values are \verb|None| and + \verb|AppDefault| \\ +pdftoolbar & boolean & true & make PDF toolbar visible \\ +pdfviewarea & name & empty & set /ViewArea of viewer preferences. Possible values are + \verb|MediaBox|, \verb|CropBox|, + \verb|BleedBox|, \verb|TrimBox|, and \verb|ArtBox|. + The dafault according to the PDF~Refence is \verb|CropBox| \\ +pdfviewclip & name & empty & set /ViewClip of viewer preferences Possible values are + \verb|MediaBox|, \verb|CropBox|, + \verb|BleedBox|, \verb|TrimBox|, and \verb|ArtBox|. + The dafault according to the PDF~Refence is \verb|CropBox| \\ +pdfwindowui & boolean & true & make PDF user interface elements visible \\ +unicode & boolean & true & Unicode encoded PDF strings +\end{longtable} + +Each link in Acrobat carries its own magnification level, which is set +using PDF coordinate space, which is not the same as \TeX's. The unit +is bp and the origin is in the lower left corner. See also +\verb|\hypercalcbp| that is explained on page \pageref{hypercalcbp}. +pdf\TeX\ +works by supplying default values for \texttt{XYZ} (horizontal $\times$ +vertical $\times$ zoom) and \texttt{FitBH}. However, drivers using +\texttt{pdfmark} do not supply defaults, so \textsf{hyperref} passes in +a value of -32768, which causes Acrobat to set (usually) sensible +defaults. The following are possible values for the \texttt{pdfview}, +\texttt{pdfstartview} and \texttt{pdfremotestartview} parameters. + +\begin{longtable}{@{}>{\ttfamily}l>{\itshape}lp{7cm}@{}} +XYZ & left top zoom & Sets a coordinate and a zoom factor. If any one is null, the source link value is used. + \textit{null null null} will give the same values as the current page. \\ +Fit & & Fits the page to the window. \\ +FitH & top & Fits the width of the page to the window. \\ +FitV & left & Fits the height of the page to the window. \\ +FitR & left bottom right top & Fits the rectangle specified by the four coordinates to the window. \\ +FitB & & Fits the page bounding box to the window. \\ +FitBH & top & Fits the width of the page bounding box to the window. \\ +FitBV & left & Fits the height of the page bounding box to the window. \\ +\end{longtable} + +The \texttt{pdfpagelayout} can be one of the following values. + +\begin{longtable}{@{}>{\ttfamily}lp{10cm}@{}} +SinglePage & Displays a single page; advancing flips the page \\ +OneColumn & Displays the document in one column; continuous scrolling. \\ +TwoColumnLeft & Displays the document in two columns, odd-numbered pages to the left. \\ +TwoColumnRight & Displays the document in two columns, odd-numbered pages to the right.\\ +TwoPageLeft & Displays two pages, odd-numbered pages to the left (since PDF 1.5).\\ +TwoPageRight & Displays two pages, odd-numbered pages to the right (since PDF 1.5). +\end{longtable} + +Finally, the \texttt{pdfpagetransition} can be one of the following +values, where \textit{/Di} stands for direction of motion in degrees, +generally in 90$^{\circ}$\ steps, \textit{/Dm} is a horizontal +(\texttt{/H}) or vertical (\texttt{/V}) dimension (e.g.\ \texttt{Blinds +/Dm /V}), and \textit{/M} is for motion, either in (\texttt{/I}) or out +(\texttt{/O}). + +\begin{longtable}{@{}>{\ttfamily}llp{8.5cm}@{}} +Blinds & /Dm & Multiple lines distributed evenly across the screen sweep in the same direction to reveal the new + page. \\ +Box & /M & A box sweeps in or out. \\ +Dissolve & & The page image dissolves in a piecemeal fashion to reveal the new page. \\ +Glitter & /Di & Similar to Dissolve, except the effect sweeps across the screen. \\ +Split & /Dm /M & Two lines sweep across the screen to reveal the new page. \\ +Wipe & /Di & A single line sweeps across the screen to reveal the new page. \\ +R & & Simply replaces the old page with the new one. \\ +Fly & /Di /M & Changes are flown out or in (as specified by /M), in the direction + specified by /Di, to or from a location that is + offscreen except when /Di is None. \\ +Push & /Di & The old page slides off the screen while the new page slides in, + pushing the old page out in the direction + specified by /Di. \\ +Cover & /Di & The new page slides on to the screen in the direction specified + by /Di, covering the old page. \\ +Uncover & /Di & The old page slides off the screen in the direction specified by + /Di, uncovering the new page in the direction + specified by /Di. \\ +Fade & & The new page gradually becomes visible through the old one. + +\end{longtable} + +\subsection{Option \texttt{pdfinfo}} + +The information entries can be set using \texttt{pdftitle}, +\texttt{pdfsubject}, \dots. Option \texttt{pdfinfo} provides an alternative +interface. It takes a key value list. The key names are the names that +appear in the PDF information dictionary directly. Known keys such as +\texttt{Title}, \texttt{Subject}, \texttt{Trapped} and other are mapped to +options \texttt{pdftitle}, \texttt{subject}, \texttt{trapped}, \dots +Unknown keys are added to the information dictionary. Their values are text +strings (see PDF specification). +Example: +\begin{quote} +\begin{verbatim} +\hypersetup{ + pdfinfo={ + Title={My Title}, + Subject={My Subject}, + NewKey={Foobar}, + % ... + } +} +\end{verbatim} +\end{quote} + +\subsection{Big alphabetical list} + +The following is a complete listing of available options for +\textsf{hyperref}, arranged alphabetically. + +\begin{longtable}{@{}>{\ttfamily}llp{7cm}@{}} +allbordercolors & & Set all border color options\\ +allcolors & & Set all color options (without border and field options)\\ +anchorcolor & \textit{black} & set color of anchors, ignored by most drivers. \\ +backref & \textit{false} & do bibliographical back references \\ +baseurl & \textit{empty} & set base URL for document \\ +bookmarks & \textit{true} & make bookmarks \\ +bookmarksnumbered & \textit{false} & put section numbers in bookmarks \\ +bookmarksopen & \textit{false} & open up bookmark tree \\ +bookmarksopenlevel & \ttfamily\ci{maxdimen} & level to which bookmarks are open \\ +bookmarkstype & \textit{toc} & to specify which `toc' file to mimic \\ +breaklinks & \textit{false} & allow links to break over lines \\ +CJKbookmarks & \textit{false} & to produce CJK bookmarks\\ +citebordercolor & \textit{0 1 0} & color of border around cites \\ +citecolor & \textit{green} & color of citation links \\ +colorlinks & \textit{false} & color links \\ + & \textit{true} & (\textsf{tex4ht}, \textsf{dviwindo}) \\ +debug & \textit{false} & provide details of anchors defined; same as verbose \\ +destlabel & \textit{false} & destinations are named by the first \verb|\label| after the anchor creation \\ +draft & \textit{false} & do not do any hyperlinking \\ +driverfallback & & default if no driver specified or detected\\ +dvipdfm & & use \textsf{dvipdfm} backend \\ +dvipdfmx & & use \textsf{dvipdfmx} backend \\ +dvips & & use \textsf{dvips} backend \\ +dvipsone & & use \textsf{dvipsone} backend \\ +dviwindo & & use \textsf{dviwindo} backend \\ +encap & & to set encap character for hyperindex \\ +extension & \textit{dvi} & suffix of linked files \\ +filebordercolor & \textit{0 .5 .5} & color of border around file links \\ +filecolor & \textit{cyan} & color of file links \\ +final & \textit{true} & opposite of option draft \\ +frenchlinks & \textit{false} & use small caps instead of color for links \\ +hidelinks & & Hide links (removing color and border) \\ +hyperfigures & \textit{false} & make figures hyper links \\ +hyperfootnotes & \textit{true} & set up hyperlinked footnotes \\ +hyperindex & \textit{true} & set up hyperlinked indices \\ +hypertex & & use \textsf{Hyper\TeX} backend \\ +hypertexnames & \textit{true} & use guessable names for links \\ +implicit & \textit{true} & redefine \LaTeX\ internals \\ +latex2html & & use \textsf{\LaTeX2HTML} backend \\ +linkbordercolor & \textit{1 0 0} & color of border around links \\ +linkcolor & \textit{red} & color of links \\ +linktoc & \textit{section} & make text be link on TOC, LOF and LOT \\ +linktocpage & \textit{false} & make page number, not text, be link on TOC, LOF and LOT \\ +menubordercolor & \textit{1 0 0} & color of border around menu links \\ +menucolor & \textit{red} & color for menu links \\ +nativepdf & \textit{false} & an alias for \textsf{dvips} \\ +naturalnames & \textit{false} & use \LaTeX-computed names for links \\ +nesting & \textit{false} & allow nesting of links \\ +pageanchor & \textit{true} & put an anchor on every page \\ +pagebackref & \textit{false} & backreference by page number \\ +pdfauthor & \textit{empty} & text for PDF Author field \\ +pdfborder & \textit{0 0 1} & width of PDF link border \\ + & \textit{0 0 0} & (\texttt{colorlinks)} \\ +pdfborderstyle & & border style for links \\ +pdfcenterwindow & \textit{false} & position the document window in the center of the screen \\ +pdfcreator & \textit{LaTeX with} & text for PDF Creator field \\ + & \textit{hyperref} & \\ +pdfdirection & \textit{empty} & direction setting \\ +pdfdisplaydoctitle & \textit{false} & display document title instead + of file name in title bar\\ +pdfduplex & \textit{empty} & paper handling option for + print dialog\\ +pdffitwindow & \textit{false} & resize document window to fit document size \\ +pdfhighlight & \textit{/I} & set highlighting of PDF links \\ +pdfinfo & \textit{empty} & alternative interface for setting document information\\ +pdfkeywords & \textit{empty} & text for PDF Keywords field \\ +pdflang & \textit{relax} & PDF language identifier (RFC 3066) \\ +pdfmark & \textit{false} & an alias for \textsf{dvips} \\ +pdfmenubar & \textit{true} & make PDF viewer's menu bar visible \\ +pdfnewwindow & \textit{false} & make links that open another PDF \\ + & & file start a new window \\ +pdfnonfullscreenpagemode + & \textit{empty} & page mode setting on exiting + full-screen mode\\ +pdfnumcopies & \textit{empty} & number of printed copies\\ +pdfpagelabels & \textit{true} & set PDF page labels \\ +pdfpagelayout & \textit{empty} & set layout of PDF pages \\ +pdfpagemode & \textit{empty} & set default mode of PDF display \\ +pdfpagescrop & \textit{empty} & set crop size of PDF document \\ +pdfpagetransition & \textit{empty} & set PDF page transition style \\ +pdfpicktraybypdfsize + & \textit{empty} & set option for print dialog \\ +pdfprintarea & \textit{empty} & set /PrintArea of viewer preferences \\ +pdfprintclip & \textit{empty} & set /PrintClip of viewer preferences \\ +pdfprintpagerange & \textit{empty} & set /PrintPageRange of viewer preferences \\ +pdfprintscaling & \textit{empty} & page scaling option for print dialog \\ +pdfproducer & \textit{empty} & text for PDF Producer field \\ +pdfremotestartview & \textit{Fit} & starting view of remote PDF documents \\ +pdfstartpage & \textit{1} & page at which PDF document opens \\ +pdfstartview & \textit{Fit} & starting view of PDF document \\ +pdfsubject & \textit{empty} & text for PDF Subject field \\ +pdftex & & use \textsf{pdf\TeX} backend \\ +pdftitle & \textit{empty} & text for PDF Title field \\ +pdftoolbar & \textit{true} & make PDF toolbar visible \\ +pdftrapped & \textit{empty} & Sets the document information Trapped entry. + Possible values are \texttt{True}, \texttt{False} and \texttt{Unknown}. + An empty value means, the entry is not set.\\ +pdfview & \textit{XYZ} & PDF `view' when on link traversal \\ +pdfviewarea & \textit{empty} & set /ViewArea of viewer preferences \\ +pdfviewclip & \textit{empty} & set /ViewClip of viewer preferences \\ +pdfwindowui & \textit{true} & make PDF user interface elements visible \\ +plainpages & \textit{false} & do page number anchors as plain Arabic \\ +ps2pdf & & use \textsf{ps2pdf} backend \\ +psdextra & \textit{false} & define more short names for PDF string commands \\ +raiselinks & \textit{false} & raise up links (for \textsf{Hyper\TeX} backend) \\ +runbordercolor & \textit{0 .7 .7} & color of border around `run' links \\ +runcolor & \textit{filecolor} & color of `run' links\\ +setpagesize & \textit{true} & set page size by special driver commands \\ +tex4ht & & use \textsf{\TeX4ht} backend \\ +textures & & use \textsf{Textures} backend \\ +unicode & \textit{true} & Unicode encoded pdf strings, starting with version 2021-02-07 v7.00h set by default to true for all engines. \\ +urlbordercolor & \textit{0 1 1} & color of border around URL links \\ +urlcolor & \textit{magenta} & color of URL links \\ +verbose & \textit{false} & be chatty \\ +vtex & & use \textsf{VTeX} backend\\ +xetex & & use \textsf{Xe\TeX} backend\\ +\end{longtable} + +\section{Additional user macros} + +If you need to make references to URLs, or write explicit links, the +following low-level user macros are provided: + +\begin{cmdsyntax} +\ci{href}\verb|[|\emph{options}\verb|]|\verb|{|\emph{URL}\verb|}{|\emph{text}\verb|}| +\end{cmdsyntax} + +\noindent The \emph{text} is made a hyperlink to the \emph{URL}; this +must be a full URL (relative to the base URL, if that is defined). The +special characters \# and \~{} do \emph{not} need to be escaped in any +way (unless the command is used in the argument of another command). + +The optional argument \emph{options} recognizes the hyperref options +\texttt{pdfremotestartview}, \texttt{pdfnewwindow} and the following +key value options: +\begin{description} +\item[\texttt{page}:] Specifies the start page number of remote +PDF documents. First page is \verb|1|. +\item[\texttt{ismap}:] Boolean key, if set to \verb|true|, the +URL should appended by the coordinates as query parameters by +the PDF viewer. +\item[\texttt{nextactionraw}:] The value of key \verb|/Next| of +action dictionaries, see PDF specification. +\end{description} + +\begin{cmdsyntax} +\ci{url}\verb|{|\emph{URL}\verb|}| +\end{cmdsyntax} + +\noindent Similar to +\ci{href}\verb|{|\emph{URL}\verb|}{|\ci{nolinkurl}\verb|{|\emph{URL}\verb|}}|. +Depending on the driver \verb|\href| also tries to detect the link type. +Thus the result can be a url link, file link, \dots + +\begin{cmdsyntax} +\ci{nolinkurl}\verb|{|\emph{URL}\verb|}| +\end{cmdsyntax} + +\noindent Write \emph{URL} in the same way as \verb|\url|, + without creating a hyperlink. + +\begin{cmdsyntax} +\ci{hyperbaseurl}\verb|{|\emph{URL}\verb|}| +\end{cmdsyntax} + +\noindent A base \emph{URL} is established, which is prepended to other +specified URLs, to make it easier to write portable documents. + +\begin{cmdsyntax} +\ci{hyperimage}\verb|{|\emph{imageURL}\verb|}{|\emph{text}\verb|}| +\end{cmdsyntax} + +\noindent The link to the image referenced by the URL is inserted, using +\emph{text} as the anchor. + + For drivers that produce HTML, the image itself is inserted by the +browser, with the \emph{text} being ignored completely. + +\begin{cmdsyntax} +\ci{hyperdef}\verb|{|\emph{category}\verb|}{|\emph{name}\verb|}{|\emph{text}\verb|}| +\end{cmdsyntax} + +\noindent A target area of the document (the \emph{text}) is marked, and +given the name \emph{category.name} + +\begin{cmdsyntax} +\ci{hyperref}\verb|{|\emph{URL}\verb|}{|\emph{category}\verb|}{|\emph{name}\verb|}{|\emph{text}\verb|}| +\end{cmdsyntax} + +\noindent \emph{text} is made into a link to \emph{URL\#category.name} + +\begin{cmdsyntax} +\ci{hyperref}\verb|[|\emph{label}\verb|]{|\emph{text}\verb|}| +\end{cmdsyntax} + +\noindent +\emph{text} is made into a link to the same place as +\verb|\ref{|\emph{label}\verb|}| would be linked. + +\begin{cmdsyntax} +\ci{hyperlink}\verb|{|\emph{name}\verb|}{|\emph{text}\verb|}| +\end{cmdsyntax} +\begin{cmdsyntax} +\ci{hypertarget}\verb|{|\emph{name}\verb|}{|\emph{text}\verb|}| +\end{cmdsyntax} + +\noindent A simple internal link is created with \verb|\hypertarget|, +with two parameters of an anchor \emph{name}, and anchor +\emph{text}. \verb|\hyperlink| has two arguments, the name of a +hypertext object defined somewhere by \verb|\hypertarget|, and the +\emph{text} which be used as the link on the page. + +Note that in HTML parlance, the \verb|\hyperlink| command inserts a +notional \# in front of each link, making it relative to the current +testdocument; \verb|\href| expects a full URL. + +\begin{cmdsyntax} +\ci{phantomsection} +\end{cmdsyntax} + +\noindent +This sets an anchor at this location. It works similar to +\verb|\hypertarget{}{}| with an automatically chosen anchor name. +Often it is used in conjunction +with \verb|\addcontentsline| for sectionlike things (index, bibliography, +preface). \verb|\addcontentsline| refers to the latest previous location +where an anchor is set. Example: +\begin{quote} +\begin{verbatim} +\cleardoublepage +\phantomsection +\addcontentsline{toc}{chapter}{\indexname} +\printindex +\end{verbatim} +\end{quote} +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. + +\begin{cmdsyntax} +\ci{autoref}\verb|{|\emph{label}\verb|}| +\end{cmdsyntax} + +\noindent +This is a replacement for the usual \verb|\ref| command that places a +contextual label in front of the reference. This gives your users a +bigger target to click for hyperlinks (e.g.\ `section 2' instead of +merely the number `2'). + +The label is worked out from the context of the original \verb|\label| +command by \textsf{hyperref} by using the macros listed below (shown +with their default values). The macros can be (re)defined in documents +using \verb|\(re)newcommand|; note that some of these macros are already +defined in the standard document classes. The mixture of lowercase and +uppercase initial letters is deliberate and corresponds to the author's +practice. + +For each macro below, \textsf{hyperref} checks \ci{*autorefname} before +\ci{*name}. For instance, it looks for \ci{figureautorefname} before +\ci{figurename}. + +\begin{longtable}{@{}lp{10cm}@{}} +\textit{Macro} & \textit{Default} \\ +\ci{figurename} & Figure \\ +\ci{tablename} & Table \\ +\ci{partname} & Part \\ +\ci{appendixname} & Appendix \\ +\ci{equationname} & Equation \\ +\ci{Itemname} & item \\ +\ci{chaptername} & chapter \\ +\ci{sectionname} & section \\ +\ci{subsectionname} & subsection \\ +\ci{subsubsectionname} & subsubsection \\ +\ci{paragraphname} & paragraph \\ +\ci{Hfootnotename} & footnote \\ +\ci{AMSname} & Equation \\ +\ci{theoremname} & Theorem\\ +\ci{page} & page\\ +\end{longtable} + +Example for a redefinition if \textsf{babel} is used: +\begin{quote} +\begin{verbatim} +\usepackage[ngerman]{babel} +\addto\extrasngerman{% + \def\subsectionautorefname{Unterkapitel}% +} +\end{verbatim} +\end{quote} + +Hint: \cs{autoref} works via the counter name that the reference +is based on. Sometimes \cs{autoref} chooses the wrong name, if +the counter is used for different things. For example, it happens +with \cs{newtheorem} if a lemma shares a counter with theorems. +Then package \xpackage{aliascnt} provides a method to generate a +simulated second counter that allows the differentiation between +theorems and lemmas: +\begin{quote} +\begin{verbatim} +\documentclass{article} + +\usepackage{aliascnt} +\usepackage{hyperref} + +\newtheorem{theorem}{Theorem} + +\newaliascnt{lemma}{theorem} +\newtheorem{lemma}[lemma]{Lemma} +\aliascntresetthe{lemma} + +\providecommand*{\lemmaautorefname}{Lemma} + +\begin{document} + +We will use \autoref{a} to prove \autoref{b}. + +\begin{lemma}\label{a} + Nobody knows. +\end{lemma} + +\begin{theorem}\label{b} + Nobody is right. +\end{theorem}. + +\end{document} +\end{verbatim} +\end{quote} + +\begin{cmdsyntax} +\ci{autopageref}\verb|{|\emph{label}\verb|}| +\end{cmdsyntax} + +\noindent +It replaces \verb|\pageref| and adds the name for page in front of +the page reference. First \ci{pageautorefname} is checked before +\ci{pagename}. + +For instances where you want a reference to use the correct counter, but +not to create a link, there are starred forms (these starred forms exist even if +hyperref has been loaded with \verb|implicit=false|): + +\begin{cmdsyntax} +\ci{ref*}\verb|{|\emph{label}\verb|}| +\end{cmdsyntax} + +\begin{cmdsyntax} +\ci{pageref*}\verb|{|\emph{label}\verb|}| +\end{cmdsyntax} + +\begin{cmdsyntax} +\ci{autoref*}\verb|{|\emph{label}\verb|}| +\end{cmdsyntax} + +\begin{cmdsyntax} +\ci{autopageref*}\verb|{|\emph{label}\verb|}| +\end{cmdsyntax} + +A typical use would be to write +\begin{verbatim} +\hyperref[other]{that nice section (\ref*{other}) we read before} +\end{verbatim} + +We want \verb|\ref*{other}| to generate the correct number, but not to +form a link, since we do this ourselves with \ci{hyperref}. + +\begin{cmdsyntax} +\ci{pdfstringdef}\verb|{|\emph{macroname}\verb|}{|\emph{\TeX string}\verb|}| +\end{cmdsyntax} + +\ci{pdfstringdef} returns a macro containing the PDF string. (Currently +this is done globally, but do not rely on it.) All the following tasks, +definitions and redefinitions are made in a group to keep them local: + +\begin{itemize} +\item Switching to PD1 or PU encoding +\item Defining the \Quote{octal sequence commands} (\verb|\345|): \verb|\edef\3{\string\3}| +\item Special glyphs of \TeX: \verb|\{|, \verb|\%|, \verb|\&|, \verb|\space|, \verb|\dots|, etc. +\item National glyphs (\textsf{german.sty}, \textsf{french.sty}, etc.) +\item Logos: \verb|\TeX|, \verb|\eTeX|, \verb|\MF|, etc. +\item Disabling commands that do not provide useful functionality in bookmarks: +\verb|\label|, \verb|\index|, \verb|\glossary|, \verb|\discretionary|, \verb|\def|, \verb|\let|, etc. +\item \LaTeX's font commands like \verb|\textbf|, etc. +\item Support for \verb|\xspace| provided by the \xpackage{xspace} package +\end{itemize} + +In addition, parentheses are protected to avoid the danger of unsafe +unbalanced parentheses in the PDF string. For further details, see Heiko +Oberdiek's Euro\TeX\ paper distributed with \textsf{hyperref}. + +\begin{cmdsyntax} +\ci{begin}\verb|{NoHyper}|\ldots\ci{end}\verb|{NoHyper}| +\end{cmdsyntax} + Sometimes we just don't want the wretched package interfering + with us. Define an environment we can put in manually, or include + in a style file, which stops the hypertext functions doing anything. + This is used, for instance, in the Elsevier classes, to stop + \verb|hyperref| playing havoc in the front matter. + +\subsection{Bookmark macros} + +\subsubsection{Setting bookmarks} + +Usually \textsf{hyperref} automatically adds bookmarks for +\verb|\section| and similar macros. But they can also set manually. + +\begin{cmdsyntax} +\ci{pdfbookmark}\verb|[|\emph{level}\verb|]{|text\verb|}{|\emph{name}\verb|}| +\end{cmdsyntax} +creates a bookmark with the specified text and at the given level (default is +0). As name for the internal anchor name is used (in conjunction with +level). Therefore the name must be unique (similar to \verb|\label|). + +\begin{cmdsyntax} +\ci{currentpdfbookmark}\verb|{|\emph{text}\verb|}{|\emph{name}\verb|}| +\end{cmdsyntax} +creates a bookmark at the current level. + +\begin{cmdsyntax} +\ci{subpdfbookmark}\verb|{|\emph{text}\verb|}{|\emph{name}\verb|}| +\end{cmdsyntax} +creates a bookmark one step down in the bookmark hierarchy. +Internally the current level is increased by one. + +\begin{cmdsyntax} +\ci{belowpdfbookmark}\verb|{|\emph{text}\verb|}{|\emph{name}\verb|}| +\end{cmdsyntax} +creates a bookmark below the current bookmark level. However after the +command the current bookmark level has not changed. + +\noindent \textbf{Hint:} Package \textsf{bookmark} replaces +\textsf{hyperref}'s bookmark organization by a new algorithm: +\begin{itemize} +\item Usually only one \LaTeX\ run is needed. +\item More control over the bookmark appearance (color, font). +\item Different bookmark actions are supported (external file links, + URLs, \dots). +\end{itemize} +Therefore I recommend using this package. + +\subsubsection{Replacement macros} + +\textsf{hyperref} takes the text for bookmarks from the arguments of +commands like \ci{section}, which can contain things like math, colors, +or font changes, none of which will display in bookmarks as is. + +\begin{cmdsyntax} +\ci{texorpdfstring}\verb|{|\emph{\TeX string}\verb|}{|\emph{PDFstring}\verb|}| +\end{cmdsyntax} + +For example, +\begin{verbatim} +\section{Pythagoras: + \texorpdfstring{$ a^2 + b^2 = c^2 $}{% + a\texttwosuperior\ + b\texttwosuperior\ = + c\texttwosuperior + }% +} +\section{\texorpdfstring{\textcolor{red}}{}{Red} Mars} +\end{verbatim} + +\ci{pdfstringdef} executes the hook \pdfstringdefPreHook before it +expands the string. Therefore, you can use this hook to perform +additional tasks or to disable additional commands. + +\begin{verbatim} +\expandafter\def\expandafter\pdfstringdefPreHook +\expandafter{% + \pdfstringdefPreHook + \renewcommand{\mycommand}[1]{}% +} +\end{verbatim} + +However, for disabling commands, an easier way is via +\ci{pdfstringdefDisableCommands}, which adds its argument to the +definition of \ci{pdfstringdefPreHook} (`@' can here be used as letter in +command names): + +\begin{verbatim} +\pdfstringdefDisableCommands{% + \let~\textasciitilde + \def\url{\pdfstringdefWarn\url}% + \let\textcolor\@gobble +} +\end{verbatim} + +\subsection{Pagelabels} +\begin{cmdsyntax} +\ci{thispdfpagelabel}\verb|{|\emph{page number format}\verb|}| +\end{cmdsyntax} + +This allows to change format of the page number shown in the tool bar of +a PDF viewer for a specific page, for example + +\verb+\thispdfpagelabel{Empty Page-\roman{page}}+ + +The command affects the page on which it is executed, so asynchronous page breaking +should be taken into account. It should be used in places where for example \verb+\thispagestyle+ can be use too. + +\subsection{Utility macros} + +\label{hypercalcbp} +\begin{cmdsyntax} +\ci{hypercalcbp}\verb|{|\emph{dimen specification}\verb|}| +\end{cmdsyntax} +\noindent +\verb|\hypercalcbp| takes a \TeX\ dimen specification and +converts it to bp and returns the number without the unit. +This is useful for options \verb|pdfview|, \verb|pdfstartview| +and \verb|pdfremotestartview|. +Example: +\begin{quote} +\begin{verbatim} +\hypersetup{ + pdfstartview={FitBH \hypercalcbp{\paperheight-\topmargin-1in + -\headheight-\headsep} +} +\end{verbatim} +\end{quote} +The origin of the PDF coordinate system is the lower left corner. + +Note, for calculations you need either package \xpackage{calc} or +\hologo{eTeX}. Nowadays the latter should automatically be enabled +for \hologo{LaTeX} formats. Users without \hologo{eTeX}, please, look +in the source documentation \verb|hyperref.dtx| for further +limitations. + +Also \cs{hypercalcbp} cannot be used in option specifications +of \cs{documentclass} and \cs{usepackage}, because +\hologo{LaTeX} expands the option lists of these commands. However +package \xpackage{hyperref} is not yet loaded and an undefined control +sequence error would arise. + +\section[New Features]{New Features% +\footnote{This section moved from the README file, needs more integration into the manual}} + + +\subsection{Option `pdflinkmargin'} + + Option `pdflinkmargin' is an experimental option for specifying + a link margin, if the driver supports this. Default is 1 pt for + supporting drivers. + + +\begin{description} +\item[pdfTeX] +\begin{itemize} + \item The link area also depends on the surrounding box. + \item Settings have local effect. + \item When a page is shipped out, pdfTeX uses the current setting + of the link margin for all links on the page. +\end{itemize} + +\item[pdfmark] +\begin{itemize} + \item Settings have global effect. +\end{itemize} + +\item[xetex] +\begin{itemize} + \item Settings must be done in the preamble or the first page and then have global effect. + The key inserts the new (x)dvipdfmx special \verb|\special{dvipdfmx:config g #1}| (with the unit removed). +\end{itemize} + +\item[Other drivers] + Unsupported. +\end{description} + + +\subsection{Field option `calculatesortkey'} + + Fields with calculated values are calculated in document order + by default. If calculated field values depend on other calculated + fields that appear later in the document, then the correct calculation + order can be specified with option `calculatesortkey'. Its value is + used as key to lexicographically sort the calculated fields. + The sort key do not need to be unique. Fields that share the same + key are sorted in document order. + + + + Currently the field option `calculatesortkey' is only supported by + the driver for pdfTeX. + + +\subsection{Option `localanchorname'} + + When an anchor is set (e.g. via \verb|\refstepcounter|, then the + anchor name is globally set to the current anchor name. + + + For example: +\begin{verbatim} + \section{Foobar} + \begin{equation}\end{equation} + \label{sec:foobar} +\end{verbatim} + With the default global setting (localanchorname=false) + a reference to `sec:foobar' jumps to the equation before. + With option `localanchorname' the anchor of the equation + is forgotten after the environment and the reference + `sec:foobar' jumps to the section title. + + + Option `localanchorname' is an experimental option, there + might be situations, where the anchor name is not available + as expected. + + +\subsection{Option `customdriver'} + + The value of option `customdriver' is the name of an external + driver file without extension `.def'. The file must have + \verb|\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. + + +\subsection{Option `psdextra'} + + LaTeX's NFSS is used to assist the conversion of arbitrary + TeX strings to PDF strings (bookmarks, PDF information entries). + Many math command names (\verb|\geq|, \verb|\notin|, ...) are not in control + of NFSS, therefore they are defined with prefix `text' + (\verb|\textgeq|, \verb|\textnotin|, ...). They can be mapped to short names + during the processing to PDF strings. The disadvantage is that + they are many hundreds macros that need to be redefined for + each PDF string conversion. Therefore this can be enabled or + disabled as option `psdextra'. On default the option is turned + off (set to `false'). Turning the option on means + that the short names are available. Then \verb|\geq| can directly + be used instead of \verb|\textgeq|. + + +\subsection{\textbackslash XeTeXLinkBox} + + When XeTeX generates a link annotation, it does not look + at the boxes (as the other drivers), but only at the character + glyphs. If there are no glyphs (images, rules, ...), then + it does not generate a link annotation. Macro \verb|\XeTeXLinkBox| + puts its argument in a box and adds spaces at the lower left + and upper right corners. An additional margin can be specified + by setting it to the dimen register \verb|\XeTeXLinkMargin|. The default + is 2pt. + + Example: + + +\begin{verbatim} + % xelatex + \documentclass{article} + \usepackage{hyperref} + \setlength{\XeTeXLinkMargin}{1pt} + \begin{document} + \section{Hello World} + \newpage + \label{sec:hello} + \hyperref[sec:hello]{% + \XeTeXLinkBox{\rule{10mm}{10mm}}% + } + \end{document} +\end{verbatim} + +\subsection{\textbackslash IfHyperBooleanExists and \textbackslash IfHyperBoolean} +\begin{verbatim} + \IfHyperBooleanExists{OPTION}{YES}{NO} +\end{verbatim} + If a hyperref OPTION is a boolean, that means it takes values + `true' or `false', then \verb|\IfHyperBooleanExists| calls YES, otherwise NO. + + +\begin{verbatim} + \IfHyperBoolean{OPTION}{YES}{NO} +\end{verbatim} + Macro \verb|\IfHyperBoolean| calls YES, if OPTION exists as boolean and is + enabled. Otherwise NO is executed. + + + + Both macros are expandable. Additionally option `stoppedearly' is + available. It is enabled if \verb|\MaybeStopEarly| or \verb|\MaybeStopNow| + end hyperref prematurely. + + +\subsection{\textbackslash unichar} + + If a Unicode character is not supported by puenc.def, it can + be given by using \verb|\unichar|. Its name and syntax is inherited + from package `ucs'. However it is defined independently for + use in hyperref's \verb|\pdfstringdef| (that converts arbitrary + TeX code to PDF strings or tries to do this). + + + + Macro \verb|\unichar| takes a TeX number as argument, + examples for U+263A (WHITE SMILING FACE): +\begin{verbatim} + \unichar{"263A}% hexadecimal notation + \unichar{9786}% decimal notation +\end{verbatim} + `"' must not be a babel shorthand character or otherwise + active. Otherwise prefix it with \verb|\string|: +\begin{verbatim} + \unichar{\string"263A}% converts `"' to `"' with catcode 12 (other) +\end{verbatim} + Users of (n)german packages or babel options may use \verb|\dq| instead: +\begin{verbatim} + \unichar{\dq 263A}% \dq is double quote with catcode 12 (other) +\end{verbatim} + + +\subsection{\textbackslash ifpdfstringunicode} + + Some features of the PDF specification needs PDF strings. + Examples are bookmarks or the entries in the information dictionary. + The PDF specification allows two encodings `PDFDocEncoding' + (8-bit encoding) and `Unicode' (UTF-16). The user can help + using \verb|\texorpdfstring| to replace complicate TeX constructs + by a representation for the PDF string. However \verb|\texorpdfstring| + does not distinguish the two encodings. This gap closes + \verb|\ifpdfstringunicode|. It is only allowed in the second argument + of \verb|\texorpdfstring| and takes two arguments, the first allows + the full range of Unicode. The second is limited to the + characters available in PDFDocEncoding. + + + + As example we take a macro definition for the Vietnamese + name of Han The Thanh. Correctly written it needs some + accented characters, one character even with a double accent. + Class `tugboat.cls' defines a macro for the typesetted name: +\begin{verbatim} + \def\Thanh{% + H\`an~% + Th\^e\llap{\raise 0.5ex\hbox{\'{}}}% + ~Th\`anh% + } +\end{verbatim} + It's not entirely correct, the second accent over the `e' is not + an acute, but a hook. However standard LaTeX does not provide + such an accent. + + Now we can extend the definition to support hyperref. + The first and the last word are already supported automatically. + Characters with two or more accents are a difficult business in + LaTeX, because the NFSS2 macros of the LaTeX kernel do not support + more than one accent. Therefore also puenc.def misses support for + them. But we can provide it using \verb|\unichar|. The character + in question is: +\begin{verbatim} + % U+1EC3 LATIN SMALL LETTER E WITH CIRCUMFLEX AND HOOK ABOVE +\end{verbatim} + Thus we can put this together: +\begin{verbatim} + \def\Thanh{% + H\`an~% + \texorpdfstring{Th\^e\llap{\raise 0.5ex\hbox{\'{}}}}% + {\ifpdfstringunicode{Th\unichar{"1EC3}}{Th\^e}}% + ~Th\`anh% + } +\end{verbatim} + For PDFDocEncoding (PD1) the variant above has dropped the + second accent. Alternatively we could provide a representation + without accents instead of wrong accents: +\begin{verbatim} + \def\Thanh{% + \texorpdfstring{% + H\`an~% + Th\^e\llap{\raise 0.5ex\hbox{\'{}}}}% + ~Th\`anh% + }{% + \ifpdfstringunicode{% + H\`an Th\unichar{"1EC3} Th\`anh% + }{% + Han The Thanh% + }% + }% + } +\end{verbatim} + +\subsection{Customizing index style file with \textbackslash nohyperpage} + + Since version 2008/08/14~v6.78f. + + + + For hyperlink support in the index, hyperref inserts \verb|\hyperpage| + into the index macros. After processing with Makeindex, \verb|\hyperpage| + analyzes its argument to detect page ranges and page comma lists. + However, only the standard settings are supported directly: +\begin{verbatim} + delim_r "--" + delim_n ", " +\end{verbatim} + (See manual page/documentation of Makeindex that explains + the keys that can be used in style files for Makeindex.) + Customized versions of + \verb|delim_r, delim_n, suffix_2p, suffix_3p, suffix_mp| + needs markup that \verb|\hyperpage| can detect and knows that + this stuff does not belong to a page number. Makro + \verb|\nohyperpage| serves as this markup. Put the customized + code for these keys inside \verb|\nohyperpage|, e.g.: +\begin{verbatim} + suffix_2p "\\nohyperpage{f.}" + suffix_3p "\\nohyperpage{ff.}" +\end{verbatim} + (Depending on the typesetting tradition some space ``\verb|\\|,'' or ``\verb|~|'' + should be put before the first f inside \verb|\nohyperpage|.) + + +\subsection{Experimental option `ocgcolorlinks'} + + The idea are colored links, when viewed, but printed without colors. + This new experimental option `ocgcolorlinks' uses Optional Content + Groups, a feature introduced in PDF 1.5. + + A better implementation which hasn't the disadvantage to prevent line breaks is + in the ocgx2 package. Check its documentation for details how to use it. +\begin{itemize} + \item The option must be given for package loading: + \verb|\usepackage[ocgcolorlinks]{hyperref}| + \item Main disadvantage: Links cannot be broken across lines. + PDF reference 1.7: 4.10.2 ``Making Graphical Content Optional'': + Graphics state operations, such as setting the color, ..., + are still applied. + Therefore the link text is put in a box and set twice, with and + without color. + \item The feature can be switched of by \verb|\hypersetup{ocgcolorlinks=false}| + inside the document. + \item Supported drivers: pdftex, dvipdfm + \item The PDF version should be at least 1.5. It is automatically + set for pdfTeX, LuaTeX and dvipdfmx. +\end{itemize} + +\subsection{Option `pdfa'} + + The new option `pdfa' tries to avoid violations of PDF/A in code + generated by hyperref. However, the result is usually not in PDF/A, + because many features aren't controlled by hyperref (XMP metadata, + fonts, colors, driver dependend low level stuff, ...). + + + + Currently, option `pdfa' sets and disables the following items: +\begin{itemize} + \item Enabled annotation flags: Print, NoZoom, NoRotate [PDF/A 6.5.3]. + \item Disabled annotation flags: Hidden, Invisible, NoView [PDF/A 6.5.3]. + \item Disabled: Launch action (\href{run:...} [PDF/A 6.6.1]. + \item Restricted: Named actions (\Acrobatmenu: NextPage, PrevPage, + FirstPage, LastPage) [PDF/A 6.6.1]. + \item Many things are disabled in PDF formulars: + \begin{itemize} + \item JavaScript actions [PDF/A 6.6.1] + \item Trigger events (additional actions) [PDF/A 6.6.2] + \item Push button (because of JavaScript) + \item Interactive Forms: Flag NeedAppearances is the default `false' + (Because of this, hyperref's implementation of Forms looks ugly). + [PDF/A 6.9] + \end{itemize} +\end{itemize} + + + + The default value of the new option `pdfa' is `false'. It influences + the loading of the package and cannot be changed after hyperref is + loaded (\verb|\usepackage{hyperref}|). + + + +\subsection{Option `linktoc' added} + + The new option `linktoc' allows more control which part + of an entry in the table of contents is made into a link: +\begin{itemize} + \item `linktoc=none' (no links) + \item `linktoc=section' (default behaviour, same as `linktocpage=false') + \item `linktoc=page' (same as `linktocpage=true') + \item `linktoc=all' (both the section and page part are links) +\end{itemize} + +\subsection{Option `pdfnewwindow' changed} + + Before 6.77b: +\begin{itemize} + \item pdfnewwindow=true $\rightarrow$ /NewWindow true + \item pdfnewwindow=false $\rightarrow$ (absent) + \item unused pdfnewwindow $\rightarrow$ (absent) +\end{itemize} + Since 6.77b: +\begin{itemize} + \item pdfnewwindow=true $\rightarrow$ /NewWindow true + \item pdfnewwindow=false $\rightarrow$ /NewWindow false + \item pdfnewwindow={} $\rightarrow$ (absent) + \item unused pdfnewwindow $\rightarrow$ (absent) +\end{itemize} + + + + Rationale: There is a difference between setting to `false' + and an absent entry. In the former case the new document + replaces the old one, in the latter case the PDF viewer + application should respect the user preference. + + +\subsection{Flag options for PDF forms} + + PDF form field macros (\verb|\TextField|, \verb|\CheckBox|, ...) support + boolean flag options. The option name is the lowercase + version of the names in the PDF specification (1.7): + + \url{http://www.adobe.com/devnet/pdf/pdf_reference.html} + + \url{http://www.adobe.com/devnet/acrobat/pdfs/pdf_reference.pdf} + + Options (convert to lowercase) except flags in square brackets: + +\begin{itemize} + \item Table 8.16 Annotation flags (page 608): + +{\obeylines + 1 Invisible + 2 Hidden (PDF 1.2) + 3 Print (PDF 1.2) + 4 NoZoom (PDF 1.3) + 5 NoRotate (PDF 1.3) + 6 NoView (PDF 1.3) + [7 ReadOnly (PDF 1.3)] ignored for widget annotations, see table 8.70 + 8 Locked (PDF 1.4) + 9 ToggleNoView (PDF 1.5) + 10 LockedContents (PDF 1.7) +} + \item Table 8.70 Field flags common to all field types (page 676): + +{\obeylines + 1 ReadOnly + 2 Required + 3 NoExport +} + \item Table 8.75 Field flags specific to button fields (page 686): + +{\obeylines + 15 NoToggleToOff (Radio buttons only) + 16 Radio (set: radio buttons, clear: check box, pushbutton: clear) + 17 Pushbutton + 26 RadiosInUniso (PDF 1.5) +} + \item Table 8.77 Field flags specific to text fields (page 691): + +{\obeylines + 13 Multiline + 14 Password + 21 FileSelect (PDF 1.4) + 23 DoNotSpellCheck (PDF 1.4) + 24 DoNotScroll (PDF 1.4) + 25 Comb (PDF 1.5) + 26 RichText (PDF 1.5) +} + \item Table 8.79 Field flags specific to choice fields (page 693): + +{\obeylines + 18 Combo (set: combo box, clear: list box) + 19 Edit (only useful if Combo is set) + 20 (Sort) for authoring tools, not PDF viewers + 22 MultiSelect (PDF 1.4) + 23 DoNotSpellCheck (PDF 1.4) (only useful if Combo and Edit are set) + 27 CommitOnSelChange (PDF 1.5) +} + \item Table 8.86 Flags for submit-form actions (page 704): + +{\obeylines + [1 Include/Exclude] unsupported, use `noexport' (table 8.70) instead + 2 IncludeNoValueFields + [3 ExportFormat] handled by option `export' + 4 GetMethod + 5 SubmitCoordinates + [6 XFDF (PDF 1.4)] handled by option `export' + 7 IncludeAppendSaves (PDF 1.4) + 8 IncludeAnnotations (PDF 1.4) + [9 SubmitPDF (PDF 1.4)] handled by option `export' + 10 CanonicalFormat (PDF 1.4) + 11 ExclNonUserAnnots (PDF 1.4) + 12 ExclFKey (PDF 1.4) + 14 EmbedForm (PDF 1.5) +} +\end{itemize} + + New option `export' sets the export format of a submit action. + Valid values are (upper- or lowercase): +\begin{itemize} + \item FDF + \item HTML + \item XFDF + \item PDF (not supported by Acrobat Reader) +\end{itemize} + +\subsection{Option `pdfversion'} + + This is an experimental option. It notifies `hyperref' about + the intended PDF version. Currently this is used in code for + PDF forms (implementation notes 116 and 122 of PDF spec 1.7). + + + + Values: 1.2, 1.3, 1.4, 1.5, 1.6, 1.7. Values below 1.2 are not + supported, because most drivers expect higher PDF versions. + + + + The option must be used early, not after \verb|\usepackage{hyperref}|. + + + In theory this option should also set the PDF version, + but this is not generally supported. +\begin{itemize} + \item pdfTeX below 1.10a: unsupported. + pdfTeX $\ge$ 1.10a and < 1.30: \verb|\pdfoptionpdfminorversion| + pdfTeX $\ge$ 1.30: \verb|\pdfminorversion| + \item dvipdfm: configuration file, example: + TeX Live 2007, texmf/dvipdfm/config/config, entry `V 2'. + \item dvipdfmx: configuration file, example: + TeX Live 2007, texmf/dvipdfm/dvipdfmx.cfg, entry `V 4'. + \item Ghostscript: option -dCompatibilityLevel (this is set in + `ps2pdf12', `ps2pdf13', `ps2pdf14'). +\end{itemize} + + + The current PDF version is used as default if this version + can be detected (only pdfTeX $\ge$ 1.10a). Otherwise the lowest + version 1.2 is assumed. Thus `hyperref' tries to avoid PDF code + that breaks this version, but is free to use ignorable higher PDF + features. + + +\subsection{Field option `name'} + + Many form objects uses the label argument + for several purposes: +\begin{itemize} + \item Layouted label. + \item As name in HTML structures. +\end{itemize} + Code that is suitable for layouting with TeX can + break in the structures of the output format. + If option `name' is given, then its value is used + as name in the different output structures. Thus + the value should consist of letters only. + + +\subsection{Option `pdfencoding'} + + The PDF format allows two encodings for bookmarks and entries + in the information dictionary: PDFDocEncoding and Unicode + as UTF-16BE. Option \xoption{pdfencoding} selects between these encodings: +\begin{itemize} + \item \xoption{pdfdoc} uses PDFDocEncoding. It uses just one byte per character, + but the supported characters are limited (244 in PDF-1.7). + \item \xoption{unicode} sets Unicode. It is encoded as UTF-16BE. Two bytes + are used for most characters, surrogates need four bytes. + \item \xoption{auto} PDFDocEncoding if the string does not contain characters + outside the encoding (outside ascii if an unicode engine is used) + and Unicode otherwise. This option is normally no suited for the unicode engines. +\end{itemize} + + All drivers use \xoption{unicode} by default now. If another encoding should be forced, + it should be done in \verb|hypersetup|. + +\subsection{Color options/package hycolor} + + See documentation of package `hycolor'. + + +\subsection{Option pdfusetitle} + + If option pdfusetitle is set then hyperref tries to + derive the values for pdftitle and pdfauthor from + \verb|\title| and \verb|\author|. An optional argument for \verb|\title| and + \verb|\author| is supported (class amsart). + + +\subsection{Starred form of \textbackslash autoref} + + \verb|\autoref*| generates a reference without link as \verb|\ref*| or \verb|\pageref*|. + + +\subsection{Link border style} + + Links can be underlined instead of the default rectangle or + options \xoption{colorlinks}, \xoption{frenchlinks}. This is done by option + \verb|pdfborderstyle={/S/U/W 1}| + + Some remarks: + +\begin{itemize} + \item AR7/Linux seems to have a bug, that don't use the default + value \verb"1" for the width, but zero, thus that the underline + is not visible without \verb"/W 1". The same applies for + dashed boxes, eg.: + pdfborderstyle={/S/D/D[3 2]/W 1} + + \item 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) + + \item The border style is removed by + pdfborderstyle={} + This is automatically done if option colorlinks is enabled. + + \item Be aware that not all PDF viewers support this feature, not + even Acrobat Reader itself: + + Some support: + \begin{itemize} + \item AR7/Linux: \xoption{underline} and \xoption{dashed}, but the border width + must be given. + \item xpdf 3.00: \xoption{underline} and \xoption{dashed} + \end{itemize} + + Unsupported: + \begin{itemize} + \item AR5/Linux + \item ghostscript 8.50 + \end{itemize} +\end{itemize} + +\subsection{Option \xoption{bookmarksdepth}} + + The depth of the bookmarks can be controlled by the new + option \xoption{bookmarksdepth}. The option acts globally and + distinguishes three cases: +\begin{itemize} + \item \xoption{bookmarksdepth} without value + Then hyperref uses the current value of counter \xoption{tocdepth}. + This is the compatible behaviour and the default. + \item \verb"bookmarksdepth=", the value is number (also negative): + The depth for the bookmarks are set to this number. + \item \verb"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 \verb|\toclevel@|. + Examples: +\begin{verbatim} + \hypersetup{bookmarksdepth=paragraph} + \hypersetup{bookmarksdepth=4} % same as before + \hypersetup{bookmarksdepth} % counter "tocdepth" is used +\end{verbatim} +\end{itemize} + +\subsection{Option \xoption{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: +\begin{itemize} + \item pdfescapeform=false + Escaping for the formulars are disabled, this is + the compatibility behaviour, therefore this is the default. + \item 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. +\end{itemize} + +\subsection{Default driver setting} + + (hyperref $\ge$ 6.72s) + If no driver is given, hyperref tries its best to guess the + most suitable driver. Thus it loads \xoption{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 \xoption{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 \verb"hyperref.cfg": +\begin{verbatim} + \providecommand*{\Hy@defaultdriver}{hdvips} +\end{verbatim} + for dvips, or +\begin{verbatim} + \providecommand*{\Hy@defaultdriver}{hypertex} +\end{verbatim} + for the default behaviour of hyperref. + + See also the new option `driverfallback'. + +\subsection{Backref entries} + + Alternative interface for formatting of backref entries, example: + +\begin{verbatim} +\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 +} + +% The list of distinct entries can be further refined: +\renewcommand*{\backrefentrycount}[2]{% + % #1: the original backref entry + % #2: the count of citations of this entry, + % in case of duplicates greater than one + #1% + \ifnum#2>1 % + ~(#2)% + \fi +} + +\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} +\end{verbatim} + +\subsection{\textbackslash phantomsection} + +Set an anchor at this location. It is often used in conjunction +with \verb|\addcontentsline| for sectionlike things (index, bibliography, +preface). \verb|\addcontentsline| refers to the latest previous location +where an anchor is set. + +\begin{verbatim} + \cleardoublepage + \phantomsection + \addcontentsline{toc}{chapter}{\indexname} + \printindex +\end{verbatim} + +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. + + + +\section{Acrobat-specific behavior} +If you want to access the menu options of Acrobat Reader or Exchange, the following +macro is provided in the appropriate drivers: + +\begin{cmdsyntax} +\ci{Acrobatmenu}\verb|{|\emph{menuoption}\verb|}{|\emph{text}\verb|}| +\end{cmdsyntax} + +\noindent The \emph{text} is used to create a button which activates the appropriate \emph{menuoption}. The following table lists the option names you can use---comparison of this with the menus in Acrobat Reader or Exchange will show what they do. Obviously some are only appropriate to Exchange. + +\medskip +\begin{longtable}{@{}l>{\raggedright\arraybackslash}p{9cm}@{}} +File & Open, Close, Scan, Save, SaveAs, Optimizer:SaveAsOpt, Print, PageSetup, Quit \\ +File$\rightarrow$Import & ImportImage, ImportNotes, AcroForm:ImportFDF \\ +File$\rightarrow$Export & ExportNotes, AcroForm:ExportFDF \\ +File$\rightarrow$DocumentInfo & GeneralInfo, OpenInfo, FontsInfo, SecurityInfo, Weblink:Base, AutoIndex:DocInfo \\ +File$\rightarrow$Preferences & GeneralPrefs, NotePrefs, FullScreenPrefs, Weblink:Prefs, AcroSearch:Preferences(Windows) + or, AcroSearch:Prefs(Mac), Cpt:Capture \\ +Edit & Undo, Cut, Copy, Paste, Clear, SelectAll, Ole:CopyFile, TouchUp:TextAttributes, + TouchUp:FitTextToSelection, TouchUp:ShowLineMarkers, TouchUp:ShowCaptureSuspects, + TouchUp:FindSuspect, \\ + & Properties \\ +Edit$\rightarrow$Fields & AcroForm:Duplicate, AcroForm:TabOrder \\ +Document & Cpt:CapturePages, AcroForm:Actions, CropPages, RotatePages, InsertPages, ExtractPages, + ReplacePages, DeletePages, NewBookmark, SetBookmarkDest, CreateAllThumbs, + DeleteAllThumbs \\ +View & ActualSize, FitVisible, FitWidth, FitPage, ZoomTo, FullScreen, FirstPage, PrevPage, + NextPage, LastPage, GoToPage, GoBack, GoForward, SinglePage, OneColumn, TwoColumns, + ArticleThreads, PageOnly, ShowBookmarks, ShowThumbs \\ +Tools & Hand, ZoomIn, ZoomOut, SelectText, SelectGraphics, Note, Link, Thread, AcroForm:Tool, + Acro\_Movie:MoviePlayer, TouchUp:TextTool, Find, FindAgain, FindNextNote, + CreateNotesFile \\ +Tools$\rightarrow$Search & AcroSrch:Query, AcroSrch:Indexes, AcroSrch:Results, AcroSrch:Assist, AcroSrch:PrevDoc, + AcroSrch:PrevHit, AcroSrch:NextHit, AcroSrch:NextDoc \\ +Window & ShowHideToolBar, ShowHideMenuBar, ShowHideClipboard, Cascade, TileHorizontal, + TileVertical, CloseAll \\ +Help & HelpUserGuide, HelpTutorial, HelpExchange, HelpScan, HelpCapture, HelpPDFWriter, + HelpDistiller, HelpSearch, HelpCatalog, HelpReader, Weblink:Home \\ +Help(Windows) & About +\end{longtable} + +\section{PDF and HTML forms} +You must put your fields inside a \texttt{Form} environment (only one per file). + +There are six macros to prepare fields: + +\begin{cmdsyntax} +\ci{TextField}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}| +\end{cmdsyntax} + +\begin{cmdsyntax} +\ci{CheckBox}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}| +\end{cmdsyntax} + +\begin{cmdsyntax} +\ci{ChoiceMenu}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}{|\emph{choices}\verb|}| +\end{cmdsyntax} + +\begin{cmdsyntax} +\ci{PushButton}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}| +\end{cmdsyntax} + +\begin{cmdsyntax} +\ci{Submit}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}| +\end{cmdsyntax} + +\begin{cmdsyntax} +\ci{Reset}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}| +\end{cmdsyntax} + +The way forms and their labels are laid out is determined by: +\begin{cmdsyntax} +\ci{LayoutTextField}\verb|{|\emph{label}\verb|}{|\emph{field}\verb|}| +\end{cmdsyntax} + +\begin{cmdsyntax} +\ci{LayoutChoiceField}\verb|{|\emph{label}\verb|}{|\emph{field}\verb|}| +\end{cmdsyntax} + +\begin{cmdsyntax} +\ci{LayoutCheckField}\verb|{|\emph{label}\verb|}{|\emph{field}\verb|}| +\end{cmdsyntax} + +These macros default to \#1 \#2 + +What is actually shown in the field is determined by: +\begin{cmdsyntax} +\ci{MakeRadioField}\verb|{|\emph{width}\verb|}{|\emph{height}\verb|}| +\end{cmdsyntax} + +\begin{cmdsyntax} +\ci{MakeCheckField}\verb|{|\emph{width}\verb|}{|\emph{height}\verb|}| +\end{cmdsyntax} +\begin{cmdsyntax} +\ci{MakeTextField}\verb|{|\emph{width}\verb|}{|\emph{height}\verb|}| +\end{cmdsyntax} +\begin{cmdsyntax} +\ci{MakeChoiceField}\verb|{|\emph{width}\verb|}{|\emph{height}\verb|}| +\end{cmdsyntax} + +\begin{cmdsyntax} +\ci{MakeButtonField}\verb|{|\emph{text}\verb|}| +\end{cmdsyntax} + +These macros default to \verb|\vbox to #2{\hbox to #1{\hfill}\vfill}|, except the +last, which defaults to \#1; it is used for buttons, and the special \ci{Submit} and \ci{Reset} +macros. + +You may also want to redefine the following macros: +\begin{verbatim} +\def\DefaultHeightofSubmit{12pt} +\def\DefaultWidthofSubmit{2cm} +\def\DefaultHeightofReset{12pt} +\def\DefaultWidthofReset{2cm} +\def\DefaultHeightofCheckBox{0.8\baselineskip} +\def\DefaultWidthofCheckBox{0.8\baselineskip} +\def\DefaultHeightofChoiceMenu{0.8\baselineskip} +\def\DefaultWidthofChoiceMenu{0.8\baselineskip} +\def\DefaultHeightofText{\baselineskip} +\def\DefaultHeightofTextMultiline{4\baselineskip} +\def\DefaultWidthofText{3cm} +\end{verbatim} + +\subsection{Forms environment parameters} + +\smallskip +\begin{longtable}{@{}>{\ttfamily}l>{\itshape}lp{9cm}@{}} +action & URL & The URL that will receive the form data if a \textsf{Submit} button is included in the form \\ +encoding & name & The encoding for the string set to the URL; FDF-encoding is usual, and \texttt{html} is the only + valid value \\ +method & name & Used only when generating HTML; values can be \texttt{post} or \texttt{get} \\ +\end{longtable} + +\subsection{Forms optional parameters} +Note that all colors must be expressed as RGB triples, in the range 0..1 (i.e.\ \texttt{color=0 0 +0.5}) + +\smallskip +\begin{longtable}{@{}>{\ttfamily}ll>{\itshape}ll@{}} +accesskey & key & & (as per HTML) \\ +align & number & 0 & alignment within text field; 0 is left-aligned,\\* + & & & 1 is centered, 2 is right-aligned. \\ +altname & name & & alternative name,\\* + & & & the name shown in the user interface\\ +backgroundcolor & & & color of box \\ +bordercolor & & & color of border \\ +bordersep & & & box border gap \\ +borderwidth & & 1 & width of box border, the value is a dimension\\ + & & & or a number with default unit bp\\ +calculate & & & JavaScript code to calculate the value of the field \\ +charsize & dimen & & font size of field text \\ +checkboxsymbol & char & 4 (\ding{\number`4}) & symbol used for check boxes (ZapfDingbats), \\ +&&& the value is a character or \cs{ding}\verb|{|\texttt{\itshape number}\verb|}|, \\ +&&& see package \xpackage{pifont} from bundle \xpackage{psnfss} \\ +checked & boolean & false & whether option selected by default \\ +color & & & color of text in box \\ +combo & boolean & false & choice list is `combo' style \\ +default & & & default value \\ +disabled & boolean & false & field disabled \\ +format & & & JavaScript code to format the field \\ +height & dimen & & height of field box \\ +hidden & boolean & false & field hidden \\ +keystroke & & & JavaScript code to control the keystrokes on entry \\ +mappingname & name & & the mapping name to be used when exporting\\* + & & & the field data\\ +maxlen & number & 0 & number of characters allowed in text field \\ +menulength & number & 4 & number of elements shown in list \\ +multiline & boolean & false & whether text box is multiline \\ +name & name & & name of field (defaults to label) \\ +onblur & & & JavaScript code \\ +onchange & & & JavaScript code \\ +onclick & & & JavaScript code \\ +ondblclick & & & JavaScript code \\ +onfocus & & & JavaScript code \\ +onkeydown & & & JavaScript code \\ +onkeypress & & & JavaScript code \\ +onkeyup & & & JavaScript code \\ +onmousedown & & & JavaScript code \\ +onmousemove & & & JavaScript code \\ +onmouseout & & & JavaScript code \\ +onmouseover & & & JavaScript code \\ +onmouseup & & & JavaScript code \\ +onselect & & & JavaScript code \\ +password & boolean & false & text field is `password' style \\ +popdown & boolean & false & choice list is `popdown' style \\ +radio & boolean & false & choice list is `radio' style \\ +radiosymbol & char & H (\ding{\number`H}) & symbol used for radio fields (ZapfDingbats), \\ +&&& the value is a character or \cs{ding}\verb|{|\texttt{\itshape number}\verb|}|, \\ +&&& see package \xpackage{pifont} from bundle \xpackage{psnfss} \\ +readonly & boolean & false & field is readonly \\ +rotation & number & 0 & rotation of the widget annotation \\* + & & & (degree, counterclockwise, multiple of 90)\\ +tabkey & & & (as per HTML) \\ +validate & & & JavaScript code to validate the entry \\ +value & & & initial value \\ +width & dimen & & width of field box +\end{longtable} + +\section{Defining a new driver} +A hyperref driver has to provide definitions for eight macros: + +\smallskip +\noindent 1. \verb|\hyper@anchor| + +\noindent 2. \verb|\hyper@link| + +\noindent 3. \verb|\hyper@linkfile| + +\noindent 4. \verb|\hyper@linkurl| + +\noindent 5. \verb|\hyper@anchorstart| + +\noindent 6. \verb|\hyper@anchorend| + +\noindent 7. \verb|\hyper@linkstart| + +\noindent 8. \verb|\hyper@linkend| +\smallskip + +The draft option defines the macros as follows +\begin{verbatim} +\let\hyper@@anchor\@gobble +\gdef\hyper@link##1##2##3{##3}% +\def\hyper@linkurl##1##2{##1}% +\def\hyper@linkfile##1##2##3{##1}% +\let\hyper@anchorstart\@gobble +\let\hyper@anchorend\@empty +\let\hyper@linkstart\@gobbletwo +\let\hyper@linkend\@empty +\end{verbatim} + +\section{Special support for other packages} + +Package \xpackage{hyperref} aims to cooperate with other packages, but there are +several possible sources for conflict, such as + +\begin{itemize} + +\item Packages that manipulate the bibliographic mechanism. Peter +William's \xpackage{harvard} package is supported. However, the +recommended package is Patrick Daly's \xpackage{natbib} package that has +specific \xpackage{hyperref} hooks to allow reliable interaction. This +package covers a very wide variety of layouts and citation styles, all +of which work with \xpackage{hyperref}. + +\item Packages that typeset the contents of the \ci{label} and \ci{ref} +macros, such as \xpackage{showkeys}. Since the \xpackage{hyperref} package +redefines these commands, you must set \texttt{implicit=false} for these +packages to work. + +\item Packages that do anything serious with the index. +\end{itemize} + +The \xpackage{hyperref} package is distributed with variants on two useful +packages designed to work especially well with it. These are \xpackage{xr} +and \xpackage{minitoc}, which support crossdocument links using \hologo{LaTeX}'s +normal \cs{label}/\cs{ref} mechanisms and per-chapter tables of contents, +respectively. + + +\subsection{Package Compatibility} + +Currently only package loading orders are available: + + + +Note: hyperref loads package \xpackage{nameref} at \verb|\begin{document}|. +Sometimes this is too late, thus this package must be loaded +earlier. + + +\subsubsection{algorithm} +\begin{verbatim} + \usepackage{float} + \usepackage{hyperref} + \usepackage[chapter]{algorithm}% eg. +\end{verbatim} + +\subsubsection{amsmath} + + The environments equation and eqnarray are not supported too well. + For example, there might be spacing problems (eqnarray isn't recommended + anyway, see CTAN:info/l2tabu/, the situation for equation is unclear, + because nobody is interested in investigating). Consider using the + environments that package amsmath provide, e.g. gather for equation. + The environment equation can even redefined to use gather: + +\begin{verbatim} + \usepackage{amsmath} + \let\equation\gather + \let\endequation\endgather +\end{verbatim} + +\subsubsection{amsrefs} + + Package loading order: + +\begin{verbatim} + \usepackage{hyperref} + \usepackage{amsrefs} +\end{verbatim} + +\subsubsection{arydshln, longtable} + + Package longtable must be put before hyperref and arydshln, + hyperref after arydshln generates an error, thus the + resulting package order is then: + +\begin{verbatim} + \usepackage{longtable} + \usepacakge{hyperref} + \usepackage{arydshln} +\end{verbatim} + +\subsubsection{babel/magyar.ldf} + + The old version 2005/03/30 v1.4j will not work. + You need at least version 1.5, maintained by P\'eter Szab\'o, + see CTAN:language/hungarian/babel/. + + +\subsubsection{babel/spanish.ldf} + + Babel's spanish.ldf redefines `\verb|\.|' to support `\verb|\...|'. + In bookmarks (\verb|\pdfstringdef|) only `\verb|\.|' is supported. + If `\verb|\...|' is needed, + \verb|\texorpdfstring{\...}{\dots}| + can be used instead. + + +\subsubsection{bibentry} + + Workaround: + +\begin{verbatim} + \makeatletter + \let\saved@bibitem\@bibitem + \makeatother + + \usepackage{bibentry} + \usepackage{hyperref} + + \begin{document} + + \begingroup + \makeatletter + \let\@bibitem\saved@bibitem + \nobibliography{database} + \endgroup +\end{verbatim} + +\subsubsection{bigfoot} + + Hyperref does not support package `bigfoot'. And package + `bigfoot' does not support hyperref's footnotes and disables + them (hyperfootnotes=false). + + +\subsubsection{chappg} + + Package `chappg' uses \verb|\@addtoreset| that is redefined by `hyperref'. + The package order is therefore: + +\begin{verbatim} + \usepackage{hyperref} + \usepackage{chappg} +\end{verbatim} + +\subsubsection{cite} + + This is from Mike Shell: + cite.sty cannot currently be used with hyperref. + However, I can do a workaround via: + +\begin{verbatim} + \makeatletter + \def\NAT@parse{\typeout{This is a fake Natbib command to fool Hyperref.}} + \makeatother + + \usepackage[hypertex]{hyperref} +\end{verbatim} + + 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). + + +\subsubsection{count1to} + + Package `count1to' adds several \verb|\@addtoreset| commands that confuse + `hyperref'. Therefore \verb|\theH<...>| has to be fixed: + +\begin{verbatim} + \usepackage{count1to} + \AtBeginDocument{% *after* \usepackage{count1to} + \renewcommand*{\theHsection}{\theHchapter.\arabic{section}}% + \renewcommand*{\theHsubsection}{\theHsection.\arabic{subsection}}% + \renewcommand*{\theHsubsubsection}{\theHsubsection.\arabic{subsubsection}}% + \renewcommand*{\theHparagraph}{\theHsubsubsection.\arabic{paragraph}}% + \renewcommand*{\theHsubparagraph}{\theHparagraph.\arabic{subparagraph}}% + } +\end{verbatim} + +\subsubsection{dblaccnt} + + pd1enc.def or puenc.def should be loaded before: +\begin{verbatim} + \usepackage{hyperref} + \usepackage{dblaccnt} +\end{verbatim} + or see entry for \xoption{vietnam}. + + +\subsubsection{easyeqn} + Not compatible, breaks. + + +\subsubsection{ellipsis} + + This packages redefines \verb|\textellipsis| + after package hyperref (pd1enc.def/puenc.def should be loaded before): +\begin{verbatim} + \usepackage{hyperref} + \usepackage{ellipsis} +\end{verbatim} + +\subsubsection{float} +\begin{verbatim} + \usepackage{float} + \usepackage{hyperref} +\end{verbatim} +\begin{itemize} + \item Several \verb|\caption| commands are not supported inside one float object. + \item Anchor are set at top of the float object, if its style is controlled + by float.sty. +\end{itemize} + +\subsubsection{endnotes} + Unsupported. + +\subsubsection{foiltex} + Update to version 2008/01/28 v2.1.4b: + Since version 6.77a hyperref does not hack into \verb|\@begindvi|, + it uses package `atbegshi' instead, that hooks into \verb|\shipout|. + Thus the patch of `foils.cls' regarding hyperref is now obsolete + and causes an undefined error message about \verb|\@hyperfixhead|. + This is fixed in FoilTeX 2.1.4b. + + +\subsubsection{footnote} + + This package is not supported, you have to disable hyperref's footnote + support by using option \verb"hyperfootnotes=false". + + +\subsubsection{geometry} + + Driver `dvipdfm' and program `dvipdfm' might generate a warning: + Sorry. Too late to change page size + Then prefer the program `dvipdfmx' or use one of the following + workarounds to move the \verb|\special| of geometry to an earlier + location: + +\begin{verbatim} + \documentclass[dvipdfm]{article}% or other classes + \usepackage{atbegshi} + \AtBeginDocument{% + \let\OrgAtBeginDvi\AtBeginDvi + \let\AtBeginDvi\AtBeginShipoutFirst + } + \usepackage[ + paperwidth=170mm, + paperheight=240mm + ]{geometry} + \AtBeginDocument{% + \let\AtBeginDvi\OrgAtBeginDvi + } + \usepackage{hyperref} + + or + + \documentclass[dvipdfm]{article}% or other classes + \usepackage{atbegshi} + \let\AtBeginDvi\AtBeginShipoutFirst + \usepackage[ + paperwidth=170mm, + paperheight=240mm + ]{geometry} + \usepackage{hyperref} +\end{verbatim} + +\subsubsection{IEEEtran.cls} + + version $\ge$ V1.6b (because of \verb|\@makecaption|, see ChangeLog) + + +\subsubsection{index} + + version $\ge$ 1995/09/28 v4.1 (because of \verb|\addcontentsline| redefinition) + + +\subsubsection{lastpage} + + Compatible. + + +\subsubsection{linguex} +\begin{verbatim} + \usepackage{hyperref} + \usepackage{linguex} +\end{verbatim} + +\subsubsection{ltabptch} +\begin{verbatim} + \usepackage{longtable} + \usepackage{ltabptch} + \usepackage{hyperref} +\end{verbatim} + +\subsubsection{mathenv} + + Unsupported. + + + + Both `mathenv' and `hyperref' messes around with + environment `eqnarray'. You can load `mathenv' after + `hyperref' to avoid an error message. But \verb|\label| + will not work inside environment `eqnarray' properly, + for example. + + +\subsubsection{minitoc-hyper} + + This package is obsolete, use the up-to-date original + package minitoc instead. + + + +\subsubsection{multind} +\begin{verbatim} + \usepackage{multind} + \usepackage{hyperref} +\end{verbatim} + +\subsubsection{natbib} +\begin{verbatim} + \usepackage{natbib} + \usepackage{hyperref} +\end{verbatim} + +\subsubsection{nomencl} +Example for introducing links for the page numbers: +\begin{verbatim} + \renewcommand*{\pagedeclaration}[1]{\unskip, \hyperpage{#1}} +\end{verbatim} + + +\subsubsection{ntheorem-hyper} + This package is obsolete, use the up-to-date original + package ntheorem instead. + + +For equations the following might work: +\begin{verbatim} + \renewcommand*{\eqdeclaration}[1]{% + \hyperlink{equation.#1}{(Equation~#1)}% + } + But the mapping from the equation number to the anchor name + is not available in general. +\end{verbatim} + +\subsubsection{parskip} +\begin{verbatim} + \usepackage{parskip} + \usepackage{hyperref}[2012/08/20] +\end{verbatim} + + + Both packages want to redefine \verb|\@starttoc|. + + +\subsubsection{prettyref} +\begin{verbatim} +%%% 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 %%% + \end{verbatim} + + +\subsubsection{setspace} +\begin{verbatim} + \usepackage{setspace} + \usepackage{hyperref} +\end{verbatim} + +\subsubsection{sidecap} +\begin{verbatim} + Before 2002/05/24 v1.5h: + \usepackage{nameref} + \usepackage{hyperref} + \usepackage{sidecap} +\end{verbatim} + +\subsubsection{subfigure} +\begin{verbatim} + 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? +\end{verbatim} + +\subsubsection{titleref} +\begin{verbatim} + \usepackage{nameref} + \usepackage{titleref}% without usetoc + \usepackage{hyperref} +\end{verbatim} + +\subsubsection{tabularx} + + Linked footnotes are not supported inside environment `tabularx', + because they uses the optional argument of \verb|\footnotetext|, see + section `Limitations'. Before version 2011/09/28 6.82i + hyperref had disabled footnotes entirely by `hyperfootnotes=false'. + + +\subsubsection{titlesec} + + \xpackage{nameref} supports titlesec, but hyperref does not + (unsolved is the anchor setting, missing with unnumbered + section, perhaps problems with page breaks with numbered ones). + + +\subsubsection{ucs/utf8x.def} + + The first time a multibyte UTF8 sequence is called, it + does some calculations and stores the result in a macro + for speeding up the next calls of that UTF8 sequence. + However this makes the first call non-expandable and + will break if used in information entries or bookmarks. + Package \xpackage{ucs} offers \verb|\PrerenderUnicode| or \verb|\PreloadUnicodePage| + to solve this: +\begin{verbatim} + \usepackage{ucs} + \usepackage[utf8x]{inputenc} + \usepackage{hyperref}% or with option unicode + \PrerenderUnicode{^^c3^^b6}% or \PrerenderUnicodePage{1} + \hypersetup{pdftitle={Umlaut example: ^^c3^^b6}} +\end{verbatim} + The notation with two carets avoids trouble with 8-bit bytes + for the README file, you can use the characters directly. + + +\subsubsection{varioref} + There are too many problems with varioref. Nobody has time to + sort them out. Therefore this package is now unsupported. + + + Perhaps you are lucky and some of the features of varioref works + with the following loading order: +\begin{verbatim} + \usepackage{nameref} + \usepackage{varioref} + \usepackage{hyperref} +\end{verbatim} + + + Also some babel versions can be problematic. For example, + 2005/05/21 v3.8g contains a patch for varioref that breaks + the hyperref support for varioref. + + + + Also unsupported: +\begin{itemize} +\item \verb|\Ref|, \verb|\Vref| do not uppercase the first letter. +\item \verb|\vpageref[]{...}| + On the same page a previous space is not suppressed. +\end{itemize} + +\subsubsection{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): + +\begin{verbatim} + \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} +\end{verbatim} + +\subsubsection{vietnam} +\begin{verbatim} + % pd1enc.def should be loaded before package dblaccnt: + \usepackage[PD1,OT1]{fontenc} + \usepackage{vietnam} + \usepackage{hyperref} +\end{verbatim} + +\subsubsection{XeTeX} + + Default for the encoding of bookmarks is \verb|pdfencoding=unicode|. + That means the strings are always treated as unicode strings. + If \verb|auto| or \verb|pdfdoc| is forced it applies only + if the string restricts to the printable ASCII set, + The reason is that the \verb|\special| does not support PDFDocEncoding. + + In older versions hyperref contained special conversion code from + UTF-16BE back to UTF-8 in a number of places for + xetex to avoid the xdvipdfmx warning + + \verb"Failed to convert input string to UTF16..." + + This is no longer needed with a current xdvipdfmx, so this code has + been removed. \verb|\csname HyPsd@XeTeXBigCharstrue\endcsname| should no + longer be used. + + +\section[Limitations]{Limitations% +\footnote{This section moved from the README file, needs more integration into the manual}} +\subsection{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: +\begin{itemize} +\item For long section or caption titles in the table of contents + or list of figures/tables option \xoption{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 overfull \verb|\hbox| + warning. +\item ``\verb|\url|''s are caught by package \xpackage{breakurl}. +\item The option \xoption{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 + \verb|\url|. (See thread ``hyperref.sty, breaklinks and url.sty 3.2'' + in comp.text.tex 2005-09). +\end{itemize} + +\subsection{Links across pages} + + In general they have problems: +\begin{itemize} + \item Some driver doesn't support them at all (see above). + \item The driver allows it, but the link result might include + the footer and/or header, or an error message can + occur sometimes. +\end{itemize} + +\subsection{Footnotes} + + LaTeX allows the separation of the footnote mark and the + footnote text (\verb|\footnotemark|, \verb|\footnotetext|). This interface + might be enough for visual typesetting. But the relation between + \verb|\footnotemark| to \verb|\footnotetext| is not as strong as \verb|\ref| to \verb|\label|. + Therefore it is not clear in general which \verb|\footnotemark| references + which \verb|\footnotetext|. But that is necessary to implement hyperlinking. + Thus the implementation of hyperref does not support the optional + argument of \verb|\footnotemark| and \verb|\footnotetext|. + + +\section[Hints]{Hints% +\footnote{This section moved from the README file, needs more integration into the manual}} + +\subsection{Spaces in option values} + + Unhappily LaTeX strips spaces from options if they are given + in \verb|\documentclass| or \verb|\usepackage| (or \verb|\RequirePackage|), e.g.: +\begin{verbatim} + \usepackage[pdfborder=0 0 1]{hyperref} +\end{verbatim} + Package hyperref now gets +\begin{verbatim} + pdfborder=001 +\end{verbatim} + and the result is an invalid PDF file. + As workaround braces can be used: +\begin{verbatim} + \usepackage[pdfborder={0 0 1}]{hyperref} +\end{verbatim} + Some options can also be given in \verb|\hypersetup| +\begin{verbatim} + \hypersetup{pdfborder=0 0 1} +\end{verbatim} + In \verb|\hypersetup| the options are directly processed as key value + options (see package keyval) without space stripping in the value part. + + + + Alternatively, LaTeX's option handling system can be adapted + to key value options by one of the packages \xpackage{kvoptions-patch} + (from project \xpackage{kvoptions}) or \xpackage{xkvltxp} (from project \xpackage{xsetkeys}). + + +\subsection{Index with makeindex} +\begin{itemize} + \item Package hyperref adds \verb|\hyperpage| commands by the encap + mechanism (see documentation of Makeindex), + if option hyperindex is set (default). + \verb|\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 \verb|\frontmatter|, \verb|\romannumbering|, ...), + then the page anchors are not unique. Therefore option + \verb"plainpages=false" is recommended. + \item 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 + \verb|\hyperpage| command. With logical markup this situation + can easily be solved: +\begin{verbatim} + \usepackage{makeidx} + \makeindex + \usepackage[hyperindex]{hyperref} + \newcommand*{\main}[1]{\textbf{\hyperpage{#1}}} + ... + \index{Some example|main} +\end{verbatim} + \item Scientic Word/Scientific WorkPlace users can use + package robustindex with hyperindex=false. + \item Other encap characters can be set by option \xoption{encap}. + Example for use of ``?'': +\begin{verbatim} + \usepackage[encap=?]{hyperref} +\end{verbatim} + \item Another possibility is the insertion of \verb|\hyperpage| by + a style file for makeindex. For this case, hyperref's + insertion will be disabled by \verb"hyperindex=false". + \verb|\hyperpage| will be defined regardless of setting of hyperindex. +\begin{verbatim} +%%% 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 %%% +\end{verbatim} +\end{itemize} + +\subsection{Warning \texttt{"bookmark level for unknown defaults to 0"}} + + Getting rid of it: +\begin{verbatim} +\makeatletter +\providecommand*{\toclevel@}{0} +\makeatother +\end{verbatim} + +\subsection{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 case, try package \xpackage{hypcap} that implements + a method to circumvent the problem. + + +\subsection{Additional unicode characters in bookmarks and pdf information entries:} +\begin{verbatim} +\documentclass[pdftex]{article} +\usepackage[unicode]{hyperref} +\end{verbatim} + +Support for additional unicode characters: + + Example: \verb|\.{a}| and \verb|\d{a}| + + 1. Get a list with unicode data, eg: + + http://www.unicode.org/Public/UNIDATA/UnicodeData.txt + + 2. Identify the characters (\verb|\.{a}|, \verb|\d{a}|): +\begin{verbatim} + 0227;LATIN SMALL LETTER A WITH DOT ABOVE;... + 1EA1;LATIN SMALL LETTER A WITH DOT BELOW;... +\end{verbatim} + + 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.) + +\begin{verbatim} + 0227 -> \002\047 + 1EA1 -> \036\241 +\end{verbatim} + + 4. Transform into a form understood by hyperref: + + Hyperref must know where the first byte starts, + this is marked by \verb"9" (8 and 9 cannot occur in + octal numbers): + +\begin{verbatim} + \002\047 -> \9002\047 + \036\241 -> \9036\241 +\end{verbatim} + + Optional: \verb"8" is used for abbreviations: + +\begin{verbatim} + \900 = \80, \901 = \81, \902 = \82, ... + + \9002\047 -> \82\047 +\end{verbatim} + + 5. Declare the character with LaTeX: + +\begin{verbatim} +\DeclareTextCompositeCommand{\.}{PU}{a}{\82\047} +\DeclareTextCompositeCommand{\d}{PU}{a}{\9036\241} + +\begin{document} +\section{\={a}, \d{a}, \'{a}, \.{a}} +\end{document} + \end{verbatim} + +\subsection{Footnotes} + + The footnote support is rather limited. It is beyond the scope + to use \verb|\footnotemark| and \verb|\footnotetext| out of order or reusing + \verb|\footnotemark|. Here you can either disable hyperref's footnote + support by \verb"hyperfootnotes=false" or fiddle with internal macros, + nasty examples: + +\begin{verbatim} +\documentclass{article} +\usepackage{hyperref} +\begin{document} +Hello% +\footnote{The first footnote} +World% +\addtocounter{footnote}{-1}% +\addtocounter{Hfootnote}{-1}% +\footnotemark. +\end{document} + + or + +\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} +\end{verbatim} + +\subsection{Subordinate counters} + + Some counters do not have unique values and require the value + of other counters to be unique. For example, sections or figures + might be numbered within chapters or \verb|\newtheorem| is used with + an optional counter argument. Internally LaTeX uses \verb|\@addtoreset| + to reset a counter in dependency to another counter. Package + hyperref hooks into \verb|\@addtoreset| to catch this situation. + Also \verb|\numberwithin| of package amsmath is caught by hyperref. + + + + However, if the definition of subordinate counters take place + before hyperref is loaded, the old meaning of \verb|\@addtoreset| is + called without hyperref's additions. Then the companion counter + macro \verb|\theH| can be redefined accordingly. Or move the + definition of subordinate counters after hyperref is loaded. + + Example for \verb|\newtheorem|, problematic case: +\begin{verbatim} + \newtheorem{corA}{CorollaryA}[section] + \usepackage{hyperref} +\end{verbatim} + Solution a) +\begin{verbatim} + \usepackage{hyperref} + \newtheorem{corA}{CorollaryA}[section} +\end{verbatim} + Solution b) +\begin{verbatim} + \newtheorem{corA}{CorollaryA}[section] + \usepackage{hyperref} + \newcommand*{\theHcorA}{\theHsection.\number\value{corA}} +\end{verbatim} + +\section{History and acknowledgments} + +The original authors of \textsf{hyperbasics.tex} and +\textsf{hypertex.sty}, from which this package descends, are Tanmoy +Bhattacharya and Thorsten Ohl. Package \xpackage{hyperref} +started as a simple port of their work to \hologo{LaTeXe} standards, but +eventually I rewrote nearly everything, because I didn't understand a +lot of the original, and was only interested in getting it to work with +\hologo{LaTeX}. I would like to thank Arthur Smith, Tanmoy Bhattacharya, Mark +Doyle, Paul Ginsparg, David Carlisle, T.\ V.\ Raman and Leslie Lamport +for comments, requests, thoughts and code to get the package into its +first useable state. Various other people are mentioned at the point in +the source where I had to change the code in later versions because of +problems they found. + +Tanmoy found a great many of the bugs, and (even better) often provided +fixes, which has made the package more robust. The days spent on +Rev\TeX\ are entirely due to him! The investigations of Bill Moss +into the later versions including +native PDF support uncovered a good many bugs, and his testing is +appreciated. Hans Hagen provided a lot of +insight into PDF. + +Berthold Horn provided help, encouragement and sponsorship for the +\textsf{dvipsone} and \textsf{dviwindo} drivers. Sergey Lesenko provided +the changes needed for \textsf{dvipdf}, and \Hanh{} supplied all the +information needed for \textsf{pdftex}. Patrick Daly kindly updated his +\xpackage{natbib} package to allow easy integration with +\xpackage{hyperref}. Michael Mehlich's \xpackage{hyper} package (developed +in parallel with \textsf{hyperref}) showed me solutions for some +problems. Hopefully the two packages will combine one day. + +The forms creation section owes a great deal to: T.\ V.\ Raman, for +encouragement, support and ideas; Thomas Merz, whose book \emph{Web +Publishing with Acrobat/PDF} provided crucial insights; D.\ P.\ Story, +whose detailed article about pdfmarks and forms solved many practical +problems; and Hans Hagen, who explained how to do it in \textsf{pdftex}. + +Steve Peter recreated the manual source in July 2003 after it had been +lost. + +Especial extra thanks to David Carlisle for the \xpackage{backref} module, +the ps2pdf and dviwindo support, frequent general rewrites of my bad +code, and for working on changes to the \xpackage{xr} package to suit +\xpackage{hyperref}. + +\begingroup + \makeatletter + \let\chapter=\section + % subsections goes into bookmarks but not toc + \hypersetup{bookmarksopenlevel=1} + \addtocontents{toc}{\protect\setcounter{tocdepth}{1}} + % The \section command acts as \subsection. + % Additionally the title is converted to lowercase except + % for the first letter. + \def\section{% + \let\section\lc@subsection + \lc@subsection + } + \def\lc@subsection{% + \@ifstar{\def\mystar{*}\lc@sec}% + {\let\mystar\@empty\lc@sec}% + } + \def\lc@sec#1{% + \lc@@sec#1\@nil + } + \def\lc@@sec#1#2\@nil{% + \begingroup + \def\a{#1}% + \lowercase{% + \edef\x{\endgroup + \noexpand\subsection\mystar{\a#2}% + }% + }% + \x + } +\clearpage + + +\chapter{GNU Free Documentation License} + +Version 1.2, November 2002 + + + Copyright \copyright\ 2000,2001,2002 Free Software Foundation, Inc.\\ + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA\\ + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + +\section*{PREAMBLE} + +The purpose of this License is to make a manual, textbook, or other +functional and useful document ``free'' in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + +\section{APPLICABILITY AND DEFINITIONS} +\label{applicability} + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (Thus, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, \LaTeX\ input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML, PostScript or PDF designed for human modification. Examples of +transparent image formats include PNG, XCF and JPG. Opaque formats +include proprietary formats that can be read and edited only by +proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML, PostScript or PDF produced by some word +processors for output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements'', +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + + +\section{VERBATIM COPYING} +\label{verbatim} + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in +section~\ref{copying}. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +\section{COPYING IN QUANTITY} +\label{copying} + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +\section{MODIFICATIONS} +\label{modifications} + +You may copy and distribute a Modified Version of the Document under +the conditions of sections~\ref{verbatim} and \ref{copying} above, +provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +\renewcommand{\labelenumi}{\Alph{enumi}.} +\begin{enumerate} +\item Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. +\item List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has fewer than five), + unless they release you from this requirement. +\item State on the Title page the name of the publisher of the + Modified Version, as the publisher. +\item Preserve all the copyright notices of the Document. +\item Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. +\item Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. +\item Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. +\item Include an unaltered copy of this License. +\item Preserve the section Entitled ``History'', Preserve its Title, and add + to it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section Entitled ``History'' in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. +\item Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the ``History'' section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. +\item For any section Entitled ``Acknowledgements'' or ``Dedications'', + Preserve the Title of the section, and preserve in the section all + the substance and tone of each of the contributor acknowledgements + and/or dedications given therein. +\item Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. +\item Delete any section Entitled ``Endorsements''. Such a section + may not be included in the Modified Version. +\item Do not retitle any existing section to be Entitled ``Endorsements'' + or to conflict in title with any Invariant Section. +\item Preserve any Warranty Disclaimers. + +\end{enumerate} + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +\section{COMBINING DOCUMENTS} +\label{combining} + +You may combine the Document with other documents released under this +License, under the terms defined in section~\ref{modifications} +above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements'', +and any sections Entitled ``Dedications''. You must delete all sections +Entitled ``Endorsements''. + + +\section{COLLECTIONS OF DOCUMENTS} +\label{collections} + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + +\section{AGGREGATION WITH INDEPENDENT WORKS} +\label{aggregation} + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section~\ref{copying} is applicable to +these copies of the Document, then if the Document is less than one half +of the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + + +\section{TRANSLATION} +\label{translation} + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of +section~\ref{modifications}. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements'', +``Dedications'', or ``History'', the requirement +(section~\ref{modifications}) to Preserve +its Title (section~\ref{applicability}) will typically require +changing the actual title. + + +\section{TERMINATION} +\label{termination} + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + +\section{FUTURE REVISIONS OF THIS LICENSE} +\label{future} + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + + +\section*{ADDENDUM: How to use this License for your documents} + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +\begin{quote} + Copyright \copyright\ YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled ``GNU + Free Documentation License''. +\end{quote} + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with...Texts.'' line with this: + + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +\endgroup + +\end{document} diff --git a/Master/texmf-dist/source/latex/hyperref/doc/manual.tex b/Master/texmf-dist/source/latex/hyperref/doc/manual.tex deleted file mode 100644 index ddd48e6ea14..00000000000 --- a/Master/texmf-dist/source/latex/hyperref/doc/manual.tex +++ /dev/null @@ -1,3396 +0,0 @@ -% This is the manual for the LaTeX hyperref package. -% -% Copyright (C) 1998-2003 Sebastian Rahtz. -% Copyright (C) 2003 Steve Peter and Karl Berry -% Copyright (C) 2006-2012 Heiko Oberdiek. -% Copyright (C) 2017-2019 David Carlisle Ulrike Fischer -% Copyright (C) 2019-2020 The LaTeX3 Project -% -% Permission is granted to copy, distribute and/or modify this document -% under the terms of the GNU Free Documentation License, Version 1.1 or -% any later version published by the Free Software Foundation; with no -% Invariant Sections, with no Front-Cover Texts, and with no Back-Cover -% Texts. A copy of the license is included in the section entitled -% ``GNU Free Documentation License.'' -% - -\def\mydate{January 2020} - -\RequirePackage{iftex} -\ifpdf % We are running pdfTeX in pdf mode -\ifx\directlua\undefinded -\documentclass[pdftex]{article} -\else -\documentclass[luatex]{article} -\fi -\else -\documentclass{article} -\fi - - -\usepackage{pifont} -\usepackage{calc} - -\usepackage{hologo} - -\def\OzTeX{O\kern-0.03em z\kern-0.15em \TeX} - -\newcommand*{\cs}[1]{% - \texttt{\textbackslash #1}% -} -\newcommand*{\xpackage}[1]{\textsf{#1}} -\newcommand*{\xoption}[1]{\textsf{#1}} - -% from doc.sty -\makeatletter -\ifx\l@nohyphenation\@undefined -\newlanguage\l@nohyphenation -\fi -\ifx\l@nohyphenation\@undefined - \newlanguage\l@nohyphenation -\fi -\DeclareRobustCommand\meta[1]{% - \ensuremath\langle - \ifmmode \expandafter \nfss@text \fi - {% - \meta@font@select - \edef\meta@hyphen@restore - {\hyphenchar\the\font\the\hyphenchar\font}% - \hyphenchar\font\m@ne - \language\l@nohyphenation - #1\/% - \meta@hyphen@restore - }% - \ensuremath\rangle -} -\def\meta@font@select{\ttfamily\itshape} -\makeatother - -% Page layout. -\advance\textwidth by 1.1in -\advance\oddsidemargin by -.55in -\advance\evensidemargin by -.55in -% -\advance\textheight by 1in -\advance\topmargin by -.5in -\advance\footskip by -.5in -% -\pagestyle{headings} -% -% Avoid some overfull boxes. -\emergencystretch=.1\hsize -\hbadness = 3000 - -% these are from lshort.sty, but lshort.sty pulls in so many other -% packages it seems cleaner to just include them here. -% -\newcommand{\bs}{\symbol{'134}}%Print backslash -\newcommand{\ci}[1]{\texttt{\bs#1}} - -\makeatletter -\@ifpackageloaded{tex4ht}{% - % separate definition for HTML case to avoid - % nasty borders with double horizontal lines with - % large gaps. - \newsavebox{\cmdsyntaxbox}% - \newenvironment{cmdsyntax}{% - \par - % \small - \addvspace{3.2ex plus 0.8ex minus 0.2ex}% - \vskip -\parskip - \noindent - \begin{lrbox}{\cmdsyntaxbox}% - \begin{tabular}{l}% - \rule{0pt}{1em}% - \ignorespaces - }{% - \end{tabular}% - \end{lrbox}% - \fbox{\usebox{\cmdsyntaxbox}}% - \par - \nopagebreak - \addvspace{3.2ex plus 0.8ex minus 0.2ex}% - \vskip -\parskip - }% -}{% - \newenvironment{cmdsyntax}{% - \par - \small - \addvspace{3.2ex plus 0.8ex minus 0.2ex}% - \vskip -\parskip - \noindent - \begin{tabular}{|l|}% - \hline - \rule{0pt}{1em}% - \ignorespaces - }{% - \\% - \hline - \end{tabular}% - \par - \nopagebreak - \addvspace{3.2ex plus 0.8ex minus 0.2ex}% - \vskip -\parskip - }% -} -\makeatother - -\usepackage{array,longtable} -\ifnum 0\ifluatex 1\else\ifxetex 1\fi\fi=0 % - \usepackage[T1]{fontenc}% - \usepackage{lmodern}% - \renewcommand*{\ttdefault}{lmvtt}% -\else - \usepackage{fontspec}% - \renewcommand*{\ttdefault}{lmvtt}% -\fi - -\newcommand*{\Quote}[1]{\textquotedblleft#1\textquotedblright} - -\def\Hanh{H\`an Th\^e\llap{\raise 0.5ex\hbox{\'{}}} Th\`anh} - -\ifpdf - \usepackage[% -% pdftex,% might be luatex, just allow automatic default - colorlinks,% - hyperindex,% - plainpages=false,% - bookmarksopen,% - bookmarksnumbered, - pdfusetitle,% - ]{hyperref} - %%?? \def\pdfBorderAttrs{/Border [0 0 0] } % No border arround Links -\else - \usepackage{hyperref} -\fi - -\makeatletter -\@ifpackageloaded{tex4ht}{% -\author{Sebastian Rahtz (deceased)\and - Heiko Oberdiek (inactive)\and - The \LaTeX3 Project (\url{https://github.com/latex3/hyperref/issues})} -}{% - \usepackage{bmhydoc}% -\author{Sebastian Rahtz\thanks{deceased}\and - Heiko Oberdiek\thanks{inactive}\and - The \LaTeX3 Project\thanks{\url{https://github.com/latex3/hyperref/issues}}} -} -\makeatother -\title{Hypertext marks in \hologo{LaTeX}: a manual for \xpackage{hyperref}} -\date{2021-02-04 v7.00g} - -\begin{document} - -% comes out too close to the toc, and we know it's page one anyway. -\thispagestyle{empty} -\maketitle -\tableofcontents -\setcounter{tocdepth}{2}% for bookmark levels - -\section{Introduction} - -The package derives from, and builds on, the work of the Hyper\hologo{TeX} -project, described at \texttt{http://xxx.lanl.gov/hypertex/}\footnote{Now: \url{https://ctan.org/tex-archive/support/hypertex/hypertex}}. It extends -the functionality of all the \hologo{LaTeX} cross-referencing commands -(including the table of contents, bibliographies etc) to produce -\cs{special} commands which a driver can turn into hypertext links; -it also provides new commands to allow the user to write \emph{ad hoc} -hypertext links, including those to external documents and URLs. - -The package is currently maintained at \url{https://github.com/latex3/hyperref/} and issues should -be reported there. - -This manual provides a brief overview of the \xpackage{hyperref} -package. For more details, you should read the additional documentation -distributed with the package, as well as the complete documentation by -processing \texttt{hyperref.dtx}. You should also read the chapter on -\xpackage{hyperref} in \textit{The \hologo{LaTeX} Web Companion}, where you will -find additional examples. - -The Hyper\hologo{TeX} specification\footnote{This is borrowed from an article -by Arthur Smith.} says that conformant viewers/translators must -recognize the following set of \cs{special} constructs: - -\begin{description} -\item[href:] \verb|html:| -\item[name:] \verb|html:| -\item[end:] \verb|html:| -\item[image:] \verb|html:| -\item[base\_name:] \verb|html:| -\end{description} - -The \emph{href}, \emph{name} and \emph{end} commands are used to do the -basic hypertext operations of establishing links between sections of -documents. The \emph{image} command is intended (as with current HTML -viewers) to place an image of arbitrary graphical format on the page in -the current location. The \emph{base\_name} command is be used to -communicate to the DVI viewer the full (URL) location of the current -document so that files specified by relative URLs may be retrieved -correctly. - -The \emph{href} and \emph{name} commands must be paired with an -\emph{end} command later in the \TeX\ file---the \TeX\ commands between -the two ends of a pair form an \emph{anchor} in the document. In the -case of an \emph{href} command, the \emph{anchor} is to be highlighted -in the \emph{DVI viewer}, and when clicked on will cause the scene to -shift to the destination specified by \emph{href\_string}. The -\emph{anchor} associated with a name command represents a possible -location to which other hypertext links may refer, either as local -references (of the form \verb|href="#name_string"| with the -\emph{name\_string} identical to the one in the name command) or as part -of a URL (of the form \emph{URL\#name\_string}). Here -\emph{href\_string} is a valid URL or local identifier, while -\emph{name\_string} could be any string at all: the only caveat is that -`$\verb|"|$' characters should be escaped with a backslash -($\backslash$), and if it looks like a URL name it may cause problems. - -However, the drivers intended to produce \emph{only} PDF use literal -PostScript or PDF \verb|\special| commands. The commands are defined in -configuration files for different drivers, selected by package options; -at present, the following drivers are supported: - -\begin{description} -\item[hypertex] DVI processors conforming to the Hyper\TeX\ guidelines (i.e.\ \textsf{xdvi}, \textsf{dvips} (with -the \textsf{-z} option), \textsf{\OzTeX}, and \textsf{Textures}) -\item[dvips] produces \verb|\special| commands tailored for \textsf{dvips} -\item[dvipsone] produces \verb|\special| commands tailored for \textsf{dvipsone} -\item[ps2pdf] a special case of output suitable for processing by earlier versions of Ghost\-script's -PDF writer; this is basically the same as that for \textsf{dvips}, but a few variations remained before version 5.21 -\item[tex4ht] produces \verb|\special| commands for use with \textsf{\TeX4ht} -\item[pdftex] pdf\TeX, \Hanh{}'s \TeX{} variant that writes PDF directly -\item[luatex] lua\TeX, Unicode \TeX{} variant that writes PDF directly -\item[dvipdfm] produces \verb|\special| commands for Mark Wicks' DVI to PDF driver \textsf{dvipdfm} -\item[dvipdfmx] produces \verb|\special| commands for driver - \textsf{dvipdfmx}, a successor of \textsf{dvipdfm} -\item[dviwindo] produces \verb|\special| commands that Y\&Y's Windows previewer interprets as hypertext jumps within the previewer -\item[vtex] produces \verb|\special| commands that MicroPress' HTML and - PDF-producing \TeX\ variants interpret as hypertext jumps within the - previewer -\item[textures] produces \verb|\special| commands that \textsf{Textures} interprets as hypertext jumps within the previewer -\item[xetex] produces \verb|\special| commands for Xe\TeX{} -\end{description} - -Output from \textsf{dvips} or \textsf{dvipsone} must be processed using -Acrobat Distiller to obtain a PDF file.\footnote{Make sure you turn off -the partial font downloading supported by \textsf{dvips} and -\textsf{dvipsone} in favor of Distiller's own system.} The result is -generally preferable to that produced by using the \textsf{hypertex} -driver, and then processing with \textsf{dvips -z}, but the DVI file is -not portable. The main advantage of using the Hyper\TeX\ \ci{special} -commands is that you can also use the document in hypertext DVI viewers, -such as \textsf{xdvi}. - -\begin{description} -\item[driverfallback] - If a driver is not given and cannot be autodetected, then use - the driver option, given as value to this option \textsf{driverfallback}. - Example: - \begin{quote} - \texttt{driverfallback=dvipdfm} - \end{quote} - Autodetected drivers (\textsf{pdftex}, \textsf{xetex}, \textsf{vtex}, - \textsf{vtexpdfmark}) are recognized from within \TeX\ and - therefore cannot be given as value to option \textsf{driverfallback}. - However a DVI driver program is run after the \TeX\ run is finished. - Thus it cannot be detected at \TeX\ macro level. Then package - \xpackage{hyperref} - uses the driver, given by \textsf{driverfallback}. If the driver - is already specified or can be autodetected, then option - \textsf{driverfallback} is ignored. -\end{description} - -\section{Implicit behavior} - -This package can be used with more or less any normal \LaTeX\ document -by specifying in the document preamble - -\begin{verbatim} -\usepackage{hyperref} -\end{verbatim} - -Make sure it comes \emph{last} of your loaded packages, to give it a -fighting chance of not being over-written, since its job is to redefine -many \LaTeX\ commands. Hopefully you will find that all cross-references -work correctly as hypertext. For example, \ci{section} commands will -produce a bookmark and a link, whereas \ci{section*} commands will only -show links when paired with a corresponding \ci{addcontentsline} -command. - -In addition, the \texttt{hyperindex} option (see below) attempts to make -items in the index by hyperlinked back to the text, and the option -\texttt{backref} inserts extra `back' links into the bibliography for -each entry. Other options control the appearance of links, and give -extra control over PDF output. For example, \texttt{colorlinks}, as its -name well implies, colors the links instead of using boxes; this is the -option used in this document. - - -\section{Package options} - -All user-configurable aspects of \xpackage{hyperref} are set using a -single `key=value' scheme (using the \xpackage{keyval} package) with the -key \texttt{Hyp}. The options can be set either in the optional argument -to the \cs{usepackage} command, or using the \cs{hypersetup} -macro. When the package is loaded, a file \texttt{hyperref.cfg} is read -if it can be found, and this is a convenient place to set options on a -site-wide basis. - -Note however that some options (for example \texttt{unicode}) can only be used as -package options, and not in \verb|\hypersetup| as the option settings are processed -as the package is read. - -As an example, the behavior of a particular file could be controlled by: -\begin{itemize} - -\item a site-wide \texttt{hyperref.cfg} setting up the look of links, -adding backreferencing, and setting a PDF display default: - -\begin{verbatim} -\hypersetup{backref, -pdfpagemode=FullScreen, -colorlinks=true} -\end{verbatim} - -\item A global option in the file, which is passed down to -\textsf{hyperref}: - -\begin{verbatim} -\documentclass[dvips]{article} -\end{verbatim} - -\item File-specific options in the \cs{usepackage} commands, which -override the ones set in \texttt{hyperref.cfg}: - -\begin{verbatim} -\usepackage[colorlinks=false]{hyperref} -\hypersetup{pdftitle={A Perfect Day}} -\end{verbatim} -\end{itemize} - -As seen in the previous example, information entries -(pdftitle, pdfauthor, \dots) should be set after the package is loaded. -Otherwise \LaTeX\ expands the values of these options prematurely. -Also \LaTeX\ strips spaces in options. Especially option `pdfborder' -requires some care. Curly braces protect the value, if given -as package option. They are not necessary in \verb|\hypersetup|. - -\begin{verbatim} -\usepackage[pdfborder={0 0 0}]{hyperref} -\hypersetup{pdfborder=0 0 0} -\end{verbatim} - -Package `kvoptions-patch' patches \LaTeX\ to make it aware -of key value options and to prevent premature value expansions. - -Some options can be given at any time, but many are restricted: before -\verb|\begin{document}|, only in \verb|\usepackage[...]{hyperref}|, -before first use, etc. - -In the key descriptions that follow, many options do not need a value, -as they default to the value true if used. These are the ones classed as -`boolean'. The values true and false can always be specified, however. - -\subsection{General options} - -Firstly, the options to specify general behavior and page size. - -\medskip -\begin{longtable}{>{\ttfamily}ll>{\itshape}ll} -draft & boolean & false & all hypertext options are turned off \\ -final & boolean & true & all hypertext options are turned on \\ -debug & boolean & false & extra diagnostic messages are printed in \\ - & & & the log file \\ -verbose & boolean & false & same as debug \\ -implicit & boolean & true & redefines \LaTeX\ internals \\ -setpagesize & boolean & true & sets page size by special driver commands -\end{longtable} - -\subsection{Options for destination names} - -Destinations names (also anchor, target or link names) are internal -names that identify a position on a page in the document. They -are used in link targets for inner document links or the bookmarks, -for example. - -Usually anchor are set, if \cs{refstepcounter} is called. -Thus there is a counter name and value. Both are used to -construct the destination name. By default the counter value -follows the counter name separated by a dot. Example for -the fourth chapter: -\begin{quote} - \verb|chapter.4| -\end{quote} -This scheme is used by: -\begin{description} -\item[\cs{autoref}] displays the description label for the - reference depending on the counter name. -\item[\cs{hyperpage}] is used by the index to get -page links. Page anchor setting (\verb|pageanchor|) must not -be turned off. -\end{description} - -It is very important that the destination names are unique, -because two destinations must not share the same name. -The counter value \cs{the} is not always unique -for the counter. For example, table and figures can be numbered -inside the chapter without having the chapter number in their -number. Therefore \xpackage{hyperref} has introduced \cs{theH} -that allows a unique counter value without messing up with -the appearance of the counter number. For example, the number -of the second table in the third chapter might be printed -as \texttt{2}, the result of \cs{thetable}. But the -destination name \texttt{table.2.4} is unique because it -has used \cs{theHtable} that gives \verb|2.4| in this case. - -Often the user do not need to set \cs{theH}. Defaults -for standard cases (chapter, \dots) are provided. And after \xpackage{hyperref} -is loaded, new counters with parent counters also define -\cs{theH} automatically, if \cs{newcounter}, \cs{@addtoreset} -or \cs{numberwithin} of package \xpackage{amsmath} are used. - -Usually problems with duplicate destination names can be solved -by an appropriate definition of \cs{theH}. If option -\texttt{hypertexnames} is disabled, then a unique artificial -number is used instead of the counter value. In case of page -anchors the absolute page anchor is used. With option \texttt{plainpages} -the page anchors use the arabic form. In both latter cases \cs{hyperpage} -for index links is affected and might not work properly. - -If an unnumbered entity gets an anchor (starred forms of -chapters, sections, \dots) or \cs{phantomsection} is used, -then the dummy counter name \texttt{section*} and an artificial -unique number is used. - -If the final PDF file is going to be merged with another file, than -the destination names might clash, because both documents might -contain \texttt{chapter.1} or \texttt{page.1}. Also \xpackage{hyperref} -sets anchor with name \texttt{Doc-Start} at the begin of the document. -This can be resolved by redefining \cs{HyperDestNameFilter}. -Package \xpackage{hyperref} calls this macro each time, it uses a -destination name. -The macro must be expandable and expects the destination name -as only argument. As example, the macro is redefined to add -a prefix to all destination names: -\begin{quote} -\begin{verbatim} -\renewcommand*{\HyperDestNameFilter}[1]{\jobname-#1} -\end{verbatim} -\end{quote} -In document \texttt{docA} the destination name \texttt{chapter.2} -becomes \texttt{docA-chapter.2}. - -Destination names can also be used from the outside in URIs(, if the -driver has not removed or changed them), for example: -\begin{quote} -\begin{verbatim} -http://somewhere/path/file.pdf#nameddest=chapter.4 -\end{verbatim} -\end{quote} -However using a number seems unhappy. If another chapter is added -before, the number changes. But it is very difficult to pass -a new name for the destination to the anchor setting process that -is usually deep hidden in the internals. The first name of -\cs{label} after the anchor setting seems a good approximation: -\begin{quote} -\begin{verbatim} - \section{Introduction} - \label{intro} -\end{verbatim} -\end{quote} -Option \texttt{destlabel} checks for each \cs{label}, if there is -a new destination name active and replaces the destination -name by the label name. Because the destination name is already in use -because of the anchor setting, the new name is recorded in the \texttt{.aux} -file and used in the subsequent \hologo{LaTeX} run. The renaming is done by -a redefinition of \cs{HyperDestNameFilter}. That leaves the old -destination names intact (e.g., they are needed for \cs{autoref}). -This redefinition is also available as \cs{HyperDestLabelReplace}, -thus that an own redefinition can use it. -The following example also adds a prefix for \emph{all} destination names: -\begin{quote} -\begin{verbatim} -\renewcommand*{\HyperDestNameFilter}[1]{% - \jobname-\HyperDestLabelReplace{#1}% -} -\end{verbatim} -\end{quote} -The other case that only files prefixed that do not have a corresponding -\cs{label} is more complicate, because \cs{HyperDestLabelReplace} needs -the unmodified destination name as argument. This is solved by an -expandable string test (\cs{pdfstrcmp} of \hologo{pdfTeX} -or \cs{strcmp} of \hologo{XeTeX}, package \xpackage{pdftexcmds} also supports -\hologo{LuaTeX}): -\begin{quote} -\begin{verbatim} -\usepackage{pdftexcmds} -\makeatletter -\renewcommand*{\HyperDestNameFilter}[1]{% - \ifcase\pdf@strcmp{#1}{\HyperDestLabelReplace{#1}} % - \jobname-#1% - \else - \HyperDestLabelReplace{#1}% - \fi -} -\makeatother -\end{verbatim} -\end{quote} - -With option \texttt{destlabel} destinations can also named manually, -if the destination is not yet renamed: -\begin{quote} -\verb|\HyperDestRename{|\meta{destination}\verb|}{|\meta{newname}\verb|}| -\end{quote} - -Hint: Anchors can also be named and set by \cs{hypertarget}. - -\medskip -\begin{longtable}{>{\ttfamily}ll>{\itshape}ll} -destlabel & boolean & false & destinations are named by first \cs{label}\\ - & & & after anchor creation\\ -hypertexnames & boolean & true & use guessable names for links \\ -naturalnames & boolean & false & use \LaTeX-computed names for links \\ -plainpages & boolean & false & Forces page anchors to be named by the Arabic form \\ - & & & of the page number, rather than the formatted form. \\ -\end{longtable} - -\subsection{Configuration options} - -\begin{longtable}{>{\ttfamily}ll>{\itshape}lp{9cm}} -raiselinks & boolean & true & In the hypertex driver, the height of links is normally calculated by the driver as - simply the base line of contained text; this options forces \verb|\special| commands to - reflect the real height of the link (which could contain a graphic) \\ -breaklinks & boolean & both & This option is in hyperref only used in the dviwindo driver, in all other cases it doesn't do anything sensible---it neither allows nor prevents links to be broken. The ocgx2 package -checks the state of the boolean.\\ -pageanchor & boolean & true & Determines whether every page is given an implicit anchor at the top left corner. If this - is turned off, \verb|\printindex| will not contain - valid hyperlinks. \\ -nesting & boolean & false & Allows links to be nested; no drivers currently support this. -\end{longtable} - -Note for option \verb|breaklinks|: -The correct value is automatically set according to the driver features. -It can be overwritten for drivers that do not support broken links. -However, at any case, the link area will be wrong and displaced. - -\subsection{Backend drivers} - -If no driver is specified, the package tries to find a driver in -the following order: -\begin{enumerate} -\item Autodetection, some \TeX\ processors can be detected at \TeX\ macro - level (pdf\TeX, Xe\TeX, V\TeX). -\item Option \textsf{driverfallback}. If this option is set, its value - is taken as driver option. -\item Macro \cs{Hy@defaultdriver}. The macro takes a driver file - name (without file extension). -\item Package default is \textsf{hypertex}. -\end{enumerate} -Many distributions are using a driver file \texttt{hypertex.cfg} that -define \cs{Hy@defaultdriver} with \texttt{hdvips}. This is recommended -because driver \textsf{dvips} provides much more features than -\textsf{hypertex} for PDF generation. - -\begin{longtable}{@{}>{\ttfamily}lp{.8\hsize}@{}} -driverfallback & Its value is used as driver option\\ - & if the driver is not given or autodetected.\\ -dvipdfm & Sets up \textsf{hyperref} for use with the \textsf{dvipdfm} driver.\\ -dvipdfmx & Sets up \textsf{hyperref} for use with the \textsf{dvipdfmx} driver.\\ -dvips & Sets up \textsf{hyperref} for use with the \textsf{dvips} driver. \\ -dvipsone & Sets up \textsf{hyperref} for use with the \textsf{dvipsone} driver. \\ -dviwindo & Sets up \textsf{hyperref} for use with the \textsf{dviwindo} Windows previewer. \\ -hypertex & Sets up \textsf{hyperref} for use with the Hyper\TeX-compliant drivers. \\ -latex2html & Redefines a few macros for compatibility with \textsf{latex2html}. \\ -nativepdf & An alias for \textsf{dvips} \\ -pdfmark & An alias for \textsf{dvips} \\ -pdftex & Sets up \textsf{hyperref} for use with the \textsf{pdftex} program.\\ -ps2pdf & Redefines a few macros for compatibility with - Ghostscript's PDF writer, otherwise identical to - \textsf{dvips}. \\ -tex4ht & For use with \textsf{\TeX4ht} \\ -textures & For use with \textsf{Textures} \\ -vtex & For use with MicroPress' \textsf{VTeX}; the PDF - and HTML backends are detected automatically. \\ -vtexpdfmark & For use with \textsf{VTeX}'s PostScript backend. \\ -xetex & For use with Xe\TeX\ (using backend for dvipdfm). -\end{longtable} -\smallskip - -If you use \textsf{dviwindo}, you may need to redefine the macro -\ci{wwwbrowser} (the default is \verb|C:\netscape\netscape|) to tell -\textsf{dviwindo} what program to launch. Thus, users of Internet -Explorer might add something like this to hyperref.cfg: - -\begin{verbatim} -\renewcommand{\wwwbrowser}{C:\string\Program\space - Files\string\Plus!\string\Microsoft\space - Internet\string\iexplore.exe} -\end{verbatim} - -\subsection{Extension options} -\begin{longtable}{@{}>{\ttfamily}ll>{\itshape}lp{8cm}@{}} -extension & text & & Set the file extension (e.g.\ \textsf{dvi}) which will be appended to file links - created if you use the \xpackage{xr} package. \\ -hyperfigures & boolean & & \\ -backref & text & false & Adds `backlink' text to the end of each item in the bibliography, as a list of - section numbers. This can only work properly \emph{if} there is a blank line after - each \verb|\bibitem|. Supported values are \verb|section|, \verb|slide|, \verb|page|, - \verb|none|, or \verb|false|. If no value is given, \verb|section| is taken as default.\\ -pagebackref & boolean & false & Adds `backlink' text to the end of each item in the bibliography, as a list of page - numbers. \\ -hyperindex & boolean & true & Makes the page numbers of index entries into hyperlinks. Relays on unique - page anchors (\verb|pageanchor|, \ldots) - \verb|pageanchors| and \verb|plainpages=false|. \\ -hyperfootnotes & boolean & true & Makes the footnote marks into hyperlinks to the footnote text. - Easily broken \ldots\\ -encap & & & Sets encap character for hyperindex \\ -linktoc & text & section & make text (\verb|section|), page number (\verb|page|), both (\verb|all|) or nothing (\verb|none|) be link on TOC, LOF and LOT \\ -linktocpage & boolean & false & make page number, not text, be link on TOC, LOF and LOT \\ -breaklinks & boolean & false & allow links to break over lines by making links over multiple lines into PDF links to - the same target \\ -colorlinks & boolean & false & Colors the text of links and anchors. The colors chosen depend on the the type of - link. At present the only types of link distinguished are citations, page references, - URLs, local file references, and other links. - Unlike colored boxes, the colored - text remains when printing.\\ -linkcolor & color & red & Color for normal internal links. \\ -anchorcolor & color & black & Color for anchor text. Ignored by most drivers. \\ -citecolor & color & green & Color for bibliographical citations in text. \\ -filecolor & color & cyan & Color for URLs which open local files. \\ -menucolor & color & red & Color for Acrobat menu items. \\ -runcolor & color & filecolor & Color for run links (launch annotations). \\ -urlcolor & color & magenta & Color for linked URLs. \\ -allcolors & color & & Set all color options (without border and field options).\\ -frenchlinks & boolean & false & Use small caps instead of color for links.\\ -hidelinks & & & Hide links (removing color and border). \\ -\end{longtable} \smallskip - -Note that all color names must be defined before use, following the -normal system of the standard \LaTeX\ \xpackage{color} package. - -\subsection{PDF-specific display options} -\begin{longtable}{@{}>{\ttfamily}ll>{\itshape}lp{7.6cm}@{}} -bookmarks & boolean & true & A set of Acrobat bookmarks are written, in a manner similar to the - table of contents, requiring two passes of \LaTeX. Some postprocessing - of the bookmark file (file extension \texttt{.out}) may be needed to - translate \LaTeX\ codes, since bookmarks must be written in PDFEncoding. - To aid this process, the \texttt{.out} file is not rewritten by \LaTeX\ - if it is edited to contain a line \verb|\let\WriteBookmarks\relax| \\ -bookmarksopen & boolean & false & If Acrobat bookmarks are requested, show them with all the subtrees - expanded. \\ -bookmarksopenlevel & parameter & & level (\ci{maxdimen}) to which bookmarks are open \\ -bookmarksnumbered & boolean & false & If Acrobat bookmarks are requested, include section numbers. \\ -bookmarkstype & text & toc & to specify which `toc' file to mimic \\ -CJKbookmarks & boolean & false & - This option should be used to produce CJK bookmarks. - Package \verb|hyperref| - supports both normal and preprocessed mode of the \xpackage{CJK} package; - during the creation of bookmarks, it simply replaces CJK's macros - with special versions which expand to the corresponding character - codes. Note that without the `unicode' option of hyperref you get - PDF files which actually violate the PDF specification because - non-Unicode character codes are used -- some PDF readers localized - for CJK languages (most notably Acroread itself) support this. - Also note that option `CJKbookmarks' cannot be used together - with option `unicode'. - - No mechanism is provided to translate non-Unicode bookmarks to - Unicode; for portable PDF documents only Unicode encoding should - be used.\\ -pdfhighlight & name & /I & How link buttons behave when selected; /I is for inverse (the default); - the other possibilities are /N (no effect), /O (outline), and /P (inset - highlighting). \\ -citebordercolor & RGB color & 0 1 0 & The color of the box around citations \\ -filebordercolor & RGB color & 0 .5 .5 & The color of the box around links to files \\ -linkbordercolor & RGB color & 1 0 0 & The color of the box around normal links \\ -menubordercolor & RGB color & 1 0 0 & The color of the box around Acrobat menu links \\ -urlbordercolor & RGB color & 0 1 1 & The color of the box around links to URLs \\ -runbordercolor & RGB color & 0 .7 .7 & Color of border around `run' links \\ -allbordercolors & & & Set all border color options \\ -pdfborder & & 0 0 1 & The style of box around links; defaults to a box with lines of 1pt thickness, - but the colorlinks option resets it to produce no border. -\end{longtable} - -Note that the color of link borders can be specified \emph{only} as 3 -numbers in the range 0..1, giving an RGB color. You cannot use colors -defined in \TeX. Since version 6.76a this is no longer true. -Especially with the help of package \xpackage{xcolor} the usual -color specifications of package \xpackage{(x)color} can be used. -For further information see description of package \xpackage{hycolor}. - -The bookmark commands are stored in a file called -\textit{jobname}\texttt{.out}. The files is not processed by \LaTeX\ so -any markup is passed through. You can postprocess this file as needed; -as an aid for this, the \texttt{.out} file is not overwritten on the -next \TeX\ run if it is edited to contain the line -\begin{verbatim} -\let\WriteBookmarks\relax -\end{verbatim} - -\subsection{PDF display and information options} -\begin{longtable}{@{}>{\ttfamily}l>{\raggedright}p{\widthof{key value}}>{\itshape}lp{7cm}@{}} -baseurl & URL & & Sets the base URL of the PDF document \\ -pdfpagemode & name & empty & Determines how the file is opening in Acrobat; the possibilities are - \verb|UseNone|, \verb|UseThumbs| (show thumbnails), \verb|UseOutlines| - (show bookmarks), \verb|FullScreen|, \verb|UseOC| (PDF 1.5), - and \verb|UseAttachments| (PDF 1.6). If no mode if explicitly chosen, but the - bookmarks option is set, \verb|UseOutlines| is used. \\ -pdftitle & text & & Sets the document information Title field \\ -pdfauthor & text & & Sets the document information Author field \\ -pdfsubject & text & & Sets the document information Subject field \\ -pdfcreator & text & & Sets the document information Creator field \\ -addtopdfcreator & text & & Adds additional text to the document information Creator field \\ -pdfkeywords & text & & Sets the document information Keywords field \\ -pdftrapped & name & empty & Sets the document information Trapped entry. Possible values are \verb|True|, \verb|False| and \verb|Unknown|. - An empty value means, the entry is not set.\\ -% -pdfinfo & key value list & empty & Alternative interface for setting the - document information.\\ -pdfview & name & XYZ & Sets the default PDF `view' for each link \\ -pdfstartpage & integer & 1 & Determines on which page the PDF file is opened. An empty value means, the entry is not set.\\ -pdfstartview & name & Fit & Set the startup page view \\ -pdfremotestartview & name & Fit & Set the startup page view of remote PDF files \\ -pdfpagescrop & n n n n & & Sets the default PDF crop box for pages. This should be a set of four numbers \\ -pdfcenterwindow & boolean & false & position the document window in the center of the screen \\ -pdfdirection & name & empty & direction setting. Possible values: \verb|L2R| (left to right) and - \verb|R2L| (right to left)\\ -pdfdisplaydoctitle & boolean & false & display document title instead of file name in title bar\\ -pdfduplex & name & empty & paper handling option for print dialog. Possible vatues are: - \verb|Simplex| (print single-sided), - \verb|DuplexFlipShortEdge| (duplex and flip on the short edge of the sheet), - \verb|DuplexFlipLongEdge| (duplex and flip on the long edge of the sheet)\\ - -pdffitwindow & boolean & false & resize document window to fit document size \\ -pdflang & name & relax & PDF language identifier (RFC 3066)\\ -pdfmenubar & boolean & true & make PDF viewer's menu bar visible \\ -pdfnewwindow & boolean & false & make links that open another PDF file start a new window \\ -pdfnonfullscreenpagemode - & name & empty & page mode setting on exiting full-screen mode. Possible values are - \verb|UseNone|, \verb|UseOutlines|, \verb|UseThumbs|, and \verb|UseOC|\\ -pdfnumcopies & integer & empty & number of printed copies \\ -pdfpagelayout & name & empty & set layout of PDF pages. Possible values: - \verb|SinglePage|, \verb|OneColumn|, - \verb|TwoColumnLeft|, \verb|TwoColumnRight|, - \verb|TwoPageLeft|, and \verb|TwoPageRight| \\ -pdfpagelabels & boolean & true & set PDF page labels \\ -pdfpagetransition & name & empty & set PDF page transition style. Possible values are - \verb|Split|, \verb|Blinds|, \verb|Box|, \verb|Wipe|, - \verb|Dissolve|, \verb|Glitter|, \verb|R|, - \verb|Fly|, \verb|Push|, - \verb|Cover|, \verb|Uncover|, - \verb|Fade|. - The default according to the PDF~Reference is \verb|R|, - which simply replaces the old page with the new one. \\ -pdfpicktraybypdfsize - & boolean & false & specify whether PDF page size is used to select input paper tray in print dialog \\ -pdfprintarea & name & empty & set /PrintArea of viewer preferences. Possible values are - \verb|MediaBox|, \verb|CropBox|, - \verb|BleedBox|, \verb|TrimBox|, and \verb|ArtBox|. - The dafault according to the PDF~Refence is \verb|CropBox| \\ -pdfprintclip & name & empty & set /PrintClip of viewer preferences. Possible values are - \verb|MediaBox|, \verb|CropBox|, - \verb|BleedBox|, \verb|TrimBox|, and \verb|ArtBox|. - The dafault according to the PDF~Refence is \verb|CropBox| \\ -pdfprintpagerange & n n (n n)* - & empty & set /PrintPageRange of viewer preferences\\ -pdfprintscaling & name & empty & page scaling option for print dialog - (option /PrintScaling of viewer - preferences, PDF 1.6); - valid values are \verb|None| and - \verb|AppDefault| \\ -pdftoolbar & boolean & true & make PDF toolbar visible \\ -pdfviewarea & name & empty & set /ViewArea of viewer preferences. Possible values are - \verb|MediaBox|, \verb|CropBox|, - \verb|BleedBox|, \verb|TrimBox|, and \verb|ArtBox|. - The dafault according to the PDF~Refence is \verb|CropBox| \\ -pdfviewclip & name & empty & set /ViewClip of viewer preferences Possible values are - \verb|MediaBox|, \verb|CropBox|, - \verb|BleedBox|, \verb|TrimBox|, and \verb|ArtBox|. - The dafault according to the PDF~Refence is \verb|CropBox| \\ -pdfwindowui & boolean & true & make PDF user interface elements visible \\ -unicode & boolean & true & Unicode encoded PDF strings -\end{longtable} - -Each link in Acrobat carries its own magnification level, which is set -using PDF coordinate space, which is not the same as \TeX's. The unit -is bp and the origin is in the lower left corner. See also -\verb|\hypercalcbp| that is explained on page \pageref{hypercalcbp}. -pdf\TeX\ -works by supplying default values for \texttt{XYZ} (horizontal $\times$ -vertical $\times$ zoom) and \texttt{FitBH}. However, drivers using -\texttt{pdfmark} do not supply defaults, so \textsf{hyperref} passes in -a value of -32768, which causes Acrobat to set (usually) sensible -defaults. The following are possible values for the \texttt{pdfview}, -\texttt{pdfstartview} and \texttt{pdfremotestartview} parameters. - -\begin{longtable}{@{}>{\ttfamily}l>{\itshape}lp{7cm}@{}} -XYZ & left top zoom & Sets a coordinate and a zoom factor. If any one is null, the source link value is used. - \textit{null null null} will give the same values as the current page. \\ -Fit & & Fits the page to the window. \\ -FitH & top & Fits the width of the page to the window. \\ -FitV & left & Fits the height of the page to the window. \\ -FitR & left bottom right top & Fits the rectangle specified by the four coordinates to the window. \\ -FitB & & Fits the page bounding box to the window. \\ -FitBH & top & Fits the width of the page bounding box to the window. \\ -FitBV & left & Fits the height of the page bounding box to the window. \\ -\end{longtable} - -The \texttt{pdfpagelayout} can be one of the following values. - -\begin{longtable}{@{}>{\ttfamily}lp{10cm}@{}} -SinglePage & Displays a single page; advancing flips the page \\ -OneColumn & Displays the document in one column; continuous scrolling. \\ -TwoColumnLeft & Displays the document in two columns, odd-numbered pages to the left. \\ -TwoColumnRight & Displays the document in two columns, odd-numbered pages to the right.\\ -TwoPageLeft & Displays two pages, odd-numbered pages to the left (since PDF 1.5).\\ -TwoPageRight & Displays two pages, odd-numbered pages to the right (since PDF 1.5). -\end{longtable} - -Finally, the \texttt{pdfpagetransition} can be one of the following -values, where \textit{/Di} stands for direction of motion in degrees, -generally in 90$^{\circ}$\ steps, \textit{/Dm} is a horizontal -(\texttt{/H}) or vertical (\texttt{/V}) dimension (e.g.\ \texttt{Blinds -/Dm /V}), and \textit{/M} is for motion, either in (\texttt{/I}) or out -(\texttt{/O}). - -\begin{longtable}{@{}>{\ttfamily}llp{8.5cm}@{}} -Blinds & /Dm & Multiple lines distributed evenly across the screen sweep in the same direction to reveal the new - page. \\ -Box & /M & A box sweeps in or out. \\ -Dissolve & & The page image dissolves in a piecemeal fashion to reveal the new page. \\ -Glitter & /Di & Similar to Dissolve, except the effect sweeps across the screen. \\ -Split & /Dm /M & Two lines sweep across the screen to reveal the new page. \\ -Wipe & /Di & A single line sweeps across the screen to reveal the new page. \\ -R & & Simply replaces the old page with the new one. \\ -Fly & /Di /M & Changes are flown out or in (as specified by /M), in the direction - specified by /Di, to or from a location that is - offscreen except when /Di is None. \\ -Push & /Di & The old page slides off the screen while the new page slides in, - pushing the old page out in the direction - specified by /Di. \\ -Cover & /Di & The new page slides on to the screen in the direction specified - by /Di, covering the old page. \\ -Uncover & /Di & The old page slides off the screen in the direction specified by - /Di, uncovering the new page in the direction - specified by /Di. \\ -Fade & & The new page gradually becomes visible through the old one. - -\end{longtable} - -\subsection{Option \texttt{pdfinfo}} - -The information entries can be set using \texttt{pdftitle}, -\texttt{pdfsubject}, \dots. Option \texttt{pdfinfo} provides an alternative -interface. It takes a key value list. The key names are the names that -appear in the PDF information dictionary directly. Known keys such as -\texttt{Title}, \texttt{Subject}, \texttt{Trapped} and other are mapped to -options \texttt{pdftitle}, \texttt{subject}, \texttt{trapped}, \dots -Unknown keys are added to the information dictionary. Their values are text -strings (see PDF specification). -Example: -\begin{quote} -\begin{verbatim} -\hypersetup{ - pdfinfo={ - Title={My Title}, - Subject={My Subject}, - NewKey={Foobar}, - % ... - } -} -\end{verbatim} -\end{quote} - -\subsection{Big alphabetical list} - -The following is a complete listing of available options for -\textsf{hyperref}, arranged alphabetically. - -\begin{longtable}{@{}>{\ttfamily}llp{7cm}@{}} -allbordercolors & & Set all border color options\\ -allcolors & & Set all color options (without border and field options)\\ -anchorcolor & \textit{black} & set color of anchors, ignored by most drivers. \\ -backref & \textit{false} & do bibliographical back references \\ -baseurl & \textit{empty} & set base URL for document \\ -bookmarks & \textit{true} & make bookmarks \\ -bookmarksnumbered & \textit{false} & put section numbers in bookmarks \\ -bookmarksopen & \textit{false} & open up bookmark tree \\ -bookmarksopenlevel & \ttfamily\ci{maxdimen} & level to which bookmarks are open \\ -bookmarkstype & \textit{toc} & to specify which `toc' file to mimic \\ -breaklinks & \textit{false} & allow links to break over lines \\ -CJKbookmarks & \textit{false} & to produce CJK bookmarks\\ -citebordercolor & \textit{0 1 0} & color of border around cites \\ -citecolor & \textit{green} & color of citation links \\ -colorlinks & \textit{false} & color links \\ - & \textit{true} & (\textsf{tex4ht}, \textsf{dviwindo}) \\ -debug & \textit{false} & provide details of anchors defined; same as verbose \\ -destlabel & \textit{false} & destinations are named by the first \verb|\label| after the anchor creation \\ -draft & \textit{false} & do not do any hyperlinking \\ -driverfallback & & default if no driver specified or detected\\ -dvipdfm & & use \textsf{dvipdfm} backend \\ -dvipdfmx & & use \textsf{dvipdfmx} backend \\ -dvips & & use \textsf{dvips} backend \\ -dvipsone & & use \textsf{dvipsone} backend \\ -dviwindo & & use \textsf{dviwindo} backend \\ -encap & & to set encap character for hyperindex \\ -extension & \textit{dvi} & suffix of linked files \\ -filebordercolor & \textit{0 .5 .5} & color of border around file links \\ -filecolor & \textit{cyan} & color of file links \\ -final & \textit{true} & opposite of option draft \\ -frenchlinks & \textit{false} & use small caps instead of color for links \\ -hidelinks & & Hide links (removing color and border) \\ -hyperfigures & \textit{false} & make figures hyper links \\ -hyperfootnotes & \textit{true} & set up hyperlinked footnotes \\ -hyperindex & \textit{true} & set up hyperlinked indices \\ -hypertex & & use \textsf{Hyper\TeX} backend \\ -hypertexnames & \textit{true} & use guessable names for links \\ -implicit & \textit{true} & redefine \LaTeX\ internals \\ -latex2html & & use \textsf{\LaTeX2HTML} backend \\ -linkbordercolor & \textit{1 0 0} & color of border around links \\ -linkcolor & \textit{red} & color of links \\ -linktoc & \textit{section} & make text be link on TOC, LOF and LOT \\ -linktocpage & \textit{false} & make page number, not text, be link on TOC, LOF and LOT \\ -menubordercolor & \textit{1 0 0} & color of border around menu links \\ -menucolor & \textit{red} & color for menu links \\ -nativepdf & \textit{false} & an alias for \textsf{dvips} \\ -naturalnames & \textit{false} & use \LaTeX-computed names for links \\ -nesting & \textit{false} & allow nesting of links \\ -pageanchor & \textit{true} & put an anchor on every page \\ -pagebackref & \textit{false} & backreference by page number \\ -pdfauthor & \textit{empty} & text for PDF Author field \\ -pdfborder & \textit{0 0 1} & width of PDF link border \\ - & \textit{0 0 0} & (\texttt{colorlinks)} \\ -pdfborderstyle & & border style for links \\ -pdfcenterwindow & \textit{false} & position the document window in the center of the screen \\ -pdfcreator & \textit{LaTeX with} & text for PDF Creator field \\ - & \textit{hyperref} & \\ -pdfdirection & \textit{empty} & direction setting \\ -pdfdisplaydoctitle & \textit{false} & display document title instead - of file name in title bar\\ -pdfduplex & \textit{empty} & paper handling option for - print dialog\\ -pdffitwindow & \textit{false} & resize document window to fit document size \\ -pdfhighlight & \textit{/I} & set highlighting of PDF links \\ -pdfinfo & \textit{empty} & alternative interface for setting document information\\ -pdfkeywords & \textit{empty} & text for PDF Keywords field \\ -pdflang & \textit{relax} & PDF language identifier (RFC 3066) \\ -pdfmark & \textit{false} & an alias for \textsf{dvips} \\ -pdfmenubar & \textit{true} & make PDF viewer's menu bar visible \\ -pdfnewwindow & \textit{false} & make links that open another PDF \\ - & & file start a new window \\ -pdfnonfullscreenpagemode - & \textit{empty} & page mode setting on exiting - full-screen mode\\ -pdfnumcopies & \textit{empty} & number of printed copies\\ -pdfpagelabels & \textit{true} & set PDF page labels \\ -pdfpagelayout & \textit{empty} & set layout of PDF pages \\ -pdfpagemode & \textit{empty} & set default mode of PDF display \\ -pdfpagescrop & \textit{empty} & set crop size of PDF document \\ -pdfpagetransition & \textit{empty} & set PDF page transition style \\ -pdfpicktraybypdfsize - & \textit{empty} & set option for print dialog \\ -pdfprintarea & \textit{empty} & set /PrintArea of viewer preferences \\ -pdfprintclip & \textit{empty} & set /PrintClip of viewer preferences \\ -pdfprintpagerange & \textit{empty} & set /PrintPageRange of viewer preferences \\ -pdfprintscaling & \textit{empty} & page scaling option for print dialog \\ -pdfproducer & \textit{empty} & text for PDF Producer field \\ -pdfremotestartview & \textit{Fit} & starting view of remote PDF documents \\ -pdfstartpage & \textit{1} & page at which PDF document opens \\ -pdfstartview & \textit{Fit} & starting view of PDF document \\ -pdfsubject & \textit{empty} & text for PDF Subject field \\ -pdftex & & use \textsf{pdf\TeX} backend \\ -pdftitle & \textit{empty} & text for PDF Title field \\ -pdftoolbar & \textit{true} & make PDF toolbar visible \\ -pdftrapped & \textit{empty} & Sets the document information Trapped entry. - Possible values are \texttt{True}, \texttt{False} and \texttt{Unknown}. - An empty value means, the entry is not set.\\ -pdfview & \textit{XYZ} & PDF `view' when on link traversal \\ -pdfviewarea & \textit{empty} & set /ViewArea of viewer preferences \\ -pdfviewclip & \textit{empty} & set /ViewClip of viewer preferences \\ -pdfwindowui & \textit{true} & make PDF user interface elements visible \\ -plainpages & \textit{false} & do page number anchors as plain Arabic \\ -ps2pdf & & use \textsf{ps2pdf} backend \\ -psdextra & \textit{false} & define more short names for PDF string commands \\ -raiselinks & \textit{false} & raise up links (for \textsf{Hyper\TeX} backend) \\ -runbordercolor & \textit{0 .7 .7} & color of border around `run' links \\ -runcolor & \textit{filecolor} & color of `run' links\\ -setpagesize & \textit{true} & set page size by special driver commands \\ -tex4ht & & use \textsf{\TeX4ht} backend \\ -textures & & use \textsf{Textures} backend \\ -unicode & \textit{true} & Unicode encoded pdf strings, starting with version 2021-02-04 v7.00g set by default to true for all engines. \\ -urlbordercolor & \textit{0 1 1} & color of border around URL links \\ -urlcolor & \textit{magenta} & color of URL links \\ -verbose & \textit{false} & be chatty \\ -vtex & & use \textsf{VTeX} backend\\ -xetex & & use \textsf{Xe\TeX} backend\\ -\end{longtable} - -\section{Additional user macros} - -If you need to make references to URLs, or write explicit links, the -following low-level user macros are provided: - -\begin{cmdsyntax} -\ci{href}\verb|[|\emph{options}\verb|]|\verb|{|\emph{URL}\verb|}{|\emph{text}\verb|}| -\end{cmdsyntax} - -\noindent The \emph{text} is made a hyperlink to the \emph{URL}; this -must be a full URL (relative to the base URL, if that is defined). The -special characters \# and \~{} do \emph{not} need to be escaped in any -way (unless the command is used in the argument of another command). - -The optional argument \emph{options} recognizes the hyperref options -\texttt{pdfremotestartview}, \texttt{pdfnewwindow} and the following -key value options: -\begin{description} -\item[\texttt{page}:] Specifies the start page number of remote -PDF documents. First page is \verb|1|. -\item[\texttt{ismap}:] Boolean key, if set to \verb|true|, the -URL should appended by the coordinates as query parameters by -the PDF viewer. -\item[\texttt{nextactionraw}:] The value of key \verb|/Next| of -action dictionaries, see PDF specification. -\end{description} - -\begin{cmdsyntax} -\ci{url}\verb|{|\emph{URL}\verb|}| -\end{cmdsyntax} - -\noindent Similar to -\ci{href}\verb|{|\emph{URL}\verb|}{|\ci{nolinkurl}\verb|{|\emph{URL}\verb|}}|. -Depending on the driver \verb|\href| also tries to detect the link type. -Thus the result can be a url link, file link, \dots - -\begin{cmdsyntax} -\ci{nolinkurl}\verb|{|\emph{URL}\verb|}| -\end{cmdsyntax} - -\noindent Write \emph{URL} in the same way as \verb|\url|, - without creating a hyperlink. - -\begin{cmdsyntax} -\ci{hyperbaseurl}\verb|{|\emph{URL}\verb|}| -\end{cmdsyntax} - -\noindent A base \emph{URL} is established, which is prepended to other -specified URLs, to make it easier to write portable documents. - -\begin{cmdsyntax} -\ci{hyperimage}\verb|{|\emph{imageURL}\verb|}{|\emph{text}\verb|}| -\end{cmdsyntax} - -\noindent The link to the image referenced by the URL is inserted, using -\emph{text} as the anchor. - - For drivers that produce HTML, the image itself is inserted by the -browser, with the \emph{text} being ignored completely. - -\begin{cmdsyntax} -\ci{hyperdef}\verb|{|\emph{category}\verb|}{|\emph{name}\verb|}{|\emph{text}\verb|}| -\end{cmdsyntax} - -\noindent A target area of the document (the \emph{text}) is marked, and -given the name \emph{category.name} - -\begin{cmdsyntax} -\ci{hyperref}\verb|{|\emph{URL}\verb|}{|\emph{category}\verb|}{|\emph{name}\verb|}{|\emph{text}\verb|}| -\end{cmdsyntax} - -\noindent \emph{text} is made into a link to \emph{URL\#category.name} - -\begin{cmdsyntax} -\ci{hyperref}\verb|[|\emph{label}\verb|]{|\emph{text}\verb|}| -\end{cmdsyntax} - -\noindent -\emph{text} is made into a link to the same place as -\verb|\ref{|\emph{label}\verb|}| would be linked. - -\begin{cmdsyntax} -\ci{hyperlink}\verb|{|\emph{name}\verb|}{|\emph{text}\verb|}| -\end{cmdsyntax} -\begin{cmdsyntax} -\ci{hypertarget}\verb|{|\emph{name}\verb|}{|\emph{text}\verb|}| -\end{cmdsyntax} - -\noindent A simple internal link is created with \verb|\hypertarget|, -with two parameters of an anchor \emph{name}, and anchor -\emph{text}. \verb|\hyperlink| has two arguments, the name of a -hypertext object defined somewhere by \verb|\hypertarget|, and the -\emph{text} which be used as the link on the page. - -Note that in HTML parlance, the \verb|\hyperlink| command inserts a -notional \# in front of each link, making it relative to the current -testdocument; \verb|\href| expects a full URL. - -\begin{cmdsyntax} -\ci{phantomsection} -\end{cmdsyntax} - -\noindent -This sets an anchor at this location. It works similar to -\verb|\hypertarget{}{}| with an automatically chosen anchor name. -Often it is used in conjunction -with \verb|\addcontentsline| for sectionlike things (index, bibliography, -preface). \verb|\addcontentsline| refers to the latest previous location -where an anchor is set. Example: -\begin{quote} -\begin{verbatim} -\cleardoublepage -\phantomsection -\addcontentsline{toc}{chapter}{\indexname} -\printindex -\end{verbatim} -\end{quote} -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. - -\begin{cmdsyntax} -\ci{autoref}\verb|{|\emph{label}\verb|}| -\end{cmdsyntax} - -\noindent -This is a replacement for the usual \verb|\ref| command that places a -contextual label in front of the reference. This gives your users a -bigger target to click for hyperlinks (e.g.\ `section 2' instead of -merely the number `2'). - -The label is worked out from the context of the original \verb|\label| -command by \textsf{hyperref} by using the macros listed below (shown -with their default values). The macros can be (re)defined in documents -using \verb|\(re)newcommand|; note that some of these macros are already -defined in the standard document classes. The mixture of lowercase and -uppercase initial letters is deliberate and corresponds to the author's -practice. - -For each macro below, \textsf{hyperref} checks \ci{*autorefname} before -\ci{*name}. For instance, it looks for \ci{figureautorefname} before -\ci{figurename}. - -\begin{longtable}{@{}lp{10cm}@{}} -\textit{Macro} & \textit{Default} \\ -\ci{figurename} & Figure \\ -\ci{tablename} & Table \\ -\ci{partname} & Part \\ -\ci{appendixname} & Appendix \\ -\ci{equationname} & Equation \\ -\ci{Itemname} & item \\ -\ci{chaptername} & chapter \\ -\ci{sectionname} & section \\ -\ci{subsectionname} & subsection \\ -\ci{subsubsectionname} & subsubsection \\ -\ci{paragraphname} & paragraph \\ -\ci{Hfootnotename} & footnote \\ -\ci{AMSname} & Equation \\ -\ci{theoremname} & Theorem\\ -\ci{page} & page\\ -\end{longtable} - -Example for a redefinition if \textsf{babel} is used: -\begin{quote} -\begin{verbatim} -\usepackage[ngerman]{babel} -\addto\extrasngerman{% - \def\subsectionautorefname{Unterkapitel}% -} -\end{verbatim} -\end{quote} - -Hint: \cs{autoref} works via the counter name that the reference -is based on. Sometimes \cs{autoref} chooses the wrong name, if -the counter is used for different things. For example, it happens -with \cs{newtheorem} if a lemma shares a counter with theorems. -Then package \xpackage{aliascnt} provides a method to generate a -simulated second counter that allows the differentiation between -theorems and lemmas: -\begin{quote} -\begin{verbatim} -\documentclass{article} - -\usepackage{aliascnt} -\usepackage{hyperref} - -\newtheorem{theorem}{Theorem} - -\newaliascnt{lemma}{theorem} -\newtheorem{lemma}[lemma]{Lemma} -\aliascntresetthe{lemma} - -\providecommand*{\lemmaautorefname}{Lemma} - -\begin{document} - -We will use \autoref{a} to prove \autoref{b}. - -\begin{lemma}\label{a} - Nobody knows. -\end{lemma} - -\begin{theorem}\label{b} - Nobody is right. -\end{theorem}. - -\end{document} -\end{verbatim} -\end{quote} - -\begin{cmdsyntax} -\ci{autopageref}\verb|{|\emph{label}\verb|}| -\end{cmdsyntax} - -\noindent -It replaces \verb|\pageref| and adds the name for page in front of -the page reference. First \ci{pageautorefname} is checked before -\ci{pagename}. - -For instances where you want a reference to use the correct counter, but -not to create a link, there are starred forms (these starred forms exist even if -hyperref has been loaded with \verb|implicit=false|): - -\begin{cmdsyntax} -\ci{ref*}\verb|{|\emph{label}\verb|}| -\end{cmdsyntax} - -\begin{cmdsyntax} -\ci{pageref*}\verb|{|\emph{label}\verb|}| -\end{cmdsyntax} - -\begin{cmdsyntax} -\ci{autoref*}\verb|{|\emph{label}\verb|}| -\end{cmdsyntax} - -\begin{cmdsyntax} -\ci{autopageref*}\verb|{|\emph{label}\verb|}| -\end{cmdsyntax} - -A typical use would be to write -\begin{verbatim} -\hyperref[other]{that nice section (\ref*{other}) we read before} -\end{verbatim} - -We want \verb|\ref*{other}| to generate the correct number, but not to -form a link, since we do this ourselves with \ci{hyperref}. - -\begin{cmdsyntax} -\ci{pdfstringdef}\verb|{|\emph{macroname}\verb|}{|\emph{\TeX string}\verb|}| -\end{cmdsyntax} - -\ci{pdfstringdef} returns a macro containing the PDF string. (Currently -this is done globally, but do not rely on it.) All the following tasks, -definitions and redefinitions are made in a group to keep them local: - -\begin{itemize} -\item Switching to PD1 or PU encoding -\item Defining the \Quote{octal sequence commands} (\verb|\345|): \verb|\edef\3{\string\3}| -\item Special glyphs of \TeX: \verb|\{|, \verb|\%|, \verb|\&|, \verb|\space|, \verb|\dots|, etc. -\item National glyphs (\textsf{german.sty}, \textsf{french.sty}, etc.) -\item Logos: \verb|\TeX|, \verb|\eTeX|, \verb|\MF|, etc. -\item Disabling commands that do not provide useful functionality in bookmarks: -\verb|\label|, \verb|\index|, \verb|\glossary|, \verb|\discretionary|, \verb|\def|, \verb|\let|, etc. -\item \LaTeX's font commands like \verb|\textbf|, etc. -\item Support for \verb|\xspace| provided by the \xpackage{xspace} package -\end{itemize} - -In addition, parentheses are protected to avoid the danger of unsafe -unbalanced parentheses in the PDF string. For further details, see Heiko -Oberdiek's Euro\TeX\ paper distributed with \textsf{hyperref}. - -\begin{cmdsyntax} -\ci{begin}\verb|{NoHyper}|\ldots\ci{end}\verb|{NoHyper}| -\end{cmdsyntax} - Sometimes we just don't want the wretched package interfering - with us. Define an environment we can put in manually, or include - in a style file, which stops the hypertext functions doing anything. - This is used, for instance, in the Elsevier classes, to stop - \verb|hyperref| playing havoc in the front matter. - -\subsection{Bookmark macros} - -\subsubsection{Setting bookmarks} - -Usually \textsf{hyperref} automatically adds bookmarks for -\verb|\section| and similar macros. But they can also set manually. - -\begin{cmdsyntax} -\ci{pdfbookmark}\verb|[|\emph{level}\verb|]{|text\verb|}{|\emph{name}\verb|}| -\end{cmdsyntax} -creates a bookmark with the specified text and at the given level (default is -0). As name for the internal anchor name is used (in conjunction with -level). Therefore the name must be unique (similar to \verb|\label|). - -\begin{cmdsyntax} -\ci{currentpdfbookmark}\verb|{|\emph{text}\verb|}{|\emph{name}\verb|}| -\end{cmdsyntax} -creates a bookmark at the current level. - -\begin{cmdsyntax} -\ci{subpdfbookmark}\verb|{|\emph{text}\verb|}{|\emph{name}\verb|}| -\end{cmdsyntax} -creates a bookmark one step down in the bookmark hierarchy. -Internally the current level is increased by one. - -\begin{cmdsyntax} -\ci{belowpdfbookmark}\verb|{|\emph{text}\verb|}{|\emph{name}\verb|}| -\end{cmdsyntax} -creates a bookmark below the current bookmark level. However after the -command the current bookmark level has not changed. - -\noindent \textbf{Hint:} Package \textsf{bookmark} replaces -\textsf{hyperref}'s bookmark organization by a new algorithm: -\begin{itemize} -\item Usually only one \LaTeX\ run is needed. -\item More control over the bookmark appearance (color, font). -\item Different bookmark actions are supported (external file links, - URLs, \dots). -\end{itemize} -Therefore I recommend using this package. - -\subsubsection{Replacement macros} - -\textsf{hyperref} takes the text for bookmarks from the arguments of -commands like \ci{section}, which can contain things like math, colors, -or font changes, none of which will display in bookmarks as is. - -\begin{cmdsyntax} -\ci{texorpdfstring}\verb|{|\emph{\TeX string}\verb|}{|\emph{PDFstring}\verb|}| -\end{cmdsyntax} - -For example, -\begin{verbatim} -\section{Pythagoras: - \texorpdfstring{$ a^2 + b^2 = c^2 $}{% - a\texttwosuperior\ + b\texttwosuperior\ = - c\texttwosuperior - }% -} -\section{\texorpdfstring{\textcolor{red}}{}{Red} Mars} -\end{verbatim} - -\ci{pdfstringdef} executes the hook \pdfstringdefPreHook before it -expands the string. Therefore, you can use this hook to perform -additional tasks or to disable additional commands. - -\begin{verbatim} -\expandafter\def\expandafter\pdfstringdefPreHook -\expandafter{% - \pdfstringdefPreHook - \renewcommand{\mycommand}[1]{}% -} -\end{verbatim} - -However, for disabling commands, an easier way is via -\ci{pdfstringdefDisableCommands}, which adds its argument to the -definition of \ci{pdfstringdefPreHook} (`@' can here be used as letter in -command names): - -\begin{verbatim} -\pdfstringdefDisableCommands{% - \let~\textasciitilde - \def\url{\pdfstringdefWarn\url}% - \let\textcolor\@gobble -} -\end{verbatim} - -\subsection{Pagelabels} -\begin{cmdsyntax} -\ci{thispdfpagelabel}\verb|{|\emph{page number format}\verb|}| -\end{cmdsyntax} - -This allows to change format of the page number shown in the tool bar of -a PDF viewer for a specific page, for example - -\verb+\thispdfpagelabel{Empty Page-\roman{page}}+ - -The command affects the page on which it is executed, so asynchronous page breaking -should be taken into account. It should be used in places where for example \verb+\thispagestyle+ can be use too. - -\subsection{Utility macros} - -\label{hypercalcbp} -\begin{cmdsyntax} -\ci{hypercalcbp}\verb|{|\emph{dimen specification}\verb|}| -\end{cmdsyntax} -\noindent -\verb|\hypercalcbp| takes a \TeX\ dimen specification and -converts it to bp and returns the number without the unit. -This is useful for options \verb|pdfview|, \verb|pdfstartview| -and \verb|pdfremotestartview|. -Example: -\begin{quote} -\begin{verbatim} -\hypersetup{ - pdfstartview={FitBH \hypercalcbp{\paperheight-\topmargin-1in - -\headheight-\headsep} -} -\end{verbatim} -\end{quote} -The origin of the PDF coordinate system is the lower left corner. - -Note, for calculations you need either package \xpackage{calc} or -\hologo{eTeX}. Nowadays the latter should automatically be enabled -for \hologo{LaTeX} formats. Users without \hologo{eTeX}, please, look -in the source documentation \verb|hyperref.dtx| for further -limitations. - -Also \cs{hypercalcbp} cannot be used in option specifications -of \cs{documentclass} and \cs{usepackage}, because -\hologo{LaTeX} expands the option lists of these commands. However -package \xpackage{hyperref} is not yet loaded and an undefined control -sequence error would arise. - -\section[New Features]{New Features% -\footnote{This section moved from the README file, needs more integration into the manual}} - - -\subsection{Option `pdflinkmargin'} - - Option `pdflinkmargin' is an experimental option for specifying - a link margin, if the driver supports this. Default is 1 pt for - supporting drivers. - - -\begin{description} -\item[pdfTeX] -\begin{itemize} - \item The link area also depends on the surrounding box. - \item Settings have local effect. - \item When a page is shipped out, pdfTeX uses the current setting - of the link margin for all links on the page. -\end{itemize} - -\item[pdfmark] -\begin{itemize} - \item Settings have global effect. -\end{itemize} - -\item[xetex] -\begin{itemize} - \item Settings must be done in the preamble or the first page and then have global effect. - The key inserts the new (x)dvipdfmx special \verb|\special{dvipdfmx:config g #1}| (with the unit removed). -\end{itemize} - -\item[Other drivers] - Unsupported. -\end{description} - - -\subsection{Field option `calculatesortkey'} - - Fields with calculated values are calculated in document order - by default. If calculated field values depend on other calculated - fields that appear later in the document, then the correct calculation - order can be specified with option `calculatesortkey'. Its value is - used as key to lexicographically sort the calculated fields. - The sort key do not need to be unique. Fields that share the same - key are sorted in document order. - - - - Currently the field option `calculatesortkey' is only supported by - the driver for pdfTeX. - - -\subsection{Option `localanchorname'} - - When an anchor is set (e.g. via \verb|\refstepcounter|, then the - anchor name is globally set to the current anchor name. - - - For example: -\begin{verbatim} - \section{Foobar} - \begin{equation}\end{equation} - \label{sec:foobar} -\end{verbatim} - With the default global setting (localanchorname=false) - a reference to `sec:foobar' jumps to the equation before. - With option `localanchorname' the anchor of the equation - is forgotten after the environment and the reference - `sec:foobar' jumps to the section title. - - - Option `localanchorname' is an experimental option, there - might be situations, where the anchor name is not available - as expected. - - -\subsection{Option `customdriver'} - - The value of option `customdriver' is the name of an external - driver file without extension `.def'. The file must have - \verb|\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. - - -\subsection{Option `psdextra'} - - LaTeX's NFSS is used to assist the conversion of arbitrary - TeX strings to PDF strings (bookmarks, PDF information entries). - Many math command names (\verb|\geq|, \verb|\notin|, ...) are not in control - of NFSS, therefore they are defined with prefix `text' - (\verb|\textgeq|, \verb|\textnotin|, ...). They can be mapped to short names - during the processing to PDF strings. The disadvantage is that - they are many hundreds macros that need to be redefined for - each PDF string conversion. Therefore this can be enabled or - disabled as option `psdextra'. On default the option is turned - off (set to `false'). Turning the option on means - that the short names are available. Then \verb|\geq| can directly - be used instead of \verb|\textgeq|. - - -\subsection{\textbackslash XeTeXLinkBox} - - When XeTeX generates a link annotation, it does not look - at the boxes (as the other drivers), but only at the character - glyphs. If there are no glyphs (images, rules, ...), then - it does not generate a link annotation. Macro \verb|\XeTeXLinkBox| - puts its argument in a box and adds spaces at the lower left - and upper right corners. An additional margin can be specified - by setting it to the dimen register \verb|\XeTeXLinkMargin|. The default - is 2pt. - - Example: - - -\begin{verbatim} - % xelatex - \documentclass{article} - \usepackage{hyperref} - \setlength{\XeTeXLinkMargin}{1pt} - \begin{document} - \section{Hello World} - \newpage - \label{sec:hello} - \hyperref[sec:hello]{% - \XeTeXLinkBox{\rule{10mm}{10mm}}% - } - \end{document} -\end{verbatim} - -\subsection{\textbackslash IfHyperBooleanExists and \textbackslash IfHyperBoolean} -\begin{verbatim} - \IfHyperBooleanExists{OPTION}{YES}{NO} -\end{verbatim} - If a hyperref OPTION is a boolean, that means it takes values - `true' or `false', then \verb|\IfHyperBooleanExists| calls YES, otherwise NO. - - -\begin{verbatim} - \IfHyperBoolean{OPTION}{YES}{NO} -\end{verbatim} - Macro \verb|\IfHyperBoolean| calls YES, if OPTION exists as boolean and is - enabled. Otherwise NO is executed. - - - - Both macros are expandable. Additionally option `stoppedearly' is - available. It is enabled if \verb|\MaybeStopEarly| or \verb|\MaybeStopNow| - end hyperref prematurely. - - -\subsection{\textbackslash unichar} - - If a Unicode character is not supported by puenc.def, it can - be given by using \verb|\unichar|. Its name and syntax is inherited - from package `ucs'. However it is defined independently for - use in hyperref's \verb|\pdfstringdef| (that converts arbitrary - TeX code to PDF strings or tries to do this). - - - - Macro \verb|\unichar| takes a TeX number as argument, - examples for U+263A (WHITE SMILING FACE): -\begin{verbatim} - \unichar{"263A}% hexadecimal notation - \unichar{9786}% decimal notation -\end{verbatim} - `"' must not be a babel shorthand character or otherwise - active. Otherwise prefix it with \verb|\string|: -\begin{verbatim} - \unichar{\string"263A}% converts `"' to `"' with catcode 12 (other) -\end{verbatim} - Users of (n)german packages or babel options may use \verb|\dq| instead: -\begin{verbatim} - \unichar{\dq 263A}% \dq is double quote with catcode 12 (other) -\end{verbatim} - - -\subsection{\textbackslash ifpdfstringunicode} - - Some features of the PDF specification needs PDF strings. - Examples are bookmarks or the entries in the information dictionary. - The PDF specification allows two encodings `PDFDocEncoding' - (8-bit encoding) and `Unicode' (UTF-16). The user can help - using \verb|\texorpdfstring| to replace complicate TeX constructs - by a representation for the PDF string. However \verb|\texorpdfstring| - does not distinguish the two encodings. This gap closes - \verb|\ifpdfstringunicode|. It is only allowed in the second argument - of \verb|\texorpdfstring| and takes two arguments, the first allows - the full range of Unicode. The second is limited to the - characters available in PDFDocEncoding. - - - - As example we take a macro definition for the Vietnamese - name of Han The Thanh. Correctly written it needs some - accented characters, one character even with a double accent. - Class `tugboat.cls' defines a macro for the typesetted name: -\begin{verbatim} - \def\Thanh{% - H\`an~% - Th\^e\llap{\raise 0.5ex\hbox{\'{}}}% - ~Th\`anh% - } -\end{verbatim} - It's not entirely correct, the second accent over the `e' is not - an acute, but a hook. However standard LaTeX does not provide - such an accent. - - Now we can extend the definition to support hyperref. - The first and the last word are already supported automatically. - Characters with two or more accents are a difficult business in - LaTeX, because the NFSS2 macros of the LaTeX kernel do not support - more than one accent. Therefore also puenc.def misses support for - them. But we can provide it using \verb|\unichar|. The character - in question is: -\begin{verbatim} - % U+1EC3 LATIN SMALL LETTER E WITH CIRCUMFLEX AND HOOK ABOVE -\end{verbatim} - Thus we can put this together: -\begin{verbatim} - \def\Thanh{% - H\`an~% - \texorpdfstring{Th\^e\llap{\raise 0.5ex\hbox{\'{}}}}% - {\ifpdfstringunicode{Th\unichar{"1EC3}}{Th\^e}}% - ~Th\`anh% - } -\end{verbatim} - For PDFDocEncoding (PD1) the variant above has dropped the - second accent. Alternatively we could provide a representation - without accents instead of wrong accents: -\begin{verbatim} - \def\Thanh{% - \texorpdfstring{% - H\`an~% - Th\^e\llap{\raise 0.5ex\hbox{\'{}}}}% - ~Th\`anh% - }{% - \ifpdfstringunicode{% - H\`an Th\unichar{"1EC3} Th\`anh% - }{% - Han The Thanh% - }% - }% - } -\end{verbatim} - -\subsection{Customizing index style file with \textbackslash nohyperpage} - - Since version 2008/08/14~v6.78f. - - - - For hyperlink support in the index, hyperref inserts \verb|\hyperpage| - into the index macros. After processing with Makeindex, \verb|\hyperpage| - analyzes its argument to detect page ranges and page comma lists. - However, only the standard settings are supported directly: -\begin{verbatim} - delim_r "--" - delim_n ", " -\end{verbatim} - (See manual page/documentation of Makeindex that explains - the keys that can be used in style files for Makeindex.) - Customized versions of - \verb|delim_r, delim_n, suffix_2p, suffix_3p, suffix_mp| - needs markup that \verb|\hyperpage| can detect and knows that - this stuff does not belong to a page number. Makro - \verb|\nohyperpage| serves as this markup. Put the customized - code for these keys inside \verb|\nohyperpage|, e.g.: -\begin{verbatim} - suffix_2p "\\nohyperpage{f.}" - suffix_3p "\\nohyperpage{ff.}" -\end{verbatim} - (Depending on the typesetting tradition some space ``\verb|\\|,'' or ``\verb|~|'' - should be put before the first f inside \verb|\nohyperpage|.) - - -\subsection{Experimental option `ocgcolorlinks'} - - The idea are colored links, when viewed, but printed without colors. - This new experimental option `ocgcolorlinks' uses Optional Content - Groups, a feature introduced in PDF 1.5. - - A better implementation which hasn't the disadvantage to prevent line breaks is - in the ocgx2 package. Check its documentation for details how to use it. -\begin{itemize} - \item The option must be given for package loading: - \verb|\usepackage[ocgcolorlinks]{hyperref}| - \item Main disadvantage: Links cannot be broken across lines. - PDF reference 1.7: 4.10.2 ``Making Graphical Content Optional'': - Graphics state operations, such as setting the color, ..., - are still applied. - Therefore the link text is put in a box and set twice, with and - without color. - \item The feature can be switched of by \verb|\hypersetup{ocgcolorlinks=false}| - inside the document. - \item Supported drivers: pdftex, dvipdfm - \item The PDF version should be at least 1.5. It is automatically - set for pdfTeX, LuaTeX and dvipdfmx. -\end{itemize} - -\subsection{Option `pdfa'} - - The new option `pdfa' tries to avoid violations of PDF/A in code - generated by hyperref. However, the result is usually not in PDF/A, - because many features aren't controlled by hyperref (XMP metadata, - fonts, colors, driver dependend low level stuff, ...). - - - - Currently, option `pdfa' sets and disables the following items: -\begin{itemize} - \item Enabled annotation flags: Print, NoZoom, NoRotate [PDF/A 6.5.3]. - \item Disabled annotation flags: Hidden, Invisible, NoView [PDF/A 6.5.3]. - \item Disabled: Launch action (\href{run:...} [PDF/A 6.6.1]. - \item Restricted: Named actions (\Acrobatmenu: NextPage, PrevPage, - FirstPage, LastPage) [PDF/A 6.6.1]. - \item Many things are disabled in PDF formulars: - \begin{itemize} - \item JavaScript actions [PDF/A 6.6.1] - \item Trigger events (additional actions) [PDF/A 6.6.2] - \item Push button (because of JavaScript) - \item Interactive Forms: Flag NeedAppearances is the default `false' - (Because of this, hyperref's implementation of Forms looks ugly). - [PDF/A 6.9] - \end{itemize} -\end{itemize} - - - - The default value of the new option `pdfa' is `false'. It influences - the loading of the package and cannot be changed after hyperref is - loaded (\verb|\usepackage{hyperref}|). - - - -\subsection{Option `linktoc' added} - - The new option `linktoc' allows more control which part - of an entry in the table of contents is made into a link: -\begin{itemize} - \item `linktoc=none' (no links) - \item `linktoc=section' (default behaviour, same as `linktocpage=false') - \item `linktoc=page' (same as `linktocpage=true') - \item `linktoc=all' (both the section and page part are links) -\end{itemize} - -\subsection{Option `pdfnewwindow' changed} - - Before 6.77b: -\begin{itemize} - \item pdfnewwindow=true $\rightarrow$ /NewWindow true - \item pdfnewwindow=false $\rightarrow$ (absent) - \item unused pdfnewwindow $\rightarrow$ (absent) -\end{itemize} - Since 6.77b: -\begin{itemize} - \item pdfnewwindow=true $\rightarrow$ /NewWindow true - \item pdfnewwindow=false $\rightarrow$ /NewWindow false - \item pdfnewwindow={} $\rightarrow$ (absent) - \item unused pdfnewwindow $\rightarrow$ (absent) -\end{itemize} - - - - Rationale: There is a difference between setting to `false' - and an absent entry. In the former case the new document - replaces the old one, in the latter case the PDF viewer - application should respect the user preference. - - -\subsection{Flag options for PDF forms} - - PDF form field macros (\verb|\TextField|, \verb|\CheckBox|, ...) support - boolean flag options. The option name is the lowercase - version of the names in the PDF specification (1.7): - - \url{http://www.adobe.com/devnet/pdf/pdf_reference.html} - - \url{http://www.adobe.com/devnet/acrobat/pdfs/pdf_reference.pdf} - - Options (convert to lowercase) except flags in square brackets: - -\begin{itemize} - \item Table 8.16 Annotation flags (page 608): - -{\obeylines - 1 Invisible - 2 Hidden (PDF 1.2) - 3 Print (PDF 1.2) - 4 NoZoom (PDF 1.3) - 5 NoRotate (PDF 1.3) - 6 NoView (PDF 1.3) - [7 ReadOnly (PDF 1.3)] ignored for widget annotations, see table 8.70 - 8 Locked (PDF 1.4) - 9 ToggleNoView (PDF 1.5) - 10 LockedContents (PDF 1.7) -} - \item Table 8.70 Field flags common to all field types (page 676): - -{\obeylines - 1 ReadOnly - 2 Required - 3 NoExport -} - \item Table 8.75 Field flags specific to button fields (page 686): - -{\obeylines - 15 NoToggleToOff (Radio buttons only) - 16 Radio (set: radio buttons, clear: check box, pushbutton: clear) - 17 Pushbutton - 26 RadiosInUniso (PDF 1.5) -} - \item Table 8.77 Field flags specific to text fields (page 691): - -{\obeylines - 13 Multiline - 14 Password - 21 FileSelect (PDF 1.4) - 23 DoNotSpellCheck (PDF 1.4) - 24 DoNotScroll (PDF 1.4) - 25 Comb (PDF 1.5) - 26 RichText (PDF 1.5) -} - \item Table 8.79 Field flags specific to choice fields (page 693): - -{\obeylines - 18 Combo (set: combo box, clear: list box) - 19 Edit (only useful if Combo is set) - 20 (Sort) for authoring tools, not PDF viewers - 22 MultiSelect (PDF 1.4) - 23 DoNotSpellCheck (PDF 1.4) (only useful if Combo and Edit are set) - 27 CommitOnSelChange (PDF 1.5) -} - \item Table 8.86 Flags for submit-form actions (page 704): - -{\obeylines - [1 Include/Exclude] unsupported, use `noexport' (table 8.70) instead - 2 IncludeNoValueFields - [3 ExportFormat] handled by option `export' - 4 GetMethod - 5 SubmitCoordinates - [6 XFDF (PDF 1.4)] handled by option `export' - 7 IncludeAppendSaves (PDF 1.4) - 8 IncludeAnnotations (PDF 1.4) - [9 SubmitPDF (PDF 1.4)] handled by option `export' - 10 CanonicalFormat (PDF 1.4) - 11 ExclNonUserAnnots (PDF 1.4) - 12 ExclFKey (PDF 1.4) - 14 EmbedForm (PDF 1.5) -} -\end{itemize} - - New option `export' sets the export format of a submit action. - Valid values are (upper- or lowercase): -\begin{itemize} - \item FDF - \item HTML - \item XFDF - \item PDF (not supported by Acrobat Reader) -\end{itemize} - -\subsection{Option `pdfversion'} - - This is an experimental option. It notifies `hyperref' about - the intended PDF version. Currently this is used in code for - PDF forms (implementation notes 116 and 122 of PDF spec 1.7). - - - - Values: 1.2, 1.3, 1.4, 1.5, 1.6, 1.7. Values below 1.2 are not - supported, because most drivers expect higher PDF versions. - - - - The option must be used early, not after \verb|\usepackage{hyperref}|. - - - In theory this option should also set the PDF version, - but this is not generally supported. -\begin{itemize} - \item pdfTeX below 1.10a: unsupported. - pdfTeX $\ge$ 1.10a and < 1.30: \verb|\pdfoptionpdfminorversion| - pdfTeX $\ge$ 1.30: \verb|\pdfminorversion| - \item dvipdfm: configuration file, example: - TeX Live 2007, texmf/dvipdfm/config/config, entry `V 2'. - \item dvipdfmx: configuration file, example: - TeX Live 2007, texmf/dvipdfm/dvipdfmx.cfg, entry `V 4'. - \item Ghostscript: option -dCompatibilityLevel (this is set in - `ps2pdf12', `ps2pdf13', `ps2pdf14'). -\end{itemize} - - - The current PDF version is used as default if this version - can be detected (only pdfTeX $\ge$ 1.10a). Otherwise the lowest - version 1.2 is assumed. Thus `hyperref' tries to avoid PDF code - that breaks this version, but is free to use ignorable higher PDF - features. - - -\subsection{Field option `name'} - - Many form objects uses the label argument - for several purposes: -\begin{itemize} - \item Layouted label. - \item As name in HTML structures. -\end{itemize} - Code that is suitable for layouting with TeX can - break in the structures of the output format. - If option `name' is given, then its value is used - as name in the different output structures. Thus - the value should consist of letters only. - - -\subsection{Option `pdfencoding'} - - The PDF format allows two encodings for bookmarks and entries - in the information dictionary: PDFDocEncoding and Unicode - as UTF-16BE. Option \xoption{pdfencoding} selects between these encodings: -\begin{itemize} - \item \xoption{pdfdoc} uses PDFDocEncoding. It uses just one byte per character, - but the supported characters are limited (244 in PDF-1.7). - \item \xoption{unicode} sets Unicode. It is encoded as UTF-16BE. Two bytes - are used for most characters, surrogates need four bytes. - \item \xoption{auto} PDFDocEncoding if the string does not contain characters - outside the encoding (outside ascii if an unicode engine is used) - and Unicode otherwise. This option is normally no suited for the unicode engines. -\end{itemize} - - All drivers use \xoption{unicode} by default now. If another encoding should be forced, - it should be done in \verb|hypersetup|. - -\subsection{Color options/package hycolor} - - See documentation of package `hycolor'. - - -\subsection{Option pdfusetitle} - - If option pdfusetitle is set then hyperref tries to - derive the values for pdftitle and pdfauthor from - \verb|\title| and \verb|\author|. An optional argument for \verb|\title| and - \verb|\author| is supported (class amsart). - - -\subsection{Starred form of \textbackslash autoref} - - \verb|\autoref*| generates a reference without link as \verb|\ref*| or \verb|\pageref*|. - - -\subsection{Link border style} - - Links can be underlined instead of the default rectangle or - options \xoption{colorlinks}, \xoption{frenchlinks}. This is done by option - \verb|pdfborderstyle={/S/U/W 1}| - - Some remarks: - -\begin{itemize} - \item AR7/Linux seems to have a bug, that don't use the default - value \verb"1" for the width, but zero, thus that the underline - is not visible without \verb"/W 1". The same applies for - dashed boxes, eg.: - pdfborderstyle={/S/D/D[3 2]/W 1} - - \item 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) - - \item The border style is removed by - pdfborderstyle={} - This is automatically done if option colorlinks is enabled. - - \item Be aware that not all PDF viewers support this feature, not - even Acrobat Reader itself: - - Some support: - \begin{itemize} - \item AR7/Linux: \xoption{underline} and \xoption{dashed}, but the border width - must be given. - \item xpdf 3.00: \xoption{underline} and \xoption{dashed} - \end{itemize} - - Unsupported: - \begin{itemize} - \item AR5/Linux - \item ghostscript 8.50 - \end{itemize} -\end{itemize} - -\subsection{Option \xoption{bookmarksdepth}} - - The depth of the bookmarks can be controlled by the new - option \xoption{bookmarksdepth}. The option acts globally and - distinguishes three cases: -\begin{itemize} - \item \xoption{bookmarksdepth} without value - Then hyperref uses the current value of counter \xoption{tocdepth}. - This is the compatible behaviour and the default. - \item \verb"bookmarksdepth=", the value is number (also negative): - The depth for the bookmarks are set to this number. - \item \verb"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 \verb|\toclevel@|. - Examples: -\begin{verbatim} - \hypersetup{bookmarksdepth=paragraph} - \hypersetup{bookmarksdepth=4} % same as before - \hypersetup{bookmarksdepth} % counter "tocdepth" is used -\end{verbatim} -\end{itemize} - -\subsection{Option \xoption{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: -\begin{itemize} - \item pdfescapeform=false - Escaping for the formulars are disabled, this is - the compatibility behaviour, therefore this is the default. - \item 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. -\end{itemize} - -\subsection{Default driver setting} - - (hyperref $\ge$ 6.72s) - If no driver is given, hyperref tries its best to guess the - most suitable driver. Thus it loads \xoption{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 \xoption{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 \verb"hyperref.cfg": -\begin{verbatim} - \providecommand*{\Hy@defaultdriver}{hdvips} -\end{verbatim} - for dvips, or -\begin{verbatim} - \providecommand*{\Hy@defaultdriver}{hypertex} -\end{verbatim} - for the default behaviour of hyperref. - - See also the new option `driverfallback'. - -\subsection{Backref entries} - - Alternative interface for formatting of backref entries, example: - -\begin{verbatim} -\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 -} - -% The list of distinct entries can be further refined: -\renewcommand*{\backrefentrycount}[2]{% - % #1: the original backref entry - % #2: the count of citations of this entry, - % in case of duplicates greater than one - #1% - \ifnum#2>1 % - ~(#2)% - \fi -} - -\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} -\end{verbatim} - -\subsection{\textbackslash phantomsection} - -Set an anchor at this location. It is often used in conjunction -with \verb|\addcontentsline| for sectionlike things (index, bibliography, -preface). \verb|\addcontentsline| refers to the latest previous location -where an anchor is set. - -\begin{verbatim} - \cleardoublepage - \phantomsection - \addcontentsline{toc}{chapter}{\indexname} - \printindex -\end{verbatim} - -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. - - - -\section{Acrobat-specific behavior} -If you want to access the menu options of Acrobat Reader or Exchange, the following -macro is provided in the appropriate drivers: - -\begin{cmdsyntax} -\ci{Acrobatmenu}\verb|{|\emph{menuoption}\verb|}{|\emph{text}\verb|}| -\end{cmdsyntax} - -\noindent The \emph{text} is used to create a button which activates the appropriate \emph{menuoption}. The following table lists the option names you can use---comparison of this with the menus in Acrobat Reader or Exchange will show what they do. Obviously some are only appropriate to Exchange. - -\medskip -\begin{longtable}{@{}l>{\raggedright\arraybackslash}p{9cm}@{}} -File & Open, Close, Scan, Save, SaveAs, Optimizer:SaveAsOpt, Print, PageSetup, Quit \\ -File$\rightarrow$Import & ImportImage, ImportNotes, AcroForm:ImportFDF \\ -File$\rightarrow$Export & ExportNotes, AcroForm:ExportFDF \\ -File$\rightarrow$DocumentInfo & GeneralInfo, OpenInfo, FontsInfo, SecurityInfo, Weblink:Base, AutoIndex:DocInfo \\ -File$\rightarrow$Preferences & GeneralPrefs, NotePrefs, FullScreenPrefs, Weblink:Prefs, AcroSearch:Preferences(Windows) - or, AcroSearch:Prefs(Mac), Cpt:Capture \\ -Edit & Undo, Cut, Copy, Paste, Clear, SelectAll, Ole:CopyFile, TouchUp:TextAttributes, - TouchUp:FitTextToSelection, TouchUp:ShowLineMarkers, TouchUp:ShowCaptureSuspects, - TouchUp:FindSuspect, \\ - & Properties \\ -Edit$\rightarrow$Fields & AcroForm:Duplicate, AcroForm:TabOrder \\ -Document & Cpt:CapturePages, AcroForm:Actions, CropPages, RotatePages, InsertPages, ExtractPages, - ReplacePages, DeletePages, NewBookmark, SetBookmarkDest, CreateAllThumbs, - DeleteAllThumbs \\ -View & ActualSize, FitVisible, FitWidth, FitPage, ZoomTo, FullScreen, FirstPage, PrevPage, - NextPage, LastPage, GoToPage, GoBack, GoForward, SinglePage, OneColumn, TwoColumns, - ArticleThreads, PageOnly, ShowBookmarks, ShowThumbs \\ -Tools & Hand, ZoomIn, ZoomOut, SelectText, SelectGraphics, Note, Link, Thread, AcroForm:Tool, - Acro\_Movie:MoviePlayer, TouchUp:TextTool, Find, FindAgain, FindNextNote, - CreateNotesFile \\ -Tools$\rightarrow$Search & AcroSrch:Query, AcroSrch:Indexes, AcroSrch:Results, AcroSrch:Assist, AcroSrch:PrevDoc, - AcroSrch:PrevHit, AcroSrch:NextHit, AcroSrch:NextDoc \\ -Window & ShowHideToolBar, ShowHideMenuBar, ShowHideClipboard, Cascade, TileHorizontal, - TileVertical, CloseAll \\ -Help & HelpUserGuide, HelpTutorial, HelpExchange, HelpScan, HelpCapture, HelpPDFWriter, - HelpDistiller, HelpSearch, HelpCatalog, HelpReader, Weblink:Home \\ -Help(Windows) & About -\end{longtable} - -\section{PDF and HTML forms} -You must put your fields inside a \texttt{Form} environment (only one per file). - -There are six macros to prepare fields: - -\begin{cmdsyntax} -\ci{TextField}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}| -\end{cmdsyntax} - -\begin{cmdsyntax} -\ci{CheckBox}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}| -\end{cmdsyntax} - -\begin{cmdsyntax} -\ci{ChoiceMenu}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}{|\emph{choices}\verb|}| -\end{cmdsyntax} - -\begin{cmdsyntax} -\ci{PushButton}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}| -\end{cmdsyntax} - -\begin{cmdsyntax} -\ci{Submit}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}| -\end{cmdsyntax} - -\begin{cmdsyntax} -\ci{Reset}\verb|[|\emph{parameters}\verb|]{|\emph{label}\verb|}| -\end{cmdsyntax} - -The way forms and their labels are laid out is determined by: -\begin{cmdsyntax} -\ci{LayoutTextField}\verb|{|\emph{label}\verb|}{|\emph{field}\verb|}| -\end{cmdsyntax} - -\begin{cmdsyntax} -\ci{LayoutChoiceField}\verb|{|\emph{label}\verb|}{|\emph{field}\verb|}| -\end{cmdsyntax} - -\begin{cmdsyntax} -\ci{LayoutCheckField}\verb|{|\emph{label}\verb|}{|\emph{field}\verb|}| -\end{cmdsyntax} - -These macros default to \#1 \#2 - -What is actually shown in the field is determined by: -\begin{cmdsyntax} -\ci{MakeRadioField}\verb|{|\emph{width}\verb|}{|\emph{height}\verb|}| -\end{cmdsyntax} - -\begin{cmdsyntax} -\ci{MakeCheckField}\verb|{|\emph{width}\verb|}{|\emph{height}\verb|}| -\end{cmdsyntax} -\begin{cmdsyntax} -\ci{MakeTextField}\verb|{|\emph{width}\verb|}{|\emph{height}\verb|}| -\end{cmdsyntax} -\begin{cmdsyntax} -\ci{MakeChoiceField}\verb|{|\emph{width}\verb|}{|\emph{height}\verb|}| -\end{cmdsyntax} - -\begin{cmdsyntax} -\ci{MakeButtonField}\verb|{|\emph{text}\verb|}| -\end{cmdsyntax} - -These macros default to \verb|\vbox to #2{\hbox to #1{\hfill}\vfill}|, except the -last, which defaults to \#1; it is used for buttons, and the special \ci{Submit} and \ci{Reset} -macros. - -You may also want to redefine the following macros: -\begin{verbatim} -\def\DefaultHeightofSubmit{12pt} -\def\DefaultWidthofSubmit{2cm} -\def\DefaultHeightofReset{12pt} -\def\DefaultWidthofReset{2cm} -\def\DefaultHeightofCheckBox{0.8\baselineskip} -\def\DefaultWidthofCheckBox{0.8\baselineskip} -\def\DefaultHeightofChoiceMenu{0.8\baselineskip} -\def\DefaultWidthofChoiceMenu{0.8\baselineskip} -\def\DefaultHeightofText{\baselineskip} -\def\DefaultHeightofTextMultiline{4\baselineskip} -\def\DefaultWidthofText{3cm} -\end{verbatim} - -\subsection{Forms environment parameters} - -\smallskip -\begin{longtable}{@{}>{\ttfamily}l>{\itshape}lp{9cm}@{}} -action & URL & The URL that will receive the form data if a \textsf{Submit} button is included in the form \\ -encoding & name & The encoding for the string set to the URL; FDF-encoding is usual, and \texttt{html} is the only - valid value \\ -method & name & Used only when generating HTML; values can be \texttt{post} or \texttt{get} \\ -\end{longtable} - -\subsection{Forms optional parameters} -Note that all colors must be expressed as RGB triples, in the range 0..1 (i.e.\ \texttt{color=0 0 -0.5}) - -\smallskip -\begin{longtable}{@{}>{\ttfamily}ll>{\itshape}ll@{}} -accesskey & key & & (as per HTML) \\ -align & number & 0 & alignment within text field; 0 is left-aligned,\\* - & & & 1 is centered, 2 is right-aligned. \\ -altname & name & & alternative name,\\* - & & & the name shown in the user interface\\ -backgroundcolor & & & color of box \\ -bordercolor & & & color of border \\ -bordersep & & & box border gap \\ -borderwidth & & 1 & width of box border, the value is a dimension\\ - & & & or a number with default unit bp\\ -calculate & & & JavaScript code to calculate the value of the field \\ -charsize & dimen & & font size of field text \\ -checkboxsymbol & char & 4 (\ding{\number`4}) & symbol used for check boxes (ZapfDingbats), \\ -&&& the value is a character or \cs{ding}\verb|{|\texttt{\itshape number}\verb|}|, \\ -&&& see package \xpackage{pifont} from bundle \xpackage{psnfss} \\ -checked & boolean & false & whether option selected by default \\ -color & & & color of text in box \\ -combo & boolean & false & choice list is `combo' style \\ -default & & & default value \\ -disabled & boolean & false & field disabled \\ -format & & & JavaScript code to format the field \\ -height & dimen & & height of field box \\ -hidden & boolean & false & field hidden \\ -keystroke & & & JavaScript code to control the keystrokes on entry \\ -mappingname & name & & the mapping name to be used when exporting\\* - & & & the field data\\ -maxlen & number & 0 & number of characters allowed in text field \\ -menulength & number & 4 & number of elements shown in list \\ -multiline & boolean & false & whether text box is multiline \\ -name & name & & name of field (defaults to label) \\ -onblur & & & JavaScript code \\ -onchange & & & JavaScript code \\ -onclick & & & JavaScript code \\ -ondblclick & & & JavaScript code \\ -onfocus & & & JavaScript code \\ -onkeydown & & & JavaScript code \\ -onkeypress & & & JavaScript code \\ -onkeyup & & & JavaScript code \\ -onmousedown & & & JavaScript code \\ -onmousemove & & & JavaScript code \\ -onmouseout & & & JavaScript code \\ -onmouseover & & & JavaScript code \\ -onmouseup & & & JavaScript code \\ -onselect & & & JavaScript code \\ -password & boolean & false & text field is `password' style \\ -popdown & boolean & false & choice list is `popdown' style \\ -radio & boolean & false & choice list is `radio' style \\ -radiosymbol & char & H (\ding{\number`H}) & symbol used for radio fields (ZapfDingbats), \\ -&&& the value is a character or \cs{ding}\verb|{|\texttt{\itshape number}\verb|}|, \\ -&&& see package \xpackage{pifont} from bundle \xpackage{psnfss} \\ -readonly & boolean & false & field is readonly \\ -rotation & number & 0 & rotation of the widget annotation \\* - & & & (degree, counterclockwise, multiple of 90)\\ -tabkey & & & (as per HTML) \\ -validate & & & JavaScript code to validate the entry \\ -value & & & initial value \\ -width & dimen & & width of field box -\end{longtable} - -\section{Defining a new driver} -A hyperref driver has to provide definitions for eight macros: - -\smallskip -\noindent 1. \verb|\hyper@anchor| - -\noindent 2. \verb|\hyper@link| - -\noindent 3. \verb|\hyper@linkfile| - -\noindent 4. \verb|\hyper@linkurl| - -\noindent 5. \verb|\hyper@anchorstart| - -\noindent 6. \verb|\hyper@anchorend| - -\noindent 7. \verb|\hyper@linkstart| - -\noindent 8. \verb|\hyper@linkend| -\smallskip - -The draft option defines the macros as follows -\begin{verbatim} -\let\hyper@@anchor\@gobble -\gdef\hyper@link##1##2##3{##3}% -\def\hyper@linkurl##1##2{##1}% -\def\hyper@linkfile##1##2##3{##1}% -\let\hyper@anchorstart\@gobble -\let\hyper@anchorend\@empty -\let\hyper@linkstart\@gobbletwo -\let\hyper@linkend\@empty -\end{verbatim} - -\section{Special support for other packages} - -Package \xpackage{hyperref} aims to cooperate with other packages, but there are -several possible sources for conflict, such as - -\begin{itemize} - -\item Packages that manipulate the bibliographic mechanism. Peter -William's \xpackage{harvard} package is supported. However, the -recommended package is Patrick Daly's \xpackage{natbib} package that has -specific \xpackage{hyperref} hooks to allow reliable interaction. This -package covers a very wide variety of layouts and citation styles, all -of which work with \xpackage{hyperref}. - -\item Packages that typeset the contents of the \ci{label} and \ci{ref} -macros, such as \xpackage{showkeys}. Since the \xpackage{hyperref} package -redefines these commands, you must set \texttt{implicit=false} for these -packages to work. - -\item Packages that do anything serious with the index. -\end{itemize} - -The \xpackage{hyperref} package is distributed with variants on two useful -packages designed to work especially well with it. These are \xpackage{xr} -and \xpackage{minitoc}, which support crossdocument links using \hologo{LaTeX}'s -normal \cs{label}/\cs{ref} mechanisms and per-chapter tables of contents, -respectively. - - -\subsection{Package Compatibility} - -Currently only package loading orders are available: - - - -Note: hyperref loads package \xpackage{nameref} at \verb|\begin{document}|. -Sometimes this is too late, thus this package must be loaded -earlier. - - -\subsubsection{algorithm} -\begin{verbatim} - \usepackage{float} - \usepackage{hyperref} - \usepackage[chapter]{algorithm}% eg. -\end{verbatim} - -\subsubsection{amsmath} - - The environments equation and eqnarray are not supported too well. - For example, there might be spacing problems (eqnarray isn't recommended - anyway, see CTAN:info/l2tabu/, the situation for equation is unclear, - because nobody is interested in investigating). Consider using the - environments that package amsmath provide, e.g. gather for equation. - The environment equation can even redefined to use gather: - -\begin{verbatim} - \usepackage{amsmath} - \let\equation\gather - \let\endequation\endgather -\end{verbatim} - -\subsubsection{amsrefs} - - Package loading order: - -\begin{verbatim} - \usepackage{hyperref} - \usepackage{amsrefs} -\end{verbatim} - -\subsubsection{arydshln, longtable} - - Package longtable must be put before hyperref and arydshln, - hyperref after arydshln generates an error, thus the - resulting package order is then: - -\begin{verbatim} - \usepackage{longtable} - \usepacakge{hyperref} - \usepackage{arydshln} -\end{verbatim} - -\subsubsection{babel/magyar.ldf} - - The old version 2005/03/30 v1.4j will not work. - You need at least version 1.5, maintained by P\'eter Szab\'o, - see CTAN:language/hungarian/babel/. - - -\subsubsection{babel/spanish.ldf} - - Babel's spanish.ldf redefines `\verb|\.|' to support `\verb|\...|'. - In bookmarks (\verb|\pdfstringdef|) only `\verb|\.|' is supported. - If `\verb|\...|' is needed, - \verb|\texorpdfstring{\...}{\dots}| - can be used instead. - - -\subsubsection{bibentry} - - Workaround: - -\begin{verbatim} - \makeatletter - \let\saved@bibitem\@bibitem - \makeatother - - \usepackage{bibentry} - \usepackage{hyperref} - - \begin{document} - - \begingroup - \makeatletter - \let\@bibitem\saved@bibitem - \nobibliography{database} - \endgroup -\end{verbatim} - -\subsubsection{bigfoot} - - Hyperref does not support package `bigfoot'. And package - `bigfoot' does not support hyperref's footnotes and disables - them (hyperfootnotes=false). - - -\subsubsection{chappg} - - Package `chappg' uses \verb|\@addtoreset| that is redefined by `hyperref'. - The package order is therefore: - -\begin{verbatim} - \usepackage{hyperref} - \usepackage{chappg} -\end{verbatim} - -\subsubsection{cite} - - This is from Mike Shell: - cite.sty cannot currently be used with hyperref. - However, I can do a workaround via: - -\begin{verbatim} - \makeatletter - \def\NAT@parse{\typeout{This is a fake Natbib command to fool Hyperref.}} - \makeatother - - \usepackage[hypertex]{hyperref} -\end{verbatim} - - 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). - - -\subsubsection{count1to} - - Package `count1to' adds several \verb|\@addtoreset| commands that confuse - `hyperref'. Therefore \verb|\theH<...>| has to be fixed: - -\begin{verbatim} - \usepackage{count1to} - \AtBeginDocument{% *after* \usepackage{count1to} - \renewcommand*{\theHsection}{\theHchapter.\arabic{section}}% - \renewcommand*{\theHsubsection}{\theHsection.\arabic{subsection}}% - \renewcommand*{\theHsubsubsection}{\theHsubsection.\arabic{subsubsection}}% - \renewcommand*{\theHparagraph}{\theHsubsubsection.\arabic{paragraph}}% - \renewcommand*{\theHsubparagraph}{\theHparagraph.\arabic{subparagraph}}% - } -\end{verbatim} - -\subsubsection{dblaccnt} - - pd1enc.def or puenc.def should be loaded before: -\begin{verbatim} - \usepackage{hyperref} - \usepackage{dblaccnt} -\end{verbatim} - or see entry for \xoption{vietnam}. - - -\subsubsection{easyeqn} - Not compatible, breaks. - - -\subsubsection{ellipsis} - - This packages redefines \verb|\textellipsis| - after package hyperref (pd1enc.def/puenc.def should be loaded before): -\begin{verbatim} - \usepackage{hyperref} - \usepackage{ellipsis} -\end{verbatim} - -\subsubsection{float} -\begin{verbatim} - \usepackage{float} - \usepackage{hyperref} -\end{verbatim} -\begin{itemize} - \item Several \verb|\caption| commands are not supported inside one float object. - \item Anchor are set at top of the float object, if its style is controlled - by float.sty. -\end{itemize} - -\subsubsection{endnotes} - Unsupported. - -\subsubsection{foiltex} - Update to version 2008/01/28 v2.1.4b: - Since version 6.77a hyperref does not hack into \verb|\@begindvi|, - it uses package `atbegshi' instead, that hooks into \verb|\shipout|. - Thus the patch of `foils.cls' regarding hyperref is now obsolete - and causes an undefined error message about \verb|\@hyperfixhead|. - This is fixed in FoilTeX 2.1.4b. - - -\subsubsection{footnote} - - This package is not supported, you have to disable hyperref's footnote - support by using option \verb"hyperfootnotes=false". - - -\subsubsection{geometry} - - Driver `dvipdfm' and program `dvipdfm' might generate a warning: - Sorry. Too late to change page size - Then prefer the program `dvipdfmx' or use one of the following - workarounds to move the \verb|\special| of geometry to an earlier - location: - -\begin{verbatim} - \documentclass[dvipdfm]{article}% or other classes - \usepackage{atbegshi} - \AtBeginDocument{% - \let\OrgAtBeginDvi\AtBeginDvi - \let\AtBeginDvi\AtBeginShipoutFirst - } - \usepackage[ - paperwidth=170mm, - paperheight=240mm - ]{geometry} - \AtBeginDocument{% - \let\AtBeginDvi\OrgAtBeginDvi - } - \usepackage{hyperref} - - or - - \documentclass[dvipdfm]{article}% or other classes - \usepackage{atbegshi} - \let\AtBeginDvi\AtBeginShipoutFirst - \usepackage[ - paperwidth=170mm, - paperheight=240mm - ]{geometry} - \usepackage{hyperref} -\end{verbatim} - -\subsubsection{IEEEtran.cls} - - version $\ge$ V1.6b (because of \verb|\@makecaption|, see ChangeLog) - - -\subsubsection{index} - - version $\ge$ 1995/09/28 v4.1 (because of \verb|\addcontentsline| redefinition) - - -\subsubsection{lastpage} - - Compatible. - - -\subsubsection{linguex} -\begin{verbatim} - \usepackage{hyperref} - \usepackage{linguex} -\end{verbatim} - -\subsubsection{ltabptch} -\begin{verbatim} - \usepackage{longtable} - \usepackage{ltabptch} - \usepackage{hyperref} -\end{verbatim} - -\subsubsection{mathenv} - - Unsupported. - - - - Both `mathenv' and `hyperref' messes around with - environment `eqnarray'. You can load `mathenv' after - `hyperref' to avoid an error message. But \verb|\label| - will not work inside environment `eqnarray' properly, - for example. - - -\subsubsection{minitoc-hyper} - - This package is obsolete, use the uptodate original - package minitoc instead. - - -\subsubsection{multind} -\begin{verbatim} - \usepackage{multind} - \usepackage{hyperref} -\end{verbatim} - -\subsubsection{natbib} -\begin{verbatim} - \usepackage{natbib} - \usepackage{hyperref} -\end{verbatim} - -\subsubsection{nomencl} -Example for introducing links for the page numbers: -\begin{verbatim} - \renewcommand*{\pagedeclaration}[1]{\unskip, \hyperpage{#1}} -\end{verbatim} - - -For equations the following might work: -\begin{verbatim} - \renewcommand*{\eqdeclaration}[1]{% - \hyperlink{equation.#1}{(Equation~#1)}% - } - But the mapping from the equation number to the anchor name - is not available in general. -\end{verbatim} - -\subsubsection{parskip} -\begin{verbatim} - \usepackage{parskip} - \usepackage{hyperref}[2012/08/20] -\end{verbatim} - - - Both packages want to redefine \verb|\@starttoc|. - - -\subsubsection{prettyref} -\begin{verbatim} -%%% 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 %%% - \end{verbatim} - -\subsubsection{ntheorem} -\begin{verbatim} - 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, ...). -\end{verbatim} - -\subsubsection{setspace} -\begin{verbatim} - \usepackage{setspace} - \usepackage{hyperref} -\end{verbatim} - -\subsubsection{sidecap} -\begin{verbatim} - Before 2002/05/24 v1.5h: - \usepackage{nameref} - \usepackage{hyperref} - \usepackage{sidecap} -\end{verbatim} - -\subsubsection{subfigure} -\begin{verbatim} - 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? -\end{verbatim} - -\subsubsection{titleref} -\begin{verbatim} - \usepackage{nameref} - \usepackage{titleref}% without usetoc - \usepackage{hyperref} -\end{verbatim} - -\subsubsection{tabularx} - - Linked footnotes are not supported inside environment `tabularx', - because they uses the optional argument of \verb|\footnotetext|, see - section `Limitations'. Before version 2011/09/28 6.82i - hyperref had disabled footnotes entirely by `hyperfootnotes=false'. - - -\subsubsection{titlesec} - - \xpackage{nameref} supports titlesec, but hyperref does not - (unsolved is the anchor setting, missing with unnumbered - section, perhaps problems with page breaks with numbered ones). - - -\subsubsection{ucs/utf8x.def} - - The first time a multibyte UTF8 sequence is called, it - does some calculations and stores the result in a macro - for speeding up the next calls of that UTF8 sequence. - However this makes the first call non-expandable and - will break if used in information entries or bookmarks. - Package \xpackage{ucs} offers \verb|\PrerenderUnicode| or \verb|\PreloadUnicodePage| - to solve this: -\begin{verbatim} - \usepackage{ucs} - \usepackage[utf8x]{inputenc} - \usepackage{hyperref}% or with option unicode - \PrerenderUnicode{^^c3^^b6}% or \PrerenderUnicodePage{1} - \hypersetup{pdftitle={Umlaut example: ^^c3^^b6}} -\end{verbatim} - The notation with two carets avoids trouble with 8-bit bytes - for the README file, you can use the characters directly. - - -\subsubsection{varioref} - There are too many problems with varioref. Nobody has time to - sort them out. Therefore this package is now unsupported. - - - Perhaps you are lucky and some of the features of varioref works - with the following loading order: -\begin{verbatim} - \usepackage{nameref} - \usepackage{varioref} - \usepackage{hyperref} -\end{verbatim} - - - Also some babel versions can be problematic. For example, - 2005/05/21 v3.8g contains a patch for varioref that breaks - the hyperref support for varioref. - - - - Also unsupported: -\begin{itemize} -\item \verb|\Ref|, \verb|\Vref| do not uppercase the first letter. -\item \verb|\vpageref[]{...}| - On the same page a previous space is not suppressed. -\end{itemize} - -\subsubsection{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): - -\begin{verbatim} - \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} -\end{verbatim} - -\subsubsection{vietnam} -\begin{verbatim} - % pd1enc.def should be loaded before package dblaccnt: - \usepackage[PD1,OT1]{fontenc} - \usepackage{vietnam} - \usepackage{hyperref} -\end{verbatim} - -\subsubsection{XeTeX} - - Default for the encoding of bookmarks is \verb|pdfencoding=unicode|. - That means the strings are always treated as unicode strings. - If \verb|auto| or \verb|pdfdoc| is forced it applies only - if the string restricts to the printable ASCII set, - The reason is that the \verb|\special| does not support PDFDocEncoding. - - In older versions hyperref contained special conversion code from - UTF-16BE back to UTF-8 in a number of places for - xetex to avoid the xdvipdfmx warning - - \verb"Failed to convert input string to UTF16..." - - This is no longer needed with a current xdvipdfmx, so this code has - been removed. \verb|\csname HyPsd@XeTeXBigCharstrue\endcsname| should no - longer be used. - - -\section[Limitations]{Limitations% -\footnote{This section moved from the README file, needs more integration into the manual}} -\subsection{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: -\begin{itemize} -\item For long section or caption titles in the table of contents - or list of figures/tables option \xoption{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 overfull \verb|\hbox| - warning. -\item ``\verb|\url|''s are caught by package \xpackage{breakurl}. -\item The option \xoption{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 - \verb|\url|. (See thread ``hyperref.sty, breaklinks and url.sty 3.2'' - in comp.text.tex 2005-09). -\end{itemize} - -\subsection{Links across pages} - - In general they have problems: -\begin{itemize} - \item Some driver doesn't support them at all (see above). - \item The driver allows it, but the link result might include - the footer and/or header, or an error message can - occur sometimes. -\end{itemize} - -\subsection{Footnotes} - - LaTeX allows the separation of the footnote mark and the - footnote text (\verb|\footnotemark|, \verb|\footnotetext|). This interface - might be enough for visual typesetting. But the relation between - \verb|\footnotemark| to \verb|\footnotetext| is not as strong as \verb|\ref| to \verb|\label|. - Therefore it is not clear in general which \verb|\footnotemark| references - which \verb|\footnotetext|. But that is necessary to implement hyperlinking. - Thus the implementation of hyperref does not support the optional - argument of \verb|\footnotemark| and \verb|\footnotetext|. - - -\section[Hints]{Hints% -\footnote{This section moved from the README file, needs more integration into the manual}} - -\subsection{Spaces in option values} - - Unhappily LaTeX strips spaces from options if they are given - in \verb|\documentclass| or \verb|\usepackage| (or \verb|\RequirePackage|), e.g.: -\begin{verbatim} - \usepackage[pdfborder=0 0 1]{hyperref} -\end{verbatim} - Package hyperref now gets -\begin{verbatim} - pdfborder=001 -\end{verbatim} - and the result is an invalid PDF file. - As workaround braces can be used: -\begin{verbatim} - \usepackage[pdfborder={0 0 1}]{hyperref} -\end{verbatim} - Some options can also be given in \verb|\hypersetup| -\begin{verbatim} - \hypersetup{pdfborder=0 0 1} -\end{verbatim} - In \verb|\hypersetup| the options are directly processed as key value - options (see package keyval) without space stripping in the value part. - - - - Alternatively, LaTeX's option handling system can be adapted - to key value options by one of the packages \xpackage{kvoptions-patch} - (from project \xpackage{kvoptions}) or \xpackage{xkvltxp} (from project \xpackage{xsetkeys}). - - -\subsection{Index with makeindex} -\begin{itemize} - \item Package hyperref adds \verb|\hyperpage| commands by the encap - mechanism (see documentation of Makeindex), - if option hyperindex is set (default). - \verb|\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 \verb|\frontmatter|, \verb|\romannumbering|, ...), - then the page anchors are not unique. Therefore option - \verb"plainpages=false" is recommended. - \item 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 - \verb|\hyperpage| command. With logical markup this situation - can easily be solved: -\begin{verbatim} - \usepackage{makeidx} - \makeindex - \usepackage[hyperindex]{hyperref} - \newcommand*{\main}[1]{\textbf{\hyperpage{#1}}} - ... - \index{Some example|main} -\end{verbatim} - \item Scientic Word/Scientific WorkPlace users can use - package robustindex with hyperindex=false. - \item Other encap characters can be set by option \xoption{encap}. - Example for use of ``?'': -\begin{verbatim} - \usepackage[encap=?]{hyperref} -\end{verbatim} - \item Another possibility is the insertion of \verb|\hyperpage| by - a style file for makeindex. For this case, hyperref's - insertion will be disabled by \verb"hyperindex=false". - \verb|\hyperpage| will be defined regardless of setting of hyperindex. -\begin{verbatim} -%%% 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 %%% -\end{verbatim} -\end{itemize} - -\subsection{Warning \texttt{"bookmark level for unknown defaults to 0"}} - - Getting rid of it: -\begin{verbatim} -\makeatletter -\providecommand*{\toclevel@}{0} -\makeatother -\end{verbatim} - -\subsection{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 case, try package \xpackage{hypcap} that implements - a method to circumvent the problem. - - -\subsection{Additional unicode characters in bookmarks and pdf information entries:} -\begin{verbatim} -\documentclass[pdftex]{article} -\usepackage[unicode]{hyperref} -\end{verbatim} - -Support for additional unicode characters: - - Example: \verb|\.{a}| and \verb|\d{a}| - - 1. Get a list with unicode data, eg: - - http://www.unicode.org/Public/UNIDATA/UnicodeData.txt - - 2. Identify the characters (\verb|\.{a}|, \verb|\d{a}|): -\begin{verbatim} - 0227;LATIN SMALL LETTER A WITH DOT ABOVE;... - 1EA1;LATIN SMALL LETTER A WITH DOT BELOW;... -\end{verbatim} - - 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.) - -\begin{verbatim} - 0227 -> \002\047 - 1EA1 -> \036\241 -\end{verbatim} - - 4. Transform into a form understood by hyperref: - - Hyperref must know where the first byte starts, - this is marked by \verb"9" (8 and 9 cannot occur in - octal numbers): - -\begin{verbatim} - \002\047 -> \9002\047 - \036\241 -> \9036\241 -\end{verbatim} - - Optional: \verb"8" is used for abbreviations: - -\begin{verbatim} - \900 = \80, \901 = \81, \902 = \82, ... - - \9002\047 -> \82\047 -\end{verbatim} - - 5. Declare the character with LaTeX: - -\begin{verbatim} -\DeclareTextCompositeCommand{\.}{PU}{a}{\82\047} -\DeclareTextCompositeCommand{\d}{PU}{a}{\9036\241} - -\begin{document} -\section{\={a}, \d{a}, \'{a}, \.{a}} -\end{document} - \end{verbatim} - -\subsection{Footnotes} - - The footnote support is rather limited. It is beyond the scope - to use \verb|\footnotemark| and \verb|\footnotetext| out of order or reusing - \verb|\footnotemark|. Here you can either disable hyperref's footnote - support by \verb"hyperfootnotes=false" or fiddle with internal macros, - nasty examples: - -\begin{verbatim} -\documentclass{article} -\usepackage{hyperref} -\begin{document} -Hello% -\footnote{The first footnote} -World% -\addtocounter{footnote}{-1}% -\addtocounter{Hfootnote}{-1}% -\footnotemark. -\end{document} - - or - -\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} -\end{verbatim} - -\subsection{Subordinate counters} - - Some counters do not have unique values and require the value - of other counters to be unique. For example, sections or figures - might be numbered within chapters or \verb|\newtheorem| is used with - an optional counter argument. Internally LaTeX uses \verb|\@addtoreset| - to reset a counter in dependency to another counter. Package - hyperref hooks into \verb|\@addtoreset| to catch this situation. - Also \verb|\numberwithin| of package amsmath is caught by hyperref. - - - - However, if the definition of subordinate counters take place - before hyperref is loaded, the old meaning of \verb|\@addtoreset| is - called without hyperref's additions. Then the companion counter - macro \verb|\theH| can be redefined accordingly. Or move the - definition of subordinate counters after hyperref is loaded. - - Example for \verb|\newtheorem|, problematic case: -\begin{verbatim} - \newtheorem{corA}{CorollaryA}[section] - \usepackage{hyperref} -\end{verbatim} - Solution a) -\begin{verbatim} - \usepackage{hyperref} - \newtheorem{corA}{CorollaryA}[section} -\end{verbatim} - Solution b) -\begin{verbatim} - \newtheorem{corA}{CorollaryA}[section] - \usepackage{hyperref} - \newcommand*{\theHcorA}{\theHsection.\number\value{corA}} -\end{verbatim} - -\section{History and acknowledgments} - -The original authors of \textsf{hyperbasics.tex} and -\textsf{hypertex.sty}, from which this package descends, are Tanmoy -Bhattacharya and Thorsten Ohl. Package \xpackage{hyperref} -started as a simple port of their work to \hologo{LaTeXe} standards, but -eventually I rewrote nearly everything, because I didn't understand a -lot of the original, and was only interested in getting it to work with -\hologo{LaTeX}. I would like to thank Arthur Smith, Tanmoy Bhattacharya, Mark -Doyle, Paul Ginsparg, David Carlisle, T.\ V.\ Raman and Leslie Lamport -for comments, requests, thoughts and code to get the package into its -first useable state. Various other people are mentioned at the point in -the source where I had to change the code in later versions because of -problems they found. - -Tanmoy found a great many of the bugs, and (even better) often provided -fixes, which has made the package more robust. The days spent on -Rev\TeX\ are entirely due to him! The investigations of Bill Moss -into the later versions including -native PDF support uncovered a good many bugs, and his testing is -appreciated. Hans Hagen provided a lot of -insight into PDF. - -Berthold Horn provided help, encouragement and sponsorship for the -\textsf{dvipsone} and \textsf{dviwindo} drivers. Sergey Lesenko provided -the changes needed for \textsf{dvipdf}, and \Hanh{} supplied all the -information needed for \textsf{pdftex}. Patrick Daly kindly updated his -\xpackage{natbib} package to allow easy integration with -\xpackage{hyperref}. Michael Mehlich's \xpackage{hyper} package (developed -in parallel with \textsf{hyperref}) showed me solutions for some -problems. Hopefully the two packages will combine one day. - -The forms creation section owes a great deal to: T.\ V.\ Raman, for -encouragement, support and ideas; Thomas Merz, whose book \emph{Web -Publishing with Acrobat/PDF} provided crucial insights; D.\ P.\ Story, -whose detailed article about pdfmarks and forms solved many practical -problems; and Hans Hagen, who explained how to do it in \textsf{pdftex}. - -Steve Peter recreated the manual source in July 2003 after it had been -lost. - -Especial extra thanks to David Carlisle for the \xpackage{backref} module, -the ps2pdf and dviwindo support, frequent general rewrites of my bad -code, and for working on changes to the \xpackage{xr} package to suit -\xpackage{hyperref}. - -\begingroup - \makeatletter - \let\chapter=\section - % subsections goes into bookmarks but not toc - \hypersetup{bookmarksopenlevel=1} - \addtocontents{toc}{\protect\setcounter{tocdepth}{1}} - % The \section command acts as \subsection. - % Additionally the title is converted to lowercase except - % for the first letter. - \def\section{% - \let\section\lc@subsection - \lc@subsection - } - \def\lc@subsection{% - \@ifstar{\def\mystar{*}\lc@sec}% - {\let\mystar\@empty\lc@sec}% - } - \def\lc@sec#1{% - \lc@@sec#1\@nil - } - \def\lc@@sec#1#2\@nil{% - \begingroup - \def\a{#1}% - \lowercase{% - \edef\x{\endgroup - \noexpand\subsection\mystar{\a#2}% - }% - }% - \x - } - \include{fdl} -\endgroup - -\end{document} diff --git a/Master/texmf-dist/source/latex/hyperref/hluatex.dtx b/Master/texmf-dist/source/latex/hyperref/hluatex.dtx index b70a38a86a9..91f9abc0061 100644 --- a/Master/texmf-dist/source/latex/hyperref/hluatex.dtx +++ b/Master/texmf-dist/source/latex/hyperref/hluatex.dtx @@ -1,10 +1,10 @@ % \iffalse % Source File: hluatex.dtx -% 2021-02-04 v7.00g +% 2021-02-07 v7.00h % % Copyright % 2016-2019 Oberdiek Package Support Group -% 2019-2020 The LaTeX3 Project +% 2019-2020 The LaTeX Project % https://github.com/latex3/hyperref/issues%% % % Derived from hpdftex.def @@ -19,7 +19,7 @@ \GetFileInfo{hluatex.def}% \title{hluatex.def} \date{}% - \author{Maintained by The \LaTeX3 Project\\% + \author{Maintained by The \LaTeX\ Project\\% \texttt{https://github.com/latex3/hyperref/issues}% } \maketitle @@ -31,7 +31,7 @@ % % \begin{macrocode} %<*luatex> -%% 2021-02-04 v7.00g +%% 2021-02-07 v7.00h %% force unicode encoding, see issue #101 %% code mostly copied from hxetex.def \HyPsd@LoadUnicode diff --git a/Master/texmf-dist/source/latex/hyperref/hyperref.dtx b/Master/texmf-dist/source/latex/hyperref/hyperref.dtx index 3e84e320ab9..5ab411463a2 100644 --- a/Master/texmf-dist/source/latex/hyperref/hyperref.dtx +++ b/Master/texmf-dist/source/latex/hyperref/hyperref.dtx @@ -4,7 +4,7 @@ %% 1995-2001 Sebastian Rahtz, with portions written by David Carlisle and Heiko Oberdiek, %% 2001-2015 Heiko Oberdiek. %% 2016-2019 Oberdiek Package Support Group -%% 2019-2021 LaTeX3 Project +%% 2019-2021 LaTeX Project %% https://github.com/latex3/hyperref/issues %% %% This file is part of the `Hyperref Bundle'. @@ -20,7 +20,7 @@ %% %% This work has the LPPL maintenance status `maintained'. %% -%% The Current Maintainer of this work is the LaTeX3 Project. +%% The Current Maintainer of this work is the LaTeX Project. %% %% The list of all files belonging to the `Hyperref Bundle' is %% given in the file `manifest.txt'. @@ -51,7 +51,7 @@ %\ProvidesFile{puarenc.def} %\ProvidesFile{psdextra.def} %\ProvidesFile{hyperref-langpatches.def} -% [2021-02-04 v7.00g % +% [2021-02-07 v7.00h % % Hypertext links for LaTeX] % Dummy hyperref (SR)] % Hyperref documentation driver file] @@ -124,7 +124,7 @@ \title{Hypertext marks in \LaTeX}% \author{Sebastian Rahtz (deceased)\\% Heiko Oberdiek (inactive)\\% - The \LaTeX3 Project\\% + The \LaTeX\ Project\\% \texttt{https://github.com/latex3/hyperref/issues}}% % \date{processed \today}% \date{\filedate\space\fileversion}% @@ -20966,7 +20966,9 @@ \DeclareTextCommand{\v}{PU}[1]{#1\83\014}% U+030C % U+030F COMBINING DOUBLE GRAVE ACCENT; dblgravecmb \DeclareTextCommand{\G}{PU}[1]{#1\83\017}% U+030F +\ifx\CYRDZE\@undefined \else \DeclareTextCommand{\C}{PU}[1]{#1\83\017}% U+030F +\fi % U+0311 COMBINING INVERTED BREVE; breveinvertedcmb \DeclareTextCommand{\textinvbreve}{PU}[1]{#1\83\021}% U+0311 \DeclareTextCommand{\newtie}{PU}[1]{#1\83\021}% U+0311 @@ -22305,8 +22307,9 @@ % \end{macrocode} % % \subsubsection{Greek and Coptic: U+0370 to U+03FF} -% +% Greek is only loaded if \cs{textBeta} is defined. % \begin{macrocode} +\ifx\textBeta\@undefined \else % U+0374 GREEK NUMERAL SIGN; numeralsigngreek \DeclareTextCommand{\textnumeralsigngreek}{PU}{\83\164}% U+0374 \DeclareTextCommand{\textdexiakeraia}{PU}{\83\164}% U+0374 @@ -22488,13 +22491,16 @@ % U+03F6 GREEK REVERSED LUNATE EPSILON SYMBOL; % \backepsilon (AmS) \DeclareTextCommand{\textbackepsilon}{PU}{\83\366}% U+03F6 +\fi % \end{macrocode} % % \subsubsection{Cyrillic: U+0400 to U+04FF} % % Thanks to Vladimir Volovich (\Email{vvv@vvv.vsu.ru}) for % the help with the Cyrillic glyph names. +% Cyrillic only loaded if \cs{CYRDZE} is defined. % \begin{macrocode} +\ifx\CYRDZE\@undefined \else % U+0400 CYRILLIC CAPITAL LETTER IE WITH GRAVE \DeclareTextCompositeCommand{\`}{PU}{\CYRE}{\84\000}% U+0400 % U+0401 CYRILLIC CAPITAL LETTER IO; Iocyrillic, *afii10023 @@ -23030,6 +23036,7 @@ \DeclareTextCommand{\CYRHHK}{PU}{\84\374}% U+04FC % U+04FD CYRILLIC SMALL LETTER HA WITH HOOK \DeclareTextCommand{\cyrhhk}{PU}{\84\375}% U+04FD +\fi % \end{macrocode} % |\84\376|: U+04FE CYRILLIC CAPITAL LETTER HA WITH STROKE\\ % |\84\377|: U+04FF CYRILLIC SMALL LETTER HA WITH STROKE @@ -23037,7 +23044,9 @@ % \subsubsection{Hebrew: U+0590 to U+05FF} % % Macro names are taken from \texttt{he8enc.def}. +% hebrew is only loaded if \cs{hebdalet} is defined % \begin{macrocode} +\ifx\hebdalet\@undefined\else % U+05C3 HEBREW PUNCTUATION SOF PASUQ \DeclareTextCommand{\sofpasuq}{PU}{\85\303}% U+05C3 % U+05D0 HEBREW LETTER ALEF @@ -23101,6 +23110,7 @@ \DeclareTextCommand{\vavyod}{PU}{\85\361}% U+05F1 % U+05F2 HEBREW LIGATURE YIDDISH DOUBLE YOD \DeclareTextCommand{\doubleyod}{PU}{\85\362}% U+05F2 +\fi % \end{macrocode} % % \subsubsection{Thai: U+0E00 to U+0E7F} diff --git a/Master/texmf-dist/source/latex/hyperref/hyperref.ins b/Master/texmf-dist/source/latex/hyperref/hyperref.ins index d8cc5275b1a..43b531fba5e 100644 --- a/Master/texmf-dist/source/latex/hyperref/hyperref.ins +++ b/Master/texmf-dist/source/latex/hyperref/hyperref.ins @@ -7,7 +7,7 @@ %% 1995-2001 Sebastian Rahtz, with portions written by David Carlisle and Heiko Oberdiek %% 2001-2015 Heiko Oberdiek %% 2016-2019 Oberdiek Package Support Group -%% 2019-2021 LaTeX3 Project +%% 2019-2021 LaTeX Project %% https://github.com/latex3/hyperref/issues %% %% This file is part of the `Hyperref Bundle'. diff --git a/Master/texmf-dist/source/latex/hyperref/nameref.dtx b/Master/texmf-dist/source/latex/hyperref/nameref.dtx index ec02e2eceb2..adc41b8fdcb 100644 --- a/Master/texmf-dist/source/latex/hyperref/nameref.dtx +++ b/Master/texmf-dist/source/latex/hyperref/nameref.dtx @@ -4,7 +4,7 @@ %% 2000 Sebastian Rahtz, Heiko Oberdiek %% 2001-2012 Heiko Oberdiek %% 2016-2019 Oberdiek Package Suport Group -%% 2019-2021 The LaTeX3 Project +%% 2019-2021 The LaTeX Project %% https://github.com/latex3/hyperref/issues %% %% This file is part of the `Hyperref Bundle'. @@ -20,7 +20,7 @@ %% %% This work has the LPPL maintenance status `maintained'. %% -%% The Current Maintainer of this work is The LaTeX3 Project. +%% The Current Maintainer of this work is The LaTeX Project. %% %% The list of all files belonging to the `Hyperref Bundle' is %% given in the file `manifest.txt'. @@ -57,7 +57,7 @@ }% \author{Sebastian Rahtz (deceased)\\% Heiko Oberdiek (inactive)\\% - The \LaTeX3 Project\\% + The \LaTeX\ Project\\% \texttt{https://github.com/latex3/hyperref/issues}}% \date{\filedate}% \maketitle -- cgit v1.2.3