mf/README

   1
   2 This is a font of music symbols.  All MF sources are original.  Most of the
   3 documentation is in comments in the MF code.
   4
   5 Non-square pixels are not supported; with other words, the horizontal and
   6 vertical resolution of the output device must be the same.
   7
   8 Currently, outline fonts are created by using `autotrace', but we are
   9 already in the process of converting the MF code directly to PostScript code
  10 with a tool called `mf2pt1', which in turn calls `FontForge' to postprocess
  11 the output (mainly to remove outline overlaps and to add hints).
  12
  13 The recommended calling sequence of mf2pt1 is
  14
  15   mf2pt1 --rounding=0.0001 <other options> <font>
  16
  17 You need mf2pt1 version 2.1 or newer.
  18
  19
  20 Here some guidelines to assure a clean conversion.
  21
  22 . Never use `---'.  Replace it with `--' together with explicit path
  23   directions (if necessary).
  24
  25 . Don't use self-intersecting outlines in general since they can confuse
  26   mf2pt1's algorithm to get the orientation of a closed path.  Note that
  27   MetaPost's implementation of the `turningnumber' primitive (which would
  28   immediately give the orientation of a path) is severely broken before
  29   version 1.0 of MetaPost, thus some hand-made code in mf2pt1.mp is used
  30   to work around this bug.
  31
  32 . If outlines intersect, avoid grazing intersections.  In case two outlines
  33   intersect in an explicitly defined point, include this point in both
  34   intersecting paths to avoid problems due to rounding errors.
  35
  36 . Don't use `draw' with a polygonal pen but for straight lines (consisting
  37   of exactly two points).  In most cases it is quite easy to emulate `draw'
  38   with an explicit definition of the outline or with `penstroke'.
  39
  40 . Don't apply transformations after calling `fill' -- for example, don't
  41   mirror `currentpicture'.  Instead, transform the path and call `fill'
  42   afterwards.  This ensures that mf2pt1 gets the correct outline directions
  43   which is a necessary prerequisite for FontForge's algorithm to remove
  44   overlaps.
  45
  46
  47 Some glyph name rules:
  48
  49 . Most glyph names have the form <group>.<name>, where <group> is defined
  50   with the `fet_begingroup' command, and <name> is given with
  51   `fet_beginchar' (within a `fet_begingroup' block).  Example:
  52   `clefs.vaticana.fa'.
  53
  54 . Sometimes it would be sensible to use negative numbers in glyph names.
  55   However, the `-' character shouldn't be used in a glyph name.  Replace it
  56   with `M'.  For example, write `rests.M3mensural' instead of
  57   `rests.-3mensural'.
  58
  59 . Glyphs which exist in both an `up' and `down' version should start the
  60   <name> part with either `u' or `d', respectively.  Example: `flags.d3',
  61   `flags.u3'.  Glyphs which are neutral w.r.t. the direction, and where
  62   members of the glyph group exist which have `up' and `down' versions,
  63   should start with an `s'.  Example: `noteheads.s0re'.
  64
  65
  66 Some design rules:
  67
  68 . Always use smooth curve transitions.  Since this is difficult to see in
  69   MetaFont proof sheets (which don't show the tangents) I recommend to call
  70   mf2pt1 like this
  71
  72     FONTFORGE=foo mf2pt1 ...
  73
  74   (`foo' should be a non-existent program; this avoids the default
  75   postprocessing).  Then call FontForge to inspect the outlines.
  76
  77 . Use rounded corners.
  78
  79
  80 Hints for stem attachment:
  81
  82 . Stem attachment of glyphs is controlled by two special variables called
  83   `charwx' and `charwy'.  Stems can be regarded as (very oblonged)
  84   rectangles with slightly rounded corners.  For stems pointing upwards the
  85   lower right corner of this rectangle is attached to the glyph at position
  86   (charwx, charwy).  For stems pointing downwards it works analogously but
  87   with the upper left corner, where the position of the attachment point is
  88   additionally reflected horizontally about the center of the glyph -- this
  89   ensures that in most cases charwx and charwy can be set to the same values
  90   for up and down stems even though these are attached at the right/left end
  91   of the note, respectively.  To make this more precise, the upper left
  92   corner of a down stem is attached at position (charwd/2 - charwx, charwy),
  93   where `charwd' is an internal metafont variable representing the glyph
  94   width as specified by the `set_char_box' command.
  95
  96 . In case different stem attachments for upward and downward pointing stems
  97   are needed, two separate glyphs must be defined in the Metafont file; of
  98   course, this also applies if two entirely different shapes are needed.
  99   These have the same name but are prefixed by `u' and `d', respectively
 100   (for `up' and `down', obviously).  In each of these glyphs the variables
 101   charwx and charwy must be set accordingly.  If, on the other hand, the
 102   attachment point is the `same' for both directions (with the
 103   abovementioned horizontal reflection taken into account), then the prefix
 104   `s' (for `symmetric') should be used.  See the existing files for
 105   examples.  The numbers in the glyph names refer to the duration of the
 106   note; e.g., `s0cross' in feta-bolletjes.mf defines the notehead for a
 107   whole cross-shaped note (similarly, `s1cross' and `s2cross' are for half
 108   and quarter notes, respectively).
 109
 110
 111 Finally, some rules to assure that rasterization at low resolutions gives
 112 good results.  Today, this is a minor issue, but in some cases it might show
 113 design flaws.
 114
 115 . Use `define_whole_pixels' and friends where appropriate.
 116
 117 . Use `hround' and `vround' consistently.  A lot of auxiliary macros are
 118   defined in feta-macros.mf.
 119
 120 . If a path element is duplicated or shifted, use an integer value for the
 121   offset.
 122
 123 . Add `eps' for mirrored paths to assure correct MetaFont rasterization.
 124   See the comment and the variables at the end of `feta-params.mf' for
 125   details how vertical symmetry should be achieved.