****************************************************************************
*                                                                          *
* This is the wprint program that allows Netscape and Mozilla users to     *
* print web pages written in (at least) UNICODE, Big5 and all ISO-8859-*   *
* charsets provided a suitable TTF font.                                   * 
*                                                                          *
****************************************************************************

The latest version of this document can be found at:

http://www.esperanto.org.uy/programoj/angle/wprint_documentation.html

Copyright (C) 2000  Eduardo Trapani (etrapani@unesco.org.uy)

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.


What you need

To use the program you only need a TTF font file with the characters you
want to print and the postscript output from Mozilla, Galeon, Netscape,
HtmlDoc.

To find free TTF fonts for you character set or language you can check out
this site: Dr Berlin's Foreign Font Archive

To build from source you need the freetype library which you can find
already packed for your distribution or here: FreeType Homepage. Both
freetype (freetype1) and freetype2 are now supported.

To test the build or the program itself you now have a test script in the
distribution. Read the README and the README.test. To further check the
program you might want to go to the Debian Homepage and select a language
from the list at the bottom of the page. See what encoding it is using by
going to "Edit" and then "View Page Info" (in Mozilla/Netscape) and print it
to a file. Be sure to specify the correct encoding and font to wprint. You
can view the postprocessed file with ghostscript or print it.

Pages can be printed correctly even if the system lacks the X fonts to show
the page properly, although the positioning done by the browser will not be
as good.

Building the program

Just run './configure' from the source directory, that will create a
Makefile for your system. Then type 'make'.

If everything goes right you might want to test the program before you
install it, go to the doc/test directory and run test.sh (you might have to
change the permisions or do '. test.sh'). Please read the file README.test.

Once you tested the program you can do 'make install' to install it on your
system

If the above does not work you can also edit the Makefile to point to
freetype and iconv (and whatever else is necessary) and then type 'make' and
follow the same procedure as above. If you still cannot build the program
you might want to write to me, I will try to help you out.

Running the program

When you print from Mozilla/Netscape you have to type the print command in
the print dialog box. That is usually something like 'lpr -P myprinter'.

Mozilla/Netscape--->'lpr -P myprinter'--->myprinter

From now on Mozilla/Netscape will send their output to wprint which in turn
(after processing) is going to send its output to the printer or a file
using a print command that is specified in the last part of each
configuration entry.

Mozilla/Netscape--->wprint -l entry--->'lpr -P myprinter'--->myprinter

Note that there might be other filters involved between 'lpr' and the
printer but that does not concern wprint.

In order to get wprint to work you just have to type 'wprint' as your
printing command for the default entry, for the other you will have to type
'wprint -l name_of_entry'. See the same wprint.conf entry 'default' and
change the printing command to suit your system. It might be a good idea to
print like that first.

Check the provided wprint.conf file, it is documented and will give you a
good idea on how to set up the font conversions for the program to work. All
my entries are there, using the font cyberbit.ttf, and I use them regularly
to print unicode text.

You can also run wprint from the command line, to process a file saved by
choosing 'print to a file' in the Mozilla/Netscape dialog.

wprint -p filename.ps -i encoding -f font_list -v -x -c conffile -l entry

 -c conffile  The filename to the config file. Used if -f is present. The
              default filename is /etc/wprint.conf.
 -i encoding  The encoding of the original page, KOI8-R or ISO_8859-3 or
              UTF-8 or whatever encoding is supported by iconv (the list is
              rather impressive). The default is UTF-8. NONE means that no
              conversion should be done (passthrough) and UNICODELITTLE is
              the value to use with Mozilla. (Note that some versions of
              Netscape print BIG5 as EUC-TW)
 -l entry     The entry in the config file. The default entry is 'default'
              if you use -c and not -l or if you use no parameters or just
              -p. This overrides the other settings: -f, -i and makes the
              output go to the filter or file at the end of the entry
 -f font_list You can either write the *filename* of a unicode font such a
              cyberbit or you can type a list in the form:
              font1[=encoding1[;xr;yr;pt]], font2[=encoding2[;xr;yr;pt]],
              ... If you don't specify the font encoding the unicode map
              will be used. The values xr, yr and pt default to 72, 72 and
              14.0.
 -p filename  The name of the postscript file you want to process and
              print. If you don't specify it standard input will be used
              instead.
 -v           Just adds some diagnostic output to stderr.
 -x           By default the font tables are constructed using a 64
              character map. You can also use a 159 character map that lead
              to fewer subfonts. It is optional because I have not tested
              it enough.

for example, the test program runs:

wprint -i UTF-8 -p netscape.ps -f courier-8859_3=ISO_8859-3 > test1.ps

wprint -c wprint-test.conf -p netscape.ps

Both lines achieve the same things, the first one with every option in the
command line and the second one using a configuration file. If the
configuration file had been /etc/wprint.conf then just 'wprint -p
netscape.ps' would have been enough.

The output of the program when there is no configuration file is stdout, so
you can pipe it to whatever you want.

I recommend that instead of printing right away to a printer you do it to a
file first and check the result with, for example, ghostscript to see if you
have your fonts set up properly. You will help save a bit of the world's
forest by running your tests this way :).

About font order and font substitution

The order of fonts in this case is very important since the fonts Netscape
uses are going to be replaced in the same order. If you specify fewer fonts
then the last ones are going to be replaced by the last font you listed.

 Netscape fonts      Mozilla fonts
                     Times-Roman
                     Times-Bold
 Times-Roman         Times-Italic
 Times-Bold          Times-BoldItalic
 Times-Italic        Helvetica-Roman
 Times-BoldItalic    Helvetica-Bold
 Courier-Roman       Helvetica-Oblique
 Courier-Bold        Helvetica-BoldOblique
 Courier-Oblique     Courier-Roman
 Courier-BoldOblique Courier-Bold
                     Courier-Oblique
                     Courier-BoldOblique
                     Symbol

Important Notes

For BIG5 pages Netscape generates EUC-TW output, so you should use EUC-TW
each time you are dealing with BIG5 in the config files.

In a similiar way, for SHIFT-JIS Japanese pages, Netscape generates EUCJP
output. (thanks to Alex Madon <madon at cma-it dot com>)

Netscape does all the positioning so that if your font does not scale well
to the size Netscape wants it to use there is very little the filter can do
at this moment. You can try to use the xy, yr and pt parameters to change
the resolution and pointsize of the characters to be created.

If you have any suggestions or corrections to the program don't hesitate to
write to me to etrapani@unesco.org.uy

wprint.conf

# The format of this file is
#
# fontpath:path Can appear anywhere and it is valid for the lines
# below it.
#
# name:encoding:font_list:file
# name: name given to the line (parameter -l to the program)
# encoding: iconv's name for the encoding
# fontlist: list of fonts in the form:
# font1[=encoding1[;xr;yr;pt]],
# font2[=encoding2[;xr;yr;pt]] ...
# file: the file the output is sent to, if it begins with
# '|' a pipe is created instead
#
# If name is 'default' that will be the default entry, there should always
# be a 'default' entry
#
# All entries but 'default' have been commented out.
# There can be no empty fields
#

#fontpath:/home/fonts/unicode/

# Unicode using cyberbit.ttf
#uni:UTF-8:cyberbit.ttf:|lpr -P printer

# Unicode using cyberbit.ttf (color printer)
#unic:UTF-8:cyberbit.ttf:|lpr -P color

# Russian coded with Windows CP1251 using cyberbit.ttf
#w1251cy:CP1251:cyberbit.ttf:|lpr -P printer

#fontpath:/home/fonts/esperanto/

# Esperanto coded with ISO_8859-3 (full mapping of fonts)
#eo3:ISO_8859-3:3TIMES.TTF=ISO_8859-3,3TIMESB.TTF=ISO_8859-3,3TIMESI.TTF=
ISO_8859-3,3TIMESBI.TTF=ISO_8859-3,3COUR.TTF=ISO_8859-3,3COURB.TTF=ISO_8859-3,
3COURI.TTF=ISO_8859-3,3COURBI.TTF=ISO_8859-3:|lpr -P printer

# Esperanto coded with UTF-8 (full mapping of fonts)
#eou:UTF-8:3TIMES.TTF=ISO_8859-3,3TIMESB.TTF=ISO_8859-3,3TIMESI.TTF=ISO_8859-3,
3TIMESBI.TTF=ISO_8859-3,3COUR.TTF=ISO_8859-3,3COURB.TTF=ISO_8859-3,3COURI.TTF=
#ISO_8859-3,3COURBI.TTF=ISO_8859-3:|lpr -P printer

#fontpath:/home/fonts/russian/

# Russian coded with KOI8-R (full mapping of Times fonts and all Courier
# like Times Roman)
#koi8:KOI8-R:BKKOI8N.TTF=KOI8-R,BKKOI8B.TTF=KOI8-R,BKKOI8I.TTF=KOI8-R,BKKOI8BI.TTF
#=KOI8-R,BKKOI8N.TTF=KOI8-R:|lpr -P printer

# Russian coded with KOI8-R and using real small letters (full mapping of
Times
# fonts and all Courier like Times Roman)
#koi8a:KOI8-R:BKKOI8N.TTF=KOI8-R;72;72;6.0,BKKOI8B.TTF=KOI8-R;72;72;6.0,
BKKOI8I.TTF=KOI8-R;72;72;6.0,BKKOI8BI.TTF=KOI8-R;72;72;6.0,BKKOI8N.TTF
=KOI8-R;72;72;6.0:1|lpr -P printer

#fontpath:/home/fonts/unicode/

# Chinese coded with big 5
#big5:EUC-TW:cyberbit.ttf:|lpr -P printer

# Chinese coded with big5 (local file)
#big5l:EUC-TW:cyberbit.ttf:mybig5.ps

# Japanese
#ja:SHIFT-JIS:cyberbit.ttf:|lpr -P printer

# Mozilla
#mozilla:UNICODELITTLE:cyberbit.ttf:|lpr -P printer

# Normal (passthrough, for Latin1 pages: spanish, english ...)
default:NONE:NONE:|lpr -P printer
