mf/README

   1
   2 LilyPond's Feta and Parmesan fonts
   3 ==================================
   4
   5 [The name `feta' is based on a non-translatable Dutch pun (`font-en-tja').
   6  Given that it is the name of a cheese type, the font for old music symbols
   7  is called `parmesan', and the OpenType font that merges these two fonts is
   8  called `emmentaler'.]
   9
  10 This is a font of music symbols.  All MetaFont sources are original.  Most
  11 of the documentation is in comments in the MetaFont code.
  12
  13 Non-square pixels are not supported; with other words, the horizontal and
  14 vertical resolution of the output device must be the same.
  15
  16
  17 Conversion from MetaFont to PostScript
  18 --------------------------------------
  19
  20 The MetaFont code gets directly converted to PostScript Type 1 font with a
  21 tool called `mf2pt1', which in turn calls `FontForge' to postprocess the
  22 output (mainly to remove outline overlaps and to add hints).
  23
  24 The recommended calling sequence of mf2pt1 is
  25
  26   mf2pt1 --rounding=0.0001 <other options> <font>
  27
  28 You need mf2pt1 version 2.1 or newer.
  29
  30 Here some guidelines to assure a clean conversion.
  31
  32 . Never use `---'.  Replace it with `--' together with explicit path
  33   directions (if necessary).
  34
  35 . Don't use self-intersecting outlines in general since they can confuse
  36   mf2pt1's algorithm to get the orientation of a closed path.  Note that
  37   MetaPost's implementation of the `turningnumber' primitive (which would
  38   immediately give the orientation of a path) is severely broken before
  39   version 1.0 of MetaPost, thus some hand-made code in mf2pt1.mp is used
  40   to work around this bug.
  41
  42 . If outlines intersect, avoid grazing intersections.  In case two outlines
  43   intersect in an explicitly defined point, include this point in both
  44   intersecting paths to avoid problems due to rounding errors.
  45
  46 . Don't use `draw' with a polygonal pen but for straight lines (consisting
  47   of exactly two points).  In most cases it is quite easy to emulate `draw'
  48   with an explicit definition of the outline or with `penstroke'.
  49
  50 . Don't apply transformations after calling `fill' -- for example, don't
  51   mirror `currentpicture'.  Instead, transform the path and call `fill'
  52   afterwards.  This ensures that mf2pt1 gets the correct outline directions,
  53   which is a necessary prerequisite for FontForge's algorithm to remove
  54   overlaps.
  55
  56
  57 Glyph name rules
  58 ----------------
  59
  60 . Most glyph names have the form <group>.<name>, where <group> is defined
  61   with the `fet_begingroup' command, and <name> is given with
  62   `fet_beginchar' (within a `fet_begingroup' block).  Example:
  63   `clefs.vaticana.fa'.
  64
  65 . Sometimes it would be sensible to use negative numbers in glyph names.
  66   However, the `-' character shouldn't be used in a glyph name.  Replace it
  67   with `M'.  For example, write `rests.M3mensural' instead of
  68   `rests.-3mensural'.
  69
  70 . Glyphs that exist in both an `up' and `down' version should start the
  71   <name> part with either `u' or `d', respectively.  Example: `flags.d3',
  72   `flags.u3'.  Glyphs that are neutral w.r.t. the direction, and where
  73   members of the glyph group exist that have `up' and `down' versions,
  74   should start with an `s'.  Example: `noteheads.s0re'.
  75
  76
  77 Design rules
  78 ------------
  79
  80 . Always use smooth curve transitions.  Since this is difficult to see in
  81   MetaFont proof sheets (which don't show the tangents) I recommend to call
  82   mf2pt1 like this
  83
  84     FONTFORGE=foo mf2pt1 ...
  85
  86   (`foo' should be a non-existent program; this avoids the default
  87   postprocessing).  Then call FontForge to inspect the outlines.
  88
  89 . Use rounded corners.
  90
  91
  92 Hints for stem attachment
  93 -------------------------
  94
  95 . Stem attachment of glyphs is controlled by two special variables called
  96   `charwx' and `charwy'.  Stems can be regarded as (very oblonged)
  97   rectangles with slightly rounded corners.  For stems pointing upwards the
  98   lower right corner of this rectangle is attached to the glyph at position
  99   (charwx, charwy).  For stems pointing downwards it works analogously but
 100   with the upper left corner, where the position of the attachment point is
 101   additionally reflected horizontally about the center of the glyph -- this
 102   ensures that in most cases `charwx' and `charwy' can be set to the same
 103   values for up and down stems even though these are attached at the
 104   right/left end of the note, respectively.  To make this more precise, the
 105   upper left corner of a down stem is attached at position
 106
 107     (charwd/2 - charwx, charwy)   ,
 108
 109   where `charwd' is an internal MetaFont variable representing the glyph
 110   width as specified by the `set_char_box' command.
 111
 112 . In case different stem attachments for upward and downward pointing stems
 113   are needed, two separate glyphs must be defined in the MetaFont file; of
 114   course, this also applies if two entirely different shapes are needed.
 115   These have the same name but are prefixed by `u' and `d', respectively
 116   (for `up' and `down', obviously).  In each of these glyphs the variables
 117   `charwx' and `charwy' must be set accordingly.  If, on the other hand, the
 118   attachment point is the `same' for both directions (with the
 119   abovementioned horizontal reflection taken into account), then the prefix
 120   `s' (for `symmetric') should be used.  See the existing files for
 121   examples.  The numbers in the glyph names refer to the duration of the
 122   note; e.g., `s0cross' in feta-noteheads.mf defines the notehead for a
 123   whole cross-shaped note (similarly, `s1cross' and `s2cross' are for half
 124   and quarter notes, respectively).
 125
 126
 127 Proofing
 128 --------
 129
 130 The proofing tool for MetaFont to inspect its output is `gftodvi',
 131 converting a font in MetaFont's native GF font format to a DVI document,
 132 which can then be viewed with DVI viewers like `xdvi'.  The `gftodvi'
 133 program needs two special fonts, `gray' and `black'.  Assuming that you are
 134 using TeXLive, say
 135
 136   mktextfm gray
 137   mktextfm black
 138
 139 on the command line to generate the needed metric files (from its source
 140 files), which are then stored within your local TEXMF tree.
 141
 142 Here is a shell script that you can use to produce two DVI files,
 143 `foo.proof.dvi' and `foo.ljfour.dvi', showing the glyphs of font `foo.mf' in
 144 proofing mode and a 600dpi rasterization for a LaserJet IV printer.
 145
 146   #!/bin/sh
 147   mf "\mode:=proof; input $1"
 148   gftodvi $1.2602gf && mv $1.dvi $1.proof.dvi
 149
 150   mf "\mode:=ljfour; input $1"
 151   echo "grayfont black
 152   " | gftodvi $1.600gf/ \
 153   && mv $1.dvi $1.ljfour.dvi
 154
 155 Assuming that you name this script `makefeta.sh', you can call it with e.g.
 156
 157   sh makefeta.sh feta23
 158
 159 The main importance of the proofing DVI output is to show points marked in
 160 the MetaFont source code with the macros `penlabels' and `labels'.  In most
 161 cases, those points are used for constructing the shapes only and are thus
 162 not present in the output after the conversion with mf2pt1.
 163
 164
 165 Rasterization
 166 -------------
 167
 168 Finally, some rules to assure that rasterization at low resolutions
 169 (produced directly with MetaFont) gives good results.  Today, this is a
 170 minor issue, but in some cases it might show design flaws.
 171
 172 . Use `define_whole_pixels' and friends where appropriate.
 173
 174 . Use `hround' and `vround' consistently.  A lot of auxiliary macros are
 175   defined in feta-macros.mf.
 176
 177 . If a path element is duplicated or shifted, use an integer value for the
 178   offset.
 179
 180 . Add `eps' for mirrored paths to assure correct MetaFont rasterization.
 181   See the comment and the variables at the end of `feta-params.mf' for
 182   details how vertical symmetry should be achieved.