Graphviz and fonts.
===================

Before we launch into the gory details, we would like to explain
why this is a hard problem.  The naming and rendering of text fonts
in Graphviz (and other programs) is complicated.  There are several reasons:

- Graphviz runs on a wide range of systems: Linux and other Unix
variants, Microsoft Windows, and Mac.
- Graphviz has a wide range of output formats: raster-oriented formats
like PNG and GIF; path-based ones like Postscript, PDF and SVG; some
idiosyncractic legacy formats, like troff PIC and HPGL.
- Often, output will be downloaded and displayed on a computer or other 
device, different than the one where the layout was created.
- Graphviz layouts should be identical in size and appearance,
regardless of the output format.
- Graphviz can run on external libraries that help with naming and
rendering text fonts, but they are not required, and stripped-down
Graphviz tools can be built without them. In fact, Graphviz may have
to run on systems with no font files installed.
- There are several major font file formats to be supported.
- Non-Western, international character sets should be supported.
- Graphviz should provide a good set of standard fonts.
- It should be easy to specify standard fonts.
- Users should be able to load their own custom fonts.
- Output should be small to download quickly.
- Output should allow the best rendering possible in a given format.
- Output files should be easy to postprocess, for example, retaining
the objects of the original graph if possible.
- It is very helpful to work around known bugs or missing features
in support libraries and popular external tools.

This is a tall order. Some of the goals conflict.  Generally our
approach has been to define defaults that favor convenience and good
looking output, and give the user options to override the defaults.

===Overview===

In the following, we will assume a ''standard'' version of Graphviz 
with the full set of support libraries (fontconfig, gd, Cairo and Pango),
running on a desktop system or server with a standard installation of
font files.

The graphviz layout engines (dot, neato, etc) create layouts with nodes
sized to enclose the text labels.  This requires knowing the size of
the text blocks, which in turn requires knowing the metrics of the font
glyphs and their composition into words, taking into account wordspacing,
kerning, hinting, etc.  So the overall process is: font specification,
then text layout, followed by Graphviz output (and final rendering on
the target display or device, which may or may not be by a Graphviz tool.)


A font is usually selected by family name ("fontname") and other properties
(see below: "Font selection"). Then fontconfig matches the request
to a system font.  [Note: in older versions of Graphviz, fontname was
simply a file name.  This required exact file name matching (with a little
bit of helpful name mangling under the hood, e.g. translating Times-Roman
to Times, or Helvetica to Arial on Windows systems (and yes we know
there is a difference).  Under fontconfig, fontnames are family names,
which fontconfig matches to the closest font it finds. This always
"succeeds", but unfortunately produces surprising results if fontconfig's
idea of "close" doesn't match yours. This can happen when you specify
a custom (or just nonexistent) font, like Steve-North-Handwriting,
and fontconfig silently falls back to something safe like a typewriter
font.]

Text layout is performed by pango, which accepts text and computes a
layout with metrics that determine node sizes.

Though line drawing is provided by cairo for many output formats (and
likely more in the future), for raster output formats, font rendering
is passed though cairo to freetype. Freetype is also called if gd is
used for drawing.  (gd can also be requested explicitly, e.g. dot -Tpng:gd,
or by default when Graphviz is built without cairo).  Freetype provides
antialiasing, hinting, kerning, and other low-level font features.  

Font metrics are obtained from the fonts installed on the system running
Graphviz.  Results are guaranteed when Graphviz outputs raster formats,
because freetype immediately renders the fonts into pixels.  On the
other hand, with path-based formats like Postscript (-Tps) and SVG (-Tsvg),
final rendering may be done on a different platform altogether, with
different font files installed.  Clearly, Your Milage May Vary.  In the
case of Postscript, the driver in Graphviz passes the expected metrics
of the text block down to the renderer, and asks it to make a final stretch
(or squeeze) to force the text to fit the metrics that were in effect at
layout time.  In Graphviz SVG, there is only a hope and a prayer that
the SVG rendering program's fonts match the ones fontconfig and freetype
used when Graphviz was run.  (More about this later.)

Default fonts and PostScript fonts.  ===================================

The default font in graphviz is, and always has been, Times-Roman.

Graphviz has historically supported some ``standard'' Postscript
fonts, initially, Times-Roman, Helvetica, Courier and Symbol.
This list was later enlarged by Adobe to include 35 fonts, which are:
	AvantGarde-Book AvantGarde-BookOblique AvantGarde-Demi
	AvantGarde-DemiOblique Bookman-Demi Bookman-DemiItalic
	Bookman-Light Bookman-LightItalic Courier Courier-Bold
	Courier-BoldOblique Courier-Oblique Helvetica
	Helvetica-Bold Helvetica-BoldOblique Helvetica-Narrow
	Helvetica-Narrow-Bold Helvetica-Narrow-BoldOblique
	Helvetica-Narrow-Oblique Helvetica-Oblique NewCenturySchlbk-Bold
	NewCenturySchlbk-BoldItalic NewCenturySchlbk-Italic
	NewCenturySchlbk-Roman Palatino-Bold Palatino-BoldItalic
	Palatino-Italic Palatino-Roman Symbol Times-Bold Times-BoldItalic
	Times-Italic Times-Roman ZapfChancery-MediumItalic ZapfDingbats

Unfortunately, fontconfig doesn't recognize PostScript-style font
names directly, so Graphviz makes custom mappings from its list of
PostScipt names into fontconfig family names for use in all cairo
and gd based renderers. In -Tps output, these fonts are used without
name translation.

Font selection.  ===============

The fontname attribute in .gv graphs is a fontconfig style specification.
From: http://www.fontconfig.org/fontconfig-user.html

	Fontconfig provides a textual representation for patterns that
	the library can both accept and generate. The representation is
	in three parts, first a family name list, second list of point sizes,
	and finally a list of additional properties:

	<families>-<point sizes>:<name1>=<values1>:<name2>=<values2>...

	Values in a list are separated with commas. The name needn't
	include either a family or point size; they can be elided. In
	addition, there are symbolic constants that simultaneously
	indicate both a name and a value. Here are some examples:

	Name				Meaning
	----------------------------------------------------------
	Times-12			12 point Times Roman
	Times-12:bold			12 point Times Bold
	Courier:italic	  		Courier Italic in the default size
	Monospace:matrix=1 .1 0   	The users preferred monospace font
					with artificial obliquing

Graphviz currently has a seperate attribute for specififying fontsize.

[ FIXME
  We should allow the fontconfig style specification.  "Times-20" does
  not currently result in a 20pt font.

  This is probably because of special treatment of '-' for postscript
  font names.
]

[ FIXME
  We seem to have a bug with use of ':' in fontnames, probably because
  of special treatment for filenames in Windows.

  In fontnames, use <space> instead of ':' to separate values.

  -Nfontname="Courier:italic" doesn't produce an italic font in
  graphviz-2.16.1, but: -Nfontname="Courier italic" works, but
  -Nfontname="Monospace matrix=1 .1 0 1" doesn't.
]


Font management with fontconfig.  ================================

How can I tell what fonts are available?
	$ fc-list

How can I tell what fonts dot is using;
	$ dot foo.gv -Tpng -o foo.png -v 2>&1 | grep font

How can I add a custom font?
  In the current version of Graphviz with fontconfig, Cairo and
  Pango, this cannot be done by simply putting a file in the
  current directory or setting the DOTFONTPATH path variable.
  Your custom font must be explicitly installed by fontconfig tools.

  For a single font, e.g., foo.ttf:
	$ mkdir -p ~/.fonts
	$ cp foo.ttf ~/.fonts/

  One can run fc-cache to speed up the use of fontconfig.
	$ fc-cache

  For Windows users, one can go to the C:\windows\fonts
  folder and use File -> Install New Font from the pull-down menus
  to install the font.

  For a new font directory, e.g., /Library/Fonts, add a new <dir> element

    <dir>/Library/Fonts</dir>

  to a .conf file. Note that the file must have a correct xml structure
  as specified by the fontconfig fonts.dtd. Possible choices for the
  .conf file are local.conf in the same directory as the system-wide
  fonts.conf file, or .fonts.conf in your home directory. 

How can I ... font?
	See: http://www.fontconfig.org/fontconfig-user.html

Can I specifiy a font by filename instead of by familyname?
	Sorry, the answer is no.  {The reason is that for this to
	work, Graphviz has to intercept the font lookup before
	fontconfig is called, and this can't be done when fonts
	are being looked up by Pango.)

    Some versions of fontconfig appear to recognize pathnames and
    attempt to use that, but this isn't always the case.

How can I be sure that a specific font is selected?
	Provide enough specification in the fontname, and test it
	with fc-match to ensure that your desired font is selected.
	(Note, this will not ensure that the same font is used in -Tps
	or -Tsvg renderings where we rely on the fonts available on the
	final printer or computer.)

	Note the downside, as mentioned previously, is that Graphviz cannot
	do much to warn you when fontconfig didn't find a very
	good match, because fontconfig just cheerfully falls back
	to some standard font.  It would be really nice if the
	fontconfig developers could provide a metric reflecting the
	quality of the font match in their API.

What about SVG fonts?
	Graphviz has a native SVG driver that we wrote (which is the
	default), and cairo's SVG driver (which you get with -Tsvg:cairo).

	Graphviz' native SVG driver generates Windows compliant names
	like "Times New Roman" or Arial by default. The names work in a
	lot of situations (like Firefox running on Windows), but are
	not guaranteed to be portable.  If you set -Gfontnames=ps,
	you get Postscript names like Times-Roman.  If you set -Gfontnames=svg
	you are guaranteed to get rock solid standards compliant SVG.
	The SVG standard says that the legal generic font names
	are Serif, Sans-Serif, and Monospace (plus Cursive and
	Fantasy which we don't use in Graphviz). We generate those names.
	The bad news is that various downstream renderers and editors
	may resolve the generic font names differently, so it's not
	quite clear how your SVG will look.  Many W3C examples show
	how to use CSS (Cascading Style Sheets) to get around this
	problem by giving a list of font family names in order of
	lookup precedence, but some downstream processors (like the
	inkscape editor in Linux) don't implement CSS, so we're up a tree here.

	The cairo SVG driver solves this in an effective though brute
	force way: it simply encodes embeds the needed fonts as lines and
	curves in the target SVG.  For small examples, -Tsvg:cairo is
	about 10 times bigger than -Tsvg, but maybe it's worth it for
	correctness.  The other problem is that such SVG is much much
	slower to render, no doubt because it bypasses any system
	font rendering services, and does it the old fashioned way.

What about Postscript fonts?

	say something here.  What about non-ASCII like Latin1.
	what about loading your own fonts via -L like in the old
	days with the weird outline font example.

==="What if" issues for nonstandard Graphviz builds===
The following only apply if you build your own version of Graphviz
by configuring and compiling the source code to build your own
custom executable.  If you don't know what this means, it
definitely does not mean you.

No freetype.  ============

When graphviz is built on systems without freetype, then only the gd
renderer will be available for bitmap outputs, and the only available
fonts are a small set of builtin bitmap fonts.  The poor quality of
these fonts will be evident, also, "dot ... -v 2>&1 | grep font"  will
say that the font is "<internal>". This may actually be desirable
for installing minimal graphviz programs on a server where fonts
may not even be installed.


No fontconfig.	==============

If graphviz is built on systems without fontconfig (e.g. Redhat-7) then
the fontname attribute will be interpreted as a font file name. The
system directories will be searched for this, or the directories can
be specified with the GDFONTPATH environment variable (or DOTFONTPATH
for historical reasons). Graphviz will use gd and freetype to obtain
metrics and render text.  No pango/cairo renderers will be available
without fontconfig support.


Disabling fontconfig.  =====================

Pango/cairo depends on fontconfig, so to disable fontconfig you also have
to disable pango/cairo.    The easiest way to do this temporarily is to
edit /usr/lib/graphviz/config and remove the entire "libpango" block.
[Note that any changes to this file will be lost the next time graphviz
is updated, or "dot -c" is run with installer priviledges.]

With pango disabled, graphviz will use gd which, even if it was built with
fontconfig support, will still allow fontnames to be given as filenames.

You can also disable cairopango at build time with configure script options.


No gd. =====

Cairopango works without gd.  We are moving graphviz to the pango/cairo
libraries, but gd still offers some features that are hard to replace,
such as JPEGs, GIFs and paletted color bitmap outputs. However, font support
is fully functional without gd so long as pango, cairo, fontconfig,
freetype are available.

No pango/cairo.  ===============

Without pango/cairo, some of the key renderers are only available
with gd, which produces lower quality (but smaller) output.

Looking forward, we expect to depend more on pango for things like:
line wrapping, multiple fonts per label, bidirectional text and
other internationalization features.

No gd and no cairopango =====
This is basically the original Graphviz without any external fonts.
It cannot render any raster formats, so it's mainly good for Postscript.
It relies on a few internal font tables