latex-hyperlinks.pdf

Upload: hector-re

Post on 02-Jun-2018

218 views

Category:

Documents


0 download

TRANSCRIPT

  • 8/11/2019 LaTeX-Hyperlinks.pdf

    1/9

    LaTeX/Hyperlinks 1

    LaTeX/Hyperlinks

    LaTeX enables typesetting of hyperlinks, useful when the resulting format is PDF, and the hyperlinks can be

    followed. It does so using the package hyperref.

    Hyperref

    The package hyperref[1]

    provides LaTeX the ability to create hyperlinks within the document. It works withpdflatex

    and also with standard "latex" used with dvips and ghostscript or dvipdfm to build a PDF file. If you load it, you will

    have the possibility to include interactive external links and all your internal references will be turned to hyperlinks.

    The compilerpdflatex makes it possible to create PDF files directly from the LaTeX source, and PDF supports more

    features than DVI. In particular PDF supports hyperlinks, and the only way to introduce them in LaTeX is using

    hyperref. Moreover, PDF can contain other information about a document such as the title, the author, etc., which

    can be edited using this same package.

    UsageThe basic usage with the standard settings is straightforward. Just load the package in the preamble:

    \usepackage{hyperref}

    This will automatically turn all your internal references into hyperlinks. It won't affect the way to write your

    documents: just keep on using the standard \label -\ref system (discussed in the chapter on Labels and

    Cross-referencing); with hyperref those "connections" will become links and you will be able to click on them to be

    redirected to the right page. Moreover the table of contents, list of figures/tables and index will be made of

    hyperlinks, too. The hyperlinks will not show-up if you are working in draft mode.

    Commands

    The package provides some useful commands for inserting links pointing outside the document.

    \hyperref

    Usage:

    \hyperref[label_name]{''link text''}

    This will have the same effect as \ref{label_name}but will make the text link text a full link, instead. The

    two can be combined. If the lemma labelled as mainlemma was number 4.1.1 the following example would result in

    We use \hyperref[mainlemma]{lemma \ref*{mainlemma}}. We use lemma 4.1.1.

    with the hyperlink as expected. Note the "*" after \reffor avoiding nested hyperlinks.

    http://en.wikibooks.org/w/index.php?title=LaTeX/Labels_and_Cross-referencinghttp://en.wikibooks.org/w/index.php?title=LaTeX/Labels_and_Cross-referencing
  • 8/11/2019 LaTeX-Hyperlinks.pdf

    2/9

    LaTeX/Hyperlinks 2

    \url

    Usage:

    \url{}

    It will show the URL using a mono-spaced font and, if you click on it, your browser will be opened pointing at it.

    \href

    Usage:

    \href{}{}

    It will show the string description using standard document font but, if you click on it, your browser will be opened

    pointing at my_url. Here is an example:

    \url{http://www.wikibooks.org}\href{http://www.wikibooks.org}{Wikibooks home}

    Both point at the same page, but in the first case the URL will be shown, while in the second case the URL will be

    hidden. Note that, if you print your document, the link stored using \hrefwill not be shown anywhere in thedocument.

    Other possibilities

    Apart from linking to websites discussed above, hyperref can be used to provide mailto links, links to local files, and

    links to anywhere within the PDF output file.

    E-mail address

    A possible way to insert email links is by

    \href{mailto:[email protected]}{my\[email protected]}

    It just shows your email address (so people can know it even if the document is printed on paper) but, if the reader

    clicks on it, (s)he can easily send you an email. Or, to incorporate the url package's formatting and line breaking

    abilities into the displayed text, use

    \href{mailto:[email protected]}{\nolinkurl{[email protected]}}

    When using this form, note that the \nolinkurlcommand is fragile and if the hyperlink is inside of a moving

    argument, it must be preceeded by a \protectcommand.

    Local file

    Files can also be linked using the url or the href commands. You simply have to add the string run: at the beginning

    of the link string:

    \url{run:/path/to/my/file.ext}\href{run:/path/to/my/file.ext}{text displayed}

    Following http:// tex.stackexchange.com/ questions/ 46488/ link-to-local-pdf-file the version with url does not

    always work, but href does.

    It is possible to use relative paths to link documents near the location of your current document; in order to do so, use

    the standard Unix-like notation (./ is the current directory, ../ is the previous directory, etc.)

    http://tex.stackexchange.com/questions/46488/link-to-local-pdf-file
  • 8/11/2019 LaTeX-Hyperlinks.pdf

    3/9

    LaTeX/Hyperlinks 3

    Hyperlink and Hypertarget

    It is also possible to create an anchor anywhere in the document (with or without caption) and to link to it. To create

    an anchor, use:

    \hypertarget{label}{target caption}

    and to link to it, use:

    \hyperlink{label}{link caption}

    where the target caption and link caption are the text that is displayed at the target location and link location

    respectively.

    Customization

    The standard settings should be fine for most users, but if you want to change something, that is also possible. There

    are several variables and two methods to pass those to the package. Options can be passed as an argument of the

    package when it is loaded (the standard way packages work), or the \hypersetup command can be used as

    follows:

    \hypersetup{ [, ...]}

    you can pass as many options as you want; separate them with a comma. Options have to be in the form:

    variable_name=new_value

    exactly the same format has to be used if you pass those options to the package while loading it, like this:

    \usepackage[]{hyperref}

    Here is a list of the possible variables you can change (for the complete list, see the official documentation). The

    default values are written in an upright font:

    Checkout 3.8 Big list at hyperref-manual at tug.org[2]

    variable values comment

    bookmarks =true,false show or hide the bookmarks bar when displaying the document

    unicode =false,true allows to use characters of non-Latin based languages in Acrobats bookmarks

    pdfborder ={RadiusHRadiusVWidth

    [Dash-Pattern]}

    set the style of the border around a link. The first two parameters (RadiusH, RadiusV)

    have no effect in most pdf viewers. Width defines the thickness of the border.

    Dash-Pattern is a series of numbers separated by space and enclosed by box-brackets.

    It is an optional parameter to specify the length of each line & gap in the dash pattern.

    For example, {0 0 0.5 [3 3]} is supposed to draw a square box (no rounded corners) of

    width 0.5 and a dash pattern with a dash of length 3 followed by a gap of length 3.

    There is no uniformity in whether/how different pdf viewers render the dash pattern.

    pdftoolbar =true,false show or hide Acrobats toolbar

    pdfmenubar =true,false show or hide Acrobats menu

    pdffitwindow =true,false resize document window to fit document size

    pdfstartview={FitH},{FitV},etc

    [3].

    fit the width of the page to the window

    pdftitle ={text} define the title that gets displayed in the "Document Info" window of Acrobat

    pdfauthor ={text} the name of the PDFs author, it works like the one above

    pdfsubject ={text} subject of the document, it works like the one above

    http://www.tug.org/applications/hyperref/manual.html#x1-120003.8
  • 8/11/2019 LaTeX-Hyperlinks.pdf

    4/9

    LaTeX/Hyperlinks 4

    pdfcreator ={text} creator of the document, it works like the one above

    pdfproducer ={text} producer of the document, it works like the one above

    pdfkeywords ={text} list of keywords, separated by brackets, example below

    pdfnewwindow (=true,false) define if a new window should get opened when a link leads out of the current

    document

    pagebackref (=false,true) activate back references inside bibliography. Must be specified as part of the

    \usepackage{} statement.

    colorlinks (=false,true) surround the links by color frames (false) or colors the text of the links (true).

    The color of these links can be configured using the following options (default colors

    are shown):

    hidelinks hide links (removing color and border)

    linkcolor =red color of internal links (sections, pages, etc.)

    linktoc =none,section,page,all defines which part of an entry in the table of contents is made into a link

    citecolor =green color of citation links (bibliography)

    filecolor =cyan color of file links

    urlcolor =magenta color of URL links (mail, web)

    linkbordercolor ={1 0 0} color of frame around internal links (if colorlinks=false)

    citebordercolor ={0 1 0} color of frame around citations

    urlbordercolor ={0 1 1} color of frame around URL links

    Please note, that explicit RGB specification is only allowed for the border colors (like linkbordercolor etc.), while

    the others may only assigned to named colors (which you can define your own, see Colors). In order to speed up

    your customization process, here is a list with the variables with their default value. Copy it in your document and

    make the changes you want. Next to the variables, there is a short explanations of their meaning:

    \hypersetup{ bookmarks=true, % show bookmarks bar? unicode=false, % non-Latin

    characters in Acrobats bookmarks pdftoolbar=true, % show Acrobats toolbar?

    pdfmenubar=true, % show Acrobats menu? pdffitwindow=false, % window fit to

    page when opened pdfstartview={FitH}, % fits the width of the page to the

    window pdftitle={My title}, % title pdfauthor={Author}, % author

    pdfsubject={Subject}, % subject of the document pdfcreator={Creator}, %

    creator of the document pdfproducer={Producer}, % producer of the document

    pdfkeywords={keyword1}{key2}{key3}, % list of keywords pdfnewwindow=true, %

    links in new window colorlinks=false, % false: boxed links; true: colored

    links linkcolor=red, % color of internal links (change box color with

    linkbordercolor) citecolor=green, % color of links to bibliography

    filecolor=magenta, % color of file links urlcolor=cyan % color of external

    links }

    If you don't need such a high customization, here are some smaller but useful examples. When creating PDFs

    destined for printing, colored links are not a good thing as they end up in gray in the final output, making it difficult

    to read. You can use color frames, which are not printed:

    \usepackage{hyperref}\hypersetup{colorlinks=false}

    or make links black:

    \usepackage[hidelinks]{hyperref}

    http://en.wikibooks.org/w/index.php?title=LaTeX/Colors
  • 8/11/2019 LaTeX-Hyperlinks.pdf

    5/9

    LaTeX/Hyperlinks 5

    When you just want to provide information for the Document Info section of the PDF file, as well as enabling back

    references inside bibliography:

    \usepackage[pdfauthor={Author's name},% pdftitle={Document Title},%

    pagebackref=true,% pdftex]{hyperref}

    By default, URLs are printed using mono-spaced fonts. If you don't like it and you want them to be printed with the

    same style of the rest of the text, you can use this:

    \urlstyle{same}

    Troubleshooting

    Problems with Links and Equations 1

    Messages like the following

    ! pdfTeX warning (ext4): destination with the same identifier (name{

    equation.1.7.7.30}) has been already used, duplicate ignored

    appear, when you have made something like

    \begin{eqnarray}a=b\nonumber\end{eqnarray}

    The error disappears, if you use instead this form:

    \begin{eqnarray*}a=b\end{eqnarray*}

    Beware that the shown line number is often completely different from the erroneous line.

    Possible solution: Place the amsmath package before the hyperref package.

    Problems with Links and Equations 2

    Messages like the following

    ! Runaway argument?

    {\@firstoffive }\fi ), Some text from your document here (\ref {re\ETC.

    Latex Error: Paragraph ended before \Hy@setref@link was complete.

    appear when you use \label inside an align environment.

    Possible solution: Add the following to your preamble:

    \AtBeginDocument{\let\textlabel\label}

    Problems with Links and Pages

    Messages like the following:

    ! pdfTeX warning (ext4): destination with the same

    identifier (name{page.1}) has been already used,

    duplicate ignored

    appear when a counter gets reinitialized, for example by using the command \mainmatterprovided by the book

    document class. It resets the page number counter to 1 prior to the first chapter of the book. But as the preface of the

    book also has a page number 1 all links to "page 1" would not be unique anymore, hence the notice that "duplicate

    has been ignored." The counter measure consists of putting plainpages=false into the hyperref options. This

  • 8/11/2019 LaTeX-Hyperlinks.pdf

    6/9

    LaTeX/Hyperlinks 6

    unfortunately only helps with the page counter. An even more radical solution is to use the option

    hypertexnames=false , but this will cause the page links in the index to stop working.

    The best solution is to give each page a unique name by using the \pagenumberingcommand:

    \pagenumbering{alph} % a, b, c, ... ... titlepage, other front matter ...

    \pagenumbering{roman}% i, ii, iii, iv, ... ... table of contents, table of

    figures, ... \pagenumbering{arabic} % 1, 2, 3, 4, ... ... beginning of the

    main matter (chapter 1) ...

    Another solution is to use \pagenumbering{alph}before the command \maketitle, which will give the

    title page the label page.a. Since the page number is suppressed, it won't make a difference to the output.

    By changing the page numbering every time before the counter is reset, each page gets a unique name. In this case,

    the pages would be numbered a, b, c, i, ii, iii, iv, v, 1, 2, 3, 4, 5, ...

    If you don't want the page numbers to be visible (for example, during the front matter part), use

    \pagestyle{empty} ... \pagestyle{plain}. The important point is that although the numbers are not

    visible, each page will have a unique name.

    Another more flexible approach is to set the counter to something negative:

    \setcounter{page}{-100} ... titlepage, other front matter ...

    \pagenumbering{roman}% i, ii, iii, iv, ... ... table of contents, table of

    figures, ... \pagenumbering{arabic} % 1, 2, 3, 4, ... ... beginning of the

    main matter (chapter 1) ...

    which will give the first pages a unique negative number.

    The problem can also occur with the algorithms package: because each algorithm uses the same line-numbering

    scheme, the line identifiers for the second and follow-on algorithms will be duplicates of the first.

    The problem occurs with equation identifiers if you use \nonumberon every line of an eqnarray environment. Inthis case, use the *'ed form instead, e.g. \begin{eqnarray*} ... \end{eqnarray*} (which is an

    unnumbered equation array), and remove the now unnecessary \nonumbercommands.

    If your url's are too long and running off of the page, try using the breakurl package to split the url over multiple

    lines. This is especially important in a multicolumn environment where the line width is greatly shortened.

    Problems with bookmarks

    The text displayed by bookmarks does not always look like you expect it to look. Because bookmarks are "just text",

    much fewer characters are available for bookmarks than for normal LaTeX text. Hyperref will normally notice such

    problems and put up a warning:

    Package hyperref Warning:

    Token not allowed in a PDFDocEncoded string:

    You can now work around this problem by providing a text string for the bookmarks, which replaces the offending

    text:

    \texorpdfstring{''TEX text''}{''Bookmark Text''}

    Math expressions are a prime candidate for this kind of problem:

    \section{\texorpdfstring{$E=mc^2$}{E=mc2}}

    which turns \section{$E=mc^2$}to E=mc2 in the bookmark area. Color changes also do not travel well into

    bookmarks:

  • 8/11/2019 LaTeX-Hyperlinks.pdf

    7/9

    LaTeX/Hyperlinks 7

    \section{\textcolor{red}{Red !}}

    produces the string "redRed!". The command \textcolorgets ignored but its argument (red) gets printed. If you

    use:

    \section{\texorpdfstring{\textcolor{red}{Red !}}{Red\ !}}

    the result will be much more legible.

    If you write your document in unicode and use the unicode option for the hyperref package you can use unicode

    characters in bookmarks. This will give you a much larger selection of characters to pick from when using

    \texorpdfstring.

    Problems with tables and figures

    The links created by hyperref point to the label created within the float environment, which, as previously described,

    must always be set after the caption. Since the caption is usually below a figure or table, the figure or table itself will

    not be visible upon clicking the link[4]

    . A workaround exists by using the package hypcap[5] with:

    \usepackage[all]{hypcap}

    Be sure to call this package after loading hyperref.

    If you use the wrapfig package[6]

    mentioned in the "Wrapping text around figures" section of the "Floats, Figures

    and Captions" chapter, or other similar packages that define their own environments, you will need to manually

    include \capstartin those environments, e.g.:

    \begin{wrapfigure}{R}{0.5\textwidth} \capstart \begin{center}

    \includegraphics[width=0.48\textwidth]{filename} \end{center}

    \caption{\label{labelname}a figure}\end{wrapfigure}

    Problems with long caption and \listoffigures or long title

    There is an issue when using \listoffigureswith hyperref for long captions or long titles. This happens when

    the captions (or the titles) are longer than the page width (about 7-9 words depending on your settings). To fix this,

    you need to use the option breaklinks when first declaring:

    \usepackage[breaklinks]{hyperref}

    This will then cause the links in the \listoffiguresto word wrap properly.

    Problems with already existing .toc, .lof and similar files

    The format of some of the auxilliary files generated by latex changes when you include the hyperref package. One

    can therefore encounter errors like

    ! Argument of \Hy@setref@link has an extra }.

    when the document is typeset with hyperref for the first time and these files already exist. The solution to the

    problem is to delete all the files that latex uses to get references right and typeset again.

    http://en.wikibooks.org/w/index.php?title=LaTeX/Floats%2C_Figures_and_Captions%23Wrapping_text_around_figureshttp://www.ctan.org/tex-archive/macros/latex/contrib/oberdiek/hypcap.pdfhttp://en.wikibooks.org/w/index.php?title=LaTeX/Floats%2C_Figures_and_Captions%23Labels_and_Cross-referencing
  • 8/11/2019 LaTeX-Hyperlinks.pdf

    8/9

    LaTeX/Hyperlinks 8

    Problems with footnotes and special characters

    See the relevant section.

    Problems with Beamer

    Using the command

    \hyperref[some_label]{some text}

    is broken when pointed at a label. Instead of sending the user to the desired label, upon clicking the user will be sent

    to the first frame. A simple work around exists; instead of using

    \phantomsection\label{some_label}

    to label your frames, use

    \hypertarget{some_label}{}

    and reference it with

    \hyperlink{some_label}{some text}

    Problems with draft mode

    WARNING! Please note that if you have activated the "draft"-option in your \documentclass declaration the

    hyperlinks will not show up in the table of contents!!!

    Notes and References

    [1] Hyperref package webpage in CTAN (http://www.ctan.org/tex-archive/macros/latex/contrib/hyperref)

    [2] http:/ /www.tug. org/applications/hyperref/manual. html#x1-120003. 8

    [3] Other possible values are defined in the hyperref manual(http://mirror. switch.ch/ftp/mirror/tex/macros/latex/

    contrib/hyperref/doc/manual. html#TBL-7-40-1)

    [4] http:/ /www.ctan. org/tex-archive/macros/latex/contrib/hyperref/README

    [5] http:/ /www.ctan. org/tex-archive/macros/latex/contrib/oberdiek/hypcap. pdf

    [6] Wrapfig package webpage in CTAN (http://www.ctan.org/tex-archive/macros/latex/contrib/wrapfig)

    http://www.ctan.org/tex-archive/macros/latex/contrib/wrapfighttp://www.ctan.org/tex-archive/macros/latex/contrib/oberdiek/hypcap.pdfhttp://www.ctan.org/tex-archive/macros/latex/contrib/hyperref/READMEhttp://mirror.switch.ch/ftp/mirror/tex/macros/latex/contrib/hyperref/doc/manual.html#TBL-7-40-1http://mirror.switch.ch/ftp/mirror/tex/macros/latex/contrib/hyperref/doc/manual.html#TBL-7-40-1http://www.tug.org/applications/hyperref/manual.html#x1-120003.8http://www.ctan.org/tex-archive/macros/latex/contrib/hyperrefhttp://en.wikibooks.org/w/index.php?title=LaTeX/Footnotes_and_Margin_Notes%23Common_problems_and_workarounds
  • 8/11/2019 LaTeX-Hyperlinks.pdf

    9/9

    Article Sources and Contributors 9

    Article Sources and ContributorsLaTeX/Hyperlinks Source: http://en.wikibooks.org/w/index.php?oldid=2626832 Contributors: Adrignola, Alejo2083, Ambrevar, Bajrangkhichi96, Belteshazzar, Blacktrumpeter, Bytecrook,

    Calimo, ChrisHodgesUK, Courcelles, Dan Polansky, Deltasun, Derbeth, Froskoy, Ghoti, Gwpl, Joeyboi, Jomegat, Juliabackhausen, Jwchong, Kevinfiesta, LaTeX, Lnkbuildingservices4u,

    MartinSpacek, Mimo, Modest Genius, Neet, Neoriddle, Niy, Pamputt, PeterAllen, Pi zero, Prawojazdy, Qwertyus, Recent Runes, Roarbakk, Robbiemorrison, SamuelLB, Shahbaz Youssefi,

    SiriusB, Teles, Thietkeweb, Tomato86, Urhixidur, Waldir, Wdcf, Xonqnopp, 64 anonymous edits

    License

    Creative Commons Attribution-Share Alike 3.0//creativecommons.org/licenses/by-sa/3.0/