POV-Ray : Newsgroups : povray.documentation.inbuilt : PDF docs enhancement Server Time: 19 Oct 2019 09:15:19 GMT
 PDF docs enhancement (Message 1 to 5 of 5)
 From: Christian Walther Subject: PDF docs enhancement Date: 2 Sep 2004 13:08:14 Message: <41371b3e$1@news.povray.org> 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   From: Thorsten Froehlich Subject: Re: PDF docs enhancement Date: 2 Sep 2004 17:42:35 Message: <41375b8b$1@news.povray.org>
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   From: ingo Subject: Re: PDF docs enhancement Date: 2 Sep 2004 17:50:07 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

 From: Christian Walther Subject: Re: PDF docs enhancement Date: 3 Sep 2004 08:39:31 Message: <41382dc3\$1@news.povray.org>
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

 From: Christoph Hormann Subject: Re: PDF docs enhancement Date: 3 Sep 2004 09:25:02 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 _____./\/^>_*_<^\/\.______