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] <pdffile[.pdf]>
     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
