I prefer to use Acrobat Reader for viewing online documentation (it looks
prettier), so I have used pdftex to format all of our Gnu documentation
into PDF files. One thing that I find very annoying in all of them is that
all of the hyperlinks (both cross-references and bookmarks) send you to the
*bottom* of the page, rather than the start of the target material. (This
is most evident when the Reader's zoom factor shows less than half of the
page, or when in continuous page mode.)
I have found one fix for this problem which is so surprisingly simple, I
wonder why it was ever written incorrectly in the first place. In the main
output routine, call \pdfmkdest *before* writing out the rest of the page
instead of after!
*** /home/trevin/Gnu/texinfo-4.0/doc/texinfo.tex Sat Sep 25 08:31:21
1999
--- texinfo.tex Tue Mar 21 10:17:25 2000
***************
*** 214,219 ****
--- 214,222 ----
\normalturnoffactive % \ in index entries must not stay \, e.g., if
% the page break happens to be in the middle of an
example.
\shipout\vbox{%
+ % Moved from the bottom of the page
+ \ifpdfmakepagedest \pdfmkdest{\the\pageno} \fi
+ %
\ifcropmarks \vbox to \outervsize\bgroup
\hsize = \outerhsize
\vskip-\topandbottommargin
***************
*** 242,249 ****
\vskip 2\baselineskip
\unvbox\footlinebox
\fi
! %
! \ifpdfmakepagedest \pdfmkdest{\the\pageno} \fi
%
\ifcropmarks
\egroup % end of \vbox\bgroup
--- 245,252 ----
\vskip 2\baselineskip
\unvbox\footlinebox
\fi
! % Moved to the top of the page
! %\ifpdfmakepagedest \pdfmkdest{\the\pageno} \fi
%
\ifcropmarks
\egroup % end of \vbox\bgroup
Now the hyperlinks will take you to the top of the target page (well,
almost; it skips past the page headline.) It would still be better if the
link could take you to the start of the target text in the middle of a
page, but that looks like it would take a bit more effort to implement (or
even a change to pdftex).
I have one other annoyance: the link color. Cyan is simply too light to
read against a white background. Why not blue?
***************
*** 891,897 ****
\fi}
\def\pdfmkdest#1{\pdfdest name{#1@} xyz}
\def\pdfmkpgn#1{#1@}
! \let\linkcolor = \Cyan
\def\endlink{\Black\pdfendlink}
% Adding outlines to PDF; macros for calculating structure of outlines
% come from Petr Olsak
--- 894,900 ----
\fi}
\def\pdfmkdest#1{\pdfdest name{#1@} xyz}
\def\pdfmkpgn#1{#1@}
! \let\linkcolor = \Blue
\def\endlink{\Black\pdfendlink}
% Adding outlines to PDF; macros for calculating structure of outlines
% come from Petr Olsak
There is also a bug in the PDF outline: Any outline item containing an
underscore shows up as a bunch of texinfo codes ("@unhbox @kern.06em
@vbox{..."). This bug was remedied by the following addition to
\pdfmakeoutlines:
***************
*** 905,911 ****
--- 908,915 ----
\ifeof 1\else\bgroup
\closein 1
\indexnofonts
\def\tt{}
+ \def\_{\normalunderscore}
% thanh's hack / proper braces in bookmarks
\edef\mylbrace{\iftrue \string{\else}\fi}\let\{=\mylbrace
\edef\myrbrace{\iffalse{\else\string}\fi}\let\}=\myrbrace
One last item: It looks like texinfo has some capabilities for making a
two-level index defined internally, but has no external macros for authors
to make use of them. In attempting to use
@dosubind{index}{topic}{subtopic} directly, I discovered that texinfo was
*not* writing "\entry{sort}{page}{topic}{subtopic}" to the index file as it
should; instead, it was writing "\entry{sort}{page}{topic subtopic}", thus
creating a one-level index with extra-long names. I made a whole bunch of
changes in order to get this part to work as it seemed to be documented.
This may not be the best way to do it, but it works for me.
***************
*** 2857,2873 ****
% If third (subentry) arg is present, add it to the index
% string. And include a space.
\ifx\thirdarg\emptymacro \else
! \toks0 = \expandafter{\the\toks0 \space #3}%
\fi
%
% Set up the complete index entry, with both the sort key
% and the original text, including any font commands. We write
% three arguments to \entry to the .?? file, texindex reduces to
% two when writing the .??s sorted result.
! \edef\temp{%
! \write\csname#1indfile\endcsname{%
! \realbackslash entry{\indexsorttmp}{\folio}{\the\toks0}}%
! }%
%
% If a skip is the last thing on the list now, preserve it
% by backing up by \lastskip, doing the \write, then inserting
--- 2861,2885 ----
% If third (subentry) arg is present, add it to the index
% string. And include a space.
\ifx\thirdarg\emptymacro \else
! %\toks0 = \expandafter{\the\toks0 \space #3}%
! \toks1 = {#3}%
\fi
%
% Set up the complete index entry, with both the sort key
% and the original text, including any font commands. We write
% three arguments to \entry to the .?? file, texindex reduces to
% two when writing the .??s sorted result.
! \ifx\thirdarg\emptymacro
! \edef\temp{%
! \write\csname#1indfile\endcsname{%
! \realbackslash entry{\indexsorttmp}{\folio}{\the\toks0}}%
! }%
! \else
! \edef\temp{%
! \write\csname#1indfile\endcsname{%
! \realbackslash
entry{\indexsorttmp}{\folio}{\the\toks0}{\the\tok
s1}}%
! }%
! \fi
%
% If a skip is the last thing on the list now, preserve it
% by backing up by \lastskip, doing the \write, then inserting
The above change revealed a problem in \secondary: it did not output a PDF
link.
***************
*** 3089,3095 ****
\def\secondary #1#2{
{\parfillskip=0in \parskip=0in
\hangindent =1in \hangafter=1
! \noindent\hskip\secondaryindent\hbox{#1}\indexdotfill #2\par
}}
% Define two-column mode, which we use to typeset indexes.
--- 3101,3113 ----
\def\secondary #1#2{
{\parfillskip=0in \parskip=0in
\hangindent =1in \hangafter=1
! \noindent\hskip\secondaryindent\hbox{#1}\indexdotfill
! \ifpdf
! \pdfgettoks#2.\ \the\toksA % The page number ends the paragraph.
! \else
! #2% The page number ends the paragraph.
! \fi
! \par
}}
% Define two-column mode, which we use to typeset indexes.
