Welcome to the public release of PStill/FreeBSD (Command line version)

(c) by Frank Siegert, 1998-2002, see COPYRIGHT file for more info
All trademarks used within this document or the PStill software belongs to
the respective owners and are used for identification purpose only.
'PStill' is a registered trademark ('wordmark') of Frank Siegert

See the pstill web page http://www.pstill.com
for more information and updates.

*** THIS IS NOT A FREEWARE PRODUCT, PLEASE READ THE FOLLOWING ***

PStill is inexpensive shareware, please do not priate this software
or further development is not possible. Private and educational use
of this FreeBSD Version is allowed without registration and costs.

Any commercial users must aquire a license, please see

	 http://www.pstill.com

to order one online or use the enclosed registration form. As 
commercial use counts any use that directly or indirectly uses 
PStill, its services or results to gain profits.

You are using this software entirely at your own risk. The author
is not responsible for any damage its use or misuse might cause.
Especially he is not responsible for the accuracy or quality of
the produced PDF files. Having said that, I hope PStill will be
helpful to you, please drop me a note if you find it useful or
encourage others to try it.

PLEASE NOTE:

You need to purchase a license for every instance of PStill you
run in a commercial environment. An instance is a running program of
PStill regardless of working environment (client or server).

Please contact frank@wizards.de for more information about licensing
options and volume licenses.


**** INSTALLATION PROCEDURE ****

1. copy the pstillXXXX.tar.gz archive to a suitable place

2. unpack it using: 

   gzcat pstillXXXX.tar.gz | tar -xvf -

   or (if gnutar is present)

   tar xzvf pstillXXXX.tar.gz

3. cd pstill_dist
  
   you should find
  
   pstill      (the converter as static binary for your platform)
   annots.sl   (the pdfmark interpreter as S-LANG script)
   init.still  (the converter initialization file)
   PSFonts     (the 'Font Pool', a directory to hold all PS fonts, now empty)
   INSTALL     (this Text)
   COPYRIGHT   (the usage conditions and registration information)
   README.*    (things you should know)
   testfile.ps (a postscript testfile)
   registration.pdf (the license order form, 
	             PDF-1.2 comp. reader needed to view!)

4. run 

   pstill -H | more

   and see the options and further procedures. In particular you may
   have to set the PSTILL_PATH environment and put pstill in your
   search path. PSTILL_PATH must point to the directory where pstill
   finds its helper programs and the PSFonts directory.

   If you do not set the PSTILL_PATH variable pstill assumes it is
   working inside its home directory (where init.still and PSFonts are located)

   Example (assuming pstill_dist in /usr/local):

   For csh/tcsh: setenv PSTILL_PATH /usr/local/pstill_dist

   For bash:     PSTILL_PATH="/usr/local/pstill_dist"
                 export PSTILL_PATH 

   Put this into your profile or .cshrc startup file.

5. Install the fonts (depending on your system you might need to have X11
   installed). You can also copy over fonts from other systems, as long
   as your font software license of your font vendor allows. Type 1 fonts
   come as files called "abcdef.pfb" or similar for use on Windows PCs.

   cd PSFonts
   ../linkAllFonts.sh      OR      copy your PFA or PFB fonts here
   cd ..
   ./pstill -vI

   PStill will not run without a font pool (in PSFonts), especially
   it will need the "Courier" font to fall back when a font is not found.
   If Courier is not installed PStill will default to a 'black dot' font
   that paints a large black dot in the place of a gylph, usually not what
   you want. "Courier" comes as part of most X11 installations.

   If some fonts fails here with an error, this is intended. PStill
   is quite picky with its fonts and if they do not pass certain
   tests they won't be used for PDF generation, to spare you problems
   later.

   You can use most Type 1 (prefered) and Type 3 PostScript fonts in
   either PFA or PFB format. Type 3 may be converted to bitmaps/outlines
   in the resulting PDF thus bloating the output, keep this in mind when
   creating PS file with dvips for use with pstill!

   PStill is now installed. Now run a test:

6. Convert the supplied testfile.ps

   pstill -cccc -gipt -o testfile.pdf testfile.ps
   
   then open it using acroread (if installed on your system, otherwise
   xpdf 0.93 or newer will work too)

   acroread testfile.pdf

   (You need Acrobat Reader >= 3.x for displaying compressed (-c option) PDFs)

If this works fine, you can convert your own files. 

If you see only black dots instead of text lines you need to install
fonts and at least Courier is missing!

To add new fonts copy the font files (pfa or pfb format, no truetype)
to the PSFonts directory and run pstill -I again. Filenames are irrelevant
as PStill will extract the 'true' fontname and rename the file accordingly.



A note about too dark colors in the PDF output:

Use option -C to write colors as RGB. Some readers show CMYK too dark.

A note about conversion speed:

PStill is made to create PDF for best printing quality. It is not
tuned for conversion speed but for output quality. Use Type 1 fonts (also
for dvips) for best speed and results.

A note about PostScript Level 2 files:

PStill emulates most Level 2 constructs, when your PS job needs to identify
a Level 2 RIP use option "-2". 

A note about Mathematica 3.0/4.x PostScript Files:

PStill was especially tuned to handle MMA 3.0 and 4.0 generated PS files and 
handle the potential problems when using the Math font family.

A note about TeX PS files:

DVIPS generated PS file with bitmap fonts tend to become very large
PDFs and distill a long time. Use FixFonts (on the pstill web page)
or recreate them using Type 1 fonts.

A note about temp space:

During its first phase (PS interpretation) PStill is writing to /tmp
and needs space to work. If no space is available it may fail during this
stage. Please provide at least 20 MByte scratch area. You may change the
default temporary directory using the '-T path' option.

A note about VM:

During its second phase (PDF generation) PStill holds the complete PDF
file in memory. For large files this could be quite a substancial amount
of memory, so please provide enough swap space (and memory). An upcoming
version of PStill will use temp space in the filesystem for larger conversions.

A note about security:

PStill includes a full interpreter with file I/O capacities, so do not
run it as root as it is able to open/read/write files if told so in the
PostScript input. Running pstill in a closed environment or check the 
PostScript files with pscheck (inquire by email for more details) before is
usually a good idea if they come from suspicious sources. PStills write
mechanism is turned off by default - you can reactivate it using option -k

A note about fonts:

You can use most any Type 1 and Type 3 fonts in PFA or PFB format for the
fontpool, however the names do always match the true fontname. Some nice
fonts can be found as part of certain OpenSource products like GIMP or 
GNU Ghostscript. Others are commercial. PStill may handle an unlimited
number of fonts in its font pool.

Be sure to read the license agreement for your fonts before including them
in a PDF.

PStill is shareware, so you have to register if you use it for commercial
purposes. 

Please provide feedback or send feature requests to frank@wizards.de
Updates are available from http://www.pstill.com

Thanks for using PStill

	Frank Siegert


