Zastaw ciekawych makroinstrukcji
Author: Włodzimierz Macewicz
Keywords: tex, latex, makroinstrukcje, pakiety makroinstrukcji, Wirtualna Akademia

## hyperref

Dołączenie pakietu umożliwia tworzenie dokumentów hipertekstowych za pomocą LaTeX-a. Dokument można przetworzyć PDFLateXem lub standardowym LaTeX-em i następnie poddać dalszej obróbce np: `dvips` i `Acrobat Distiller`.

Jeżeli dokument jest napisany zgodnie z regułami sztuki, to nie są wymagane inne zabiegi -- wszystkie odwołania do etykiet, bibliografii, numery stron w skorowidzu, pozycje w spisach staną się automatycznie odwołaniami hipertekstowymi (lokalnymi). Oprócz tego możemy umieszczać odwołania do dokumentów zewnętrznych i definiować etykiety globalne, na które można się powołać w innych dokumentach.

Odsyłacze, jak i miejsca etykietowane mogą być wyróżnione kolorem lub obwódką. Sposób oznaczania określamy za pomocą parametrów sterujących (opcji). Nadawanie wartości parametrom odbywa się w następujący sposób:
`\usepackage[opcja={wartość},`
`opcja={wartość},`
`...`
`opcja={wartość}]{hyperref}`
Możemy również utworzyć zbiór `hyperref.cfg` i umieścić w nim wartości parametrów. W tym celu należy utworzyć poniższą konstrukcję:
`\hypersetup{
opcja={wartość}},
...
opcja={wartość}}
}`
Jak łatwo się domyśleć najpierw analizowany jest zbiór `hyperref.cfg`, a następnie parametry podawane przy wywołaniu pakietu.

Pakiet `hyperref`, w przypadku użycia opcji `colorlinks`, dołącza pakiet `color` (oczywiście można pakiet ten dołączyć niezależnie). Dołączany jest również pakiet `url` -- adresy prezentowane za pomocą polecenia `url` stają się automatycznie połączeniami hipertekstowymi.

W przypadku dołączenia pakietu `xr` (z pakietem `hyperref` dostarczana jest zmodyfikowana wersja tego pakietu) dostępne jest polecenie `\externaldocument`. Ogólna postać wywołania wygląda następująco:
`\externaldocument[prefix]{document}[URL]`
gdzie:

prefix
  w przypadku konfliktu etykiet w zbiorze zewnętrznym i bieżącym można określić prefix; wtedy na etykiety zewnętrzne powołujemy się jako: prefixetykieta (dokument na który się powołujemy też musi być kompilowany z dołączonym pakietem `hyperref`; inna jest postać polecenia `newlabel`)
document
  nazwa dokumentu zewnętrznego -- w czasie kompilacji wczytywany jest zbiór dokument`.aux`, w celu pobrania definicji etykiet
URL
  adres dokumentu1 (znaki specjalne (np. `~`) pozostają nimi). Do nazwy zbioru dopisywany jest ciąg znaków zdefiniowany parametrem `extension`. W przypadku pominięcia tego parametru zbiorem zewnętrznym staje się zbiór określony przez parametr document2

#### Polecenia

`\Acrobatmenu{wywoływana funkcja}{tekst opisujący}`
  polecenie tworzy menu które umożliwia wywołanie funkcji przeglądarki; znane są następujące funkcje:

  kategoria | nazwa funkcji
  File | `Open, Close, Scan, Save, SaveAs, Optimizer:SaveAsOpt, Print, PageSetup, Quit`
  | `ImportImage, ImportNotes, AcroForm:ImportFDF`
  | `ExportNotes, AcroForm:ExportFDF`
  | `GeneralInfo, OpenInfo, FontsInfo, SecurityInfo, Weblink:Base, AutoIndex:DocInfo`
  | `GeneralPrefs, NotePrefs, FullScreenPrefs, Weblink:Prefs, AcroSearch:Preferences (Windows) lub AcroSearchPrefs (Mac), Cpt:Capture`
  Edit | `Undo, Cut, Copy, Paste, Clear, SelectAll, Ole:CopyFile, TouchUp:TextAttributes, TouchUp:FitTextToSelection, TouchUp:ShowLineMarkers, TouchUp:ShowCaptureSuspects, TouchUp:FindSuspect, Properties`
  | `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_Movi:MoviePlayer, TouchUp:TextTool, Find, FindAgain, FindNextNote, CreateNotesFile`
  | `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, About (Windows)`

`\pdfbookmark{tekst do zakładki}{etykieta}`
  ,,ręczne'' wstawienie pozycji do menu przeglądarki (zakładka) (p. opcje: `bookmark` i `bookmarksopen`)
`\href{URL}{tekst opisujący odsyłacz}`
  tworzy odsyłacz do dokumentu w sieci internet (WWW)
`\url{URL}`
  tworzy odsyłacz do dokumentu w sieci internet (WWW) (tekstem opisującym jest sam adres; patrz opis pakietu `url`)
`\hyperbaseurl{???}`
  -- patrz opcja `baseurl`
`\hyperimage{URL}{tekst opisujący odsyłacz}`
  tworzy odsyłacz do rysunku
`\hypertarget{nazwa etykiety}{tekst opisu}`
  oznacza tekst opisu etykietą lokalną nazwa etykiety , na zdefiniowaną etykietę można się powołać poleceniem `hyperlink`; oznaczony tekst wyświetlany jest w kolorze określonym przez opcję `anchorlink`
`\hyperlink{nazwa etykiety}{obiekt opisujący odsyłacz}`
  tworzy odsyłacz do innego miejsca (oznaczonego etykietą; p. polecenie `hypertarget`) w bieżącym dokumencie; obiekt może być tekstem bądź rysunkiem, np:

      \hyperlink{etykieta}{\epsfig{figure=picture,height=1in}}

`\hyperref{URL}{kategoria}{etykieta}{tekst opisujący}`
  polecenie definiuje odsyłacz do innego dokumentu. Zostanie on wczytany zamiast bieżącego, zostanie pokazana strona zawierająca etykietę o podanej nazwie i kategorii (tak naprawdę realizowane jest odwołanie do etykiety w postaci: kategoria.etykieta (patrz `hyperdef`)

      \hyperref{file:test2.pdf}{equation}{1}{hello}

`\hyperref[lokalna etykieta]?????`
  powołanie się na odsyłacz zdefiniowany poleceniem `hyperdef` i nazwany etykietą (etykieta lokalna) (nie udało mi się uzyskać pozytywnych efektów)
`\hyperdef{etykieta}{kategoria}{tekst opisujący}`
  tekst opisujący jest oznaczany etykietą, do której można się odwołać z innego dokumentu (p. `hyperref`)

      \hyperdef{equation}{1}{hello}

`\hyperdef[lokalna etykieta]{etykieta}{kategoria}{tekst opisujący}`
  tworzy również etykietę lokalną na którą można się powołać w poleceniu `hyperref` (nie udało mi się uzyskać pozytywnych efektów)
`\PDFOpen{????}`
  ?????
`\PDFNextPage{tekst}`
  tworzy odsyłacz hipertekstowy do następnej strony
`\PDFPreviousPage{tekst}`
  tworzy odsyłacz hipertekstowy do poprzedniej strony
`\PDFPage{kwalifikator}{tekst}`
  tworzy odsyłacz hipertekstowy do strony określonej przez kwalifikator (nie znam listy możliwych określeń)

      \PDFPage{/Next}{następna strona}

`\htmlref{tekst opisujący}{etykieta}`
  podobnie jak `hyperref` tyle, że do dokumentu `HTML` (nie udało mi się uzyskać pozytywnych efektów)
`\hyperpageanchor`
  definicja etykiety hipertekstowej do strony bieżącej w postaci `page.`numer strony (kategoria ,,page'') numer strony jest reprezentowany w postaci liczby -- opcja `plainpages` (bez względu na sposób wizualizacji licznika strony) lub tak jak jest on określony przez makro `thepage` (tak jak wygląda on w dokumennie)
`\hyperpage{numer strony}`
  hiperodwołanie się do strony o podanym numerze (numer strony staje się opisem odsyłacza) -- używane głównie w skorowidzu
`\begin{NoHyper}`
`\end{NoHyper}`
  tworzy środowisko w którym nie są tworzone hiperreferencje

#### Opcje główne

Opcja | Opis
--- | ---
4 | Włączenie rozszerzeń wersji 4 Acrobata??? (Acrobat 4.05 sygnalizuje błąd przy wczytaniu dokumentu wygenerowanego przez pdflatexa)
`draft` | wyłącza wszystkie opcje hipertekstowe
`debug` | daje informacje o hiperreferencjach
`a4paper` | wyjściowy format papieru (210x297 mm)
`a5paper` | wyjściowy format papieru (148x210 mm)
`b5paper` | wyjściowy format papieru (176x250 mm)
`letterpaper` | wyjściowy format papieru (8.5x11 in)
`legalpaper` | wyjściowy format papieru (8.5x14 in)
`executivepaper` | wyjściowy format papieru (7.25x10.5 in)

#### Opcje konfiguracyjne

Opcja (po `=` wartość domyślna) | Opis
--- | ---
`raiselinks={`false`}` | dla niektórych driwerów ustawia sposób wyróżnienia opisu odsyłacza -- kolor albo obniżenie tekstu
`breaklinks={`false`}` | włącza/wyłącza możliwość złamania linii w tekście opisującym link (np. pozycja spisu treści)
`pageanchor={`true`}` | włącza/wyłącza automatyczne hiper etykietowanie stron etykietą w postaci: `page.`numer strony; jeśli zostanie wyłączona spis treści nie będzie realizował hiperodwołań
`plainpages={`true`}` | ustawia jak mają być reprezentowane numery stron w etykietach hipertekstowych; zawsze jako liczba (bez względu na sposób wizualizacji) lub tak jak określa to makro `thepage`
`nesting={`false`}` | nie używana
`hypertexnames={`true`}` | nazwami hiperodwołań są nazwy LaTeXowe, a nie nazwy liczników -- bardzo elitarna opcja!!
`bookmarkstype={`toc`}` | wprowadza do zbioru zakładek listę obiektów wprowadzanych do danego zbioru (`toc` -- spis treści; nie udało mi się osiągnąć pozytywnego efektu dla typów różnych od `toc` (np: `lof` -- spis rysunków)
`implicit={`true`}` | ????????
`naturalnames={false}` | ????
`frenchlinks={false}` | oprócz koloru, wyróżnikiem hiperodwołania jest skład z użyciem czcionki `CapSmall` ma to znaczenie wtedy, kiedy opis hiperwołania jest tekstem, w przypadku spisu treści zamiana na skład czcionką `CapsSmall` odbywa się dopiero powyżej 1 poziomu (`section`)!?

#### Opcje związane z typem postprocesora przetwarzającego zbiór `.dvi`

Opcja | Program przetwarzający
--- | ---
`pdftex` | `pdftex`'a
`hyperref` | nic nie robi
`tekstures` |
`htex4ht` | htex4ht.def
`dvipdf` | hdifpdf.def -- dla programu Lesenko
`dvipdfm` | dla programu dvipdfm
`nativepdf` | hdvips.def pdfmark.def -- dla `dvips`'a
`pdfmark` | synonim do `dvips`ef
`dvips` | `dvips`
`hypertex` | `xdvi`, `dvips` (z opcją `-z`) i `OzTeX`
`dviwindo` | windowsowa przeglądarka Y&Y (włącza opcję `colorlinks`)
`latex2html` | skrypt perlowy `latex2html`
`ps2pdf` | przetwarzanie `Ghostscript`-em
`dvipsone` | `dvipsone`

#### Opcje związane z zakresem hiperodwołań

Opcja (po `=` wartość domyślna) | Opis
--- | ---
`extension={`???`}` | ciąg znaków dodawany do nazwy zbioru określonego przez polecenie (związany z funkcją pakietu `xr` -- znak `.` dodawany jest automatycznie)
`hyperfigures={`false`}` | ???????? p. `hyperimages`
`backref={`false`}` | jeżeli po każdej pozycji bibliograficznej wystąpi pusta linia to dodawana jest lista numerów sekcji (section) w których występowało powołanie się tę pozycję bibliograficzną (opcje `backref` i `pagebackref` nie mogą być razem aktywne)
`pagebackref{`false`}` | na końcu każdej pozycji bibliograficznej dodawana jest lista stron na których wystąpiło powołanie się na tę pozycję (opcje `backref` i `pagebackref` nie mogą być razem aktywne)
`linktocpage={`false`}` | odsyłaczem (polem aktywnym) w spisie staje się numer strony, a nie tytuł
`hyperindex={`true`}` | ????? włącza/wyłącza realizację hiperodwołań dla pozycji skorowidza
`colorlinks={`false`}` | włącza/wyłącza kolorowanie odsyłaczy (jeśli `true` dołączany jest pakiet `color`)
`linkcolor={`red`}` | kolor czcionki wyświetlania normalnych odsyłaczy
`anchorcolor={`black`}` | miejsca etykietowane są wyświetlane czcionką o tym kolorze
`citecolor={`green`}` | kolor czcionki wyświetlania odsyłacza do bibliografii
`filecolor={`cyan`}` | kolor czcionki dla odsyłacza do zbioru -- (polecenie `href` odwołujące się do zbioru)
`menucolor={`red`}` | kolor czcionki wyświetlania menu przeglądarki PDF-ów
`pagecolor={`red`}` | nie zauważyłem skutków działania -- wydaje się być nieużywana
`urlcolor={`magenta`}` | kolor czcionki wyświetlania odsyłacza do dokumentu internetowego
`bookmarks={`true`}` | jest generowany i dołączany zbiór definiujący zakładki (jeżeli wartość opcji jest `false` to nie jest on dołączany mimo, że już istnieje)
`bookmarksopen={`false`}` | włącza/wyłącza rozwijanie wszystkich poziomów zakładek
`bookmarksnumbered={`false`}` | w zakładkach pojawią się również numery rozdziałów, a nie tylko tytuły
`bookmarksopenlevel={`\maxdimen`}` | ???? określa poziom rozwinięcia zakładek po załadowaniu dokumentu; wartością parametru jest liczba (a nie długość) określająca poziom i nie wiem dlaczego wartością domyślną jest `/maxdimen`
`pdfhighlight={`/I`}` | zmienia sposób stylizacji ,,przycisków'' przy ich ,,naciśnięciu'' (`/I` -- inwersja, `/N` -- bez zmian, `/O` -- outline, `/P` -- podświetlenie)
`citebordercolor={`0 1 0`}` | kolor (`RGB`; nie może być użyta nazwa TeX-owa) ramki obejmującej pozycję cytowaną (aktywna jeśli wyłączona jest opcja `colorlinks`)
`filebordercolor={`0 .5 .5`}` | kolor (`RGB`; nie może być użyta nazwa TeX-owa) ramki obejmującej opis odsyłacza do zbioru (aktywna jeśli wyłączona jest opcja `colorlinks`)
`linkbordercolor={`1 0 0`}` | kolor (`RGB`; nie może być użyta nazwa TeX-owa) ramki obejmującej opis odsyłacza (aktywna jeśli wyłączona jest opcja `colorlinks`)
`menubordercolor={`1 0 0`}` | kolor (`RGB`; nie może być użyta nazwa TeX-owa) ramki obejmującej opis menu definiowanego poleceniem `AcrobatMenu` (aktywna jeśli wyłączona jest opcja `colorlinks`)
`pagebordercolor={`1 1 0`}` | kolor (`RGB`; nie może być użyta nazwa TeX-owa) ramki opisu odsyłacza dla polecenia `PDFPage` (aktywna jeśli wyłączona jest opcja `colorlinks`)
`urlbordercolor={`0 1 1`}` | kolor (`RGB`; nie może być użyta nazwa TeX-owa) ramki obejmującej opis odsyłacza do adresu definiowanego przez polecenie `url` (aktywna jeśli wyłączona jest opcja `colorlinks`)
`pdfborder={`0 0 1`}` | kolor ramki (`RGB`; nie może być użyta nazwa TeX-owa) otaczającej opis odsyłacza dla poleceń `PDFNextPage`, `PDFPreviousPage` i `PDFPage` (aktywna jeśli wyłączona jest opcja `colorlinks`)

#### Opcje sterujące przeglądarką pdf-ów

`baseurl={???}` | nie zauważyłem skutków działania
`pdfpagemode={`UseOutlines`}` | ustawia tryb pracy przeglądarki; może przyjmować następujące wartości: `FullScreen` dokument zajmuje całą stronę okna przeglądarki `None` używane są ustawienia standardowe przeglądarki `UseThumbs` pokazywane są miniatury stron `UseOutlines` widoczne są zakładki
`pdftitle={tytuł}` | tytuł dokumentu -- pojawia się w ,,document info'' przeglądarki PDF-ów
`pdfauthor={autor}` | autor dokumentu -- pojawia się w ,,document info'' przeglądarki PDF-ów
`pdfsubject={opis}` | pojawia się w ,,document info'' przeglądarki PDF-ów
`pdfcreator={`LaTeX with hyperref package}}``
| program za pomocą którego został utworzony zbiór -- pojawia się w ,,document info'' przeglądarki PDF-ów
`pdfproducer={`dvips + Distiller}}``
| program który wygenerował PDF-a (może być inna wartość; zależy to od użytych deklaracji driverów) -- pojawia się w ,,document info'' przeglądarki PDF-ów
`pdfkeywords={słowa kluczowe}` | lista słów kluczowych pojawia się w ,,document info'' przeglądarki PDF-ów
`pdfview={`FitBH`}` | ???
`pdfstartpage={`1`}` | numer strony początkowej, pokazywanej przez przeglądarkę PDF-ów
`pdfstartview={`Fit`}` | ???
`pdfpagescrop={n n n n}` | ?????
`pdfcenterwindow={`False`}` | strona dokumentu powinna być wycentrowana w oknie przeglądarki????
`pdffitwindow={`false`}` | strona dokumentu jest skalowana tak, aby maksymalnie wypełnić okno przeglądarki

1Wydaje mi się, że w tym miejscu może wystąpić jedynie nazwa zbioru lokalnego
2 Uwaga! błąd. Standardowym rozszerzeniem jest `.pdf` -- dodawane jest również rozszerzenia określone przez parametr `extension` (domyślnie `.pdf`); tak więc użyta zostanie nazwa document`.pdf.pdf`

Włodzimierz Macewicz

Ostatnie zmiany: 05.05.2014.