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

[lilypond.git] / mf / README

diff --git a/mf/README b/mf/README
index adf02251458d7da4fc5a1de0a8a63c14a2cc4bae..bcea8964b22c97a8198089fe0537b236c9f4b312 100644 (file)
--- 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.
 
 
 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
 
 
 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.
 
 
 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
 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'
 
 . 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.
 
 
   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'.
 
 
 . 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'.
 
   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',
   <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'.
 
 
   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
 
 . 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.
 
 
 . 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)
 
 . 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
   (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
   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
   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
   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).
 
 
   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.
 
 
 . Use `define_whole_pixels' and friends where appropriate.