\ProvidesFile{hypertoc.tex}[2011/01/24 documenting hypertoc.sty]
\title{\textsf{hypertoc.sty}\\---\\Decent Links 
       in Tables of Contents\thanks{This 
       document describes version 
       \textcolor{blue}{\UseVersionOf{\jobname.sty}} 
       of \textsf{\jobname.sty} as of \UseDateOf{\jobname.sty}.}}
% \listfiles 
{ \RequirePackage{makedoc} \ProcessLineMessage{} 
  \MakeJobDoc{18}%                  %% 2011/01/23
  {\SectionLevelOneParseInput}  }
\documentclass{article}%% TODO paper dimensions!?
\input{makedoc.cfg} %% shared formatting settings
\usepackage{color}                  %% readprov in makedoc.cfg 2011/01/23
\sloppy
\begin{document}
\maketitle
\begin{abstract}\noindent
'hypertoc.sty' changes macros for the table of contents 
so that colored frames to indicate links look acceptable. 
In the present version, this is achieved by inserting struts 
and only addresses \LaTeX's standard 'article.cls'.
\end{abstract}

\tableofcontents

\section{Why}
By default, the 'hyperref' package highlights sectioning titles 
as printed in the table of contents (TOC) by red-framed boxes. 
It looks horrible, because of 
(\textit{i})~the aggressive color and 
(\textit{ii})~the irregular, ``random" shapes of the boxes.

To avoid this, it seems to be standard to use 'hyperref''s 
package option `[colorlinks]'. I don't like this either. 
It is confusing as to how the printed output will look like, 
the chosen color doesn't create a much more pleasant look; 
indeed, the publisher's graphical designer may have chosen 
colors for printing the table of contents---this design 
then is spoiled. 

Therefore I prefer (\textit{a})~choosing a more decent color 
and (\textit{b})~using struts so that the boxes have a more 
regular shape. 

In a publisher's package I even have found the idea 
to make a box for the entire TOC entry, including the page number. 
Then the frames look regular indeed, and you need less precision 
in moving the mouse for clicking at an entry. 
It would be nice if this could be integrated here later.

\section{Usage}
The file 'hypertoc.sty' is provided ready, installation only requires 
putting it somewhere where \TeX\ finds it 
(which may need updating the filename data 
 base).\footnote{\url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=inst-wlcf}}

Below the `\documentclass' line(s) and above `\begin{document}', 
you load 'hypertoc.sty' (as usually) by
\begin{verbatim}
  \usepackage{hypertoc}
\end{verbatim}

This controls the \emph{shapes} of the frames. 
The \emph{color} must be chosen by the 'hyperref' package option 
`[linkbordercolor]', I have used 
\[`linkbordercolor={1 .9 .7},'\]
---cf.~`makedoc.cfg'.

\section{The Package File}
The package essentially has just \emph{six} code lines at present.

\input{hypertoc.doc}
\end{document}

VERSION HISTORY

2011/01/23  for v0.1, very first
2011/01/24  \ProvidesFile date corrected