

   How the notes are arranged on the staff in abc2ps
   =================================================

   This file contains more detailed information on the way in which
   the layout is calculated in abc2ps, for those who are interested 
   or would like to change the layout.


   ----- General points -----

   When typesetting music, an important feature is presumably 
   that notes and rests are arranged in some way which indicates
   the note durations. The following considerations entered
   into abc2ps:
   
   (a) The space assigned a note should be qualitatively proportional
   to its durations, but this mapping should not be strictly linear.
   It seems best to "saturate" the mapping so that whole notes
   are somewhat less than twice as wide as half notes. At the other
   end, the width allocated to 8th and 16th notes must be  
   more similar than a factor of 1/2 or the layout looks uneven.
   Thus, for durations approaching zero the note width should go
   to some constant. A modifiable function nwidth(len) defines 
   the mapping.

   (b) Given a sequence of notes (or rests) within a bar, the space 
   between any two should reflect the duration of the first. 
   If this is done strictly, the distance along the staff becomes
   the correct "time axis" but the output looks uneven.
   Therefore there is an "asymmetry" parameter beta to adjust. 
   For beta=0, the internote spacing comes equally from both neighbor 
   notes, and for beta=1 only the first note of each pair is taken 
   into account.
   
   (c) When notes are grouped under a beam, they are moved slightly
   closer together. 

   (d) The spacing between a note at the start of a measure and the
   preceding bar line is a separate case. On the one hand, the duration
   of the note could influence the spacing. On the other hand,
   music often seems to be written with this spacing some fixed standard
   distance. The treatment here is to choose a standard space (eg. some 
   fraction of a full measure) and another tuning parameter beta. For beta=0 
   the standard distance is used, and for beta=1 the space is taken from 
   the note duration. Notes at the end of a measure are treated similarily.
   
   (e) If a measure has only one note in it, one can put the note exactly 
   into the middle and calculate the measure width from the note duration.
   Alternatively, this case can be treated like case (d) as a bar-note
   and a note-bar case. A further parameter interpolates between these 
   alternatives.


   ----- Puristic layout -----
      
   To change the layout rules, the parameters in file "style.h" should
   be modified. As a starting point, it is useful to consider a strict 
   layout defined as follows (see file "style.pure"):

   (a) Make the mapping between note length and the space on the paper linear.

   (b) Make the space between two notes exactly proportional to the length 
       of the first note.

   (c) Do not move notes under beams closer together.

   (d) Put notes at the start of a measure at a fixed distance behind the bar.
       Put a bar behind a note at a spacing proportional to the note length.
   
   (e) Treat a measure with a single note in it like case (d).

   For this layout, the position of each note exactly gives the time when
   the note starts. It looks more or less like what one wants, but it is 
   too strict for good readability. One way to get suitable layout
   parameters is to start from the settings in "style.pure" and twiddle 
   on the parameters.


   ----- Algorithm for filling out the staffs -----

   This is similar to the procedure used by Knuth in TeX
   as described in the TeXBook, chapter on "Glue".
   Three different sets of spacings are defined: shrink, space, stretch.

   shrink:  the smallest acceptable spacings. These are controlled
            by function set_sym_widths().
   space:   prefered "natural" spacings at which layout looks best.
            All parameters in style.h ending in 'p' are relevant.
   stretch: spacings for an expanded "stretched" layout.
            All parameters in style.h ending in 'x' are relevant.

   To set a line, the natural spacings are added together. If the sum is
   larger than the desired staff length, the final spacings are obtained
   by linear interpolation between the "shrink" and "space" values.
   If the sum is smaller, the spacings are obtained by interpolating
   between the "space" and "stretch" values. Compression does not go 
   beyond the "shrink" spacings but expansion is allowed to any width. 
   (Formal note: the definition of shrink and stretch used here is not
   the same as in TeX; eg. the minimal spacing is here 'shrink' 
   whereas in TeX it is 'space-shrink'.)


   ----- How to proceed when changing the layout -----

   When changing the output appearance, the important thing is to modify
   the three glue modes "shrink", "space", and "stretch" separately.
   Since a typical music line is a mixture of these modes, it is
   difficult to see what is happening when changing the parameters
   in the "fill" mode. In detail:

   (1) Use info field 'E:shrink' or the flag "-g shrink" to force 
   maximally compressed output. In this mode, no extra glue is put 
   between the symbols. The layout should be as compressed as possible 
   while still being acceptable. The spacings are here given by
   the left and right widths wl,wr which are defined in routine 
   set_sym_widths(). These are presently set so that symbols 
   have a small space around them, taking into account dots, flags, 
   accidentals etc. Slightly more space is left around open notes and 
   fat bars.

   (2) Next, use 'E:space' or "-g space" to force the prefered natural 
   spacing. This layout should be adjusted to get the ouput which looks 
   best. As in case (1), there are left and right widths for each symbol,
   now called pl and pr, which are also set in set_sym_widths().
   The important difference is that spacings around notes and rests
   are influenced by the durations. This is done according
   to the rules described above, using the parameters ending in 'p'
   in style.h. The relevant routine is set_sym_poslist(). 

   (3) Finally, use 'E:stretch' to force stretched output. 
   This output should be something like twice as wide but should still be 
   easily readable. For example, this implies that internote spacings are 
   more even than in the "space" mode. Internally, the stretched spacings 
   are calculated exactly as the prefered spacings, using left and right 
   widths xl and xr, function xwidth(len), and the parameters ending 
   in 'x' in style.h.
   
   The idea is that after obtaining satisfactory layouts for the shrink, 
   space, and stretch modes separately, the output should look good
   when the spacings are interpolated to fill out the staff.

   If you change the style file to your tastes, you might as well 
   give the layout a new name, by changing the macro STYLE in style.h.
   This is so that the command 'abc2ps -V' can show what style is 
   currently being used.


   Michael Methfessel, Feb 1996.
