doc/latex

git-svn-id: svn://tug.org/texlive/trunk@84 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 396 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/hyperref/README b/Master/texmf-dist/doc/latex/hyperref/README
new file mode 100644
index 00000000000..4baa2d9454b
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/hyperref/README
@@ -0,0 +1,396 @@
+README for hyperref bundle 2003/07/27
+
+TABLE OF CONTENTS
+=================
+
+Introduction
+Download
+Installation
+Additional Packages
+New Features
+Package Compatibility
+Hints
+Authors/Maintainers
+Bugreports
+Known Problems
+ToDo
+
+
+INTRODUCTION
+============
+
+This package is used to emend cross-referencing commands in LaTeX to
+produce some sort of \special commands; there are backends for the
+\special set defined for HyperTeX dvi processors, for embedded pdfmark
+commands for processing by Acrobat Distiller (dvips and dvipsone), for
+dviwindo, for pdfTeX, for TeX4ht, and for VTEX's pdf and HTML
+backends.
+
+Included are:
+
+  a) `backref' a package by David Carlisle to provide links back from
+     bibliography to the main text; these are hypertext links after using
+     hyperref.
+  b)  `nameref' a package to allow reference to the *names* of sections rather
+     than their numbers.
+
+Sebastian Rahtz <sebastian.rahtz@oucs.ox.ac.uk>
+Heiko Oberdiek <oberdiek@ruf.uni-freiburg.de>
+
+December 1994-March 2002
+
+DOWNLOAD
+========
+
+`hyperref' is available on CTAN:
+  CTAN:macros/latex/contrib/supported/hyperref/
+
+`CTAN:' means one of the `Comprehensive TeX Archive Network'
+nodes or one of its mirrors.  This is explained in
+  http://www.tex.ac.uk/cgi-bin/texfaq2html?label=archives
+
+The files are organized in three, sometimes four directories:
+  ./
+    Root directory that contains `README', `.dtx',
+    and `.ins' files.
+  doc/
+    Directory for documentation files.
+  test/
+    Directory for some test files.
+  beta/
+    Sometimes this directory exists and contains
+    the latest beta/test versions of some files,
+    often `hyperref.dtx'.
+
+The main repository of hyperref is located at the server
+of the international `TeX User Group' (TUG). The hyperref
+directory at the TUG server
+  http://www.tug.org/applications/hyperref/
+contains the following files:
+  hyperref.zip
+  hyperref-doc.zip
+  hyperref-test.zip
+  hyperref-beta.zip
+    The files of the four directories, described above, are
+    packed into four ZIP archives, so that they can be easily
+    downloaded. (The ZIP files do not contain directories.)
+
+  manual.html
+  manual2.html
+  manual.css
+    HTML version of the quite old hyperref manual in `doc/manual.pdf'.
+
+The CTAN stuff will be mirrored automatically from the
+ftp server, so
+  ftp://ftp.tug.org/pub/tex/hyperref/
+corresponds to
+  CTAN:macros/latex/contrib/supported/hyperref/
+
+INSTALLATION
+============
+
+a) Download the hyperref files from CTAN or the TUG server.
+   If necessary, unpack them.
+b) Replace the files by the counterparts in the beta directory,
+   if you want to use the latest versions.
+c) Generate the package and driver files:
+     tex hyperref.ins
+d) Install the files `*.sty', `*.def', and `*.cfg' in your TDS tree:
+     cp *.sty *.def *.cfg .../texmf/tex/latex/hyperref/
+   Replace `...' by the prefix of your TDS tree.
+e) Update the databases if necessary, eg. for teTeX:
+     mktexlsr .../texmf
+
+ADDITIONAL PACKAGES
+===================
+
+Depending on the driver, hyperref loads other packages:
+* url.sty
+    CTAN:macros/latex/contrib/other/misc/url.sty
+* keyval.sty, color.sty:
+    CTAN:macros/latex/required/graphics/
+  An uptodate pdftex.def is available at
+    http://www.tug.org/applications/pdftex/pdftex.def
+    CTAN:macros/pdftex/graphics/pdftex.def
+
+NEW FEATURES
+============
+
+* Default driver setting (hyperref >= 6.72s).
+  If no driver is given, hyperref tries its best to guess the
+  most suitable driver. Thus it loads "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 "hypertex" is loaded that supports the
+  HyperTeX features that are recognized by xdvi for example.
+  This behaviour, however, can easily changed in the configuration
+  file "hyperref.cfg":
+    \providecommand*{\Hy@defaultdriver}{hdvips}
+  for dvips, or
+    \providecommand*{\Hy@defaultdriver}{hypertex}
+  for the default behaviour of hyperref.
+
+PACKAGE COMPATIBILITY
+=====================
+
+Currently only package loading orders are available:
+
+algorithm:
+  \usepackage{hyperref}
+  \usepackage[chapter]{algorithm}% eg.
+
+babel/magyar.ldf: unsupported
+  magyar.ldf's redefinitions of many LaTeX internals conflict
+  with hyperref's redefinitions of these commands.
+
+cite:
+  This is from Mike Shell:
+> cite.sty cannot currently be used with hyperref.
+> However, I can do a workaround via:
+>
+> \makeatletter
+> \def\NAT@parse{\typeout{This is a fake Natbib command to fool Hyperref.}}
+> \makeatother
+>
+> \usepackage[hypertex]{hyperref}
+>
+> 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).
+
+dblaccnt:
+  pd1enc.def or puenc.def should be loaded before:
+  \usepackage{hyperref}
+  \usepackage{dblaccnt}
+  or see entry for "vietnam".
+
+easyeqn: not compatible, breaks.
+
+float:
+  \usepackage{float}
+  \usepackage{hyperref}
+  
+  * Several \caption commands are not supported inside one float object.
+  * Anchor are set at top of the float object, if its style is controlled
+    by float.sty.
+
+footnote:
+  This package is not supported, you have to disable hyperref's footnote
+  support by using option "hyperfootnotes=false".
+
+IEEEtran.cls:
+  version >= V1.6b (because of \@makecaption, see ChangeLog)
+
+lastpage: compatible
+
+linguex:
+  \usepackage{hyperref}
+  \usepackage{linguex}
+
+ltabptch:
+  \usepackage{longtable}
+  \usepackage{ltabptch}
+  \usepackage{hyperref}
+
+minitoc-hyper:
+  This package is obsolete, use the uptodate original
+  package minitoc instead.
+
+natbib:
+  \usepackage{natbib}
+  \usepackage{hyperref}
+
+nomencl:
+Example for introducing links for the page numbers:
+\renewcommand*{\pagedeclaration}[1]{\unskip, \hyperpage{#1}}
+
+prettyref:
+%%% 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 %%%
+
+ntheorem:
+  ntheorem-hyper.sty is an old patched version of ntheorem.sty.
+  Newer versions of ntheorem know the option hyperref:
+  \usepackage{hyperref}
+  \usepackage[hyperref]{ntheorem}
+
+setspace:
+  \usepackage{setspace}
+  \usepackage{hyperref}
+
+sidecap before 2002/05/24 v1.5h:
+  \usepackage{nameref}
+  \usepackage{hyperref}
+  \usepackage{sidecap}
+
+subfigure 1995/03/06 v2.0:
+  \usepackage{subfigure}
+  \usepackage{hyperref}
+  % hypertexnames is set to false.
+subfigure v2.1:
+  \usepackage{nameref}
+  \usepackage{subfigure}
+  \usepackage{hyperref}
+  or
+  \usepackage{hyperref}
+  \usepackage{subfigure}
+subfigure v2.1.2:
+  please update
+subfigure v2.1.3:
+  \usepackage{hyperref}
+  \usepackage{subfigure}
+  or vice versa?
+
+titleref:
+  \usepackage{nameref}
+  \usepackage{titleref}% without usetoc
+  \usepackage{hyperref}
+
+titlesec:
+  "nameref" supports titlesec, but hyperref does not
+  (unsolved is the anchor setting, missing with unnumbered
+  section, perhaps problems with page breaks with numbered ones).
+
+varioref:
+  \usepackage{nameref}
+  \usepackage{varioref}
+  \usepackage{hyperref}
+
+vietnam:
+  % pd1enc.def should be loaded before package dblaccnt:
+  \usepackage[PD1,OT1]{fontenc}
+  \usepackage{vietnam}
+  \usepackage{hyperref}
+
+
+HINTS
+=====
+
+* Index with makeindex
+  * Package hyperref adds \hyperpage commands by the encap
+    mechanism, if option hyperindex is set (default).
+    \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 \frontmatter, \romannumbering, ...),
+    then the page anchors are not unique. Therefore option
+    "plainpages=false" is recommended.
+  * The encap mechanism of hyperref allows one command only.
+    If the user sets such a command, hyperref suppresses its
+    \hyperpage command. With logical markup this situation
+    can easily solved:
+      \usepackage{makeidx}
+      \makeindex
+      \usepackage[hyperindex]{hyperref}
+      \newcommand*{\main}[1]{\textbf{\hyperpage{#1}}}
+      ...
+      \index{Some example|main}
+  * Other encap characters can be set by option "encap".
+    Example for use of "?":
+      \usepackage[encap=?]{hyperref}
+  * An other possibility is the insertion of \hyperpage by
+    a style file for makeindex. For this case, hyperref's
+    insertion will be disabled by "hyperindex=false".
+    \hyperpage will be defined regardless of setting of hyperindex.
+
+%%% 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 %%%
+
+* Warning "bookmark level for unknown <foobar> defaults to 0".
+  Getting rid of it:
+
+\makeatletter
+\providecommand*{\toclevel@<foobar>}{0}
+\makeatother
+
+* 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 cases, try package "hypcap.sty" that implements
+  a method to circumvent the problem.
+
+
+AUTHORS/MAINTAINERS
+===================
+
+* Sebastian Rahtz <sebastian.rahtz@computing-services.oxford.ac.uk>
+* Heiko Oberdiek <oberdiek@uni-freiburg.de>
+
+
+BUGREPORTS
+==========
+
+A bug report should contain:
+* Comprehensive problem description. This includes error or
+  warning messages.
+  * \errorcontextlines=\maxdimen can be added in the TeX code
+    to get more informations in TeX error messages.
+* Minimal test file that shows the problem, but does not
+  contain any unnecessary packages and code.
+* Used drivers/programs.
+* Version information about used packages and programs.
+  * If you are using LaTeX, then add "\listfiles" to get
+    a list of version informations at the end of the
+    LaTeX run.
+* Please no other files than the minimal test file.
+  The other files .log, .dvi, .ps, .pdf are seldom necessary,
+  so send them only on request.
+
+Bug address: Heiko Oberdiek <oberdiek@uni-freiburg.de>
+
+
+KNOWN PROBLEMS
+==============
+
+* (half-done) hyper images (link from thumbnail in text)
+* Relative links are not sorted out or documented well.
+  For PDF generation:
+  * With baseurl: all links are considered relative to this URL.
+  * Without baseurl: a relative link without "file:" can be
+    achieved by:
+      \begingroup
+        \hypersetup{linkfileprefix={}}%
+        \href{../foo/bar.html}{bar.html}
+      \endgroup
+* ...
+
+TODO
+====
+
+* modules
+* bookmark organisation
+* documentation
+* PDF threads
+* more for PDF forms
+  * per object setting
+  * vary gap between text and box
+* better color interface for *bordercolor options
+* ...