pdftops/README

   1 Xpdf
   2 ====
   3
   4 version 2.02
   5 2003-mar-24
   6
   7 The Xpdf software and documentation are
   8 copyright 1996-2003 Glyph & Cog, LLC.
   9
  10 Email: derekn@foolabs.com
  11 WWW: http://www.foolabs.com/xpdf/
  12
  13 The PDF data structures, operators, and specification are
  14 copyright 1985-2001 Adobe Systems Inc.
  15
  16
  17 What is Xpdf?
  18 -------------
  19
  20 Xpdf is an open source viewer for Portable Document Format (PDF)
  21 files.  (These are also sometimes also called 'Acrobat' files, from
  22 the name of Adobe's PDF software.)  The Xpdf project also includes a
  23 PDF text extractor, PDF-to-PostScript converter, and various other
  24 utilities.
  25
  26 Xpdf runs under the X Window System on UNIX, VMS, and OS/2.  The non-X
  27 components (pdftops, pdftotext, etc.) also run on Win32 systems and
  28 should run on pretty much any system with a decent C++ compiler.
  29
  30 Xpdf is designed to be small and efficient.  It can use Type 1,
  31 TrueType, or standard X fonts.
  32
  33
  34 Distribution
  35 ------------
  36
  37 Xpdf is licensed under the GNU General Public License (GPL), version
  38 2.  In my opinion, the GPL is a convoluted, confusing, ambiguous mess.
  39 But it's also pervasive, and I'm sick of arguing.  And even if it is
  40 confusing, the basic idea is good.
  41
  42 In order to cut down on the confusion a little bit, here are some
  43 informal clarifications:
  44
  45 - I don't mind if you redistribute Xpdf in source and/or binary form,
  46   as long as you include all of the documentation: README, man pages
  47   (or help files), and COPYING.  (Note that the README file contains a
  48   pointer to a web page with the source code.)
  49
  50 - Selling a CD-ROM that contains Xpdf is fine with me, as long as it
  51   includes the documentation.  I wouldn't mind receiving a sample
  52   copy, but it's not necessary.
  53
  54 - If you make useful changes to Xpdf, please make the source code
  55   available -- post it on a web site, email it to me, whatever.
  56
  57 If you're interested in commercial licensing, please see the Glyph &
  58 Cog web site:
  59
  60     http://www.glyphandcog.com/
  61
  62
  63 Compatibility
  64 -------------
  65
  66 Xpdf is developed and tested on a Linux 2.2 x86 system.
  67
  68 In addition, it has been compiled by others on Solaris, AIX, HP-UX,
  69 SCO UnixWare, Digital Unix, Irix, and numerous other Unix
  70 implementations, as well as VMS and OS/2.  It should work on pretty
  71 much any system which runs X11 and has Unix-like libraries.  You'll
  72 need ANSI C++ and C compilers to compile it.
  73
  74 The non-X components of Xpdf (pdftops, pdftotext, pdfinfo, pdffonts,
  75 pdfimages) can also be compiled on Win32 systems.  See the Xpdf web
  76 page for details.
  77
  78 If you compile Xpdf for a system not listed on the web page, please
  79 let me know.  If you're willing to make your binary available by ftp
  80 or on the web, I'll be happy to add a link from the Xpdf web page.  I
  81 have decided not to host any binaries I didn't compile myself (for
  82 disk space and support reasons).
  83
  84 If you can't get Xpdf to compile on your system, send me email and
  85 I'll try to help.
  86
  87 Xpdf has been ported to the Acorn, Amiga, BeOS, and EPOC.  See the
  88 Xpdf web page for links.
  89
  90
  91 Getting Xpdf
  92 ------------
  93
  94 The latest version is available from:
  95
  96   http://www.foolabs.com/xpdf/
  97
  98 or:
  99
 100   ftp://ftp.foolabs.com/pub/xpdf/
 101
 102 Source code and several precompiled executables are available.
 103
 104 Announcements of new versions are posted to several newsgroups
 105 (comp.text.pdf, comp.os.linux.announce, and others) and emailed to a
 106 list of people.  If you'd like to receive email notification of new
 107 versions, just let me know.
 108
 109
 110 Running Xpdf
 111 ------------
 112
 113 To run xpdf, simply type:
 114
 115   xpdf file.pdf
 116
 117 To generate a PostScript file, hit the "print" button in xpdf, or run
 118 pdftops:
 119
 120   pdftops file.pdf
 121
 122 To generate a plain text file, run pdftotext:
 123
 124   pdftotext file.pdf
 125
 126 There are four additional utilities (which are fully described in
 127 their man pages):
 128
 129   pdfinfo -- dumps a PDF file's Info dictionary (plus some other
 130              useful information)
 131   pdffonts -- lists the fonts used in a PDF file along with various
 132               information for each font
 133   pdftopbm -- converts a PDF file to a series of PBM-format bitmaps
 134   pdfimages -- extracts the images from a PDF file
 135
 136 Command line options and many other details are described in the man
 137 pages (xpdf.1, etc.) and the VMS help files (xpdf.hlp, etc.).
 138
 139
 140 Upgrading from Xpdf 0.9x
 141 ------------------------
 142
 143 WARNING: Xpdf 1.x switched to a completely different config file setup
 144 than Xpdf 0.9x.
 145
 146 Many of the configuration options that used to be X resources have
 147 been moved into the Xpdf config file.  There are also lots of new and
 148 improved options.  If you're upgrading from Xpdf 0.9x, please read
 149 through the sample config file (doc/sample-xpdfrc) and the xpdfrc(5)
 150 man page.
 151
 152 The Asian language support has been pulled out into separate packages,
 153 loaded at run time.  This is much cleaner than the 0.9x approach -- it
 154 makes the base distribution smaller, allows the language support
 155 packages to be upgraded separately, and lets users customize Xpdf for
 156 other text encodings without modifying the source.  See the web site
 157 (http://www.foolabs.com/xpdf) for info on downloading the language
 158 support packages.
 159
 160 All of the Xpdf tools, including the X viewer and the command line
 161 programs, read the same config file.  They first attempt to read the
 162 user's personal config file:
 163
 164     $HOME/.xpdfrc
 165
 166 If it is not found, the Xpdf tools read a system-wide config file,
 167 typically something like:
 168
 169     /usr/local/etc/xpdfrc
 170
 171 (this location can be customized when building Xpdf).
 172
 173 The Win32 command line tools look in the directory containing the
 174 executable, e.g.:
 175
 176     C:/Program Files/Xpdf/xpdfrc
 177
 178 Xpdf comes with a "sample-xpdfrc" file in the doc directory.  This is
 179 a good starting point for constructing your own config file.
 180
 181 For full details, please see the xpdfrc(5) man page.
 182
 183
 184 Fonts
 185 -----
 186
 187 By default, Xpdf will use X server fonts.  It requires the following
 188 fonts:
 189
 190 * Courier: medium-r, bold-r, medium-o, and bold-o
 191 * Helvetica: medium-r, bold-r, medium-o, and bold-o
 192 * Times: medium-r, bold-r, medium-i, and bold-i
 193 * Symbol: medium-r
 194 * Zapf Dingbats: medium-r
 195
 196 Most X installations should already have all of these fonts (except
 197 maybe Zapf Dingbats).
 198
 199 If Xpdf is built with support for t1lib (or FreeType 2), you can get
 200 much higher quality text by using Type 1 fonts instead of X server
 201 fonts.  For example, you can use the Type 1 fonts that come with
 202 ghostscript.  To do this, add the following lines to the xpdfrc file
 203 (e.g., /usr/local/etc/xpdfrc or $HOME/.xpdfrc):
 204
 205 displayFontT1 Times-Roman               /usr/local/share/ghostscript/fonts/n021003l.pfb
 206 displayFontT1 Times-Italic              /usr/local/share/ghostscript/fonts/n021023l.pfb
 207 displayFontT1 Times-Bold                /usr/local/share/ghostscript/fonts/n021004l.pfb
 208 displayFontT1 Times-BoldItalic          /usr/local/share/ghostscript/fonts/n021024l.pfb
 209 displayFontT1 Helvetica                 /usr/local/share/ghostscript/fonts/n019003l.pfb
 210 displayFontT1 Helvetica-Oblique         /usr/local/share/ghostscript/fonts/n019023l.pfb
 211 displayFontT1 Helvetica-Bold            /usr/local/share/ghostscript/fonts/n019004l.pfb
 212 displayFontT1 Helvetica-BoldOblique     /usr/local/share/ghostscript/fonts/n019024l.pfb
 213 displayFontT1 Courier                   /usr/local/share/ghostscript/fonts/n022003l.pfb
 214 displayFontT1 Courier-Oblique           /usr/local/share/ghostscript/fonts/n022023l.pfb
 215 displayFontT1 Courier-Bold              /usr/local/share/ghostscript/fonts/n022004l.pfb
 216 displayFontT1 Courier-BoldOblique       /usr/local/share/ghostscript/fonts/n022024l.pfb
 217 displayFontT1 Symbol                    /usr/local/share/ghostscript/fonts/s050000l.pfb
 218 displayFontT1 ZapfDingbats              /usr/local/share/ghostscript/fonts/d050000l.pfb
 219
 220 You will need to replace '/usr/local/share/ghostscript/fonts' with the
 221 appropriate path on your system.
 222
 223
 224 Compiling Xpdf
 225 --------------
 226
 227 See the separate file, INSTALL.
 228
 229
 230 Bugs
 231 ----
 232
 233 If you find a bug in Xpdf, i.e., if it prints an error message,
 234 crashes, or incorrectly displays a document, and you don't see that
 235 bug listed here, please send me email, with a pointer (URL, ftp site,
 236 etc.) to the PDF file.
 237
 238
 239 Acknowledgments
 240 ---------------
 241
 242 Thanks to:
 243
 244 * Patrick Voigt for help with the remote server code.
 245 * Patrick Moreau, Martin P.J. Zinser, and David Mathog for the VMS
 246   port.
 247 * David Boldt and Rick Rodgers for sample man pages.
 248 * Brendan Miller for the icon idea.
 249 * Olly Betts for help testing pdftotext.
 250 * Peter Ganten for the OS/2 port.
 251 * Michael Richmond for the Win32 port of pdftops and pdftotext and the
 252   xpdf/cygwin/XFree86 build instructions.
 253 * Frank M. Siegert for improvements in the PostScript code.
 254 * Leo Smiers for the decryption patches.
 255 * Rainer Menzner for creating t1lib, and for helping me adapt it to
 256   xpdf.
 257 * Pine Tree Systems A/S for funding the OPI and EPS support in
 258   pdftops.
 259 * Easy Software Products for funding the "sh" operator support.
 260 * Tom Kacvinsky for help with FreeType and for being my interface to
 261   the FreeType team.
 262 * Theppitak Karoonboonyanan for help with Thai support.
 263 * Leonard Rosenthol for help and contributions on a bunch of things.
 264 * Alexandros Diamantidis and Maria Adaloglou for help with Greek
 265   support.
 266 * Lawrence Lai for help with the CJK Unicode maps.
 267
 268 Various people have contributed modifications made for use by the
 269 pdftex project:
 270
 271 * Han The Thanh
 272 * Martin Schröder of ArtCom GmbH
 273
 274
 275 References
 276 ----------
 277
 278 Adobe Systems Inc., _PDF Reference: Adobe Portable Document Format
 279 version 1.4_, 3nd ed.
 280 Addison-Wesley, 2001, ISBN 0-201-75839-3.
 281 http://partners.adobe.com/asn/developer/acrosdk/docs/filefmtspecs/PDFReference.pdf
 282 [The printed manual for PDF version 1.4.]
 283
 284 Adobe Systems Inc., _Portable Document Format: Changes from Version
 285 1.3 to 1.4_, Adobe Developer Support Technical Note #5409.
 286 June 11, 2001.
 287 http://partners.adobe.com/asn/developer/acrosdk/docs/filefmtspecs/PDF14Deltas.pdf
 288 [Updates for PDF 1.4.]
 289
 290 Adobe Systems Inc., _PostScript Language Reference_, 3rd ed.
 291 Addison-Wesley, 1999, ISBN 0-201-37922-8.
 292 [The official PostScript manual.]
 293
 294 Adobe Systems, Inc., _The Type 42 Font Format Specification_,
 295 Adobe Developer Support Technical Specification #5012.  1998.
 296 http://partners.adobe.com/asn/developer/pdfs/tn/5012.Type42_Spec.pdf
 297 [Type 42 is the format used to embed TrueType fonts in PostScript
 298 files.]
 299
 300 Adobe Systems, Inc., _Adobe CMap and CIDFont Files Specification_,
 301 Adobe Developer Support Technical Specification #5014.  1995.
 302 http://www.adobe.com/supportservice/devrelations/PDFS/TN/5014.CIDFont_Spec.pdf
 303 [CMap file format needed for Japanese and Chinese font support.]
 304
 305 Adobe Systems, Inc., _Adobe-Japan1-4 Character Collection for
 306 CID-Keyed Fonts_, Adobe Developer Support Technical Note #5078.
 307 2000.
 308 http://partners.adobe.com/asn/developer/PDFS/TN/5078.CID_Glyph.pdf
 309 [The Adobe Japanese character set.]
 310
 311 Adobe Systems, Inc., _Adobe-GB1-4 Character Collection for
 312 CID-Keyed Fonts_, Adobe Developer Support Technical Note #5079.
 313 2000.
 314 http://partners.adobe.com/asn/developer/pdfs/tn/5079.Adobe-GB1-4.pdf
 315 [The Adobe Chinese GB (simplified) character set.]
 316
 317 Adobe Systems, Inc., _Adobe-CNS1-3 Character Collection for
 318 CID-Keyed Fonts_, Adobe Developer Support Technical Note #5080.
 319 2000.
 320 http://partners.adobe.com/asn/developer/PDFS/TN/5080.CNS_CharColl.pdf
 321 [The Adobe Chinese CNS (traditional) character set.]
 322
 323 Adobe Systems Inc., _Supporting the DCT Filters in PostScript Level
 324 2_, Adobe Developer Support Technical Note #5116.  1992.
 325 http://www.adobe.com/supportservice/devrelations/PDFS/TN/5116.PS2_DCT.PDF
 326 [Description of the DCTDecode filter parameters.]
 327
 328 Adobe Systems Inc., _Open Prepress Interface (OPI) Specification -
 329 Version 2.0_, Adobe Developer Support Technical Note #5660.  2000.
 330 http://partners.adobe.com/asn/developer/PDFS/TN/5660.OPI_2.0.pdf
 331
 332 Adobe Systems Inc., CMap files.
 333 ftp://ftp.oreilly.com/pub/examples/nutshell/cjkv/adobe/
 334 [The actual CMap files for the 16-bit CJK encodings.]
 335
 336 Adobe Systems Inc., Unicode glyph lists.
 337 http://partners.adobe.com/asn/developer/type/unicodegn.html
 338 http://partners.adobe.com/asn/developer/type/glyphlist.txt
 339 http://partners.adobe.com/asn/developer/type/corporateuse.txt
 340 http://partners.adobe.com/asn/developer/type/zapfdingbats.txt
 341 [Mappings between character names to Unicode.]
 342
 343 Aldus Corp., _OPI: Open Prepress Interface Specification 1.3_.  1993.
 344 http://partners.adobe.com/asn/developer/PDFS/TN/OPI_13.pdf
 345
 346 Anonymous, RC4 source code.
 347 ftp://ftp.ox.ac.uk/pub/crypto/misc/rc4.tar.gz
 348 ftp://idea.sec.dsi.unimi.it/pub/crypt/code/rc4.tar.gz
 349 [This is the algorithm used to encrypt PDF files.]
 350
 351 T. Boutell, et al., "PNG (Portable Network Graphics) Specification,
 352 Version 1.0.  RFC 2083.
 353 [PDF uses the PNG filter algorithms.]
 354
 355 CCITT, "Information Technology - Digital Compression and Coding of
 356 Continuous-tone Still Images - Requirements and Guidelines", CCITT
 357 Recommendation T.81.
 358 http://www.w3.org/Graphics/JPEG/
 359 [The official JPEG spec.]
 360
 361 A. Chernov, "Registration of a Cyrillic Character Set".  RFC 1489.
 362 [Documentation for the KOI8-R Cyrillic encoding.]
 363
 364 Roman Czyborra, "The ISO 8859 Alphabet Soup".
 365 http://czyborra.com/charsets/iso8859.html
 366 [Documentation on the various ISO 859 encodings.]
 367
 368 L. Peter Deutsch, "ZLIB Compressed Data Format Specification version
 369 3.3".  RFC 1950.
 370 [Information on the general format used in FlateDecode streams.]
 371
 372 L. Peter Deutsch, "DEFLATE Compressed Data Format Specification
 373 version 1.3".  RFC 1951.
 374 [The definition of the compression algorithm used in FlateDecode
 375 streams.]
 376
 377 Jim Flowers, "X Logical Font Description Conventions", Version 1.5, X
 378 Consortium Standard, X Version 11, Release 6.1.
 379 ftp://ftp.x.org/pub/R6.1/xc/doc/hardcopy/XLFD/xlfd.PS.Z
 380 [The official specification of X font descriptors, including font
 381 transformation matrices.]
 382
 383 Foley, van Dam, Feiner, and Hughes, _Computer Graphics: Principles and
 384 Practice_, 2nd ed.  Addison-Wesley, 1990, ISBN 0-201-12110-7.
 385 [Colorspace conversion functions, Bezier spline math.]
 386
 387 Robert L. Hummel, _Programmer's Technical Reference: Data and Fax
 388 Communications_.  Ziff-Davis Press, 1993, ISBN 1-56276-077-7.
 389 [CCITT Group 3 and 4 fax decoding.]
 390
 391 ISO/IEC, _Information technology -- Lossy/lossless coding of bi-level
 392 images_.  ISO/IEC 14492, First edition (2001-12-15).
 393 http://webstore.ansi.org/
 394 [The official JBIG2 standard.  The final draft of this spec is
 395 available from http://www.jpeg.org/jbighomepage.html.]
 396
 397 ITU, "Standardization of Group 3 facsimile terminals for document
 398 transmission", ITU-T Recommendation T.4, 1999.
 399 ITU, "Facsimile coding schemes and coding control functions for Group 4
 400 facsimile apparatus", ITU-T Recommendation T.6, 1993.
 401 http://www.itu.int/
 402 [The official Group 3 and 4 fax standards - used by the CCITTFaxDecode
 403 stream, as well as the JBIG2Decode stream.]
 404
 405 Christoph Loeffler, Adriaan Ligtenberg, George S. Moschytz, "Practical
 406 Fast 1-D DCT Algorithms with 11 Multiplications".  IEEE Intl. Conf. on
 407 Acoustics, Speech & Signal Processing, 1989, 988-991.
 408 [The fast IDCT algorithm used in the DCTDecode filter.]
 409
 410 Microsoft, _TrueType 1.0 Font Files_, rev. 1.66.  1995.
 411 http://www.microsoft.com/typography/tt/tt.htm
 412 [The TrueType font spec (in MS Word format, naturally).]
 413
 414 Thai Industrial Standard, "Standard for Thai Character Codes for
 415 Computers", TIS-620-2533 (1990).
 416 http://www.nectec.or.th/it-standards/std620/std620.htm
 417 [The TIS-620 Thai encoding.]
 418
 419 P. Peterlin, "ISO 8859-2 (Latin 2) Resources".
 420 http://sizif.mf.uni-lj.si/linux/cee/iso8859-2.html
 421 [This is a web page with all sorts of useful Latin-2 character set and
 422 font information.]
 423
 424 Charles Poynton, "Color FAQ".
 425 http://www.inforamp.net/~poynton/ColorFAQ.html
 426 [The mapping from the CIE 1931 (XYZ) color space to RGB.]
 427
 428 R. Rivest, "The MD5 Message-Digest Algorithm".  RFC 1321.
 429 [MD5 is used in PDF document encryption.]
 430
 431 Unicode Consortium, "Unicode Home Page".
 432 http://www.unicode.org/
 433 [Online copy of the Unicode spec.]
 434
 435 W3C Recommendation, "PNG (Portable Network Graphics) Specification
 436 Version 1.0".
 437 http://www.w3.org/Graphics/PNG/
 438 [Defines the PNG image predictor.]
 439
 440 Gregory K. Wallace, "The JPEG Still Picture Compression Standard".
 441 ftp://ftp.uu.net/graphics/jpeg/wallace.ps.gz
 442 [Good description of the JPEG standard.  Also published in CACM, April
 443 1991, and submitted to IEEE Transactions on Consumer Electronics.]
 444
 445 F. Yergeau, "UTF-8, a transformation format of ISO 10646".  RFC 2279.
 446 [A commonly used Unicode encoding.]