readme.txt for project thumbpdf 2000/01/19 v1.11 TABLE OF CONTENTS ================= A. Project thumbpdf B. Copyright, Disclaimer, Lizenz C. Files D. Requirements E. Installation F. User Interface G. Author H. Questions, Suggested Improvements I. Known Problems J. History A. PROJECT THUMBPDF ================== Support of thumbnails with pdfTeX, plain/LaTeX formats. Thumbnails are small images, pictograms or reduced images from the pages of a document. They support the navigation through the document, if the viewer supports it (e. g. AcrobatReader). There is a powerful program to generate pdf files: pdfTeX written by Han The Thanh. But there is no direct support for thumbnails (in the future?). The only way I found is, to include the thumbnails as images with \pdfimage. The guessed object number of this image can be used as thumbnail. However I do not want to set the thumbnails in the document visible or invisible (e. g. \maxdimen apart from the margin of the page). Secondly I do not want to guess any object numbers. So I developed this project `thumbpdf': 0. The user produces from his TeX source a PDF file. 1. Now the thumbnails (thumb???.png) are generated by ghostscript, if the user does not want to provide his own ones. 2. With pdfTeX a second pdf file (thumbpdf.pdf) is produced, which contains the thumbnails set by the \pdfimage command. The program `thumbpdf.tex' looks for files with names `thumb000.png' to `thumb999.png' and additional ones specified in `thumbopt.tex'. 3. Then the above generated pdf file is parsed to get the object representation of the thumbnails. This is written to a TeX readable file (thumbdta.tex). 4. If the user's TeX source include the package (thumbpdf.sty), the object data are read and inserted by the \pdfobject command. Now \pdflastobject reports the object number of the thumbnails. Before every shipout of a page the thumbnail for this page is specified in the page attributes. This is done automatically, so an user have to input the package only. B. COPYRIGHT, DISCLAIMER, LIZENZ ================================ Copyright (C) 1999 Heiko Oberdiek. This program may be distributed and/or modified under the conditions of the LaTeX Project Public License, either version 1.2 of this license or (at your option) any later version. The latest version of this license is in http://www.latex-project.org/lppl.txt and version 1.2 or later is part of all distributions of LaTeX version 1999/12/01 or later. C. FILES ======== The project `thumbpdf' consists of four files: thumbpdf.pl: The main program is a perl script. It * calls ghostscript to generate the thumbnails (1.), * calls pdfTeX to produce a thumbnail pdf file (2.), * parses this pdf file and writes the object represenation to `thumbdta.tex' (3.). thumbpdf.tex: A pdfTeX program to produce the thumbnail pdf file (2.). thumbpdf.sty: The package for the user to be included in his TeX source (4.) readme.txt: Documentation, the file you are reading. Following files are produced if `thumbpdf' is invoked: thumb???.png: The thumbnails in PNG format. They are numberd from `thumb001.png' until `thumb999.png'. (Is there a need to support more than 999 pages?) thumbpdf.pdf: The thumbnail pdf file (2.). thumbpdf.log: The protocol file of the pdfTeX run (2.). thumbdta.tex: The object representation of the thumbnails, the result of the perl script's parsing the file `thumbpdf.pdf' (3.). The user can also use additional thumbnails. These are specified in the file `thumbopt.tex'. D. REQUIREMENTS =============== * Perl5 (version 5 of the perl interpreter) * ghostscript with png devices is recommanded or the thumbnails have to be generated with other tools manually. (dos users: there is no precompiled one in the version 5.50, version 5.10 misses the png devices, see section Installation) * pdfTeX, of course. (Tested with versions 0.13a/0.13b). E. INSTALLATION =============== 1. TeX directory structure (TDS): The files `readme.txt' (documentation) `thumbpdf.tex' (pdftex) `thumbpdf.sty' (pdf(e)tex, pdf(e)latex, (e)tex, (e)latex) go to texmf/doc/pdftex/thumbpdf/readme.txt texmf/tex/generic/thumbpdf/thumbpdf.tex texmf/tex/generic/thumbpdf/thumbpdf.sty (These now definite places in the TDS tree are a result of a discussion with Thomas Esser, who supports them in his great teTeX 1.0). 2. Perl script `thumbpdf.pl': Unix * Your are allowed to rename `thumbpdf.pl' to `thumbpdf': mv thumbpdf.pl thumbpdf * Ensure that the execute permission is set: chmod +x thumbpdf * Move the file to a directory where the shell can find it (environment variable PATH, e.g. /usr/local/bin/). Dos/Windows/(OS2) * Running the perl interpreter directly with the perl script: perl thumbpdf.pl ... * Methods for calling by typing the script name without extension and perl interpreter: a) If your perl distribution provides a pl2exe program, use it to generate `thumbpdf.exe'. Advantage: I/O redirection works. b) A good method is a dos program of John Dallman: #!perl.exe (versions below 4) hbperl.exe (version 4) http://www.perl.com/CPAN/authors/id/JDALLMAN/hbp_403.zip Move thumbpdf.pl in a PERLLIB directory and copy the exe program to `thumbpdf.exe'. Then the program looks for the perl interpreter, the script and calls them. Advantage: I/O redirection works. c) Windows NT 4.0 users can use associated file types: SET PATHEXT=.pl;%PATHEXT% See perl win32 faq "How do I associate Perl scripts with perl?": http://www.activestate.com/support/faqs/win32/perlwin32faq4.html Disadvantage: I/O redirection does not work. d) 4DOS: SET .PL=c:/bin/perl.exe See perl win32 faq "How can I get Perl to run a Perl script at the 4DOS command line by typing the name of the script without the extension or "perl", just like a regular exe file?": http://www.activestate.com/support/faqs/win32/perlwin32faq1.html e) Convert the perl script to a batch file `thumbpdf.bat', if your distribution provides `pl2bat.bat'. Disadvantage: I/O redirection does not work. Many of this methods are listed in the perl win32 faq "What's the equivalent of the shebang ("#!") syntax for Win32?": http://www.activestate.com/support/faqs/win32/perlwin32faq4.html Dos * There is not a precompiled ghostscript interpreter for version 5.5, and version 5.10 misses the png devices. So you have to compile ghostscript for dos or you can use another program to generate the thumbnails (names: thumb001.png, thumb002.png, ...). The ghostscript step is skipped by omitting the filename: thumbpdf [options] Windows 3.1x with win32s * The png files can be produced with gswin32(c), but the means of the operating system to start windows programs with command line arguments are very poor. I found no way to invoke ghostscript via perl, so the thumbnails must be generated manually. F. USER INTERFACE ================= * Perl script `thumbpdf.pl' a) thumbpdf --help gives a help screen with the options and default values. b) thumbpdf [options] Without specifying a pdf file, the perl script thinks, the user have already generated his own thumbnails, so it let them unchanged and omits the ghostcript step. c) thumbpdf [options] Ghostscript is called to generate the thumbnails of the pdffile. * Package `thumbpdf.sty' a) pdf(e)tex (plain format): \input thumbpdf.sty b) pdf(e)latex (latex format): \usepackage{thumbpdf} \thisthumb{name} uses the thumbnail meantioned in `thumbopt.tex' for this page. * Additional thumbnails: `thumbopt.tex' If `thumbdta.tex' is found, the thumbnails are automatically included by the program `thumbpdf.tex'. Format of this file: \thumb{filename without `.png' extension}% or \thumb[name]{filename with/without extension} Examples: \thumb{one}% --> \thisthumb{one}, recommended \thumb{one.png}% --> \thisthumb{one.png} \thumb[two]{one}% --> \thisthumb{two} \thumb[one]{./extrathumb/one.png}% --> thisthumb{one} The first example shows that the `.png' extension is supported and recommended. But `.jpg' or `.tif' files also works. * Program `thumbpdf.tex' Execept for debugging there is no reason for an user to call it manually. But if so the number of the files to be looked for can be reduced, because it takes some time to test 1000 thumbnails if they exist. A maximum number can be specified before: pdftex \def\thumbmax{20}\input thumbpdf The highest thumbnail is now `thumb020.png'. Example: Addition of thumbnails for `example.tex': pdfelatex example % or pdf(e)(la)tex, whatever example needs. thumbpdf example pdfelatex example % example.tex contains \usepackage{thumbpdf} G. AUTHOR ========= Heiko Oberdiek Email: oberdiek@ruf.uni-freiburg.de H. QUESTIONS, SUGGESTED IMPROVEMENTS ==================================== If you have questions, problems with `thumbpdf', error reports, if you have improvements or want to have additional features, please send them to the author. I. KNOWN PROBLEMS ================= * Incompatibility with option `pdfpagetransition' of package `hyperref' versions below 6.64. This option overwrites the previous contents of `\pdfpageattr', used by `thumbpdf.sty'. * If there is a package that overloads `\shipout' to rearrange pages (two pages to one, ...), then `thumbpdf.sty' should be loaded first. J. HISTORY ========== 1999/02/14 v1.0 first release 1999/02/23 v1.1 * Bug in thumbpdf.sty removed (#2->#1). * New option in thumbpdf.pl: --resolution. * Automatic calculation of the resolution for ghostscript (max. size 106x106). 1999/03/01 v1.2 * Optimizition: indirect objects for length values removed. 1999/03/12 v1.3 * Copyright: LPPL 1999/05/05 v1.4 * Detecting of cygwin-perl. * Save memory by sharing `RGB' objects (devices: png16, png256). 1999/06/13 v1.5 * Gs detection extended (thumbpdf.pl). * Installation part of readme.txt rewritten and table of contents added. 1999/07/27 v1.6 * Bug in thumbpdf.sty fixed (handling of \pdfpageattr). * Warning if there are missing thumbs (thumbpdf.sty). * Added section `Known Problems' in `readme.txt'. 1999/08/08 v1.7 * Bug in thumbpdf.sty fixed. This bug was introduced in version 1.6, therefore this version should not be used. * Adaptation for pdfTeX version 0.14a. * LPPL 1.1 1999/09/09 v1.8 * Bug in thumbpdf.sty fixed. \PackageWarning cannot be used in \shipout, because \protect has been set to \noexpand (mysterious LaTeX behaviour?). 1999/09/16 v1.9 * The perl script now detects direct /Length objects, that pdfTeX uses including JPEG images. 2000/01/11 v1.10 * Bug in /Length detection removed. * Direct /Length in RGB objects supported. * \immediate before \pdfximage removed. * thumbpdf.sty revised. 2000/01/19 v1.11 * Small fix for perl versions that cannot handle "my" in "for" loops. * LPPL 1.2