LaTeX (carte)/Hyperlinkuri

LaTeX permite scrierea de hyperlinkuri în document, lucru util când formatul rezultat este PDF, iar hyperlinkurile pot fi urmate. Se poate face asta cu pachetul hyperref.

Hyperref

Pachetul hyperref oferă sistemului LaTeX abilitatea de a crea hyperlinkuri în document. Merge cu programul de compilare pdflatex, dar și cu comanda standard "latex" utilizată cu dvips și ghostscript sau dvipdfm pentru a genera un fișier PDF. Dacă încărcați acest pachet, veți avea posibilitatea de a include linkuri externe interactive și atunci toate referințele interne vor fi transformate în hyperlinkuri. Compilatorul pdflatex face posibilă crearea de fișiere PDF direct din sursa LaTeX. Formatul PDF suportă mai multe trăsături decât DVI. În particular, PDF suportă hyperlinkuri, iar singurul mod de a le introduce în LaTeX este cu ajutorul pachetului hyperref. Mai mult, un PDF poate conține și alte informații despre document, cum ar fi titlul, autorul, etc., elemente pe care le puteți edita prin intermediul aceluiași pachet.

Utilizare

Utilizarea de bază cu setările standard este destul de simplă. Includeți pachetul în preambul, după ce ați inclus toate celelalte pachete, însă înaintea altor setări:

\usepackage{hyperref}

Asta va transforma automat toate referințele interne în hyperlinkuri. Nu va afecta modul în care scrieți documentele: continuați să utilizați sistemul standard \label/\ref; cu hyperref, aceste "conexiuni" vor deveni linkuri și le veți putea selecta pentru a ajunge la paginile spre care indică. Mai mult, Cuprinsul, listele de figuri și tabele, precum și indexul vor fi constituite din hyperlinkuri, la rândul lor.

Pachetul oferă trei comenzi utile pentru a insera linkuri ce indică în afara documentului:

• \hyperref[nume_etichetă]{text pentru link}: acesta va avea același efect ca \ref{nume_etichetă}, însă va face din textul pentru link un link ce poate fi selectat. Cele două comenzi pot fi combinate, ca în exemplul următor:

\hyperref[lema_principală]{lema \ref*{lema_principală}}

Notați caracterul * de după \ref pentru a evita hyperlinkurile imbricate.

Dacă lema etichetată "lema_principală" avea numărul 4.1.1, atunci textul generat ar fi "lema 4.1.1" cu hyperlinkul după cum era de așteptat.

• \url{URL}: va afișa URL-ul cu un font mono-space și, dacă îl selectați, se va deschide browserul la acel URL.

• \href{URL}{descriere}: va afișa șirul de caractere "descriere" cu fontul standard al documentului, iar dacă îl selectați, browserul va fi deschis la "URL". Iată un exemplu:

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

Ambele indică spre aceeași pagină Web, însă în primul caz, se va afișa URL-ul, în vreme ce în al doilea, URL-ul va fi ascuns, afișând în schimb descrierea dorită. Notați că, dacă tipăriți sau vizualizați documentul final, linkul păstrat de \href nu va apare nicăieri în document. Puteți folosi căi relative pentru a indica spre documente apropiate de locul documentului curent; pentru a face asta, utilizați notația standard de tip UNIX (./ este directorul curent, ../ este directorul părinte, etc.).

O cale posibilă de a insera emailuri este:

\href{mailto:adresă@wikibooks.org}{adresă@wikibooks.org}

Asta vă va afișa adresa de email (astfel că oamenii o pot afla chiar dacă documentul este tipărit), însă, dacă cititorul selectează linkul din documentul în format electronic, vă poate trimite ușor un email. Ori, pentru a încorpora abilitățile de formatare și separare a liniilor oferite de pachetul url în textul afișat, puteți folosi .

\href{mailto:adresă@wikibooks.org}{\nolinkurl{adresă@wikibooks.org}}

Când utilizați acest format, notați că această comandă, \nolinkurl, este instabilă, iar dacă hyperlinkul se găsește într-un argument flexibil, trebuie să fie precedată de o comandă \protect.

Personalizare

Configurările standard ar trebui să fie suficiente pentru majoritatea utilizatorilor, dar dacă vreți să schimbați ceva, puteți face asta cu ușurință. Sunt mai multe variabile pe care le puteți schimba și sunt două metode prin care le puteți transmite pachetului. Puteți pasa opțiunile ca argumente ale pachetului la încărcarea acestuia în preambul (aceasta este versiunea standard folosită de pachete), sau puteți folosi comanda \hypersetup:

\hypersetup{opțiunea1 [, ...]}

Puteți transmite câte opțiuni doriți, separate prin virgulă. Opțiunile trebuie să fie sub forma:

nume_variabilă=valoare_nouă

Trebuie să utilizați exact același format dacă transmiteți opțiunile pachetului la încărcare:

\usepackage[opțiunea1, opțiunea2]{hyperref}

Iată o listă a variabilelor pe care le puteți modifica (pentru lista completă, vezi documentația oficială). Valorile implicite sunt scrise cu font normal:

Variabilă	Valori	Comentariu
bookmarks	=true,false	Arată sau ascunde bara cu marcaje (bookmarks) când se afișează documentul final
unicode	=false,true	Permite utilizarea caracterelor ne-latinești în marcajele Acrobat
pdfborder	={text}	Configurează stilul marginii din jurul unui link; de exemplu, {0 0 0} înseamnă nicio margine
pdftoolbar	=true,false	Arată sau ascunde bara de instrumente a Acrobat
pdfmenubar	=true,false	Arată sau ascunde meniul Acrobat
pdffitwindow	=true,false	Redimensionează fereastra documentului pentru a se adapta la mărimea documentului
pdfstartview	={FitH},{FitV},etc.	Ajustează lățimea paginii la mărimea ferestrei
pdftitle	={text}	Definește titlul ce va fi afișat în fereastra "Document Info" a Acrobat
pdfauthor	={text}	Numele autorului documentului PDF, merge la fel ca opțiunea dinainte
pdfsubject	={text}	Subiectul documentului, la fel ca mai devreme
pdfcreator	={text}	Creatorul documentului, ca mai sus
pdfproducer	={text}	Producătorul documentului, ca opțiunea de mai înainte
pdfkeywords	={text}	Lista de cuvinte cheie, separate de paranteze drepte, ca în exemplul de mai jos
pdfnewwindow	(=true,false)	Stabilește dacă linkurile externe vor fi deschise într-o fereastră nouă
pagebackref	(=false,true)	Activează referințele anterioare în bibliografie. Trebuie specificată în declarația \usepackage{}.
colorlinks	(=false,true)	Înconjoară linkurile cu niște cadre colorate (false) sau colorează textul linkurilor (true). Culoarea acestor linkuri poate fi configurată cu următoarele opțiuni (se prezintă culorile implicite):
linkcolor	=red (roșu)	Culoarea linkurilor interne (la secțiuni, pagini, etc.)
linktoc	=none,section,page,all	Stabilește ce parte a unei intrări din Cuprins va deveni un link
citecolor	=green (verde)	Culoarea linkurilor de citare (la bibliografie)
filecolor	=magenta	Culoarea linkurilor la fișiere
urlcolor	=cyan	Culoarea linkurilor la URL-uri (email, Web)
linkbordercolor	={1 0 0}	Culoarea cadrului din jurul linkurilor interne (dacă colorlinks=false)
citebordercolor	={0 1 0}	Culoarea cadrului din jurul citărilor

Pentru a accelera procesul de personalizare, iată o listă cu unele variabile și valorile lor implicite. Copiați-o în document și faceți modificările dorite. Alături de variabile, găsiți o scurtă explicație a semnificației lor:

\hypersetup
{
    bookmarks=true,         % arată bara cu marcaje
    unicode=false,          % caractere ne-latinești în marcajele Acrobat
    pdftoolbar=true,        % arată bara cu instrumente a Acrobat
    pdfmenubar=true,        % arată meniul Acrobat
    pdffitwindow=false,     % fereastra se ajustează la mărimea paginii când se deschide
    pdfstartview={FitH},    % ajustează lățimea paginii la fereastră
    pdftitle={Titlu},       % titlu
    pdfauthor={Autor},      % autor
    pdfsubject={Subiect},   % subiectul documentului
    pdfcreator={Creator},   % creatorul documentului
    pdfproducer={Producător}, % producătorul documentului
    pdfkeywords={cheia1} {cheia2}, % lista de cuvinte cheie
    pdfnewwindow=true,      % linkurile se deschid într-o fereastră nouă
    colorlinks=false,       % false: linkuri în căsuțe colorate; true: linkuri colorate
    linkcolor=red,          % culoarea linkurilor interne
    citecolor=green,        % culoarea linkurilor la bibliografie
    filecolor=magenta,      % culoarea linkurilor la fișiere
    urlcolor=cyan           % culoarea linkurilor externe
}

Dacă nu vreți să modificați atâtea opțiuni, iată niște exemple utile mai restrânse. Când creați PDF-uri destinate pentru tipărire, linkurile colorate nu sunt o idee bună dacă listați alb-negru întrucât vor fi printate cu gri, fiind greu de citit. Puteți folosi în schimb cadre colorate, care nu vor fi tipărite:

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

Sau puteți face linkurile negre:

\usepackage{hyperref}
\hypersetup
{
    colorlinks,
    citecolor=black,
    filecolor=black,
    linkcolor=black,
    urlcolor=black
}

Dacă vreți doar să includeți informații pentru secțiunea Document Info a fișierului PDF, dar și să activați referințele anterioare în bibliografie:

\usepackage[pdfauthor={Nume autor},
pdftitle={Titlu document},
pagebackref=true,
pdftex]{hyperref}

Implicit, URL-urile sunt afișate cu fonturi mono-spațiate. Dacă nu vă place aspectul lor și vreți să fie afișate cu același font ca și restul textului, utilizați comanda:

 \urlstyle{same}

Probleme cu linkurile și ecuațiile

Apar mesaje de genul:

! pdfTeX warning (ext4): destination with the same identifier
(name{equation.1.7.7.30}) has been already used, duplicate ignored

când faceți așa ceva:

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

Eroarea dispare, dacă scrieți:

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

Aveți grijă că numărul liniei afișat poate fi complet diferit de numărul liniei pe care apare eroarea.

Probleme cu linkurile și paginile

Mesaje de genul:

! pdfTeX warning (ext4): destination with the same
identifier (name{page.1}) has been already used,
duplicate ignored

apar când un contor este reinițializat, spre exemplu prin utilizarea comenzii \mainmatter oferită de clasa de documente carte (book). Aceasta resetează contorul numărului de pagină la 1 înaintea primului capitol al cărții. Dar deoarece prefața are și ea o pagină numerotată cu 1, toate linkurile către „pagina 1” nu ar mai fi unice, prin urmare avertismentul "duplicate has been ignored" (pagina duplicat a fost ignorată). Soluția pentru contor constă în a pune plainpages=false la opțiunile pachetului hyperref. Asta nu ajută din păcate decât la numerotarea paginilor. O soluție și mai radicală ar fi setarea opțiunii hypertexnames=false, însă asta va face să nu mai meargă linkurile la pagini din index.

Cea mai bună soluție ar fi să dați fiecărei pagini un nume unic folosind comanda \pagenumbering:

\pagenumbering{alph}    % a, b, c, ...
... pagina titlu, alte antete similare ...
\pagenumbering{roman}   % i, ii, iii, iv, ...
\setcounter{page}{1}
... Cuprinsul, tabelul cu figuri, ...
\pagenumbering{arabic}  % 1, 2, 3, 4, ...
\setcounter{page}{1}
... începutul subiectului de bază (Capitolul 1) ...

O altă soluție constă în utilizarea \pagenumbering{alph} înaintea comenzii \maketitle, lucru care va da paginii titlu eticheta page.a (pentru cărți). Deoarece numerotarea paginilor nu este încă activată, nu va schimba cu nimic outputul.

Modificând modul de numerotare a paginilor de fiecare dată când resetați contorul, fiecare pagină primește un nume unic. În acest caz, paginile vor fi numerotate a, b, c, i, ii, iii, iv, v, 1, 2, 3, 4, 5, ...

Dacă nu vreți să fie vizibile anumite numere de pagini (spre exemplu, înainte de începerea capitolelor), folosiți comenzile \pagestyle{empty} ... \pagestyle{plain}. Trebuie să rețineți că deși numerele paginilor nu sunt vizibile, fiecare pagină va avea un nume unic.

Aceeași problemă poate să apară și cu pachetele de algoritmi: întrucât fiecare algoritm folosește aceeași schemă de numerotare a liniilor, identificatorii de linii pentru al doilea algoritm și următorii vor fi duplicați ai primului.

Problema apare și în cazul identificatorilor de ecuații dacă utilizați comanda \nonumber pe fiecare linie a unui mediu eqnarray. În cazul acesta, folosiți mai bine formele stelate, de exemplu begin{eqnarray*} ... end{eqnarray*} (care dă o ecuație nenumerotată), înlăturând comenzile de acum nenecesare \nonumber.

Probleme cu semnele de carte

Textul afișat de semnele de carte (bookmarks) nu arată întotdeauna după cum ar fi de așteptat. Întrucât acestea sunt "doar text", pentru ele sunt disponibile mult mai puține caractere decât pentru textul normal din LaTeX. Pachetul hyperref ar trebui să detecteze astfel de probleme și să emită un avertisment:

Package hyperref Warning:
Token not allowed in a PDFDocEncoded string:

Puteți rezolva acum această problemă oferind un text pentru bookmark, care înlocuiește textul ce a dat avertismentul:

\texorpdfstring{Text TeX}{Text bookmark}

Expresiile matematice sunt un candidat principal pentru acest tip de problemă:

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

Comanda de mai sus înlocuiește $E=mc^2$ cu E=mc2 pentru semnele de carte. Schimbarea culorilor nu dă rezultatul așteptat cu bookmark-uri:

\section{\textcolor{red}{Roșu !}}

produce "redRoșu!". Comanda \textcolor este ignorată, însă argumentul ei (red) este afișat.

Dacă utilizați:

\section{\texorpdfstring{\textcolor{red}{Roșu !}}{Roșu\ !}}

veți obține rezultatul dorit.

Dacă scrieți documentul cu caractere Unicode și utilizați opțiunea unicode pentru pachetul hyperref, puteți folosi caractere Unicode în semnele de carte. Asta vă va da o bază mult mai mare de selecție pentru caracterele de folosit cu comanda \texorpdfstring.

Probleme cu tabelele și figurile

Linkurile create de pachetul hyperref indică spre eticheta creată în mediul flotant, care, după cum a fost descris mai devreme, trebuie setată întotdeauna după notă sau titlu. Deoarece titlul este așezat de obicei sub o figură sau un tabel, figura sau tabelul în sine nu vor fi vizibile la selectarea linkului. Puteți rezolva această problemă cu ajutorul pachetului hypcap [1]:

\usepackage[all]{hypcap}

Aveți grijă să includeți acest pachet după hyperref, care altfel ar trebui încărcat ultimul.

Dacă utilizați pachetul wrapfig menționat în secțiunea "Text în jurul figurilor" din capitolul "Elemente flotante, figuri și note", sau alte pachete similare ce definesc propriile medii, va trebui să includeți manual comanda \capstart în acele medii:

\begin{wrapfigure}{R}{0.5\textwidth}
  \capstart
  \begin{center}
    \includegraphics[width=0.48\textwidth]{nume_fișier}
  \end{center}  
  \caption{\label{nume_etichetă}o figură}
\end{wrapfigure}

Probleme cu notele și titlurile lungi cu \listoffigures

Există o problemă legată de utilizarea comenzii \listoffigures cu pachetul hyperref în cazul notelor și titlurilor lungi. Asta se întâmplă când notele (sau titlurile) sunt mai lungi decât lățimea paginii (cam 7-9 cuvinte, în funcție de configurările curente). Pentru a rezolva această problemă, trebuie să folosiți opțiunea breaklinks la includerea pachetului în preambul:

\usepackage[breaklinks]{hyperref}

Asta va face ca linkurile din \listoffigures să se împartă în mod corespunzător pe mai multe linii.

Probleme cu fișierele .toc, .lof și alte fișiere similare existente

Când includeți pachetul hyperref, se schimbă formatul unora dintre fișierele auxiliare generate de LaTeX. Puteți întâlni prin urmare erori de genul ! Argument of \Hy@setref@link has an extra }. când formatați documentul pentru prima oară cu hyperref, iar aceste fișiere deja există. Soluția la această problemă ar fi să ștergeți toate fișierele pe care le folosește LaTeX pentru referințe și să recompilați documentul.