home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / programs / textual / pdf / Docs / xpdf_docs / README < prev    next >
Text File  |  1998-02-22  |  12KB  |  361 lines
  1. xpdf
  2. ====
  3. and: pdftops, pdftotext
  4.  
  5. version 0.7a (beta)
  6. 98-feb-22
  7.  
  8. The xpdf, pdftops, and pdftotext software and documentation are
  9. copyright 1996-1998 Derek B. Noonburg.
  10.  
  11. Email: derekn@aimnet.com
  12. WWW: http://www.aimnet.com/~derekn/xpdf/
  13.  
  14. The PDF data structures, operators, and specification are
  15. copyright 1995 Adobe Systems Inc.
  16.  
  17.  
  18. What is xpdf?
  19. -------------
  20.  
  21. Xpdf is a viewer for Portable Document Format (PDF) files.  (These are
  22. also sometimes also called 'Acrobat' files, from the name of Adobe's
  23. PDF software.)  Xpdf runs under the X Window System on UNIX, VMS, and
  24. OS/2.
  25.  
  26. Xpdf is designed to be small and efficient.  It does not use the Motif
  27. or Xt libraries.  It uses standard X fonts.  Xpdf is quite usable on a
  28. 486-66 PC running Linux.
  29.  
  30.  
  31. Compatibility
  32. -------------
  33.  
  34. Xpdf is developed and tested on a Linux 2.0 x86 system.
  35.  
  36. In addition, it has been compiled by others on Solaris, AIX, HP-UX,
  37. SCO UnixWare, Digital Unix, Irix, and numerous other Unix
  38. implementations, as well as VMS, and OS/2.  It should work on pretty
  39. much any system which runs X11 and has Unix-like libraries.  You'll
  40. need ANSI C++ and C compilers to compile it.
  41.  
  42. If you compiled xpdf for a system not listed on the web page, please
  43. let me know.  If you're willing to make your binary available by ftp
  44. or on the web, I'll be happy to add a link from the xpdf web page.  I
  45. have decided not to host any binaries I didn't compile myself (for
  46. disk space and support reasons).
  47.  
  48. If you can't get xpdf to compile on your system, send me email and
  49. I'll try to help.
  50.  
  51. Ports of xpdf to the Acorn and Amiga have been made.  See the xpdf web
  52. page for links.
  53.  
  54.  
  55. Getting xpdf
  56. ------------
  57.  
  58. The latest version is available from:
  59.  
  60.   http://www.aimnet.com/~derekn/xpdf/
  61.  
  62. or:
  63.  
  64.   ftp://ftp.aimnet.com/pub/users/derekn/xpdf/
  65.  
  66. Source code and several precompiled executables are available.
  67.  
  68. Announcements of new versions are posted to several newsgroups
  69. (comp.text.pdf, comp.os.linux.announce, and others) and emailed to a
  70. list of people.  If you'd like to receive email notification of new
  71. versions, just let me know.
  72.  
  73.  
  74. Running xpdf
  75. ------------
  76.  
  77. To run xpdf, simply type:
  78.  
  79.   xpdf file.pdf
  80.  
  81. To generate a PostScript file, hit the "print" button in xpdf, or run
  82. pdftops:
  83.  
  84.   pdftops file.pdf
  85.  
  86. To generate a plain text file, run pdftotext:
  87.  
  88.   pdftotext file.pdf
  89.  
  90. Command line options and many other details are described in the man
  91. pages (xpdf.1, pdftops.1, and pdftotext.1) and the VMS help files
  92. (xpdf.hlp, pdftops.hlp, and pdftotext.hlp).
  93.  
  94.  
  95. Fonts
  96. -----
  97.  
  98. Xpdf uses X server fonts.  It requires the following fonts:
  99.  
  100. * Courier: medium-r, bold-r, medium-o, and bold-o
  101. * Helvetica: medium-r, bold-r, medium-o, and bold-o
  102. * Times: medium-r, bold-r, medium-i, and bold-i
  103. * Symbol: medium-r
  104. * Zapf Dingbats: medium-r
  105.  
  106. Most X installations should already have all of these fonts, except
  107. Zapf Dingbats.  You can install a Type 1 Zapf Dingbats font -- see the
  108. mkfontdir(1) man page for details.  Use this font descriptor in your
  109. fonts.scale file:
  110.  
  111.     -itc-zapfdingbats-medium-r-normal--0-0-0-0-p-0-adobe-fontspecific
  112.  
  113. You can get a Type 1 font file from the ghostscript 4.x distribution
  114. (look for d050000l.pfb).
  115.  
  116. X servers, starting at R5, support font scaling.  Xpdf will
  117. automatically take advantage of this.  There are two types of scaling.
  118. The first type uses standard bitmap fonts: if a font doesn't exist in
  119. the requested size, the server will scale the bitmapped characters.
  120. This is reasonably fast, and the results are readable but not very
  121. pretty.  X servers can also handle true scalable, e.g., Type 1, fonts.
  122. (See the mkfontdir(1) man page for details on setting these up.)
  123. Scalable fonts are slower, especially since PDF documents tend to use
  124. lots of fonts, but they look much nicer.
  125.  
  126. Some X servers also support font rotation.  Xpdf will use this feature
  127. if available.
  128.  
  129.  
  130. The Unisys LZW Patent
  131. ---------------------
  132.  
  133. Nearly all PDF files include data which has been compressed with the
  134. LZW compression algorithm.  Unfortunately, LZW is covered by a
  135. software patent which is owned by Unisys Corporation.  Unisys refuses
  136. to license this patent for PDF-related use in software such as xpdf
  137. which is released for free and which may be freely redistributed.
  138. (This is same algorithm which is used by GIF.  However, Unisys is not
  139. doing licensing for free PDF viwers in the same way as for free GIF
  140. viewers.)
  141.  
  142. As a workaround, xpdf converts PDF-format LZW data to compress-format
  143. LZW data.  (The standard UNIX compress utility also uses LZW, but with
  144. a slightly different file format.)  This conversion does *not*
  145. decompress the data; it simply converts it to a different file format.
  146. Xpdf then calls uncompress to actually decompress the data.
  147.  
  148. I have been told by several notable people that the LZW patent covers
  149. compression only, and does not cover decompression.  This seems pretty
  150. fuzzy to me, so I'm going to stick with my workaround, at least for
  151. now.
  152.  
  153. For Unisys's slant on things (mostly regarding GIF), see
  154. <http://www.unisys.com/LeadStory/lzwterms.html> and
  155. <http://www.unisys.com/LeadStory/lzwfaq.html>.  These pages mention
  156. an email address for feedback.
  157.  
  158.  
  159. Compiling xpdf
  160. --------------
  161.  
  162. Xpdf is written in C++ (with a little bit of C).  It should work with
  163. any ANSI-compliant C++ and C compilers.  The systems and compilers
  164. it's been tested with are listed on the xpdf web page.
  165.  
  166. *** To compile xpdf for UNIX:
  167.  
  168. * Run the configure script:
  169.  
  170.     ./configure
  171.  
  172.   This should produce a set of makefiles customized for your system.
  173.   The configure script accepts the following options (in addition to
  174.   the usual things accepted by autoconf configure scripts):
  175.  
  176.     --enable-a4-paper
  177.         Switches the paper size for PostScript output (xpdf and
  178.         pdftops) to A4.  The default is Letter size.
  179.  
  180.     --enable-no-text-select
  181.         With this option, xpdf will not copy text.  (This is only
  182.         useful on closed systems where the user can't get at the PDF
  183.         file directly.)
  184.  
  185.     --with-gzip
  186.         Use gzip instead of uncompress.
  187.  
  188. * Type 'make'.  This should build the executables:
  189.  
  190.     xpdf/xpdf
  191.     pdftops/pdftops
  192.     pdftotext/pdftotext
  193.  
  194.   You can also do 'make xpdf', etc., to compile just one of the
  195.   executables.
  196.  
  197. * If desired, type 'make install' to install the binaries and man
  198.   pages.
  199.  
  200. If the configure script doesn't work for some reason, the old
  201. Makefile.config and Makefiles are included (as Makefile.config.old,
  202. Makefile.old, and */Makefile.old).  But please let me
  203. (derekn@aimnet.com) know what went wrong, as I don't intend to support
  204. Makefile.config anymore.
  205.  
  206. *** To compile xpdf for OS/2:
  207.  
  208. Xpdf is known to run under OS/2 with the EMX runtime environment and
  209. XFree86.  The configure script has not been tested on OS/2, however.
  210.  
  211. *** To compile xpdf for VMS:
  212.  
  213. * There are two sets of scripts: vmscomp.com (for gcc on VAX) and
  214.   vmsdecccomp.com (for DEC C on Alpha).  There are four of each: in
  215.   the top-level directory, [.goo], [.ltk], and [.xpdf].  You may need
  216.   to edit these scripts as appropriate for your system.
  217.  
  218. * The 'stddef.h' include file which comes with older versions of gcc
  219.   may be missing a definition for wchar_t.  In this case, add the
  220.   following lines:
  221.   -----
  222.   File GNU_CC:[INCLUDE]STDDEF.H;2
  223.    44   /* Wide characters, not yet supported by VAXCRTL [match VAXC's <stddef.
  224.    45   #if !defined(_WCHAR_T) && !defined(_WCHAR_T_)
  225.    46   typedef unsigned int wchar_t;
  226.    47   #endif
  227.    48   #define _WCHAR_T
  228.    49   #define _WCHAR_T_
  229.    50
  230.   -----
  231.  
  232. * Type '@vmscomp' or '@vmsdecccomp' in the top-level directory.
  233.  
  234. * The executables will be left in '[.xpdf]xpdf' and '[.xpdf]pdftops'.
  235.  
  236.  
  237. Distribution
  238. ------------
  239.  
  240. Xpdf may be distributed under the following conditions:
  241.  
  242. 1. This file ('README') is included, unmodified, in the distribution.
  243.  
  244. 2. The distribution includes:
  245.    a. all of the xpdf source code and documentation, unmodified; OR
  246.    b. one or more xpdf executables, compiled from the unmodified
  247.       source code, plus the associated documentation (UNIX man pages
  248.       or VMS help files); OR
  249.    c. both of the above.
  250.  
  251. If you distribute xpdf, I would appreciate receiving a pointer (ftp
  252. site, BBS phone number, etc.) or a copy (disk, CD-ROM, etc.).
  253.  
  254. Modified versions of xpdf or applications using some or all of the
  255. xpdf code (i.e., 'derivative works' under copyright law) may not be
  256. distributed without explicit permission.
  257.  
  258.  
  259. Bugs
  260. ----
  261.  
  262. This is a beta release of xpdf, and there are still a bunch of PDF
  263. features which I have yet to implement.
  264.  
  265. At this point, the biggest problem is that embedded fonts are not
  266. handled correctly.
  267.  
  268. If you find a bug in xpdf, i.e., if it prints an error message,
  269. crashes, or incorrectly displays a document, and you don't see that
  270. bug listed here, please send me email, with a pointer (URL, ftp site,
  271. etc.) to the PDF file.
  272.  
  273.  
  274. Acknowledgments
  275. ---------------
  276.  
  277. Thanks to:
  278.  
  279. * Patrick Voigt for help with the remote server code.
  280. * Patrick Moreau for the VMS port.
  281. * David Boldt and Rick Rodgers for sample man pages.
  282. * Brendan Miller for the icon idea.
  283. * Olly Betts for help testing pdftotext.
  284. * Peter Ganten for the OS/2 port.
  285. * Michael Richmond for the Win32 port of pdftops and pdftotext.
  286.  
  287.  
  288. References
  289. ----------
  290.  
  291. Adobe Systems Inc., _Portable Document Format Reference Manual_.
  292. Addison-Wesley, 1993, ISBN 0-201-62628-4.
  293. [The printed manual for PDF version 1.0.]
  294.  
  295. Adobe Systems Inc., _Portable Document Format Reference Manual_,
  296. Version 1.2.  November 12, 1996.
  297. [Updated manual for PDF 1.2.  Also includes the encryption spec.
  298. Available on the WWW as
  299. http://www.adobe.com/supportservice/devrelations/PDFS/TN/PDFSPEC.PDF .]
  300.  
  301. Adobe Systems Inc., _PostScript Language Reference Manual_, 2nd ed.
  302. Addison-Wesley, 1990, ISBN 0-201-18127-4.
  303. [The official PostScript manual.]
  304.  
  305. Adobe Systems Inc., _Supporting the DCT Filters in PostScript Level
  306. 2_, Adobe Developer Support Technical Note #5116.  1992.
  307. [Description of the DCTDecode filter parameters.]
  308.  
  309. Anonymous, RC4 source code.
  310. [This is the algorithm used to encrypt PDF files.  Available on
  311. various ftp sites, e.g., ftp://ftp.ox.ac.uk/pub/crypto/misc/rc4.tar.gz
  312. or ftp://idea.sec.dsi.unimi.it/pub/crypt/code/rc4.tar.gz .]
  313.  
  314. CCITT, _Blue Book_, Volume VII Fascicle 3: "Terminal Equipment and
  315. Protocols for Telematic Services", Recommendations T.4 and T.6.
  316. [The official Group 3 and 4 fax standards.  These are available on the
  317. net (but misformatted) as
  318. ftp://ftp.uu.net/doc/standards/ccitt/1988/7_3_01.ps and 7_3_02.ps .]
  319.  
  320. L. Peter Deutsch, "ZLIB Compressed Data Format Specification version
  321. 3.3".  RFC 1950.
  322. [Information on the general format used in FlateDecode streams.]
  323.  
  324. L. Peter Deutsch, "DEFLATE Compressed Data Format Specification
  325. version 1.3".  RFC 1951.
  326. [The definition of the compression algorithm used in FlateDecode
  327. streams.]
  328.  
  329. Jim Flowers, "X Logical Font Description Conventions", Version 1.5, X
  330. Consortium Standard, X Version 11, Release 6.1.
  331. [The official specification of X font descriptors, including font
  332. transformation matrices.  Available on the net as
  333. ftp://ftp.x.org/pub/R6.1/xc/doc/hardcopy/XLFD/xlfd.PS.Z .]
  334.  
  335. Foley, van Dam, Feiner, and Hughes, _Computer Graphics: Principles and
  336. Practice_, 2nd ed.  Addison-Wesley, 1990, ISBN 0-201-12110-7.
  337. [Colorspace conversion functions, Bezier spline math.]
  338.  
  339. Robert L. Hummel, _Programmer's Technical Reference: Data and Fax
  340. Communications_.  Ziff-Davis Press, 1993, ISBN 1-56276-077-7.
  341. [CCITT Group 3 and 4 fax decoding.]
  342.  
  343. Christoph Loeffler, Adriaan Ligtenberg, George S. Moschytz, "Practical
  344. Fast 1-D DCT Algorithms with 11 Multiplications".  IEEE Intl. Conf. on
  345. Acoustics, Speech & Signal Processing, 1989, 988-991.
  346. [The fast IDCT algorithm used in the DCTDecode filter.]
  347.  
  348. R. Rivest, "The MD5 Message-Digest Algorithm".  RFC 1321.
  349. [MD5 is used in PDF document encryption.]
  350.  
  351. Gregory K. Wallace, "The JPEG Still Picture Compression Standard".
  352. [Good description of the JPEG standard.  Available on the net as
  353. ftp://ftp.uu.net/graphics/jpeg/wallace.ps.gz .  Also published in
  354. CACM, April 1991, and submitted to IEEE Transactions on Consumer
  355. Electronics.]
  356.  
  357. "ISO 8859-2 (Latin 2) Resources".
  358. [This is a web page with all sorts of useful Latin-2 character set and
  359. font information:
  360. http://sizif.mf.uni-lj.si/linux/cee/iso8859-2.html .]
  361.