manual.tex

latex学习例子

% This is the manual for the LaTeX hyperref package.
%
% Copyright (C) 1998, 2003 Sebastian Rahtz.
%
% Permission is granted to copy, distribute and/or modify this document
% under the terms of the GNU Free Documentation License, Version 1.1 or
% any later version published by the Free Software Foundation; with no
% Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
% Texts.  A copy of the license is included in the section entitled
% ``GNU Free Documentation License.''

\RequirePackage{ifpdf}
\ifpdf % We are running pdfTeX in pdf mode
\documentclass[pdftex]{article}
\else
\documentclass{article}
\fi

% Page layout.
\advance\textwidth by 1.1in
\advance\oddsidemargin by -.55in
\advance\evensidemargin by -.55in
%
\advance\textheight by 1in
\advance\topmargin by -.5in
\advance\footskip by -.5in
%
\pagestyle{headings}
%
% Avoid some overfull boxes.
\emergencystretch=.1\hsize
\hbadness = 3000

% these are from lshort.sty, but lshort.sty pulls in so many other
% packages it seems cleaner to just include them here.
%
\newcommand{\bs}{\symbol{'134}}%Print backslash
\newcommand{\ci}[1]{\texttt{\bs#1}}

\makeatletter
\@ifpackageloaded{tex4ht}{%
  % separate definition for HTML case to avoid
  % nasty borders with double horizontal lines with
  % large gaps.
  \newsavebox{\cmdsyntaxbox}%
  \newenvironment{cmdsyntax}{%
    \par
    % \small
    \addvspace{3.2ex plus 0.8ex minus 0.2ex}%
    \vskip -\parskip
    \noindent
    \begin{lrbox}{\cmdsyntaxbox}%
      \begin{tabular}{l}%
        \rule{0pt}{1em}%
        \ignorespaces
  }{%
      \end{tabular}%
    \end{lrbox}%
    \fbox{\usebox{\cmdsyntaxbox}}%
    \par
    \nopagebreak
    \addvspace{3.2ex plus 0.8ex minus 0.2ex}%
    \vskip -\parskip
  }%
}{%
  \newenvironment{cmdsyntax}{%
    \par
    \small
    \addvspace{3.2ex plus 0.8ex minus 0.2ex}%
    \vskip -\parskip
    \noindent
    \begin{tabular}{|l|}%
      \hline
      \rule{0pt}{1em}%
      \ignorespaces
  }{%
      \\%
      \hline
    \end{tabular}%
    \par
    \nopagebreak
    \addvspace{3.2ex plus 0.8ex minus 0.2ex}%
    \vskip -\parskip
  }%
}
\makeatother

\usepackage{array,longtable}
\usepackage[T1]{fontenc}

\newcommand*{\Quote}[1]{\textquotedblleft#1\textquotedblright}

\def\Hanh{H\`an Th\^e\llap{\raise 0.5ex\hbox{\'{}}} Th\`anh}

\ifpdf
  \usepackage[%
    pdftex,%
    colorlinks,%
    hyperindex,%
    plainpages=false,%
    bookmarksopen,%
    bookmarksnumbered%
  ]{hyperref}
  %%?? \def\pdfBorderAttrs{/Border [0 0 0] } % No border arround Links
  \usepackage{thumbpdf}
\else
  \usepackage{hyperref}
\fi

\title{Hypertext marks in \LaTeX: a manual for \textsf{hyperref}}
\author{Sebastian Rahtz \and  Heiko Oberdiek}
% Manual updated by Steve Peter and Karl Berry, 7/03.
\date{February 2004}

\begin{document}

% comes out too close to the toc, and we know it's page one anyway.
\thispagestyle{empty}
\maketitle
\tableofcontents
\setcounter{tocdepth}{2}% for bookmark levels

\section{Introduction}

The package derives from, and builds on, the work of the Hyper\TeX\
project, described at \url{http://xxx.lanl.gov/hypertex/}. It extends
the functionality of all the \LaTeX\ cross-referencing commands
(including the table of contents, bibliographies etc) to produce
\verb|\special| commands which a driver can turn into hypertext links;
it also provides new commands to allow the user to write \emph{ad hoc}
hypertext links, including those to external documents and URLs.

This manual provides a brief overview of the \textsf{hyperref}
package. For more details, you should read the additional documentation
distributed with the package, as well as the complete documentation by
processing \texttt{hyperref.dtx}. You should also read the chapter on
\textsf{hyperref} in \textit{The \LaTeX\ Web Companion}, where you will
find additional examples.

The Hyper\TeX\ specification\footnote{This is borrowed from an article
by Arthur Smith.} says that conformant viewers/translators must
recognize the following set of \verb|\special| constructs:

\begin{description}
\item[href:] \verb|html:<a href = "href_string">|
\item[name:] \verb|html:<a name = "name_string">|
\item[end:] \verb|html:</a>|
\item[image:] \verb|html:<img src = "href_string">|
\item[base\_name:] \verb|html:<base href = "href_string">|
\end{description}

The \emph{href}, \emph{name} and \emph{end} commands are used to do the
basic hypertext operations of establishing links between sections of
documents. The \emph{image} command is intended (as with current HTML
viewers) to place an image of arbitrary graphical format on the page in
the current location. The \emph{base\_name} command is be used to
communicate to the DVI viewer the full (URL) location of the current
document so that files specified by relative URL's may be retrieved
correctly.

The \emph{href} and \emph{name} commands must be paired with an
\emph{end} command later in the \TeX\ file---the \TeX\ commands between
the two ends of a pair form an \emph{anchor} in the document. In the
case of an \emph{href} command, the \emph{anchor} is to be highlighted
in the \emph{DVI viewer}, and when clicked on will cause the scene to
shift to the destination specified by \emph{href\_string}. The
\emph{anchor} associated with a name command represents a possible
location to which other hypertext links may refer, either as local
references (of the form \verb|href="#name_string"| with the
\emph{name\_string} identical to the one in the name command) or as part
of a URL (of the form \emph{URL\#name\_string}). Here
\emph{href\_string} is a valid URL or local identifier, while
\emph{name\_string} could be any string at all: the only caveat is that
`$\verb|"|$' characters should be escaped with a backslash
($\backslash$), and if it looks like a URL name it may cause problems.

However, the drivers intended to produce \emph{only} PDF use literal
PostScript or PDF \verb|\special| commands. The commands are defined in
configuration files for different drivers, selected by package options;
at present, the following drivers are supported:

\begin{description}
\item[hypertex] DVI processors conforming to the Hyper\TeX\ guidelines (i.e.\ \textsf{xdvi}, \textsf{dvips} (with
the \textsf{-z} option), \textsf{OzTeX}, and \textsf{Textures})
\item[dvips] produces \verb|\special| commands tailored for \textsf{dvips}
\item[dvipsone] produces \verb|\special| commands tailored for \textsf{dvipsone}
\item[ps2pdf] a special case of output suitable for processing by earlier versions of Ghost\-script's
PDF writer; this is basically the same as that for \textsf{dvips}, but a few variations remained before version 5.21
\item[tex4ht] produces \verb|\special| commands for use with \textsf{\TeX4ht}
\item[pdftex] pdf\TeX, \Hanh{}'s \TeX{} variant that writes PDF directly
\item[dvipdf] produces \verb|\special| commands for the DVI to PDF driver \textsf{dvipdf}
\item[dvipdfm] produces \verb|\special| commands for Mark Wicks' DVI to PDF driver \textsf{dvipdfm}
\item[dviwindo] produces \verb|\special| commands that Y\&Y's Windows previewer interprets as hypertext jumps within the previewer
\item[vtex] produces \verb|\special| commands that MicroPress' HTML and
     PDF-producing \TeX\ variants interpret as hypertext jumps within the
     previewer
\item[textures] produces \verb|\special| commands that \textsf{Textures} interprets as hypertext jumps within the previewer
\end{description}

Output from \textsf{dvips} or \textsf{dvipsone} must be processed using
Acrobat Distiller to obtain a PDF file.\footnote{Make sure you turn off
the partial font downloading supported by \textsf{dvips} and
\textsf{dvipsone} in favor of Distiller's own system.} The result is
generally preferable to that produced by using the \textsf{hypertex}
driver, and then processing with \textsf{dvips -z}, but the DVI file is
not portable. The main advantage of using the Hyper\TeX\ \ci{special}
commands is that you can also use the document in hypertext DVI viewers,
such as \textsf{xdvi}.

\section{Implicit behavior}

This package can be used with more or less any normal \LaTeX\ document
by specifying in the document preamble

\begin{verbatim}
\usepackage{hyperref}
\end{verbatim}

Make sure it comes \emph{last} of your loaded packages, to give it a
fighting chance of not being over-written, since its job is to redefine
many \LaTeX\ commands. Hopefully you will find that all cross-references
work correctly as hypertext. For example, \ci{section} commands will
produce a bookmark and a link, whereas \ci{section*} commands will only
show links when paired with a corresponding \ci{addcontentsline}
command.

In addition, the \texttt{hyperindex} option (see below) attempts to make
items in the index by hyperlinked back to the text, and the option
\texttt{backref} inserts extra `back' links into the bibliography for
each entry. Other options control the appearance of links, and give
extra control over PDF output. For example, \texttt{colorlinks}, as its
name well implies, colors the links instead of using boxes; this is the
option used in this document.


\section{Package options}

All user-configurable aspects of \textsf{hyperref} are set using a
single `key=value' scheme (using the \textsf{keyval} package) with the
key \texttt{Hyp}. The options can be set either in the optional argument
to the \verb|\usepackage| command, or using the \verb|\hypersetup|
macro. When the package is loaded, a file \texttt{hyperref.cfg} is read
if it can be found, and this is a convenient place to set options on a
site-wide basis.

As an example, the behavior of a particular file could be controlled by:
\begin{itemize}

\item	a site-wide \texttt{hyperref.cfg} setting up the look of links,
adding backreferencing, and setting a PDF display default:

\begin{verbatim}
\hypersetup{backref,
pdfpagemode=FullScreen,
colorlinks=true}
\end{verbatim}

\item	A global option in the file, which is passed down to
\textsf{hyperref}:

\begin{verbatim}
\documentclass[dvips]{article}
\end{verbatim}

\item	File-specific options in the \verb|\usepackage| commands, which
override the ones set in \texttt{hyperref.cfg}:

\begin{verbatim}
\usepackage[pdftitle={A Perfect Day},colorlinks=false]{hyperref}
\end{verbatim}
\end{itemize}

Some options can be given at any time, but many are restricted: before
\verb|\begin{document}|, only in \verb|\usepackage[...]{hyperref}|,
before first use, etc.

In the key descriptions that follow, many options do not need a value,
as they default to the value true if used. These are the ones classed as
`boolean'. The values true and false can always be specified, however.

\subsection{General options}