From 07738f8eb905830429df922aaf6c26032be999f1 Mon Sep 17 00:00:00 2001 From: ellson Date: Fri, 14 Dec 2007 22:06:54 +0000 Subject: [PATCH] a font faq --- doc/fontfaq.txt | 217 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 doc/fontfaq.txt diff --git a/doc/fontfaq.txt b/doc/fontfaq.txt new file mode 100644 index 000000000..cec8f31f7 --- /dev/null +++ b/doc/fontfaq.txt @@ -0,0 +1,217 @@ +Graphviz and fonts. +=================== + +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. + +The font is normally selected by family name, and any other required properties, +(see: FAQ item: "Font selection") then fontconfig is used to match the font request +to a specific font available on the system. (see FAQ item: "No fontconfig.") + +[Note. In older versions of dot, fontname was a font filename, which was +exact, and which either existed or it didn't. With fontconfig, fontnames are +now family names, which fontconfig will match to the closest font it can find. +This should always succeed, but unfortunately sometimes produces surprising +results if its idea of "close" doesn't match yours.] + +Text layout is normally performed by pango, which accepts text and +produces a layout with metrics which we can use to size the node shapes. +(See FAQ item: "No pango.") + +Line drawing is provided by cairo for many output formats, and likely more in +the future, however font rendering is passed though cairo to freetype. The same +is true if gd is used for drawing. (See FAQ items: "No cairo," "No gd.") + +Font rendering is provided by freetype, which provides antialiasing, hinting, +kerning, and other low-level font features. +(See FAQ item: "No freetype.") + +The font metrics are obtained using fonts available on the system running dot. +This works fine, except for outputs like -Tps and -Tsvg where the final rendering +may be done on a different platform altogether, where the same fonts might not +be available. For these cases (in PostScript only at this time) we pass down the +expected metrics of the text block to the renderer and ask it to make a final +stretch (or squeeze) to make the text fit the metrics that were used at layout time. + +Default fonts and PostScript fonts. +=================================== + +The default font in graphviz is, and always has been, Times-Roman. +Unfortunately, fontconfig doesn't recognize this PostScript-style font +specification directly, so we have custom mappings from a basic set of +PostScipt fontnames into fontconfig family names for use in all cairo and gd +based renderers. In -Tps output, these fonts are used without name +translation. + +The supported PostScript fontnames 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 + +Font selection. +=============== + +The fontname attribute in .dot 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 list + of family names, second a list of point sizes and finally a list of additional + properties: + + -:=:=... + + + Values in a list are separated with commas. The name needn't include either + families or point sizes; 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 1 The users preferred monospace font + with artificial obliquing + +In graphviz we currently have 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 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.dot -Tpng -o foo.png -v 2>&1 | grep font + +How can I add a new font? + $ mkdir -p ~/.fonts + $ cp foo.ttf ~/.fonts/ + $ fc-cache + +How can I ... font? + See: http://www.fontconfig.org/fontconfig-user.html + +Can I specifiy a font by filename instead of by familyname? + Not if fontconfig is enabled. +[ FIXME + I thought we still recognized any fontname containing a path separator ( '/' + or '\') as a font filename. This doesn't seem to work anymore. +] + +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.) + + +No freetype. +============ + +If graphviz is built on systems without freetype, then only the gd renderer +will be available for bitmap outputs, and all fonts will revert to a set of +builtin bitmap fonts. The poor quality of these fonts will be evident, +also, "dot ... -v 2>&1 | grep font" will indicate that the font is "" + + +No fontconfig. +============== + +If graphviz is built on systems without fontconfig (e.g. Redhat-7) then the +fontname attribute will accept a filename for a fontfile and use gd and +freetype to obtain metrics and render the font. The PATH searched for fonts +can be specified with the GDFONTPATH environment variable. + +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. + + +No pango/cairo. +=============== + +Without pango/cairo many of the renderers will available only via gd +which produces lower quality output. + +Looking forward, we expect to depend more on pango for things like: line +wrapping, multiple fonts per label, bidi. text and other internationalization +features. + + +No gd +===== + +We have been trying to move graphviz to the newer pango/cairo libraries, but +gd still offers some features that are hard to replace, such as JPGs, GIFs and +paletted color bitmap outputs. However, font support is fully functional without gd +so long as pango, cairo, fontconfig, freetype are available. + -- 2.40.0