home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / xpdf093.zip / XFree86 / lib / X11 / xpdf / README < prev    next >
Text File  |  2001-10-26  |  16KB  |  426 lines
  1. Xpdf
  2. ====
  3.  
  4. version 0.93
  5. 2001-oct-25
  6.  
  7. The Xpdf software and documentation are
  8. copyright 1996-2001 Derek B. Noonburg.
  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 1995 Adobe Systems Inc.
  15.  
  16.  
  17. What is Xpdf?
  18. -------------
  19.  
  20. Xpdf is a viewer for Portable Document Format (PDF) files.  (These are
  21. also sometimes also called 'Acrobat' files, from the name of Adobe's
  22. PDF software.)  Xpdf runs under the X Window System on UNIX, VMS, and
  23. OS/2.  The non-X components of the package (pdftops, pdftotext, etc.)
  24. also run on Win32 systems and should run on pretty much any system
  25. with a decent C++ compiler.
  26.  
  27. Xpdf is designed to be small and efficient.  It can use Type 1,
  28. TrueType, or standard X fonts.
  29.  
  30.  
  31. Distribution
  32. ------------
  33.  
  34. Xpdf is licensed under the GNU General Public License (GPL), version
  35. 2.  In my opinion, the GPL is a convoluted, confusing, ambiguous mess.
  36. But it's also pervasive, and I'm sick of arguing.  And even if it is
  37. confusing, the basic idea is good.
  38.  
  39. In order to cut down on the confusion a little bit, here are some
  40. informal clarifications:
  41.  
  42. - I don't mind if you redistribute Xpdf in source and/or binary form,
  43.   as long as you include all of the documentation: README, man pages
  44.   (or help files), and COPYING.  (Note that the README file contains a
  45.   pointer to a web page with the source code.)
  46.  
  47. - Selling a CD-ROM that contains Xpdf is fine with me, as long as it
  48.   includes the documentation.  I wouldn't mind receiving a sample
  49.   copy, but it's not necessary.
  50.  
  51. - If you make useful changes to Xpdf, please make the source code
  52.   available -- post it on a web site, email it to me, whatever.
  53.  
  54. If you're interested in commercial licensing, please contact me by
  55. email: derekn@foolabs.com .
  56.  
  57.  
  58. Compatibility
  59. -------------
  60.  
  61. Xpdf is developed and tested on a Linux 2.2 x86 system.
  62.  
  63. In addition, it has been compiled by others on Solaris, AIX, HP-UX,
  64. SCO UnixWare, Digital Unix, Irix, and numerous other Unix
  65. implementations, as well as VMS and OS/2.  It should work on pretty
  66. much any system which runs X11 and has Unix-like libraries.  You'll
  67. need ANSI C++ and C compilers to compile it.
  68.  
  69. The non-X components of Xpdf (pdftops, pdftotext, pdfinfo, pdfimages)
  70. can also be compiled on Win32 systems.  See the Xpdf web page for
  71. details.
  72.  
  73. If you compile Xpdf for a system not listed on the web page, please
  74. let me know.  If you're willing to make your binary available by ftp
  75. or on the web, I'll be happy to add a link from the Xpdf web page.  I
  76. have decided not to host any binaries I didn't compile myself (for
  77. disk space and support reasons).
  78.  
  79. If you can't get Xpdf to compile on your system, send me email and
  80. I'll try to help.
  81.  
  82. Xpdf has been ported to the Acorn, Amiga, BeOS, and EPOC.  See the
  83. Xpdf web page for links.
  84.  
  85.  
  86. Getting Xpdf
  87. ------------
  88.  
  89. The latest version is available from:
  90.  
  91.   http://www.foolabs.com/xpdf/
  92.  
  93. or:
  94.  
  95.   ftp://ftp.foolabs.com/pub/xpdf/
  96.  
  97. Source code and several precompiled executables are available.
  98.  
  99. Announcements of new versions are posted to several newsgroups
  100. (comp.text.pdf, comp.os.linux.announce, and others) and emailed to a
  101. list of people.  If you'd like to receive email notification of new
  102. versions, just let me know.
  103.  
  104.  
  105. Running Xpdf
  106. ------------
  107.  
  108. To run xpdf, simply type:
  109.  
  110.   xpdf file.pdf
  111.  
  112. To generate a PostScript file, hit the "print" button in xpdf, or run
  113. pdftops:
  114.  
  115.   pdftops file.pdf
  116.  
  117. To generate a plain text file, run pdftotext:
  118.  
  119.   pdftotext file.pdf
  120.  
  121. There are three additional utilities (which are fully described in
  122. their man pages):
  123.  
  124.   pdfinfo -- dumps a PDF file's Info dictionary (plus some other
  125.              useful information)
  126.   pdftopbm -- converts a PDF file to a series of PBM-format bitmaps
  127.   pdfimages -- extracts the images from a PDF file
  128.  
  129. Command line options and many other details are described in the man
  130. pages (xpdf.1, etc.) and the VMS help files (xpdf.hlp, etc.).
  131.  
  132.  
  133. Fonts
  134. -----
  135.  
  136. Xpdf uses X server fonts.  It requires the following fonts:
  137.  
  138. * Courier: medium-r, bold-r, medium-o, and bold-o
  139. * Helvetica: medium-r, bold-r, medium-o, and bold-o
  140. * Times: medium-r, bold-r, medium-i, and bold-i
  141. * Symbol: medium-r
  142. * Zapf Dingbats: medium-r
  143.  
  144. Most X installations should already have all of these fonts, except
  145. Zapf Dingbats.  You can install a Type 1 Zapf Dingbats font -- see the
  146. mkfontdir(1) man page for details.  Use this font descriptor in your
  147. fonts.scale file:
  148.  
  149.     -itc-zapfdingbats-medium-r-normal--0-0-0-0-p-0-adobe-fontspecific
  150.  
  151. You can get a Type 1 font file from the ghostscript 4.x distribution
  152. (look for d050000l.pfb).
  153.  
  154. X servers, starting at R5, support font scaling.  Xpdf will
  155. automatically take advantage of this.  There are two types of scaling.
  156. The first type uses standard bitmap fonts: if a font doesn't exist in
  157. the requested size, the server will scale the bitmapped characters.
  158. This is reasonably fast, and the results are readable but not very
  159. pretty.  X servers can also handle true scalable, e.g., Type 1, fonts.
  160. (See the mkfontdir(1) man page for details on setting these up.)
  161. Scalable fonts are slower, especially since PDF documents tend to use
  162. lots of fonts, but they look much nicer.
  163.  
  164. Some X servers also support font rotation.  Xpdf will use this feature
  165. if available.
  166.  
  167. For Japanese support, you will need a Japanese font of the form:
  168.  
  169.     -*-fixed-medium-r-normal-*-NN-*-*-*-*-*-jisx0208.1983-0
  170.  
  171. and an X server that can handle 16-bit fonts.  You can also set this
  172. font using the xpdf.japaneseFont resource.
  173.  
  174. For Chinese GB (simplified Chinese) support, you will need a font of
  175. the form:
  176.  
  177.     -*-fangsong ti-medium-r-normal-*-%s-*-*-*-*-*-gb2312.1980-0
  178.  
  179. You can replace this font using the xpdf.chineseGBFont resource.
  180.  
  181. For Chinese CNS (traditional Chinese) support, you will need a font of
  182. the form:
  183.  
  184.     -*-fixed-medium-r-normal--*-%s-*-*-*-*-big5-0
  185.  
  186. You can replace this font using the xpdf.chineseCNSFont resource.
  187.  
  188. If compiled with t1lib support, xpdf will use t1lib to render embedded
  189. Type 1 and Type 1C fonts.  In addition, xpdf can be configured to use
  190. t1lib for the base 14 fonts and for substituted fonts.  To enable this
  191. feature, you must set an X resource for each Type 1 font file.  For
  192. example:
  193.  
  194.     xpdf.t1TimesRoman:           /usr/local/fonts/Times-Roman.pfa
  195.     xpdf.t1TimesItalic:          /usr/local/fonts/Times-Italic.pfa
  196.     xpdf.t1TimesBold:            /usr/local/fonts/Times-Bold.pfa
  197.     xpdf.t1TimesBoldItalic:      /usr/local/fonts/Times-BoldItalic.pfa
  198.     xpdf.t1Helvetica:            /usr/local/fonts/Helvetica.pfa
  199.     xpdf.t1HelveticaOblique:     /usr/local/fonts/Helvetica-Oblique.pfa
  200.     xpdf.t1HelveticaBold:        /usr/local/fonts/Helvetica-Bold.pfa
  201.     xpdf.t1HelveticaBoldOblique: /usr/local/fonts/Helvetica-BoldOblique.pfa
  202.     xpdf.t1Courier:              /usr/local/fonts/Courier.pfa
  203.     xpdf.t1CourierOblique:       /usr/local/fonts/Courier-Oblique.pfa
  204.     xpdf.t1CourierBold:          /usr/local/fonts/Courier-Bold.pfa
  205.     xpdf.t1CourierBoldOblique:   /usr/local/fonts/Courier-BoldOblique.pfa
  206.     xpdf.t1Symbol:               /usr/local/fonts/Symbol.pfa
  207.     xpdf.t1ZapfDingbats:         /usr/local/fonts/ZapfDingbats.pfa
  208.  
  209. Ghostscript comes with a set of free, high-quality Type 1 fonts,
  210. donated by URW++ Design and Development Incorporated.  The xpdf X
  211. resources needed for these fonts are:
  212.  
  213.     xpdf.t1TimesRoman:           /usr/ghostscript/fonts/n021003l.pfb
  214.     xpdf.t1TimesItalic:          /usr/ghostscript/fonts/n021023l.pfb
  215.     xpdf.t1TimesBold:            /usr/ghostscript/fonts/n021004l.pfb
  216.     xpdf.t1TimesBoldItalic:      /usr/ghostscript/fonts/n021024l.pfb
  217.     xpdf.t1Helvetica:            /usr/ghostscript/fonts/n019003l.pfb
  218.     xpdf.t1HelveticaOblique:     /usr/ghostscript/fonts/n019023l.pfb
  219.     xpdf.t1HelveticaBold:        /usr/ghostscript/fonts/n019004l.pfb
  220.     xpdf.t1HelveticaBoldOblique: /usr/ghostscript/fonts/n019024l.pfb
  221.     xpdf.t1Courier:              /usr/ghostscript/fonts/n022003l.pfb
  222.     xpdf.t1CourierOblique:       /usr/ghostscript/fonts/n022023l.pfb
  223.     xpdf.t1CourierBold:          /usr/ghostscript/fonts/n022004l.pfb
  224.     xpdf.t1CourierBoldOblique:   /usr/ghostscript/fonts/n022024l.pfb
  225.     xpdf.t1Symbol:               /usr/ghostscript/fonts/s050000l.pfb
  226.     xpdf.t1ZapfDingbats:         /usr/ghostscript/fonts/d050000l.pfb
  227.  
  228. You will obviously need to replace '/usr/ghostscript/fonts' with the
  229. appropriate path on your system.
  230.  
  231.  
  232. The Unisys LZW Patent
  233. ---------------------
  234.  
  235. Nearly all PDF files include data which has been compressed with the
  236. LZW compression algorithm.  Unfortunately, LZW is covered by a
  237. software patent which is owned by Unisys Corporation.  Unisys refuses
  238. to license this patent for PDF-related use in software such as Xpdf
  239. which is released for free and which may be freely redistributed.
  240. (This is same algorithm which is used by GIF.  However, Unisys is not
  241. doing licensing for free PDF viwers in the same way as for free GIF
  242. viewers.)
  243.  
  244. As a workaround, Xpdf converts PDF-format LZW data to compress-format
  245. LZW data.  (The standard UNIX compress utility also uses LZW, but with
  246. a slightly different file format.)  This conversion does *not*
  247. decompress the data; it simply converts it to a different file format.
  248. Xpdf then calls uncompress to actually decompress the data.
  249.  
  250. I have been told by several notable people that the LZW patent covers
  251. compression only, and does not cover decompression.  This seems pretty
  252. fuzzy to me, so I'm going to stick with my workaround, at least for
  253. now.
  254.  
  255. For Unisys's slant on things (mostly regarding GIF), see
  256. <http://www.unisys.com/LeadStory/lzwterms.html> and
  257. <http://www.unisys.com/LeadStory/lzwfaq.html>.  These pages mention
  258. an email address for feedback.
  259.  
  260.  
  261. Compiling Xpdf
  262. --------------
  263.  
  264. See the separate file, INSTALL.
  265.  
  266.  
  267. Bugs
  268. ----
  269.  
  270. Type 3 fonts are still not well supported by Xpdf.
  271.  
  272. If you find a bug in Xpdf, i.e., if it prints an error message,
  273. crashes, or incorrectly displays a document, and you don't see that
  274. bug listed here, please send me email, with a pointer (URL, ftp site,
  275. etc.) to the PDF file.
  276.  
  277.  
  278. Acknowledgments
  279. ---------------
  280.  
  281. Thanks to:
  282.  
  283. * Patrick Voigt for help with the remote server code.
  284. * Patrick Moreau, Martin P.J. Zinser, and David Mathog for the VMS
  285.   port.
  286. * David Boldt and Rick Rodgers for sample man pages.
  287. * Brendan Miller for the icon idea.
  288. * Olly Betts for help testing pdftotext.
  289. * Peter Ganten for the OS/2 port.
  290. * Michael Richmond for the Win32 port of pdftops and pdftotext.
  291. * Frank M. Siegert for improvements in the PostScript code.
  292. * Leo Smiers for the decryption patches.
  293. * Rainer Menzner for creating t1lib, and for helping me adapt it to
  294.   xpdf.
  295. * Pine Tree Systems A/S for funding the OPI and EPS support in
  296.   pdftops.
  297.  
  298.  
  299. References
  300. ----------
  301.  
  302. Adobe Systems Inc., _PDF Reference_, 2nd ed.
  303. Addison-Wesley, 2000, ISBN 0-201-61588-6.
  304. [The printed manual for PDF version 1.3.]
  305.  
  306. Adobe Systems Inc., _Portable Document Format: Changes from Version
  307. 1.3 to 1.4_, Adobe Developer Support Technical Note #5409.
  308. June 11, 2001.
  309. http://partners.adobe.com/asn/developer/acrosdk/docs/filefmtspecs/PDF14Deltas.pdf
  310. [Updates for PDF 1.4.]
  311.  
  312. Adobe Systems Inc., _PostScript Language Reference_, 3rd ed.
  313. Addison-Wesley, 1999, ISBN 0-201-37922-8.
  314. [The official PostScript manual.]
  315.  
  316. Adobe Systems, Inc., _The Type 42 Font Format Specification_,
  317. Adobe Developer Support Technical Specification #5012.  1998.
  318. http://partners.adobe.com/asn/developer/pdfs/tn/5012.Type42_Spec.pdf
  319. [Type 42 is the format used to embed TrueType fonts in PostScript
  320. files.]
  321.  
  322. Adobe Systems, Inc., _Adobe CMap and CIDFont Files Specification_,
  323. Adobe Developer Support Technical Specification #5014.  1995.
  324. http://www.adobe.com/supportservice/devrelations/PDFS/TN/5014.CIDFont_Spec.pdf
  325. [CMap file format needed for Japanese and Chinese font support.]
  326.  
  327. Adobe Systems, Inc., _Adobe-Japan1-2 Character Collection for
  328. CID-Keyed Fonts_, Adobe Developer Support Technical Note #5078.
  329. 1994.
  330. http://partners.adobe.com/asn/developer/PDFS/TN/5078.CID_Glyph.pdf
  331. [The Adobe Japanese character set.]
  332.  
  333. Adobe Systems, Inc., _Adobe-GB1-3 Character Collection for
  334. CID-Keyed Fonts_, Adobe Developer Support Technical Note #5079.
  335. 1998.
  336. http://partners.adobe.com/asn/developer/PDFS/TN/5079.GB_CharColl.pdf
  337. [The Adobe Chinese GB character set.]
  338.  
  339. Adobe Systems, Inc., _Adobe-CNS1-3 Character Collection for
  340. CID-Keyed Fonts_, Adobe Developer Support Technical Note #5080.
  341. 2000.
  342. http://partners.adobe.com/asn/developer/PDFS/TN/5080.CNS_CharColl.pdf
  343. [The Adobe Chinese CNS character set.]
  344.  
  345. Adobe Systems Inc., _Supporting the DCT Filters in PostScript Level
  346. 2_, Adobe Developer Support Technical Note #5116.  1992.
  347. http://www.adobe.com/supportservice/devrelations/PDFS/TN/5116.PS2_DCT.PDF
  348. [Description of the DCTDecode filter parameters.]
  349.  
  350. Adobe Systems Inc., _Open Prepress Interface (OPI) Specification -
  351. Version 2.0_, Adobe Developer Support Technical Note #5660.  2000.
  352. http://partners.adobe.com/asn/developer/PDFS/TN/5660.OPI_2.0.pdf
  353.  
  354. Adobe Systems Inc., CMap files.
  355. ftp://ftp.oreilly.com/pub/examples/nutshell/cjkv/adobe/
  356. [The actual CMap files for the 16-bit CJK encodings.]
  357.  
  358. Aldus Corp., _OPI: Open Prepress Interface Specification 1.3_.  1993.
  359. http://partners.adobe.com/asn/developer/PDFS/TN/OPI_13.pdf
  360.  
  361. Anonymous, RC4 source code.
  362. ftp://ftp.ox.ac.uk/pub/crypto/misc/rc4.tar.gz
  363. ftp://idea.sec.dsi.unimi.it/pub/crypt/code/rc4.tar.gz
  364. [This is the algorithm used to encrypt PDF files.]
  365.  
  366. CCITT, _Blue Book_, Volume VII Fascicle 3: "Terminal Equipment and
  367. Protocols for Telematic Services", Recommendations T.4 and T.6.
  368. ftp://ftp.uu.net/doc/standards/ccitt/1988/7_3_01.ps
  369. ftp://ftp.uu.net/doc/standards/ccitt/1988/7_3_02.ps
  370. [The official Group 3 and 4 fax standards.  The online copies are
  371. unfortunately misformatted.]
  372.  
  373. L. Peter Deutsch, "ZLIB Compressed Data Format Specification version
  374. 3.3".  RFC 1950.
  375. [Information on the general format used in FlateDecode streams.]
  376.  
  377. L. Peter Deutsch, "DEFLATE Compressed Data Format Specification
  378. version 1.3".  RFC 1951.
  379. [The definition of the compression algorithm used in FlateDecode
  380. streams.]
  381.  
  382. Jim Flowers, "X Logical Font Description Conventions", Version 1.5, X
  383. Consortium Standard, X Version 11, Release 6.1.
  384. ftp://ftp.x.org/pub/R6.1/xc/doc/hardcopy/XLFD/xlfd.PS.Z
  385. [The official specification of X font descriptors, including font
  386. transformation matrices.]
  387.  
  388. Foley, van Dam, Feiner, and Hughes, _Computer Graphics: Principles and
  389. Practice_, 2nd ed.  Addison-Wesley, 1990, ISBN 0-201-12110-7.
  390. [Colorspace conversion functions, Bezier spline math.]
  391.  
  392. Robert L. Hummel, _Programmer's Technical Reference: Data and Fax
  393. Communications_.  Ziff-Davis Press, 1993, ISBN 1-56276-077-7.
  394. [CCITT Group 3 and 4 fax decoding.]
  395.  
  396. Christoph Loeffler, Adriaan Ligtenberg, George S. Moschytz, "Practical
  397. Fast 1-D DCT Algorithms with 11 Multiplications".  IEEE Intl. Conf. on
  398. Acoustics, Speech & Signal Processing, 1989, 988-991.
  399. [The fast IDCT algorithm used in the DCTDecode filter.]
  400.  
  401. Microsoft, _TyueType 1.0 Font Files_, rev. 1.66.  1995.
  402. http://www.microsoft.com/typography/tt/tt.htm
  403. [The TrueType font spec (in MS Word format, naturally).]
  404.  
  405. Charles Poynton, "Color FAQ".
  406. http://www.inforamp.net/~poynton/ColorFAQ.html
  407. [The mapping from the CIE 1931 (XYZ) color space to RGB.]
  408.  
  409. R. Rivest, "The MD5 Message-Digest Algorithm".  RFC 1321.
  410. [MD5 is used in PDF document encryption.]
  411.  
  412. Gregory K. Wallace, "The JPEG Still Picture Compression Standard".
  413. ftp://ftp.uu.net/graphics/jpeg/wallace.ps.gz
  414. [Good description of the JPEG standard.  Also published in CACM, April
  415. 1991, and submitted to IEEE Transactions on Consumer Electronics.]
  416.  
  417. W3C Recommendation, "PNG (Portable Network Graphics) Specification
  418. Version 1.0".
  419. http://www.w3.org/Graphics/PNG/
  420. [Defines the PNG image predictor.]
  421.  
  422. "ISO 8859-2 (Latin 2) Resources".
  423. http://sizif.mf.uni-lj.si/linux/cee/iso8859-2.html
  424. [This is a web page with all sorts of useful Latin-2 character set and
  425. font information.]
  426.