mf/README: Revised. Add section on MetaFont proofing.

1 files changed, 83 insertions, 26 deletions

diff --git a/mf/README b/mf/README
index adf0225145..bcea8964b2 100644
--- a/mf/README
+++ b/mf/README
@@ -1,14 +1,25 @@
 
-This is a font of music symbols.  All MF sources are original.  Most of the
-documentation is in comments in the MF code.
+LilyPond's Feta and Parmesan fonts
+==================================
+
+[The name `feta' is based on a non-translatable Dutch pun (`font-en-tja').
+ Given that it is the name of a cheese type, the font for old music symbols
+ is called `parmesan', and the OpenType font that merges these two fonts is
+ called `emmentaler'.]
+
+This is a font of music symbols.  All MetaFont sources are original.  Most
+of the documentation is in comments in the MetaFont code.
 
 Non-square pixels are not supported; with other words, the horizontal and
 vertical resolution of the output device must be the same.
 
-Currently, outline fonts are created by using `autotrace', but we are
-already in the process of converting the MF code directly to PostScript code
-with a tool called `mf2pt1', which in turn calls `FontForge' to postprocess
-the output (mainly to remove outline overlaps and to add hints).
+
+Conversion from MetaFont to PostScript
+--------------------------------------
+
+The MetaFont code gets directly converted to PostScript Type 1 font with a
+tool called `mf2pt1', which in turn calls `FontForge' to postprocess the
+output (mainly to remove outline overlaps and to add hints).
 
 The recommended calling sequence of mf2pt1 is
 
@@ -16,7 +27,6 @@ The recommended calling sequence of mf2pt1 is
 
 You need mf2pt1 version 2.1 or newer.
 
-
 Here some guidelines to assure a clean conversion.
 
 . Never use `---'.  Replace it with `--' together with explicit path
@@ -39,31 +49,33 @@ Here some guidelines to assure a clean conversion.
 
 . Don't apply transformations after calling `fill' -- for example, don't
   mirror `currentpicture'.  Instead, transform the path and call `fill'
-  afterwards.  This ensures that mf2pt1 gets the correct outline directions
+  afterwards.  This ensures that mf2pt1 gets the correct outline directions,
   which is a necessary prerequisite for FontForge's algorithm to remove
   overlaps.
 
 
-Some glyph name rules:
+Glyph name rules
+----------------
 
 . Most glyph names have the form <group>.<name>, where <group> is defined
   with the `fet_begingroup' command, and <name> is given with
   `fet_beginchar' (within a `fet_begingroup' block).  Example:
   `clefs.vaticana.fa'.
 
-. Sometimes it would be sensible to use negative numbers in glyph names. 
+. Sometimes it would be sensible to use negative numbers in glyph names.
   However, the `-' character shouldn't be used in a glyph name.  Replace it
   with `M'.  For example, write `rests.M3mensural' instead of
   `rests.-3mensural'.
 
-. Glyphs which exist in both an `up' and `down' version should start the
+. Glyphs that exist in both an `up' and `down' version should start the
   <name> part with either `u' or `d', respectively.  Example: `flags.d3',
-  `flags.u3'.  Glyphs which are neutral w.r.t. the direction, and where
-  members of the glyph group exist which have `up' and `down' versions,
+  `flags.u3'.  Glyphs that are neutral w.r.t. the direction, and where
+  members of the glyph group exist that have `up' and `down' versions,
   should start with an `s'.  Example: `noteheads.s0re'.
 
 
-Some design rules:
+Design rules
+------------
 
 . Always use smooth curve transitions.  Since this is difficult to see in
   MetaFont proof sheets (which don't show the tangents) I recommend to call
@@ -77,7 +89,8 @@ Some design rules:
 . Use rounded corners.
 
 
-Hints for stem attachment:
+Hints for stem attachment
+-------------------------
 
 . Stem attachment of glyphs is controlled by two special variables called
   `charwx' and `charwy'.  Stems can be regarded as (very oblonged)
@@ -86,19 +99,22 @@ Hints for stem attachment:
   (charwx, charwy).  For stems pointing downwards it works analogously but
   with the upper left corner, where the position of the attachment point is
   additionally reflected horizontally about the center of the glyph -- this
-  ensures that in most cases charwx and charwy can be set to the same values
-  for up and down stems even though these are attached at the right/left end
-  of the note, respectively.  To make this more precise, the upper left
-  corner of a down stem is attached at position (charwd/2 - charwx, charwy),
-  where `charwd' is an internal metafont variable representing the glyph
+  ensures that in most cases `charwx' and `charwy' can be set to the same
+  values for up and down stems even though these are attached at the
+  right/left end of the note, respectively.  To make this more precise, the
+  upper left corner of a down stem is attached at position
+
+    (charwd/2 - charwx, charwy)   ,
+
+  where `charwd' is an internal MetaFont variable representing the glyph
   width as specified by the `set_char_box' command.
 
 . In case different stem attachments for upward and downward pointing stems
-  are needed, two separate glyphs must be defined in the Metafont file; of
-  course, this also applies if two entirely different shapes are needed. 
+  are needed, two separate glyphs must be defined in the MetaFont file; of
+  course, this also applies if two entirely different shapes are needed.
   These have the same name but are prefixed by `u' and `d', respectively
   (for `up' and `down', obviously).  In each of these glyphs the variables
-  charwx and charwy must be set accordingly.  If, on the other hand, the
+  `charwx' and `charwy' must be set accordingly.  If, on the other hand, the
   attachment point is the `same' for both directions (with the
   abovementioned horizontal reflection taken into account), then the prefix
   `s' (for `symmetric') should be used.  See the existing files for
@@ -108,9 +124,50 @@ Hints for stem attachment:
   and quarter notes, respectively).
 
 
-Finally, some rules to assure that rasterization at low resolutions gives
-good results.  Today, this is a minor issue, but in some cases it might show
-design flaws.
+Proofing
+--------
+
+The proofing tool for MetaFont to inspect its output is `gftodvi',
+converting a font in MetaFont's native GF font format to a DVI document,
+which can then be viewed with DVI viewers like `xdvi'.  The `gftodvi'
+program needs two special fonts, `gray' and `black'.  Assuming that you are
+using TeXLive, say
+
+  mktextfm gray
+  mktextfm black
+
+on the command line to generate the needed metric files (from its source
+files), which are then stored within your local TEXMF tree.
+
+Here is a shell script that you can use to produce two DVI files,
+`foo.proof.dvi' and `foo.ljfour.dvi', showing the glyphs of font `foo.mf' in
+proofing mode and a 600dpi rasterization for a LaserJet IV printer.
+
+  #!/bin/sh
+  mf "\mode:=proof; input $1"
+  gftodvi $1.2602gf && mv $1.dvi $1.proof.dvi
+
+  mf "\mode:=ljfour; input $1"
+  echo "grayfont black
+  " | gftodvi $1.600gf/ \
+  && mv $1.dvi $1.ljfour.dvi
+
+Assuming that you name this script `makefeta.sh', you can call it with e.g.
+
+  sh makefeta.sh feta23
+
+The main importance of the proofing DVI output is to show points marked in
+the MetaFont source code with the macros `penlabels' and `labels'.  In most
+cases, those points are used for constructing the shapes only and are thus
+not present in the output after the conversion with mf2pt1.
+
+
+Rasterization
+-------------
+
+Finally, some rules to assure that rasterization at low resolutions
+(produced directly with MetaFont) gives good results.  Today, this is a
+minor issue, but in some cases it might show design flaws.
 
 . Use `define_whole_pixels' and friends where appropriate.