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

In article <41371b3e$1@news.povray.org> , Christian Walther 
<cwa### [at] gmxch>  wrote:

> 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).

Thanks for pointing this out!

> 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".

Ah yes, this is an artifact of the documentation creation process which uses
these relative pathes.  I suppose adding a note to the TeX documentation
will have to do for this as it would make the doc building even more complex
when two TeX documents would need to be generated and validated, sorry!

> 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.

We are very well aware of the hyperref package.  As we explicitly state on
the download page, the PDF and PostScript versions of the documentation are
for *printing*.  The printable documentation should obviously not be
cluttered with useless hyperlinks that also destroy the printed version's
layout.

> 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.

PDF is a document format designed for printing and not for viewing. As such,
usability problems of Adobe Acrobat Reader and similar products when trying
to use PDFs for on screen viewing should be reported to their developers,
not us.

HTML is a hypertext format and if you desire hypertext navigation you should
be using the HTML version, not the documentation for printing! :-)

> I just downloaded the POV-Ray 3.6.1 PDF documentation, which I prefer
> over the HTML version because it's easier to search,

The Windows and Macintosh HTML documentation is fully searchable by the
respective system help viewers.

    Thorsten

____________________________________________________
Thorsten Froehlich, Duisburg, Germany
e-mail: tho### [at] trfde

Visit POV-Ray on the web: http://mac.povray.org

Post a reply to this message

in news:41371b3e$1@news.povray.org Christian Walther wrote:

> 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: 
> [...]

Christian,

The PDF's of the documentation are intendet for printing only, as each 
official distribution comes with a "platform specific" help file for on-
screen use. This is the reason why the first two points in your comment 
are the way they are. I doubt they will be changed.

I'll have a look at the two last points.

Thanks,

Ingo

Post a reply to this message

Thorsten Froehlich wrote:
> We are very well aware of the hyperref package.  As we explicitly state on
> the download page, the PDF and PostScript versions of the documentation are
> for *printing*.  The printable documentation should obviously not be
> cluttered with useless hyperlinks that also destroy the printed version's
> layout.

How do the hyperlinks destroy the layout? As far as I see my hyperlinked 
version of the PDF looks exactly the same as your non-hyperlinked.

> PDF is a document format designed for printing and not for viewing. As such,
> usability problems of Adobe Acrobat Reader and similar products when trying
> to use PDFs for on screen viewing should be reported to their developers,
> not us.

I should report to Apple that Preview doesn't magically invent the 
bookmarks and hyperlinks that aren't present in the PDF? :)

And, well, I probably wouldn't be using the PDF docs if I had to use 
Adobe Reader. But Preview is nice. :)

> The Windows and Macintosh HTML documentation is fully searchable by the
> respective system help viewers.

Ah, right, didn't think of that. I always used a web browser, not Help 
Viewer. Though I think I still like searching in Preview better than in 
Help Viewer.

Anyway, I'm fine with your decisions. After all, I can still use my own 
hyperlinked and bookmarked version of the PDF. Just keep the TeX source 
available...

  -Christian

Post a reply to this message

Thorsten Froehlich wrote:
> 
> The Windows and Macintosh HTML documentation is fully searchable by the
> respective system help viewers.

And on all other systems you can use:

http://www.tu-bs.de/%7Ey0013390/povdoc/index.html


Christoph

-- 
POV-Ray tutorials, include files, Sim-POV,
HCR-Edit and more: http://www.tu-bs.de/~y0013390/
Last updated 06 Jul. 2004 _____./\/^>_*_<^\/\.______

Post a reply to this message