README for hy­per­ref bun­dle

2019-06-12

INTRODUCTION

This pack­age is used to emend cross-ref­er­enc­ing com­mands in LaTeX to pro­duce some sort of spe­cial com­mands; there are back­ends for the spe­cial set de­fined for HyperTeX dvi pro­ces­sors, for em­bed­ded pdf­mark com­mands for pro­cess­ing by Acro­bat Dis­tiller (dvips and dvip­sone), for dvi­windo, for pdfTeX, for dvipdfm, for TeX4ht, and for VTEX's pdf and HTML back­ends.

In­cluded are:

1. hyperef' The main hyperlinking functionality.
2. backref' a package by David Carlisle to provide links back from bib­li­og­ra­phy to the main text; these are hy­per­text links af­ter us­ing hy­per­ref.
3. nameref' a pack­age to al­low ref­er­ence to the names of sec­tions rather than their num­bers.

DOWNLOAD

hyperref' is available on CTAN: CTAN:macros/la­tex/con­trib/hy­per­ref/

Also a ZIP file is pro­vided that con­tains the files, al­ready sorted in a TDS tree: CTAN:in­stall/macros/la­tex/con­trib/hy­per­ref.tds.zip

"CTAN:" means one of the Comprehensive TeX Archive Network'nodes or one of its mir­rors. This is ex­plained in https://tex­faq.org/FAQ-archives

The main repos­i­tory of hy­per­ref is lo­cated at github https://github.com/ho-tex/hy­per­ref

INSTALLATION

In­stal­la­tion with ZIP file in TDS for­mat

The ZIP file hyperref.tds.zip' contains the files sortedin a TDS tree. Thus you can di­rectly un­pack the ZIP file in­side a TDS tree. (See CTAN:tds.zip for an ex­pla­na­tion of TDS.) Ex­am­ple:

  cd /...somewhere.../texmf
  unzip /...downloadpath.../hyperref.tds.zip

Do not for­get to re­fresh the file name database of this TDS tree, Ex­am­ple:

  texhash /...somewhere.../texmf

Man­ual in­stal­la­tion

1. Down­load the hy­per­ref files from CTAN or the TUG server. If nec­es­sary, un­pack them.
2. If di­rec­tory beta' exists, replace the files by the counterparts in this di­rec­tory, if you want to use the lat­est ver­sions.
3. Gen­er­ate the pack­age and driver files: tex hy­per­ref.ins
4. In­stall the files *.sty', .def', and *.cfg' in your TDS tree: cp .sty .def .cfg TDS:tex/la­tex/hy­per­ref/ Re­place TDS:' by the prefix of your TDS tree (texmf directory). The ex­cep­tion is bmhy­doc.sty, it be­longs to the source files (TDS:source/la­tex/hy­per­ref/).
5. Copy the doc­u­men­ta­tion files to "TDS:doc/la­tex/hy­per­ref/": man­ual.pdf, README.md, ChangeLog.txt, slides.pdf, pa­per.pdf, op­tions.pdf, hy­per­ref.pdf, back­ref.pdf, nameref.pdf (Also the HTML ver­sion of the man­ual can be put there.)
6. Up­date the databases if nec­es­sary, eg. for teTeX: mk­texlsr .../texmf

## AUTHORS/MAINTAINERS

• Se­bas­tian Rahtz (died 2016)
• Heiko Oberdiek
• David Carlisle (via GitHub ho-tex ori­g­an­i­sa­tion)

BUG REPORTS

A bug re­port should con­tain:

• Com­pre­hen­sive prob­lem de­scrip­tion. This in­cludes er­ror or warn­ing mes­sages.
  • er­ror­con­textlines=maxdi­men can be added in the TeX code to get more in­for­ma­tions in TeX er­ror mes­sages.
• Min­i­mal test file that shows the prob­lem, but does not con­tain any un­nec­es­sary pack­ages and code.
• Used drivers/pro­grams.
• Ver­sion in­for­ma­tion about used pack­ages and pro­grams.
  • If you are us­ing LaTeX, then add "list­files". Then a list of ver­sion in­for­ma­tions is printed at the end of the LaTeX run.
• Please no other files than the min­i­mal test file. The other files .log, .dvi, .ps, .pdf are sel­dom nec­es­sary, so send them only on re­quest.

## Bug ad­dress

A bug tracker is avail­able at github: https://github.com/ho-tex/oberdiek/is­sues

Al­ter­na­tively bug re­ports can be send to the sup­port group pub­lic email list: <ho-tex at tug dot org>

Viet­namese part

Re­spon­si­ble for the Viet­namese trans­la­tions of the au­toref names and pu­vnenc.def are: Han The Thanh <han­thethanh at gmail dot com> Rein­hard Ko­tucha <rein­hard dot ko­tucha at web dot de>

Ara­bic part

Re­spon­si­ble for the ad­di­tions to PU en­cod­ing for Arabi is Youssef Jabri <yjabri at ensa dot univ-ou­jda dot ac dot ma>

KNOWN PROBLEMS

• (half-done) hy­per im­ages (link from thumb­nail in text)
• Rel­a­tive links are not sorted out or doc­u­mented well. For PDF gen­er­a­tion:
  • With baseurl: all links are con­sid­ered rel­a­tive to this URL.
  • Without baseurl: a rel­a­tive link with­out "file:" can be achieved by:

    \begingroup
      \hypersetup{linkfileprefix={}}%
      \href{../foo/bar.html}{bar.html}
    \endgroup
    

• ...

TODO

• mod­ules
• book­mark or­gan­i­sa­tion
• doc­u­men­ta­tion
• PDF threads
• more for PDF forms
  • per ob­ject set­ting
  • vary gap be­tween text and box
• PostScript driver: the cur­rent im­ple­men­ta­tion doesn't relly sup­port nested links. The start po­si­tions should be re­mem­bered in a stack, but there are com­pli­ca­tions with page breaks.
• ...

VERSIONS IN TEX DISTRIBUTIONS