trunk/Master/texmf/doc/pkfix

git-svn-id: svn://tug.org/texlive/trunk@44 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 241 insertions, 0 deletions

diff --git a/Master/texmf/doc/pkfix/README b/Master/texmf/doc/pkfix/README
new file mode 100644
index 00000000000..5e97fa2d779
--- /dev/null
+++ b/Master/texmf/doc/pkfix/README
@@ -0,0 +1,241 @@
+README for project pkfix 2005/02/25 v1.3
+
+TABLE OF CONTENTS
+=================
+A. Project pkfix
+B. Copyright, Disclaimer, License
+C. Files
+D. Requirements
+E. Installation
+F. User Interface
+G. Author
+H. Questions, Suggested Improvements
+I. Known Problems
+J. History
+
+A. PROJECT PKFIX
+================
+Often PostScript files with embedded pk fonts are available that
+were generated by dvips. If these files are converted to pdf,
+the quality is very poor because of the bitmapped fonts.
+But what can be done, if the sources dvi or tex are not available?
+  This project pkfix tries a solution by replacing the used
+pk fonts by the type 1 ones.
+  It scans the file for the pk fonts by searching the comments,
+introduced by not too old dvips versions. For each detected bitmap
+font pkfix generates a tex file that uses this font. Then it runs
+dvips with option setting for pdf and hopes, that the corresponding
+type 1 font is found and included in the temporary PostScript file.
+So this font will be extracted and replaces the bitmapped font of
+the original PostScript file.
+
+CAUTION: The state is experimental. Tests are only done with teTeX.
+
+B. COPYRIGHT, DISCLAIMER, LICENSE
+=================================
+Copyright (C) 2001, 2005 Heiko Oberdiek.
+
+This work may be distributed and/or modified under the
+conditions of the LaTeX Project Public License, either version 1.3
+of this license or (at your option) any later version.
+The latest version of this license is in
+  http://www.latex-project.org/lppl.txt
+and version 1.3 or later is part of all distributions of LaTeX
+ version 2003/12/01 or later.
+This work has the LPPL maintenance status "maintained".
+This Current Maintainer of this work is Heiko Oberdiek.
+
+C. FILES
+========
+The project `pkfix' consists of two files:
+pkfix(.pl): This perl script is the main program. The extension
+            `.pl' may be omitted.
+README:     Documentation, the file you are reading.
+
+Following temporary files are produced if `pkfix' is invoked
+($$ means the job number):
+_pkfix_$$.tex, _pkfix_$$.log, _pkfix_$$.dvi, _pkfix_$$.ps
+eventually missfont.log
+
+D. REQUIREMENTS
+===============
+* Perl5 (version 5 of the perl interpreter).
+* TeX (plain format)
+* dvips (not too old, for example 5.86)
+* texps.pro (part of dvips)
+* fonts
+
+E. INSTALLATION
+===============
+1. TeX directory structure (TDS):
+   The file
+     `README' (documentation)
+   go to
+     texmf/doc/programs/pkfix/README
+   or
+     texmf/doc/pkfix/README
+
+2. Perl script `pkfix.pl':
+
+   Unix
+   * Your are allowed to rename `pkfix.pl' to `pkfix':
+       mv pkfix.pl pkfix
+   * Ensure that the execute permission is set:
+       chmod +x pkfix
+   * Move the file to a directory where the shell can find it
+     (environment variable PATH, e.g. /usr/local/bin/).
+
+   Dos/Windows/(OS2)
+   * Running the perl interpreter directly with the perl script:
+       perl pkfix.pl ...
+   * Methods for calling by typing the script name without extension
+     and perl interpreter:
+     a) If your perl distribution provides a pl2exe program,
+        use it to generate `pkfix.exe'.
+        Advantage: I/O redirection works.
+     b) A good method is a dos program of John Dallman:
+          #!perl.exe (versions below 4)
+          hbperl.exe (version 4)
+        http://www.perl.com/CPAN/authors/id/JDALLMAN/hbp_403.zip
+        Move pkfix.pl in a PERLLIB directory and copy the
+        exe program to `pkfix.exe'. Then the program looks
+        for the perl interpreter, the script and calls them.
+        Advantage: I/O redirection works.
+     c) Windows NT 4.0 users can use associated file types:
+          SET PATHEXT=.pl;%PATHEXT%
+        See perl win32 faq "How do I associate Perl scripts with perl?":
+        http://www.activestate.com/support/faqs/win32/perlwin32faq4.html
+        Disadvantage: I/O redirection does not work.
+     d) 4DOS: SET .PL=c:/bin/perl.exe
+        See perl win32 faq "How can I get Perl to run a Perl script at
+        the 4DOS command line by typing the name of the script without
+        the extension or "perl", just like a regular exe file?":
+        http://www.activestate.com/support/faqs/win32/perlwin32faq1.html
+     e) Convert the perl script to a batch file `pkfix.bat', if your
+        distribution provides `pl2bat.bat'.
+        Disadvantage: I/O redirection does not work.
+     Many of this methods are listed in the perl win32 faq
+     "What's the equivalent of the shebang ("#!") syntax for Win32?":
+     http://www.activestate.com/support/faqs/win32/perlwin32faq4.html
+
+F. USER INTERFACE
+=================
+The perl script `pkfix.pl' can be invoked in two ways:
+a) pkfix --help
+   prints a help screen with the options and some default values.
+b) pkfix [options] <input.ps> <output.ps>
+   <input.ps> is the original PostScript file with pk fonts,
+   <output.ps> will be the result.
+
+Options:
+--clean:       Removing of the temporary files.
+--quiet        Messages except warnings are suppressed.
+--verbose      Informations about the actions are printed.
+--debug        Additional messages for debugging purposes;
+               also option `--clean' is disabled.
+--options opt  Here the options for the dvips run can be changed,
+               default is "-Ppdf -G0".
+The other options are experimental.
+
+Example:
+  pkfix --verbose test.ps out.ps
+
+If a file name is replaced by "-" then the standard input/output is
+used. In case of standard output, messages of pkfix are written to
+standard error output. Thus pkfix can be used in pipes, eg:
+  pkfix foo.ps - | ps2pdf - foo.pdf
+  cat foo.ps | pkfix --quiet - - | ps2pdf - - >foo.pdf
+
+Environment variable `PKFIX':
+Before scanning the command line for options the perl script
+`pkfix.pl' looks for the environment variable `PKFIX'.
+Example (bash syntax):
+  export PKFIX="--verbose"
+Example (DOS syntax):
+  SET PKFIX=--verbose
+
+G. AUTHOR
+=========
+Heiko Oberdiek
+Email: oberdiek@uni-freiburg.de
+
+Many thanks to Berthold Crysmann (crysmann at dfki.de)
+and Harald Harders (h.harders at tu-bs.de) for testing
+and bug reports.
+
+H. QUESTIONS, SUGGESTED IMPROVEMENTS
+====================================
+If you have questions, problems with `pkfix', error reports,
+if you have improvements or want to have additional features,
+please send them to the author.
+
+My environment for developing and testing:
+* linux, suse 9.1
+* perl 5.8.1
+* tex 3.14159
+* dvips 5.94a
+* kpsewhich 3.5.2
+
+I. KNOWN PROBLEMS
+=================
+* I have only tested with a few test files on a linux machine
+  with teTeX.
+* PostScript files, generated with older dvips versions
+  (for example 5.58), do not contain the essential comments,
+  so pkfix does not detect pk fonts.
+* The perl script pkfix uses dvips and analyses its output,
+  so the version should not be too old (5.86 recommanded).
+  Some older (not too old) versions do not know the option
+  "-G0". As workaround the options for dvips can currently
+  be overwritten by an option for pkfix "--options".
+  Example: --options="-Pcmz -Pamz".
+* The new embedded type 1 fonts are not added to the
+  DSC comment %%DocumentFonts'.
+* It is assumed that the conversion bitmap to type 1 font
+  does not result in type 1 fonts that are already present.
+  Then this font would be added twice with probably differnt
+  subsettings with the consequence of missing characters.
+
+J. HISTORY
+==========
+2001/04/12 v0.1:
+  * First try.
+2001/04/13 v0.2:
+  * TeX/dvips is called for each font for the case of errors.
+  * First release.
+2001/04/15 v0.3:
+  * Call of kpsewhich with option --progname.
+  * Extracting of texps.pro from temporary PostScript file,
+    if kpsewhich failed.
+  * Option -G0 for dvips run added.
+2001/04/16 v0.4:
+  * Support for merging PostScript fonts added.
+  * \special{!...}/@fedspecial detection added.
+  * Bug fix: I detection.
+2001/04/17 v0.5:
+  * Redirection of stderr (dvips run) if possible.
+2001/04/20 v0.6:
+  * Bug fix: dvips font names can contain numbers.
+2001/04/21 v0.7:
+  * Bug fix: long dvi file name in ps file.
+2001/04/23 v0.8:
+  * Bug fix: post string parsing.
+2001/04/26 v0.9:
+  * Check of version number of dvips in PostScript file.
+2001/06/30 v1.0:
+  * Problem with DOS line ending fixed.
+2005/01/28 v1.1:
+  * Bug fix: encoding files are now included.
+  * The intermediate DVI files are written directly.
+  * LPPL 1.3
+2005/01/29 v1.2:
+  * Merging is now based on type 1 names. This solves
+    the problem, if different bitmap fonts maps to the
+    same type 1 font, eg. (ecrm1000, larm1000) -> SFRM1000.
+  * Suppression of PK generation, if environment variable
+    MKTEXPK is supported.
+  * If output file is "-" (standard output) then messages of
+    pkfix are written to standard error output.
+2005/02/25 v1.3:
+  * Bug fix: Detection of "@fedspecial end" improved.
+  * Bug fix: Typo corrected (PRT -> $PRT).