I just downloaded the POV-Ray 3.6.1 PDF documentation, which I prefer 
over the HTML version because it's easier to search, and found a few 
points that I didn't like. So I downloaded the TeX source and fixed them:

o There are no PDF bookmarks for the table of contents, and no 
hyperlinks from the table of contents and the index to the text. This 
can be fixed by using the hyperref package (together with pdftex, which 
you seem to be using as well - I didn't test whether it works with 
tex+dvips+ghostscript). This package would also allow including the 
in-text hyperlinks, but these are not in the TeX source, so that would 
have to be added to your master-to-TeX script. There are lots of 
additional options in hyperref that I didn't use, see its documentation.

o I don't like the roman page numbers for the front matter. They're fine 
for printed books, but for on-screen navigation they are a little 
annoying because they make the printed page numbers go out of sync with 
the PDF page numbers. So I removed them. (Of course that's my personal 
opinion, and if yours is different, you may just as well leave them in.)


Two problems that I ran into while TeXing, and that were easily fixed:

o In the section "Photon Tips", there are two nested itemize 
environments, and TeX doesn't seem to like that. That's probably a bug 
in the master source, as it also occurs in the HTML version (but there 
it doesn't cause any problems).

o The paths for the figures don't match the actual directory structure 
in the downloaded ZIP file. They are like 
"../final/tex/images/reference/gamma" when they should be like 
"images/reference/gamma".


Here are the actual changes I made to reference-a4.tex (should be easily 
adapted to the us-letter format and the tutorial):

----8<----------------------------------
diff -u old/reference-a4.tex new/reference-a4.tex
--- old/reference-a4.tex        Sun Aug  1 13:47:06 2004
+++ new/reference-a4.tex        Thu Sep  2 14:11:14 2004
@@ -69,6 +69,7 @@
  \usepackage{fancyhdr}
  \usepackage{graphicx}
  \usepackage[latin1]{inputenc}
+\usepackage[a4paper, pdftex, hyperindex, bookmarksnumbered, 
pdfborder=false]{hyperref}

  \makeindex

@@ -118,7 +119,7 @@
  \date{for POV-Ray Version 3.6.1}


-\title{POV-\discretionary{}{}{}Ray Reference} \pagenumbering{roman} 
\maketitle \tableofcontents \listof{figure}{Figures} 
\listof{table}{Tables} \cleardoublepage \pagenumbering{arabic}
+\title{POV-\discretionary{}{}{}Ray Reference} \maketitle 
\tableofcontents \listof{figure}{Figures} \listof{table}{Tables} 
\cleardoublepage

  \clearpage \chapter{Introduction}

@@ -23657,7 +23658,7 @@
  % reference/000327.html


-\begin{itemize}
+%\begin{itemize}

   \begin{itemize}

@@ -23681,7 +23682,7 @@

   \end{itemize}

-\end{itemize}
+%\end{itemize}

  \subsection{Advanced Techniques}

----8<----------------------------------

What do you think? Any chances of adding any of these to the official docs?

  -Christian

Post a reply to this message