[Gnome-print] Gnome-print FAQ

[Lauris Kaplinski <lauris ximian com>]

Hello!

This is my initial gnome-print FAQ.
Please read and comment.

Btw: please forgive my abundant typos. I promise to do proofreading
tomorrow, as it does not make much sense at moment ;)

Lauris

GNOME-PRINT FAQ
Version 0.1
03/05/2001
Lauris Kaplinski <lauris@ximian.com>

What is gnome-print?

Gnome-print is high-quality printing framework for GNOME.


What is there in gnome-print?

Gnome-print implements:
- device-independent printing API, modelled loosely after PostScript language
- font abstraction that allows device-independent text display (within
  reasonable limits)
- powerful configuration engine, dealing with all levels of output
  pipeline
- set of actual printer drivers (PostScript, PDF, fax)
- print preview widget
- printer selector widget


Is there a mailing list for gnome-print?

Yes, there is. You can acess both subscription/unsubscription and
archives from web address:
http://lists.ximian.com/mailman/listinfo/gnome-print
The adress of list (for posting messages) is:
gnome-print@ximian.com


I found a bug in gnome-print. How should I report it?

The best way is to use gnome bug tracking system
(http://bugzilla.gnome.org/). Bugs entered there are never forgot by
developers, as bugs reported by email often are.
If reporting bug, be as exact as possible. Code examples are great. If
reporting bugs related to PostScript printing, try to attach resulting
PostScript file in addition to description, how your program produced
it.


Which application use gnome-print?

The list is continuously growing. The best known ones are:
- gnumeric
- evolution
- gtkhtml
- gnucash
- gedit
- sodipodi
- ghex
- guppi
- eog


Does gnome-print use ghostscript? lpr? CUPS?

Current gnome-print relies entirely on underlying printing system for
interfacing with actual printers. So it uses whatever
libraries/prograsm your printing system use.
In future it may implement direct drivers too, but of course, the
general ones remain always present.


Why my application should use gnome-print? After all it is not so
difficult to produce PostScript manually and doing so gives me endless
possibilities.

The main role of gnome-print is standardization:
- shared printer configuration profiles for all gnome apps
- uniform print preview
- standard set of printer configuration widgets
- standard set of fonts, guaranteed to print on any device
In general gnome-print tries to hide all complexity of different
printing systems and printers, while presenting uniform easy-to-use
and powerful-enough interface to application.


I want feature XYZ to be implemented!

First send a message to gnome-print mailing list. Maybe someone is
already implementing it, or has better ideas how to solve your problem.
Then you can file a 'WISHLIST' bug report, using
bugzilla.gnome.org. If your idea has value for general audience,
the chances for it to be implemented are good.


How I can help developing gnome-print library?

Send message to gnome-print list and we will contact you ;)
While you do not need any permission to start hacking on gnome-print,
it is usually better to ask first, whether your idea is already in
work, or does somebody have better idea, how to implement that.
If you think you have produced useful patch, send it to gnome-print
mailing list, or directly to maintainers. The former is preferred, as
maintainer may be sick, in vacation or buried alive under emails at
moment, and then your valuable contribution will remain unnoticed.


How I can get gnome-print?

The easiest way is to use gnome binary distribution. Consult
http://www.gnome.org/start/ about both how to get binaries and/or
source for gnome packages. If you are using realatively modern
GNU/Linux distribution chances are that gnome-print is already
included in it. But as gnome-print is rapidly developing, you may want
to check for updates.


How I can compile gnome-print from source tarball?

Just unpack tarball into separate directory. cd to gnome-print-X.Y
directory and issue commands:
./configure --prefix=PREFIX
make
Become superuser
make install
Where PREFIX is your gnome installation prefix. If unsure, try
gnome-config --prefix


What other libraries I need to compile gnome-print?

Generally you need working gnome installation. More specifically:
gnome-libs
gdk-pixbuf
gnome-xml (old) or libxml (new)
gtk, gdk, glib
X libraries


I have MY_LIBRARY installed, but gnome-print compilation says I have
not!

If you have installed gnome from binary packages, make sure that you
have installed corresponding development packages as well.
If you have compiled MY_LIBRARY yourself, make sure that prefixes match.


How can I use gnome-print from my programs?

Unfortunately there is no good documentation about using
gnome-print. The best way is probably to look into example code in
tests directory in gnome-print source.


Can I use gnome-print from console programs?

Yes, you can. You still need X, Gtk+ and gnome to be installed, but X
does not have to run on your machine. Of course, you cannot use print
preview or printer selection widgets in that case.
You also have to start your console program with gtk_type_init instead
of gtk_init or gnome-init.


Which coordinate system does gnome-print use?

Gnome-print uses the same coordinate system as PostScript
page description language. I.e. initially the 0,0 is at lower-left
corner of page, x grows to right, y upwards and one unit corresponds
to 1/72th of inch.
You can change coordinate system using following methods:
  gnome_print_translate (pc, x, y)
  gnome_print_scale (pc, xscale, yscale)
  gnome_print_concat (pc, matrix)
If unsure, consult some textbook about computational geomtery. But in
most cases you do not need anything other than translate and scale.
Also, it is usually good idea to embed coordinate manipulation between
gnome_print_gsave and gnome_print_grestore or you will soon loose
track, which coordinate system is in use at any given moment.


I want to print! How I can get that GnomePrintContext?

Either use
  printer = gnome_printer_new_generic_ps (filename)
  pc = gnome_print_context_new_with_paper_size (printer, "PAPER_NAME")
It works for console, but does not allow you to choose driver (but in
most cases you want PostScript anyways).
  printer = gnome_printer_dialog_new_modal ()
  pc = gnome_print_context_new_with_paper_size (printer, "PAPER_NAME")
It works only from X, but presents user with printer selection dialog.
Instead of dialog, you can use printer selection widget and embed it
into your own page setup widget, consult gnome_printer_dialog.h for
more information.


Can I send output to pipe? To program as file argument?

Yes, you can.
Use '|program' as output file name to pipe otuput to program
Use '*program' as output file name to send output to file and
execute program with file name as argument.


How can I get that nice print preview?

Use GnomePrintMaster and GnomePrintMasterPreview:
gpm = gnome_print_master_new ()
pc = gnome_print_master_get_context (gpm)
gpmp = gnome_print_master_preview_new (gpm, "title");
gnome_print_master_close (gpm);


How do I draw line in gnome-print?

gnome_print_newpath (pc)
gnome_print_moveto (pc, x0, y0)
gnome_print_lineto (pc, x1, y1)
gnome_print_stroke (pc)
You may, of course, want to specify graphic settings, like color, line
width and so on.


Is gnome-print methods identical to PostScript operators?

No, they are not. Most important differences are:
- Every page has to start with gnome_print_beginpage
- All graphic operators except line construction ones make
  currentpoint and currentpath value undefined. 
- gnome_print_show expects text to be in utf8 encoding


Bitmap images look bad on printout, but everything seems fine in
preview!

Most probably you are using bitmaps with alpha channel. As PostScript
cannot print semitransparent images, all bitmaps with alpha are
rendered into temporary buffer and later sent to printer as RGB
bitmaps. That method has currently (version 0.28) hardcoded resolution
of 72dpi.
Please note, that your image does not have to use any transparency -
just having a channel is enough to force intermediate rendering. If
you are using gdk-pixbuf to read images, try either changing file
format to png without alpha or jpeg, or reconde images manually to
RGB. Some file formats are always loaded with alpha channel by
gdk-pixbuf.


Everything prints except bitmap images. Should I file bug report?

Make sure that you set up correct transformation matrix before
printing bitmaps. Gnome-print uses PostScript convention to scale all
bitmaps to (0,0 - 1,1) square in user coordinates. So if you do not
set coordinate system, your image will be printed as tiny dot in
lower-left corner of page (and usually falls into printers unprintable
area).
The correct way to print unscaled upright image is:
gnome_print_gsave (pc)
gnome_print_translate (pc, image_left_x, image_bottom_y)
gnome_print_scale (pc, image_width, image_height)
gnome_print_{rgb|rgba|gray}image (pc, pixels, width, height, rowstride)
gnome_print_grestore (pc)


Can gnome-print use TrueType fonts?

At moment (version 0.28) unfortunately not. This is much asked feature
and will be present in next version of gnome-print.


How I can add fonts to gnome-print?

It depends of your gnome-print version. Up to version 0.26 you have to
manually add these to fontmap file (found at PREFIX/fonts).
Starting from version 0.27 you can use program
gnome-font-install. Just run it, giving the directory(ies) with your
font files (pfb and afm) as argument, and send output to either
PREFIX/fontmap2 or ~/.gnome/fonts/fontmap.


Which text encoding gnome-print uses?

Some legacy code aside, gnome-print uses strictly utf-8 text encoding.


Character metrics are not calculated correctly!

Please note, that several methods use glyph, not character
value. Glyphs are actual printable shapes, as opposed to characters,
that are language units - so single glyph may represent many
characters (ligatures) or single character may be represented by
several glyphs. Glyphs are font-dependent.


So, how can you find, which glyph corresponds to given character?

If your typographic needs are modest, you can use
gnome_font_face_lookup_default (face, character)
For advanced typography you have to use afm files directly, and
extract necessary information from glyph names.


My russian Type1 fonts print well from almost any applications, but
not from the ones using gnome-print!

Make sure, that your fonts use afiiXYZQ names for cyrillic
glyphs. Some russian fonts use latin1 glyph names (like Aacute,
otilde) for cyrillic glyphs, so supposed latin1 encoding becomes
actually KOI8 or some similar cyrillic encoding. Gnome-print uses
unicode internally and reencodes all fonts to private encoding, so it
cannot be so easily fooled. As it does not find any cyrillic glyph
names in font description, it supposes that given font cannot output
cyrillic text.


How can I output formatted text in gnome-print?

You have to use glyphlist interface.


What is glyphlist?

Glyphlist is intermediate text format, used by gnome-print to generate
identical text display on all output devices. Glyphlist uses
font-specific glyphs instead of characters, so there is no ambiguity
in actual text formatting (whether to use fi ligature, whether to use
swashes etc.), but can preserve actual text flow (i.e. you give
starting position and series of glyphs, instead of specifying the
position of every glyph manually). Of course, if you need more complex
placement (like typesetting 'TeX' ;), you can specify glyph positions
manually too. In addition to that you can switch fonts and colors, and
for flowing glyphs specify the amount of kerning and letterspacing.


What are GnomeFontFace, GnomeFont, GnomeRFont

GnomeFontFace is unscaled typeface. I.e. all metrics are specified as
of the font with 1000x1000 em square. GnomeFontFace implements the
actual font file parsing code, so character-glyph mapping is done on
it.

GnomeFont is typeface scaled to master output device and requested
font size. I.e. 12pt Helvetica GnomeFont metrics correspond to 12x12
em square. Or by other words - GnomeFont is font scaled to gnome-print
base coordinate system units.

GnomeRFont is instance of GnomeFont, adjusted for printing on certain
raster device with resolution that can be quite different from
gnome-print base coordinate system. For example, 12pt Helvetica
GnomeRFont for 720x720dpi printer metrics correspond to 120x120 em
square.


Why that font complexity? Wouldn't it be easier to use just single
font class?

We have tried to resolve unavoidable grid-aligning problem. I.e. for
actual printing font metrics are usually scaled to integer values in
given device grid (resolution). So if you try to print long line of
glyphs on different devices, either:
- you place every glyph manually and line ending is always at the same
  place, but inter-character distances may sometimes vary from
  correct ones by one pixel (because positions are rounded to nearest
  integer), so text does not look nice on low resolution
- you let glyph flow freely, so inter-character distances are always
  optimal, even on low-resolution device - but line ending may vary a
  lot between devices.
So the idea is to have GnomeFont, that is adjusted to master output
device (for example typesetter), and for every actual output device we
generate different GnomeRFont. If actual output device == master
output device, the metrics of GnomeFont and GnomeRFont are identical
(if multiplied by resolution difference), for any other they differ a
little. Using glyphlists you can choose best strategy to minimise
visual distortions for your application.


What about CMYK colorspace?

We want it too. Hopefully in some near future version of
gnome-print. Unfortunately it is area picked with patents, so probably
we cannot give top-of-the-industry solution here.


It would be cool to have printing interface on canvas items!

It is not so cool at all. In model-view-controller context both
current gnome-canvas and gnome-print-context implement single
view. Adding subview (printing interface) to existing view (canvas) is
not very good idea.
What would be cool is either:
- Make generic graphic object class, that can render to different
  views (canvas and gnome-print)
- Make model-view based canvas, so objects are clearly distinct from
  display (and you can have multiple views of same object)