README for project pkfix 2012/04/18 v1.7

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.

NOTICE:
  pkfix works only for PostScript files that are generated
  by dvips 5.58 or newer. These versions records the used
  font in a PostScript comment.
    Scott Pakin wrote `pkfix-helper' that uses a heuristics
  to guess the original fonts and writes a PostScript file
  that is suitable for processing by pkfix. The Perl script
  `pkfix-helper' is available at CTAN:support/pkfix-helper.

B. COPYRIGHT, DISCLAIMER, LICENSE
=================================
Copyright (C) 2001, 2005, 2007, 2009, 2011, 2012 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: heiko.oberdiek at googlemail.com

Many thanks to
* Berthold Crysmann (crysmann at dfki.de) and
  Harald Harders (h.harders at tu-bs.de) for testing
  and bug reports.
* Melissa O'Neill for providing a patch to support dvips 5.399.
* Scott Pakin who wrote pkfix-helper.

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.

The environment that I had used for developing and testing:
* linux, suse 9.1
* perl 5.8.1
* tex 3.14159
* dvips 5.94a
* kpsewhich 3.5.2

(Nowadays I have installed TeX Live, for instance).

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. See Scott Pakin's pkfix-helper
  that addresses this problem.
* 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).
2007/11/07 v1.4:
  * Deprecation warning of perl 5.8.8 fixed.
2009/03/18 v1.5:
  * Patch to support dvips 5.399 (submitted by Melissa O'Neill).
2011/04/22 v1.6:
  * Bug fix: input and output files are read and written in
    binary mode (thanks M.S. Dousti for bug report).
2012/04/18 v1.7:
  * Option --version added.