readme.txt for project thumbpdf 1999/02/23 v1.1

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 doesn't 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.

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. He have to specify
these in the file 'thumbopt.tex'.

REQUIREMENTS
============
* Perl5
* 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,
   in version 5.10 you have to recompile if you have the
   right compiler - I don't :-()
  (win 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).
* pdfTeX, of course. (Tested with versions 0.13a/0.13b).

INSTALLATION
============
1. perl script 'thumbpdf.pl':
   a) Dos/Windows/OS2
   Look at your perl documentation where to put 'thumbpdf.pl'.
   I have it in a directory, specified in the environment
   variable 'PERLLIB'. To call it, I use '#!perl.exe', a
   very useful program by John Dallman (hbp_30.zip) :-).
   b) Unix
   Your are allowed to rename 'thumbpdf.pl' to 'thumbpdf'. Put it in
   a directory, where executable files can be found (environment
   variable PATH, e. g. /usr/local/bin/). Don't forget to set
   the execute permission (e. g. 'chmod a+x thumbpdf').
2. The TeX files 'thumbpdf.tex', 'thumbpdf.sty'
   should be moved to a directory, where pdf(e)(La)TeX can find
   them:
   a) Proposed place in TDS (web2c, teTeX, ...)
    .../texmf/pdftex/generic/thumbpdf/
   (thumbpdf.sty can be used by plain or LaTeX formats, thumbpdf.tex
   requires plain format.) Don't forget 'texhash', 'mktexlsr',
   'maketexl', or whatever you have to call to update the ls-r data.
   b) emTeX: %EMTEXDIR%\texinput\thumbpdf\
3. Dokumentation 'readme.txt':
   a) TDS: .../texmf/doc/generic/thumbpdf/
   b) emTeX: %EMTEXDIR%\doc\thumbpdf\
   or another appropiate place.

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}, recommanded
    \thumb{one.png}%  --> \thisthumb{one.png}
    \thumb[two]{one}% --> \thisthumb{two}
    \thumb[one]{./extrathumb/one.png}% --> thisthumb{one}
* 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}

DISCLAIMER, COPYRIGHT
=====================
#include <standard_disclaimer>
Especially:
* No warranties:
  not for the correct working of the software,
  not for any harm or damages by the software.
* You are allowed to distribute it only, if all four files
  (see above) are distributed together (unchanged).
Copyright (c) 1999 by Heiko Oberdiek.

AUTHOR
======
Heiko Oberdiek
Email: oberdiek@ruf.uni-freiburg.de

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.

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