Description of abc2ps (version 1.2)
===================================

Program abc2ps reads an input file containing music in abc format
and typesets it directly in PostScript. It can also be used to list 
the contents of an abc file.

For a description of the abc syntax, please see the abc userguide 
which is a part of the abc2mtex package written by Chris Walshaw.


----- Files -----

ReadMe.abc2ps      this file
License            GNU general public license 
Changes            history of changes to the program
New.Features       description of new features in 1.2.5
layout.txt         information about the music layout
abc2ps.c           main program 
buffer.h           routines to control the output buffer
format.h           routines for output formatting
syms.h             routines to define postscript macros
subs.h             general routines
util.h             more general routines
pssubs.h           routines for postscript output
parse.h            routines to parse input lines
music.h            routines to typeset music 
style.h            parameters for music layout
style.pure         alternative style file for "puristic" layout
sample.abc         input for demo and test
<others>.abc       sample input files


----- Installation -----

This is a single C program, consisting of file abc2ps.c and some
include files *.h. It can be compiled in the usual way to make
the executable abc2ps:

   cc -o abc2ps abc2ps.c

To test the program, unleash it on file sample.abc like this:

   ./abc2ps sample -o

The result can be inspected by using a PostScript previewer such as
ghostview on the output file Out.ps.


Possible problems:

By default, the generated PostScript is level 2 since it uses
the operator "selectfont". If you want level 1 output instead, set 
macro PS_LEVEL to 1 in abc2ps.c.

Sometimes problems arise with the "stat" function. This used at the
end of the program to determine the size of the output file. 
The call to 'stat' is in routine get_file_size in file subs.h.
This file also contains an alternative plodding version of
get_file_size, which can be used if the 'stat' version causes problems.
Alternatively, just throw out the call to get_file_size in the bottom 
of abc2ps.c and change the printf statement accordingly... printing
out the file size is only for user information.


----- Program structure -----

The program defines a number of PostScript macros for drawing
elementary components like note heads, stems, flags, bars, 
rests etc. These definitions are written to the output
file Out.ps first. The symbols are mostly defined using Bezier
curves. At some stage, the macros should probably be changed 
to user paths for more efficiency. 

The input lines are read and interpreted one at a time.
The processing of the info fields is straightforward.

The main work is done for lines of music. Such a line is parsed
into a list of symbols. To position the symbols horizontally along 
the staff, the program uses a method adapted from the "glue" used
Donald E. Knuth in the TeX program. The algorithm calculates
three separate sets of spacings:

  "shrink":   put the symbols as close together as is acceptable;
  "space":    space the symbols "naturally", whereby the space
              behind a note reflects its length;
  "stretch":  make a similar but stretched layout which still looks good.

To fill the staff, the spacings are interpolated between the "shrink" 
and "space" cases (if the sum of the natural spacings is larger than 
the staff length) or between the "space" and "stretch" cases (if the 
sum of the natural spacings is too short).

After the positions of all symbols are decided, lines are written to 
Out.ps to invoke the previously defined PostScript macros with 
suitable parameters.

File "layout.txt" gives information on the positioning and how to 
modify the layout.


----- Page breaking -----

Page breaking: version 1.2 avoids splitting a tune over pages
as much as possible. For each tune, the program checks whether 
the remaining space on the page is large enough to fit it in.
If not, a page break is put in before the tune.

To do this, the Postscript output is accumulated in a buffer first.
For really large tunes, the buffer might overflow. In that case,
the output is just written out without attempting to place the
page breaks cleverly.


----- Line breaking -----

The best output is usually obtained if the staff breaks are
chosen explicitly by suitable line breaks in the input file.
In this standard usage, the program tries to set the music as well 
as possible for each line separately. The symbols '*' and '**' at 
the end of a line are ignored, as well as the field 'E:' for
the elementary length.

However, if a line is too long to fit onto one staff, the overhang 
is spilled onto the next staff in this version. This makes it possible 
to get reasonable output even when the input is one long logical line. 
In practice, this is equivalent to automatic line breaking. 

To control line breaking, the following flags are available:

 -b    break at all line ends, even if they end with the
       continuation symbol '\'.

 -c    consider the input as one long line, ie., implicitly append 
       the continuation symbol '\' to every line of music.
      
 -B n  try to typeset with n bars on each line.

 -a x  set the maximal amount of permitted shrinking to x,
       where x lies between 0 and 1.

If none of these is specified, the standard line-by-line procedure
is followed, ie:
 
   abc2ps infile -o

For completely automatic line breaking, use the command

   abc2ps infile -c -o   

This should produce reasonable staff breaks in most cases. However, 
repeat bars, 1st and 2nd endings, and slurs might not be positioned 
very nicely.

When doing automatic line breaking with -c, the user can control the 
spacing of the symbols along the staff by specifying the "compression 
parameter" alfa with the -a flag.  A value of 0.0 means that no 
shrinking is allowed, and a value of 1.0 allows shrinking until 
the symbols are almost touching. When -c is used, by default alfa 
is set to an intermediate value (displayed with 'abc2ps -c -h'). 
When -c is not used, maximal shrinking and stretching are allowed.

Thus, to really squeeze everything as much as possible, that is,
to get automatic line breaking together with maximal shrinking, use

   abc2ps infile -c -o -a1

For more stretched output, use (for example)

   abc2ps infile -c -o -a 0.2


The flag "-B n" formats with n bars on each line. This is useful 
e.g. to try various spacings before deciding on how to set the
linebreaks explicitly in the file. 

There is not complete agreement on what output should be generated
when a staff is underfull, which happens when maximal stretching 
is not sufficient to fill the staff. The behaviour can be determined
by the following macros in abc2ps.c:

STRETCH_MODE:  allowed values are
   0   music for undefull staves is bunched to the left.
   1   music for underfull staves is left-bunched for the last staff only.
   2   underfull staves are spread over the whole staff.

STRETCH_STAFF: allowed values are
   0   when music is bunched to the left, the staff is also shortened.
   1   staff lines are always drawn all the way across the page.


Abc2ps 1.2 tries to take care of slurs and 1st & 2nd endings at the 
line breaks. But in general, a tune will look a substantially better 
when the breaks are chosen by hand.


----- General usage -----

Basically, the usage is:   

   abc2ps file1 file2.. 

where file1, file2.. are the abc input files. This will list 
the file contents. To generate Postscript output, add flag -o:

   abc2ps file1 file2.. -o

Note that most flags (see below) can be used in any sequence. 
Of course, the position does matter for flags e,f,C,S,R,T since
these determine how the following arguments are interpreted.

Flags can be contracted together if the meaning is clear, 
and a numerical argument for the last flag can be appended.
That is,  '-b -s 0.7 -v 1' can be contracted to '-bs0.7 -v1'.


----- Tune selection -----

To select specific tunes from the files, use

   abc2ps file1 file2.. -e selector1 selector2 ...

where each selector is a set of xref numbers or a pattern. Without -o, 
this will list only the selected tunes found in the files. With -o, 
output is generated only for the selected tunes.

Examples:

To list all the tunes in a file, say book1 or book1.abc (whichever exists):
      abc2ps book1

To list selected tunes: 

      abc2ps book1 -e 1-3 5,20- 'House*' Hall

This selects xref numbers 1 to 3, 5, and 20 and above,
as well as those tunes whose title either starts with "House" or 
contains the string "Hall". A pattern without wildcards such 
as 'Hall' is treated as '*Hall*'

Optionally, the search can be done on other fields using these flags
in place of -e:
      flag -R    seaches the rhythm field
      flag -C    searches the composer field
      flag -S    searches the source field.
      flag -T    seaches the title field (default)

Thus
      abc2ps book1 -C "John" 

selects all tunes whose composer string contains "John".
If the -C flag is used, the composer field is also displayed when 
the file are listed. The same goes for the flags -R and -S.

Flag -A selects all tunes, overriding other selectors.


----- Selection on multiple input files -----

To filter several files with the same set of selectors, the format is:

      abc2ps file1 file2 -e selectors...
   
To use a different set of selectors for the separate files,
use a command such as
   
      abc2ps file1 -e 1-3 -f file2 file3 -R Jig

This will select tunes 1-3 from file1 and the tunes with 'Jig' in the
rhythm field from file2 and file3. More precisely, flag -f indicates 
that the following arguments (up to the next -e flag) are file names. 
Each set of selectors is applied to the files preceeding it. 
As before, the flags -C -S -R can be used in place of -e to change
the searched field.

For convenience, there are two conventions:

   1. An argument with the extension .abc is always assumed to be a
      file name, and is treated as if it were preceeded by the flag -f. 

   2. An argument which is obviously a set of xref numbers is assumed 
      to be a selector, and is treated as if it were preceeded by the 
      flag -e. 

For example, these three commands all select tunes 1-3 from A.abc
and tunes 5-7 from B.abc:

      abc2ps A.abc -e 1-3 -f B.abc -e 5-7 

      abc2ps A.abc -e 1-3 B.abc -e 5-7 
   
      abc2ps A.abc 1-3 B.abc 5-7 

On the other hand, this will NOT work in the expected way:

      abc2ps A 1-3 B 5-7 -o

because the program has no way of knowing that B is an input
file name and not a pattern selector. 

For complicated selections on multiple input files, it might be 
better to run the program interactively (see below).


----- Making Postscript output -----

By adding flag '-o', the selected tunes are typeset and written
to the output file. To typeset all tunes in file "book1.abc":

      abc2ps book1 -o

To typeset selected tunes, use a command such as

      abc2ps book1 -e 1-3 5,20- 'House*' Hall -o
   
The idea is to vary the numbers and/or patterns until the desired  
titles are listed, then add -o to the argument list to make the
output file. 

By default, all selected tunes are written into the same file, 
with suitable page breaks added. By using the flag -E, EPSF output
is made. Each tune is then put into a separate file with a correct
bounding box and no page breaks. 

Flag -O determines where the output goes. The argument to -O can be
either a file name or the '=' sign. The latter case tells abc2ps
to choose the name by itself.

For the PS and EPS modes, the output file names are:

PS mode:
   default        Out.ps
   -O NAME        NAME.ps
   -O =           Output for "foo.abc" is written to "foo.ps"

EPSF:
   default        Outnnn.eps, where nnn is a running index
   -O NAME        NAMEnnn.eps      
   -O =           Outfile name is <tune_title>.eps

Note: an output file is overwritten if it already exists.
This will happen if two tunes have the same name and flag "-O =" 
is used for EPSF output.


----- Modifying the output  -----

These flags change the output appearance:
   
   -x      includes the xref numbers in the tune title.

   -1      writes every tune on a separate page.

   -n      includes historical notes and other stuff at the bottom 
           of each tune.

   -p      generates pretty output, with more whitespace between tunes,
           larger fonts for titles, and larger music symbols.  By default, 
           the layout squeezes the tunes to reduce the number of pages.

   -s xxx  scales the music output by factor xxx.

   -w www  sets the width of the staff to www points.

   -m mmm  sets the left margin to mmm points.

   -g shrink|space|stretch|fill   sets the "glue mode".
           The default mode is fill, which fills the staff.
           This flag is useful when changing the layout parameters, 
           to see what effect the changes have for each mode separately.

   -B n    format with n bars on every staff

   -b      forces a staff break at the end of each line, even if
           the line has the continuation symbol \ at the end.

   -c      append the continuation symbol to all music lines, 
           which amounts to automatic line breaking.

   -a x    set the maximal allowed shrinkage to x, where x lies
           between 0.0 and 1.0


----- On-line help  -----

Flags for on-line help:

   -h      quick help, equivalent to "abc2ps" without any arguments.
           This also shows the default settings for some parameters.

   -v n    sets the verbosity for output to the screen to n.
           Hereby -v0 gives very little, -v1,v2,v3.. show successively 
           more information. Verbosity >= 10 is for debugging.

   -V      shows the version number.


----- Interactive mode -----

If the command list contains the flag -i, abc2ps runs in
interactive mode. This makes it possible to build up an output
file piece by piece. The disadvantage is that you have to start
over if you make a mistake.

Interactive mode is started with
      
      abc2ps -i

The program then prompts for input with the line

      select tunes:

The response should be a row of arguments, which are treated
in exactly the same way as in the non-interactive mode.
The only difference is that the input is not first run through
the shell, so that wildcards are not expanded and quotes are
not removed. Consequently Jig* should be used instead of 'Jig*' etc.
when specifying strings for selection, and filenames must be written 
out in full.

To exit from interactive mode, enter 'q', 'quit' or an empty input.

For example, a "session" could look like this:

      abc2ps -i                start abc2ps interactively
      book1                    list tunes in book1.abc
      book1 -e 1-10            list tunes with xrefs 1-10 in book1
      book1 -e 1-10 -o         write these to Out.ps
      book2                    list tunes in book2.abc
      book2 -e House -o        write tunes with 'House' in the title
      quit                     exit abc2ps
   

To make things easier, there are three special characters:
      ?   shows the last input used;
      !   at the start of line is substituted by the last files used;
      *   at the start of line is substituted by the last input.

This means that the same effect as above can be obtained in 
shorter form like this:
   
      abc2ps -i                start abc2ps interactively
      book1                    list tunes 
      ! 1-10                   equivalent to 'book1 1-10'
      * -o                     equivalent to 'book1 1-10 -o'
      book2                    list tunes in book2.abc
      ! -e House -o            equivalent to 'book2 -e House -o'
      q                        exit abc2ps

Note that the -e flag is not needed in the line '* 1-10'
because it is clear that '1-10' is a selector (see above).


Another point is that if additional flags are used when starting
interactively, these function as defaults for the interactive mode.
For example, by starting the program with 
      
      abc2ps -io

all selected tunes are immediately written to the output file. 
The program usage is then very similar to that of abc2mtex. Of course, 
it is not possible to list the file contents (to help choose among
the titles) when using the program in this way.

In interactive mode, flags -O -E can be used as before to redirect
the output. When switching to another output file, the previous
file is closed. Switching back to the same file later will overwrite 
the file. 

   
----- Examples -----

These examples assume that wildcards '*' in the argument list
are automatically expanded out by the operating system, as 
happens e.g. under the C shell under Unix. If not, the input files 
should be specified explicitly, that is:
   abc2ps x1.abc x2.abc x3.abc  instead of  abc2ps x*.abc

To list the contents of file 'mytunes.abc':

   abc mytunes.abc

To typeset all tunes in 'mytunes.abc':

   abc mytunes.abc -o

To typeset all tunes, choosing all line breaks automatically:

   abc mytunes.abc -o -c

To do the same, but squeeze notes together more:

   abc mytunes.abc -o -c -a0.9

To list the contents of all abc files in the current directory:

   abc2ps *.abc

To search all abc files for tunes containing 'House' in the title:

   abc2ps *.abc -e House

To list the contents of all abc files, showing the Rhythm field also:

   abc2ps *.abc -R

To search all abc files for tunes with rhythm 'jig' or 'Jig':
   
   abc2ps *.abc -R jig Jig

To do the same while avoiding cases like 'slip jig':
   
   abc2ps *.abc -R 'jig*' 'Jig*'

To output all tunes by composer 'Carolan' in all abc files:

   abc2ps *.abc -C Carolan -o

To output tunes 1 to 10 in A.abc and 11-20 in B.abc:

   abc2ps A -e 1-10 -f B -e 11-20 -o
or 
   abc2ps A.abc 1-10 B.abc 11-20 -o
or 
   abc2ps A 1-10 B.abc 11-20 -o

To output all tunes with the string 'House' in the title or with
xref numbers 10-12, in all abc files whose name starts with X,
including historical notes and xref numbers in the output, 
forcing a line break at continuation lines, with reduced size
of the symbols, putting one tune per page:

   abc2ps X*.abc -e House 10,11,12 -onx -s0.9 -b1
   

----- Differences to abc2mtex ------

Essentially, all features described in the abc2mtex userguide 
should work. The are a few exceptions:

   -  The slur denotation S was replaced by the syntax (...) 
      (see below)

   -  Key signatures HP and Hp probably aren't treated 
      in exactly the right way.

   -  There is no automatic beam checking.

   -  There is no way to automatically transpose music in this version.
   

----- Some extra features --- -----

For examples, see file sample.abc.

   -  Codes for decorations: including the ones defined in the
      standard abc syntax, the following decorations are interpreted:
         .   dot, staccato
         J   slide
         M   bar (M='em-phasis')
         H   hold sign (fermata)
         ~   gracing
         R   roll 
         u   up-bow
         v   down-bow


   -  Escape sequences: embedding a string between two backslashes
      in a music line delimits an escape sequence. In the present version,
      these are treated as information fields. This makes it easy to 
      change key, meter, or default length within a line (see sample.abc). 


   -  N-tuplets: abc2ps can handle general n-tuplet cases using the syntax
      
         (p:q:r abcd ..

      This means "put p notes into the time of q for the next r notes."
      If q is not given, it defaults as described in the abc2mtex
      user guide. If r is not given, it defaults to p. For example:

         (3::2 = (3:2:2  ;  (3 = (3:2:3 

      The number written over the n-plet is p. This generalized
      syntax is compatible with the older usage. Actually, q is not used 
      at all here; it is only relevant for programs which play the music.
      

   -  Chords: The program accepts the +...+ notation, but it seems more
      intuitive to use some kind of brackets to group together the notes
      which make a chord. This program will accept square brackets:

          [ace][adf] 

      in place of the +..+ syntax.
      The abc notation formally permits notes with different durations 
      on the same stem: [a/bc2] and so on. This program assigns all
      notes in a chord the duration of the first note in the bracket.
   
      A chord with two identical notes makes a union (one head
      with stems going both up and down), eg: [AA].
   

   -  Slurs and ties: in place of the syntax "SabcSd" for a slur 
      over notes abcd, this program uses the notation

          (abcd) 
   
      for a slur over the notes abcd. It permits cases such as

          (ab(cd))  and  ((ab)cd)  and  (a(bc)d) 

      and similar slurs-below-slurs. To connect three or four notes 
      by ties (e.g., for a note held over several bars) use

          (a(b)c)  or by ties   a-b-c

      The rule is that any note alone within brackets like (b) 
      terminates a previous slur and at the same time starts a new one.

      Note that the slur syntax (..) does not interfere with the (3abc 
      style for n-tuplets. If a bracket '(' is followed by a digit k, 
      it is interpreted as the start of a k-tuplet, otherwise it is the 
      start of a slur. For example, a slur is put over the last two 
      triplets in this line: (3abc ((3cde) ((3efg).

      An unbalanced parenthesis ')' or '(' indicates the continuation
      of a slur on a neighboring line. This is needed (for example)
      in order to make automatic line breaking possible. It will also
      lead to unexpected strange-looking additional slurs if the input
      file contains the wrong syntax (3abc) instead of (3abc for triplets.


   -  Bars: The following symbols denote fat double bars 
      at the start or end of a piece (without repeat dots). 
      Namely: [| for thick-thin, |] for thin-thick.
   
      For better results when using automatic line breaking, the program 
      will split up some types of bars when these are at the end of a line, 
      for example:
        ::  becomes :|  together with |: on the next line 
        |:  becomes |   together with |: on the next line
        :|2 becomes :|  together with [2 on the next line etc.


   -  Field E: this field can be used to set some parameters from
      within the file:

         shrink    set glue mode to compress      
         space     set to natural glue widths
         stretch   stretched glue mode
         fill      normal mode to fill staffs
         break     ignore continuations
         xref      write xref numbers to output
         one       write one tune per page.
         newpage   start new page for next tune
         lw ppp    set local staff width to ppp points.

      For example, to output a single tune in a narrower format,
      put 'E:lw 400' into the header of this tune. If this is put
      after the header but within the tune body, only the music is set 
      with a different width and the title is written as before.


----- Customization -----

1. First of all, the horizontal layout of the notes can be changed 
extensively. This is described in 'layout.txt'.

2. Then there are a number of macros in the main program abc2ps.c
which determine the page layout, ie:

   PAGEHEIGHT    height of paper 
   PAGEWIDTH     width of paper 

The following block determines the layout in the "pretty" mode (-p).
The numbers are various font sizes, skips between tunes etc.,
the seperation between staffs, and page margins. A similar 
block (MAINTITLE2 ...) defines the normal, more compact mode.

   MAINTITLE1          18 
   SUBTITLE1           15 
   SUBSUBTITLE1        12
   ASKIP1              0.6 * CM
   BSKIP1              0.6 * CM
   CSKIP1              1.2 * CM
   DSKIP1              0.5 * CM
   TOP_SEP1            25 
   BOT_SEP1            25 
   LSCALE1            0.8    
   LMARGIN1           1.5 * CM
   RMARGIN1           2.0 * CM
   TMARGIN1           2.0 * CM
   BMARGIN1           1.0 * CM

For example, the default staff width is calculated from these 
parameters as PAGEWIDTH-LMARGIN-RMARGIN. The flags -w and -m change 
this width and the left margin, respectively.


3. The behavior for underfull lines can be chosen (see "Line breaks").
   Also consider these two parameters:

   ALFA_C   default compression when using the -c flag.
   BETA_X   maximal expansion allowed before considering a staff
            underfull.

Thus, setting BETA_X to 100.0 lets lines be stretched to any 
arbitrary amount quietly.


4. Parameters which influence the musical symbols (all dimensions 
are in pt, relative to a fundamental spacing between staff lines of 6pt):

   DECO_IS_ROLL  How gracings ~ are interpreted. For 0, draws a trill sign.
                 For 1, draws a roll sign (cap) over the note.
   LSCALE0       Overall scale factor. The "internal" height for the
                 staff is 24 pt, that is, 6 pt between the lines. This 
                 is rather big, so LSCALE0 scales the size down.
   BASEWIDTH     Width of lines within music (bars, stems etc).
   SLURWIDTH     Width of Bezier curves when drawing slurs.
   STEM_YOFF     Offset of stem from note head center, y direction
   STEM_XOFF     Offset of stem from note head center, x direction
   STEM          Standard stem length for single notes.
   STEM_MIN      Minimal stem length when drawing beams.
   STEM_CH       Standard stem length for chords.
   STEM_CH_MIN   Minimal stem length for chords under beams.
   BEAM_DEPTH    Width of the horizontal stroke for beams.
   BEAM_SHIFT    How far the second, third beams are shifted up or down.
   BEAM_FLATFAC  Long beams are drawn with slope reduced by this factor.
   BEAM_THRESH   If the slope of a beam lies below this threshold, 
                 it is drawn with slope zero.
   MAX_SLOPE     Upper limit for the slope of a beam.
   DOTSHIFT      Extra shift, to avoid putting the dot into the flag
                 on some notes.
   GSTEM         Grace note stem length.
   GSTEM_XOFF    Offset of grace note stem to head center.
   GSPACE0       Space between grace note and main note.
   GSPACE        Space between grace notes.



----- Summary of differences to version 1.1 -----

   -  better page breaking 

   -  automatic line breaking possible

   -  EPSF output possible

   -  Slurs improved; slurs to previous/next staff allowed.

   -  New decorations: fermata, bar, up/down bow, roll sign, slide

   -  unions as [aa]

   -  thick-thin and thin-thick bars now [| and |]

   -  normal or pretty output, depending on flag -p

   -  horizontal beams positioned more cleverly

   -  n-plets can contain rests, eg. (3zab or (3azb; 
      uses brackets if the notes are not all on one beam.

   -  general n-plet syntax (p:q:r added


----  Feedback -------

Any suggestions for improvement or bug reports are welcome.

Michael Methfessel (msm@ihp-ffo.de), June 1996.