| 1 |
README for project thumbpdf 2018/09/07 v3.17 |
| 2 |
|
| 3 |
TABLE OF CONTENTS |
| 4 |
================= |
| 5 |
A. Project thumbpdf |
| 6 |
B. Copyright, Disclaimer, License |
| 7 |
C. Files |
| 8 |
D. Requirements |
| 9 |
E. Installation |
| 10 |
F. User Interface |
| 11 |
G. Author |
| 12 |
H. Questions, Suggested Improvements |
| 13 |
I. Known Problems |
| 14 |
J. History |
| 15 |
|
| 16 |
A. PROJECT THUMBPDF |
| 17 |
================== |
| 18 |
THUMBPDF adds thumbnails to TeX documents which will be converted |
| 19 |
to PDF files. The following routes are supported by this package: |
| 20 |
* pdfTeX |
| 21 |
* dvips/ps2pdf (with Ghostscript version 6.0) |
| 22 |
* dvips/Distiller (tested with versions 3 and 4) |
| 23 |
* VTeX in PostScript mode (tested with versions 7.51, 7.53) |
| 24 |
Because the support for dvips/ps2pdf, dvips/Distiller, and |
| 25 |
VTeX/PS uses pdfmark specials both routes are shortly called |
| 26 |
the pdfmark route in the following. |
| 27 |
|
| 28 |
Both plain and LaTeX formats are supported. |
| 29 |
|
| 30 |
Thumbnails are small images, pictograms or reduced images from |
| 31 |
the pages of a document. They support the navigation through the |
| 32 |
document if the viewer supports it (e. g. AcrobatReader). |
| 33 |
|
| 34 |
The mode of action: |
| 35 |
In the following the user TeX file is called `<jobname>.tex'. |
| 36 |
0. The user compiles the TeX file to get `<jobname>.pdf'. |
| 37 |
1. Now the perl script generates the thumbnails in the form |
| 38 |
of png images by the help of Ghostscript. Versions below |
| 39 |
5.50 are not recommended because of some bugs in the pdf |
| 40 |
support of Ghostscript (see section I. Known Problems). |
| 41 |
2. Then pdfTeX compiles the driver file `thumbpdf.tex' which |
| 42 |
looks for these thumbnails and includes them as images. |
| 43 |
`thumbpdf.pdf' will contain on each page a thumbnail. |
| 44 |
3. The perl script scans `thumbpdf.pdf' to get the thumbnails |
| 45 |
as pdf objects. They are written in data files: |
| 46 |
`<jobname>.tpt' for pdfTeX and |
| 47 |
`<jobname>.tpm' for the pdfmark route. |
| 48 |
4. If the user compiles now his TeX file which loads package |
| 49 |
`thumbpdf.sty' then he gets a pdf file with thumbnails. |
| 50 |
|
| 51 |
B. COPYRIGHT, DISCLAIMER, LICENSE |
| 52 |
================================= |
| 53 |
Copyright (C) 1999-2014 Heiko Oberdiek. |
| 54 |
|
| 55 |
This work may be distributed and/or modified under the |
| 56 |
conditions of the LaTeX Project Public License, either version 1.3 |
| 57 |
of this license or (at your option) any later version. |
| 58 |
The latest version of this license is in |
| 59 |
http://www.latex-project.org/lppl.txt |
| 60 |
and version 1.3 or later is part of all distributions of LaTeX |
| 61 |
version 2003/12/01 or later. |
| 62 |
|
| 63 |
This work has the LPPL maintenance status "maintained". |
| 64 |
|
| 65 |
This Current Maintainer of this work is Heiko Oberdiek. |
| 66 |
|
| 67 |
C. FILES |
| 68 |
======== |
| 69 |
The project `thumbpdf' consists of four files: |
| 70 |
thumbpdf(.pl): This perl script is the main program. The extension |
| 71 |
`.pl' may be omitted. |
| 72 |
thumbpdf.tex: A pdfTeX program to produce the thumbnail pdf |
| 73 |
file (A2.). |
| 74 |
thumbpdf.sty: The package for the user to be included in his TeX |
| 75 |
source (A4.) |
| 76 |
README: Documentation, the file you are reading. |
| 77 |
|
| 78 |
Following temporary files are produced if `thumbpdf' is invoked: |
| 79 |
thb*.png: The thumbnails in PNG format: |
| 80 |
`thb1.png', `thb2.png', ..., `thb10.png', ... |
| 81 |
thumbpdf.pdf: The thumbnail pdf file (A2.). |
| 82 |
thumbpdf.log: The protocol file of the pdfTeX run (A2.). |
| 83 |
|
| 84 |
The result is written to (A3.): |
| 85 |
<jobname>.tpt: Thumbnail data file for pdfTeX. |
| 86 |
(tpt = Thumbnail PdfTex) |
| 87 |
<jobname>.tpm: Thumbnail data file as pdfmark specials for |
| 88 |
the pdfmark route. |
| 89 |
(tpm = Thumbnail PdfMark) |
| 90 |
|
| 91 |
Additional thumbnails for the `\thisthumb' feature have to be |
| 92 |
declared in the file `<jobname>.tno'. This can also be done |
| 93 |
with \DeclareThumbs in the user's TeX file. Package |
| 94 |
`thumbpdf.sty' then writes the file `<jobmane>.tno'. |
| 95 |
(tno = ThumbNail Optional) |
| 96 |
|
| 97 |
D. REQUIREMENTS |
| 98 |
=============== |
| 99 |
* Perl5 (version 5 of the perl interpreter). |
| 100 |
* Ghostscript: |
| 101 |
* Thumbnail generation: version 5.50 or better 6.0 (see section I.) |
| 102 |
* Including thumbnails with ps2pdf: version 6.0. |
| 103 |
* pdfTeX (also when pdfmark mode is used). |
| 104 |
|
| 105 |
E. INSTALLATION |
| 106 |
=============== |
| 107 |
1. TeX directory structure (TDS, see CTAN:tds/tds.pdf): |
| 108 |
The archive `thumbpdf.tds.zip' contains all the files sorted |
| 109 |
into a TDS tree (texmf tree): |
| 110 |
CTAN:install/support/thumbpdf.tds.zip |
| 111 |
For installation just unpack `thumbpdf.tds.zip' in the texmf tree |
| 112 |
of your choice and update the file data base when your |
| 113 |
distribution supports it (mikTeX, teTeX, TeX Live, ...). |
| 114 |
Check E.2 for installation of the perl script. |
| 115 |
|
| 116 |
Alternatively you can install the files manually: |
| 117 |
The files |
| 118 |
`readme.txt' (documentation) |
| 119 |
`thumbpdf.tex' (pdftex) |
| 120 |
`thumbpdf.sty' (pdf(e)tex, pdf(e)latex, (e)tex, (e)latex) |
| 121 |
go to |
| 122 |
texmf/doc/generic/thumbpdf/readme.txt |
| 123 |
texmf/tex/generic/thumbpdf/thumbpdf.tex |
| 124 |
texmf/tex/generic/thumbpdf/thumbpdf.sty |
| 125 |
(These now definite places in the TDS tree are a result of |
| 126 |
a discussion with Thomas Esser, who supports them in his |
| 127 |
great teTeX 1.0). |
| 128 |
|
| 129 |
2. Perl script `thumbpdf.pl': |
| 130 |
|
| 131 |
Unix |
| 132 |
* Your are allowed to rename `thumbpdf.pl' to `thumbpdf': |
| 133 |
mv thumbpdf.pl thumbpdf |
| 134 |
* Ensure that the execute permission is set: |
| 135 |
chmod +x thumbpdf |
| 136 |
* Move the file to a directory where the shell can find it |
| 137 |
(environment variable PATH, e.g. /usr/local/bin/). |
| 138 |
|
| 139 |
Dos/Windows/(OS2) |
| 140 |
* Running the perl interpreter directly with the perl script: |
| 141 |
perl thumbpdf.pl ... |
| 142 |
* Methods for calling by typing the script name without extension |
| 143 |
and perl interpreter: |
| 144 |
a) If your perl distribution provides a pl2exe program, |
| 145 |
use it to generate `thumbpdf.exe'. |
| 146 |
Advantage: I/O redirection works. |
| 147 |
b) A good method is a dos program of John Dallman: |
| 148 |
#!perl.exe (versions below 4) |
| 149 |
hbperl.exe (version 4) |
| 150 |
http://www.perl.com/CPAN/authors/id/JDALLMAN/hbp_403.zip |
| 151 |
Move thumbpdf.pl in a PERLLIB directory and copy the |
| 152 |
exe program to `thumbpdf.exe'. Then the program looks |
| 153 |
for the perl interpreter, the script and calls them. |
| 154 |
Advantage: I/O redirection works. |
| 155 |
c) Windows NT 4.0 users can use associated file types: |
| 156 |
SET PATHEXT=.pl;%PATHEXT% |
| 157 |
See perl win32 faq "How do I associate Perl scripts with perl?": |
| 158 |
http://www.activestate.com/support/faqs/win32/perlwin32faq4.html |
| 159 |
Disadvantage: I/O redirection does not work. |
| 160 |
d) 4DOS: SET .PL=c:/bin/perl.exe |
| 161 |
See perl win32 faq "How can I get Perl to run a Perl script at |
| 162 |
the 4DOS command line by typing the name of the script without |
| 163 |
the extension or "perl", just like a regular exe file?": |
| 164 |
http://www.activestate.com/support/faqs/win32/perlwin32faq1.html |
| 165 |
e) Convert the perl script to a batch file `thumbpdf.bat', if your |
| 166 |
distribution provides `pl2bat.bat'. |
| 167 |
Disadvantage: I/O redirection does not work. |
| 168 |
Many of this methods are listed in the perl win32 faq |
| 169 |
"What's the equivalent of the shebang ("#!") syntax for Win32?": |
| 170 |
http://www.activestate.com/support/faqs/win32/perlwin32faq4.html |
| 171 |
* TeXLive 7+/fpTeX contain a compiled version "thumbpdf.exe". |
| 172 |
|
| 173 |
Dos |
| 174 |
* I do not know a precompiled Ghostscript interpreter for |
| 175 |
version 5.5 or 6.0. Version 5.10 misses the png devices. |
| 176 |
So you have to compile Ghostscript for dos or you |
| 177 |
can use another program to generate the thumbnails |
| 178 |
(names: `thb1.png', `thb2.png', ...). |
| 179 |
* If Ghostscript cannot be started by perl because |
| 180 |
of serious problems (segmentation faults, ...), |
| 181 |
option `printgscmd' can be used: Thumbpdf prints the command line |
| 182 |
arguments for the ghostscript call in the file `thumbpdf.gs' |
| 183 |
and finishes. Then Ghostscript can manually be invoked to |
| 184 |
create the png files, e.g.: |
| 185 |
gs386/gswin32c @thumbpdf.gs (DOS/Win3.1) |
| 186 |
You need a Ghostscript executable that contains the png devices. |
| 187 |
For example version 5.50 can be run under Win3.1/Win32s by making |
| 188 |
a program icon with the correct working directory and |
| 189 |
the command `PATH/gswin32(c) @thumbpdf.gs', e.g: |
| 190 |
c:\gstools\gs5.50\gswin32 -Ic:\gstools\gs5.50 @thumbpdf.gs |
| 191 |
In the next call of thumbpdf the Ghostscript step is omitted by |
| 192 |
option `nomakepng'. |
| 193 |
Example command sequence: |
| 194 |
thumbpdf --printgscmd test |
| 195 |
gswin32c @thumbpdf.gs |
| 196 |
thumbpdf --nomakepng test |
| 197 |
|
| 198 |
Windows 3.1x with win32s |
| 199 |
* The png files can be produced with gswin32(c), but the means |
| 200 |
of the operating system to start windows programs with command |
| 201 |
line arguments are very poor. I found no way to invoke Ghostscript |
| 202 |
via perl, so the thumbnails must be generated manually (see above). |
| 203 |
|
| 204 |
F. USER INTERFACE |
| 205 |
================= |
| 206 |
* The perl script `thumbpdf.pl' can be invoked in two ways: |
| 207 |
a) thumbpdf --help |
| 208 |
prints a help screen with the options and some default values. |
| 209 |
b) thumbpdf [options] <jobname>[.pdf|.ps] |
| 210 |
`<jobname>' is the file name of user's TeX file without extension. |
| 211 |
The extension `.pdf' can be omitted. If option `--useps' is |
| 212 |
active, thumbpdf will look for `<jobname>.ps'. |
| 213 |
|
| 214 |
Action options (see section C.): |
| 215 |
--makepng: Call of Ghostscript to generate the thumbnails (A1.). |
| 216 |
--makepdf: Call of pdfTeX to produce a thumbnail pdf file (A2.). |
| 217 |
--makedata: Parsing of this pdf file and writing the bject |
| 218 |
represenation to `<jobname>.tpt' or `<jobname>.tpm' (A3.). |
| 219 |
--clean: Removing of the temporary files. |
| 220 |
|
| 221 |
Configuration options for --makepng: |
| 222 |
--useps: Use the PostScript file `<jobname>.ps' instead of the |
| 223 |
pdf file `<jobname>.pdf' for generating the thumbnails. |
| 224 |
--gscmd <name>: Name of the ghostscript command. |
| 225 |
--device|png [png]<dev>: (dev = mono, gray, 16, 256, 16m) |
| 226 |
Ghostscript device for producing the thumbnails, e.g.: |
| 227 |
--device=mono, --device=pnggray, --png=256 |
| 228 |
--resolution: Without the option thumbpdf checks the /MediaBox |
| 229 |
and calculates the resolution, that neither height |
| 230 |
nor width exceed the recommended 106 pixels. |
| 231 |
For a4 or letter paper the resolution is about 9 DPI. |
| 232 |
With this option, the default behaviour can be |
| 233 |
overwritten. |
| 234 |
--compress: The compress level of the thumbnail images. There |
| 235 |
is no reason not to use the maximal value, except |
| 236 |
for debugging or drafts. |
| 237 |
* Note for the pdfTeX route: |
| 238 |
Value 10 has a special meaning: streams are compressed |
| 239 |
like value 9, but unnecessary white spaces are removed |
| 240 |
in the dictionaries |
| 241 |
* Note for Distiller: |
| 242 |
The Distiller does not recognize compressed streams |
| 243 |
and uses its own settings to compress the streams. |
| 244 |
Because previously compressed streams are not |
| 245 |
detected and /Filter entries are overwritten, the |
| 246 |
double compressed streams will be invalid. Therefore |
| 247 |
the PostScript code in `<jobname>.tpm' uncompresses |
| 248 |
the streams, if Distiller is detected. |
| 249 |
Although the compression of thumbpdf is quite useless |
| 250 |
with Distiller, compression can be turned on for a |
| 251 |
possible reuse with ps2pdf or to keep the file |
| 252 |
`<jobname>.tpm' small. |
| 253 |
--password: Password for an encrypted pdf file. |
| 254 |
The following patch is required for ghostscript: |
| 255 |
http://www.ozemail.com.au/~geoffk/pdfencrypt/pdf_sec.ps |
| 256 |
--antialias: Set anti-aliasing parameters for ghostscript. |
| 257 |
It expects numbers with values 0, 1, 2, or 4. |
| 258 |
The meaning of 0 and 1 is the same and disables |
| 259 |
anti-aliasing. |
| 260 |
If two numbers are given, the first sets |
| 261 |
anti-aliasing for text (TextAlphaBits), the second |
| 262 |
for graphics (GraphicsAlphaBits). If only one number |
| 263 |
is present, then it is taken for both text and graphics. |
| 264 |
Examples: |
| 265 |
--antialias=1 disable anti-aliasing |
| 266 |
--antialias=4 max. anti-aliasing |
| 267 |
--antialias=14 -dTextAlphaBits=1 -dGraphicsAlphaBits=4 |
| 268 |
--greek: The text is printed in Greek style, the characters are |
| 269 |
replaced by gray boxes. Three limitations: |
| 270 |
* Only fonts in Type 1 format are supported. |
| 271 |
* The `show' operator is redefined in `userdict'. |
| 272 |
So it will not work, if the characters are displayed |
| 273 |
by other methods. |
| 274 |
* The color is lightened, assuming a white background. |
| 275 |
Status: experimental. |
| 276 |
|
| 277 |
Configuration option for --makedata: |
| 278 |
--modes: Select the modes for which you want that thumbpdf |
| 279 |
generates the thumbnail data files: |
| 280 |
* pdftex: <jobname>.tpt |
| 281 |
* pdfmark|dvips|ps2pdf|vtexpdfmark: <jobname>.tpm |
| 282 |
* all: synonym for the list `pdftex,pdfmark' |
| 283 |
--level2: `<jobname>.tpm' is written with PostScript level 2 |
| 284 |
features to reduce the size of this file. |
| 285 |
(This decreases the size of the final PostScript file, |
| 286 |
but does not affect the size of the final pdf file.) |
| 287 |
|
| 288 |
Options for message control: |
| 289 |
--quiet Messages except warnings are suppressed. |
| 290 |
--verbose Informations about the actions are printed. |
| 291 |
--debug Additional messages for debugging purposes. |
| 292 |
Also option `--clean' is disabled. |
| 293 |
|
| 294 |
Environment variable `THUMBPDF': |
| 295 |
Before scanning the command line for options the perl script |
| 296 |
`thumbpdf.pl' looks for the environment variable `THUMBPDF'. |
| 297 |
Example (bash syntax): |
| 298 |
export THUMBPDF="--modes=pdfmark --level2" |
| 299 |
To avoid syntax errors the equal sign can be replaced by a space, |
| 300 |
for example (DOS syntax): |
| 301 |
SET THUMBPDF=--modes pdfmark --level2 |
| 302 |
The reason for this environment variable is, that users of ps2pdf |
| 303 |
can omit the option 'modes', if they have set `THUMBPDF': |
| 304 |
SET THUMBDPF=--modes pdfmark |
| 305 |
Or if both data files should be generated: |
| 306 |
SET THUMBPDF=--modes all |
| 307 |
|
| 308 |
* Package `thumbpdf.sty' |
| 309 |
* LaTeX format: \usepackage{thumbpdf} |
| 310 |
Options: pdftex, pdfmark, dvips, ps2pdf |
| 311 |
(the last three options are synonyms). |
| 312 |
* Plain format: \input thumbpdf.sty |
| 313 |
Define \ThumbpdfDriver to inform `thumbpdf.sty' about the driver: |
| 314 |
\def\ThumbpdfDriver{ps2pdf}\input thumbpdf.sty |
| 315 |
* If you want to use option `pdfmark' in all cases exept pdfTeX in |
| 316 |
pdf mode, you can use a configuration file `thumbpdf.cfg': |
| 317 |
\ifx\ThumbpdfDriver\UnDeFiNeD |
| 318 |
\def\ThumbpdfDriver{pdfmark}% |
| 319 |
\fi |
| 320 |
\endinput |
| 321 |
This works, because `\ThumbpdfDriver' is ignored, if pdfTeX in |
| 322 |
pdf mode is detected. A more politically correct example of |
| 323 |
the configuration file `thumbpdf.cfg': |
| 324 |
\expandafter\ifx\csname ThumbpdfDriver\endcsname\relax |
| 325 |
\def\ThumbpdfDriver{pdfmark}% |
| 326 |
\ifx\pdfoutput\UnDeFiNeD |
| 327 |
\else |
| 328 |
\ifx\pdfoutput\relax |
| 329 |
\else |
| 330 |
\ifnum\pdfoutput>0 |
| 331 |
\def\ThumbpdfDriver{pdftex}% |
| 332 |
\fi |
| 333 |
\fi |
| 334 |
\fi |
| 335 |
\fi |
| 336 |
\endinput |
| 337 |
* Because pdfTeX can be detected at run time, it is not necessary |
| 338 |
to specify driver `pdftex'; even the other drivers are ignored. |
| 339 |
* \thisthumb{name} uses the thumbnail mentioned in |
| 340 |
`<jobname>.tno' for this page. (This file can be written by |
| 341 |
the \DeclareThumbs feature, see below.) |
| 342 |
* \DeclareThumbs contains the content of the file `<jobname>.tno', |
| 343 |
see below. |
| 344 |
|
| 345 |
* Additional thumbnails: `<jobname>.tno' |
| 346 |
If `<jobname>.tno' is found, the thumbnails are automatically |
| 347 |
included by the program `thumbpdf.tex'. |
| 348 |
Format of this file:# |
| 349 |
|
| 350 |
``` |
| 351 |
\thumb{filename without `.png' extension}% or |
| 352 |
\thumb[name]{filename with/without extension} |
| 353 |
``` |
| 354 |
|
| 355 |
Examples: |
| 356 |
|
| 357 |
``` |
| 358 |
\thumb{one}% --> \thisthumb{one}, recommended |
| 359 |
\thumb{one.png}% --> \thisthumb{one.png} |
| 360 |
\thumb[two]{one}% --> \thisthumb{two} |
| 361 |
\thumb[one]{./extrathumb/one.png}% --> thisthumb{one} |
| 362 |
``` |
| 363 |
|
| 364 |
The first example shows that the `.png' extension |
| 365 |
is supported and recommended. But `.jpg' or `.tif' |
| 366 |
files also work. |
| 367 |
This data can be included in the main tex file that |
| 368 |
includes `thumbpdf.sty' with the \DeclareThumbs feature: |
| 369 |
|
| 370 |
``` |
| 371 |
\usepackage{thumbpdf}% or \input thumbpdf.sty |
| 372 |
\DeclareThumbs{ |
| 373 |
\thumb{one} |
| 374 |
\thumb[two]{./extra/two.jpg} |
| 375 |
} |
| 376 |
``` |
| 377 |
|
| 378 |
Then the file `\jobname.tno' is written with the thumbnail |
| 379 |
declarations. (LaTeX's \nofiles is respected.) |
| 380 |
* Program `thumbpdf.tex' |
| 381 |
Execept for debugging there is no reason for an user to call it |
| 382 |
manually. But if so the number of the files to be looked for can |
| 383 |
be reduced, because it takes some time to test 1000 thumbnails if |
| 384 |
they exist. A maximum number can be specified before: |
| 385 |
pdftex \def\thumbmax{20}\input thumbpdf |
| 386 |
The highest thumbnail is now `thumb020.png'. |
| 387 |
`<jobname>.tno' can only be found, if `thumbpdf.tex' knows about |
| 388 |
this `<jobname>': |
| 389 |
\pdftex \def\thumbjob{<jobname>}\input thumbpdf |
| 390 |
If `\thumbjob' is undefined, `thumbpdf.tex' looks for |
| 391 |
`thumbopt.tex'. |
| 392 |
|
| 393 |
Example: Addition of thumbnails for `example.tex': |
| 394 |
pdfelatex example % or pdf(e)(la)tex, whatever example needs. |
| 395 |
thumbpdf example |
| 396 |
pdfelatex example % example.tex contains \usepackage{thumbpdf} |
| 397 |
or for the dvips/ps2pdf route: |
| 398 |
latex example |
| 399 |
dvips example |
| 400 |
ps2pdf example.ps example.pdf |
| 401 |
thumbpdf --modes=dvips example |
| 402 |
latex example % example.tex contains \usepackage[dvips]{thumbpdf} |
| 403 |
dvips example |
| 404 |
ps2pdf example.ps example.pdf |
| 405 |
|
| 406 |
* Option `clean': |
| 407 |
It clears the temporary files of the current thumbpdf run: |
| 408 |
* thumb*.png (by `makepng') |
| 409 |
* thumbpdf.pdf, thumbpdf.log (by `makepdf') |
| 410 |
Previously generated files are untouched. This option will |
| 411 |
be automatically disabled, if options `debug', `nomakepdf', |
| 412 |
or `nomakedef' are active. |
| 413 |
|
| 414 |
G. AUTHOR |
| 415 |
========= |
| 416 |
Heiko Oberdiek |
| 417 |
Email: heiko.oberdiek at googlemail.com |
| 418 |
ho-tex at tug.org |
| 419 |
|
| 420 |
H. QUESTIONS, SUGGESTED IMPROVEMENTS |
| 421 |
==================================== |
| 422 |
If you have questions, problems with `thumbpdf', error reports, |
| 423 |
if you have improvements or want to have additional features, |
| 424 |
please send them via github issues: |
| 425 |
https://github.com/ho-tex/thumbpdf/issues |
| 426 |
|
| 427 |
|
| 428 |
Other ps->pdf routes: |
| 429 |
* pstill: I did not succeed. It seems that the used pdfmark specials |
| 430 |
are not supported. |
| 431 |
* Adobe Distiller: Because I do not have access to it, I am curious |
| 432 |
to hear whether it works. Theoretically it should. |
| 433 |
|
| 434 |
I. KNOWN PROBLEMS |
| 435 |
================= |
| 436 |
* Compressed PDF objects (version PDF-1.5) are not supported, |
| 437 |
thus the PDF file should be generated with \pdfobjcompresslevel=0, |
| 438 |
before running thumbpdf. |
| 439 |
* The most bug reports I get are perl script error messages regarding |
| 440 |
Ghostscript. Especially versions below 5.50 often have problems |
| 441 |
with the pdf support. Sometimes it can be necessary to update |
| 442 |
to version 6.0. |
| 443 |
Before writing a bug report, please check, if your pdf file |
| 444 |
is processible by your Ghostscript version. If upgrading do not |
| 445 |
help, you have two possibilities: |
| 446 |
a) Use of another program to generate the thumbnails. But |
| 447 |
an other program that uses Ghostscript to do the job will not |
| 448 |
help of course. |
| 449 |
The thumbnails should be named `thb1.png', `thb2.png', ... |
| 450 |
Then run `thumbpdf' and omit the Ghostscript step by the |
| 451 |
option `--nomakepng'. |
| 452 |
b) Generate a PostScript version of your TeX file and run |
| 453 |
`thumbpdf' with option `--useps'. Getting the PostScript |
| 454 |
file by Acrobat's conversion feature often fails. So it is |
| 455 |
better to generate the PostScript file from the TeX source |
| 456 |
with TeX/dvips, for example. |
| 457 |
* Incompatibility with option `pdfpagetransition' of package `hyperref' |
| 458 |
versions below 6.64. This option overwrites the previous contents |
| 459 |
of `\pdfpageattr', used by `thumbpdf.sty'. |
| 460 |
* If there is a package that overloads `\shipout' to rearrange pages |
| 461 |
(two pages to one, ...), then `thumbpdf.sty' should be loaded first. |
| 462 |
* Some builds of the perl port of ActiveState, version 5.6.0 |
| 463 |
for Windows do not work correctly: for example, after |
| 464 |
a successful call of system commands with the backtick |
| 465 |
operator (``), $? ($CHILD_ERROR) returns -1 instead of 0. |
| 466 |
Summary of informations contributed by users: |
| 467 |
- These builds for Windows do not work: 612, 613, 616 |
| 468 |
? Windows port: 618 (one user suceeds, one user fails) |
| 469 |
+ The following Windows builds work: 522 |
| 470 |
+ The Linux versions work. |
| 471 |
Workaround: Use another version or port, |
| 472 |
see `http://www.cpan.org/'. |
| 473 |
|
| 474 |
J. HISTORY |
| 475 |
========== |
| 476 |
|
| 477 |
1999/02/14 v1.0 first release |
| 478 |
|
| 479 |
1999/02/23 v1.1 |
| 480 |
* Bug in thumbpdf.sty removed (#2->#1). |
| 481 |
* New option in thumbpdf.pl: --resolution. |
| 482 |
* Automatic calculation of the resolution for Ghostscript |
| 483 |
(max. size 106x106). |
| 484 |
|
| 485 |
1999/03/01 v1.2 |
| 486 |
* Optimizition: indirect objects for length values removed. |
| 487 |
|
| 488 |
1999/03/12 v1.3 |
| 489 |
* Copyright: LPPL |
| 490 |
|
| 491 |
1999/05/05 v1.4 |
| 492 |
* Detecting of cygwin-perl. |
| 493 |
* Save memory by sharing `RGB' objects (devices: png16, png256). |
| 494 |
|
| 495 |
1999/06/13 v1.5 |
| 496 |
* Gs detection extended (thumbpdf.pl). |
| 497 |
* Installation part of readme.txt rewritten and table of contents |
| 498 |
added. |
| 499 |
|
| 500 |
1999/07/27 v1.6 |
| 501 |
* Bug in thumbpdf.sty fixed (handling of \pdfpageattr). |
| 502 |
* Warning if there are missing thumbs (thumbpdf.sty). |
| 503 |
* Added section `Known Problems' in `readme.txt'. |
| 504 |
|
| 505 |
1999/08/08 v1.7 |
| 506 |
* Bug in thumbpdf.sty fixed. This bug was introduced in |
| 507 |
version 1.6, therefore this version should not be used. |
| 508 |
* Adaptation for pdfTeX version 0.14a. |
| 509 |
* LPPL 1.1 |
| 510 |
|
| 511 |
1999/09/09 v1.8 |
| 512 |
* Bug in thumbpdf.sty fixed. \PackageWarning cannot be used |
| 513 |
in \shipout, because \protect has been set to \noexpand |
| 514 |
(mysterious LaTeX behaviour?). |
| 515 |
|
| 516 |
1999/09/16 v1.9 |
| 517 |
* The perl script now detects direct /Length objects, |
| 518 |
that pdfTeX uses including JPEG images. |
| 519 |
|
| 520 |
2000/01/11 v1.10 |
| 521 |
* Bug in /Length detection removed. |
| 522 |
* Direct /Length in RGB objects supported. |
| 523 |
* \immediate before \pdfximage removed. |
| 524 |
* thumbpdf.sty revised. |
| 525 |
|
| 526 |
2000/01/19 v1.11 |
| 527 |
* Small fix for perl versions that cannot handle "my" |
| 528 |
in "for" loops. |
| 529 |
* LPPL 1.2 |
| 530 |
|
| 531 |
2000/02/11 v1.12 (not released) |
| 532 |
* Option `clean' added. |
| 533 |
* `<jobname>.tnd' replaces `thumbpdf.tex', if thumbpdf is called: |
| 534 |
thumbpdf [options] <jobname>[.pdf] |
| 535 |
* `<jobname>.tno' can be used instead of `thumbopt.tex'. |
| 536 |
* \DeclareThumbs added. |
| 537 |
|
| 538 |
2000/02/22 v2.0 |
| 539 |
* Support for the dvips/ps2pdf route by pdfmark specials. |
| 540 |
* Temporary files are removed. |
| 541 |
* Renaming of files: |
| 542 |
thumb%03d.png (thumb001.png) ==> thb%d.png (thb1.png) |
| 543 |
thumbdta.tex ==> <jobname>.tpt, <jobname>.tpm added |
| 544 |
thumbopt.tex ==> <jobname>.tno |
| 545 |
* Syntax change: <jobname> is now required. |
| 546 |
|
| 547 |
2000/02/28 v2.1 |
| 548 |
* Environment variable `THUMBPDF' supported. |
| 549 |
* `thumbpdf.cfg' supported. |
| 550 |
* TDS place for readme.txt: texmf/doc/generic/thumbpdf/readme.txt |
| 551 |
* Errors in `readme.txt' corrected. |
| 552 |
|
| 553 |
2000/03/07 v2.2 |
| 554 |
* Support for Distiller 3 and 4, the streams are uncompressed. |
| 555 |
* Call of gs is changed in order to show the currently processed |
| 556 |
page number of the pdf file. |
| 557 |
* Option --printgscmd creates the command line file `thumbpdf.gs' |
| 558 |
for the Ghostscript call. |
| 559 |
|
| 560 |
2000/03/22 v2.3 |
| 561 |
* Bug fix: --useps now works. |
| 562 |
|
| 563 |
2000/04/10 v2.4 |
| 564 |
* Fix for ActiveState Perl 5.6.0: uc line changed, fork removed. |
| 565 |
(Thanks to Andreas Buehmann <[email protected]>.) |
| 566 |
* Test of `thumbpdf.tex' version. |
| 567 |
|
| 568 |
2000/07/29 v2.5 |
| 569 |
* Save trick in call of ghostscript. |
| 570 |
* Undocumented option --gspages added. |
| 571 |
* Problem with ActiveState perl 5.6.0 (win32) added |
| 572 |
to section "Known Problems". |
| 573 |
|
| 574 |
2000/09/27 v2.6 |
| 575 |
* Information about ActiveState perl 5.6.0 updated. |
| 576 |
|
| 577 |
2000/10/27 v2.7 |
| 578 |
* -dFIXEDMEDIA=0 added in gs call. |
| 579 |
|
| 580 |
2001/01/12 v2.8: |
| 581 |
* Bug fix in dvips mode and active option `level2': |
| 582 |
pack parameter corrected for little-endian machines. |
| 583 |
* /Rotate in pdf pages: |
| 584 |
ghostscript versions around 6.01 have added a hack |
| 585 |
in /pdfshowpage_setpage, that ignores the /Rotate entry. |
| 586 |
A patch is added to disable the hack. |
| 587 |
* Ghostscript uses the MediaBox for calculating the |
| 588 |
page size. For version 6.50 a patch is added to use |
| 589 |
the /CropBox instead. |
| 590 |
|
| 591 |
2001/03/29 v2.9: |
| 592 |
* Option --password added. |
| 593 |
|
| 594 |
2001/04/02 v2.10: |
| 595 |
* Small corrections in readme.txt, contributed by Michael Wiedmann. |
| 596 |
|
| 597 |
2001/04/26 v2.11: |
| 598 |
* Option --antialias added (suggestion of Juergen Bausa). |
| 599 |
* This version is not released. |
| 600 |
|
| 601 |
2002/01/11 v3.0: |
| 602 |
* Syntax of option --antialias changed. The option is enabled |
| 603 |
as default, so that the ghostscript step is now slower. |
| 604 |
* Support for VTeX's PS mode added. |
| 605 |
* Greek mode added (experimental). |
| 606 |
* Signal handlers added for cleanup. |
| 607 |
|
| 608 |
2002/05/26 v3.1: |
| 609 |
* SIG_HUP unkown in Windows. |
| 610 |
* Bug fix: The signal function for __DIE__ "cleanup" aborts |
| 611 |
before the error message of "die" is printed. |
| 612 |
Replaced by "clean" that does not contain "exit 1". |
| 613 |
* Small bug fix in mode detection and mode "vtex" |
| 614 |
removed from list. "vtexpdfmark" was detected, |
| 615 |
"vtex" did not work and perhaps it will be used |
| 616 |
later for VTeX in PDF mode. |
| 617 |
|
| 618 |
2002/05/26 v3.2: |
| 619 |
* Fix: "MacOS/X: darwin" is now not interpreted as |
| 620 |
Windows. |
| 621 |
|
| 622 |
2003/03/19 v3.3: |
| 623 |
* Fix for gs 8.00 in mode dvips: |
| 624 |
THB_DistillerPatch also applied to ghostscript >= 8.00. |
| 625 |
|
| 626 |
2003/06/06 v3.4: |
| 627 |
* Bug fix, two forgotten "pop"s added for Distiller case. |
| 628 |
|
| 629 |
2004/10/24 v3.5: |
| 630 |
* Revert Cygwin detection: is unix (request by Jan Nieuwenhuizen). |
| 631 |
* LPPL 1.3. |
| 632 |
|
| 633 |
2004/11/19 v3.6: |
| 634 |
* Bug fix for dvips mode and gs < 8.00 (/stackunderflow in pop). |
| 635 |
|
| 636 |
2004/11/19 v3.7: |
| 637 |
* For easier debugging, the special thumbpdf objects are now |
| 638 |
valid PDF objects that are referenced in the Catalog. |
| 639 |
* Remove of extra '\n' before "endstream" that is added |
| 640 |
by pdfTeX 1.20a. |
| 641 |
|
| 642 |
2005/07/06 v3.8: |
| 643 |
* Fix because of pdfTeX 1.30. |
| 644 |
|
| 645 |
2007/11/07 v3.9: |
| 646 |
* Deprecation warning of perl 5.8.8 fixed. |
| 647 |
|
| 648 |
2008/04/16 v3.10: |
| 649 |
* TDS archive `thumbpdf.tds.zip' provided. |
| 650 |
|
| 651 |
2010/07/07 v3.11: |
| 652 |
* \pdfcompresslevel=0 and \pdfminorversion=4 added for thumbpdf.tex. |
| 653 |
* \input is used with file name extension for "thumbpdf.tex". |
| 654 |
* Warning if \pdfobjcompresslevel>0. |
| 655 |
|
| 656 |
2011/08/09 v3.12: |
| 657 |
* Support for LuaTeX added. |
| 658 |
|
| 659 |
2011/08/10 v3.13: |
| 660 |
* Use gswin64c in Windows with 64 bits. |
| 661 |
* Fix of version date of thumbpdf.sty. |
| 662 |
|
| 663 |
2012/04/09 v3.14: |
| 664 |
* Fix for plain TeX compatibility (offending \RequirePackage). |
| 665 |
|
| 666 |
2012/04/18 v3.15: |
| 667 |
* Option --version added. |
| 668 |
* File `readme.txt' renamed to `README'. |
| 669 |
|
| 670 |
2014/07/15 v3.16 |
| 671 |
* Patch for `thumbpdf.pl' by Norbert Preining because of |
| 672 |
pdfTeX 1.40.15 (TeX Live 2014). |
| 673 |
|
| 674 |
2018/09/07 v3.17 |
| 675 |
* Move to ho-tex github organisation |
| 676 |
https://github.com/ho-tex/thumbpdf |
| 677 |
* Patch for `thumbpdf.pl' by David Carlisle for new perl { regex handling |
| 678 |
* Update warning messages for Oberdiek bundle issue 46 from Karl Berry |