

Description of abc2ps (version 2.0 of January 2007)
===================================================

Program abc2ps reads an input file containing music in abc format
and typesets it directly in PostScript. The output can be viewed
(e.g. using PostScript) or sent to a printer. In addition,
the program can produce an audio playback in .wav or .au format
and it can transpose the music, optionally writing an abc file
containing the transposed music. 


----- Files -----

ReadMe.txt         this file
License            GNU general public license 
Changes            history of changes to the program
Makefile           make file
layout.txt         information about the layout algorithm 
sample.abc         sample input file
sound.abc          sample input file for playback

The source code is distributed over the following files.
There are also corresponding include files <xx>.h.
   abc2ps.c       main program
   buffer.c       functions to control the output buffer
   format.c       functions for output formatting
   music.c        functions to typeset music 
   parse.c        functions to parse input lines
   playback.c     functions for audio playback
   pssubs.c       functions for postscript output
   style.c        parameters for music layout
   subs.c         general functions
   syms.c         functions to define postscript macros
   util.c         various low-level utility functions
   wav.c          functions for audio output in wav format


----- Brief introduction to the abc format -----

Abc2ps reads one file (say test.abc) and writes another (usually Out.ps).
File test.abc contains the musical information for one or more
pieces of music in abc format. File Out.ps contains the typeset
music in PostScript format. 

There are good detailed descriptions of the ABC syntax, such as 
the user guide of the ABC Plus project (http://abcplus.sourceforge.net/).

A very brief introduction to abc for the uninitiated follows:

The abc input file contains one or more block, each describing one 
musical piece. A block starts at the first header line, which 
must be "X: <xref_number>". This is followed by the other header
lines, to specify the title, default note length, meter, and key,
among other things. Officially the last header line is the key 
specification "K: <keyspec>", but this is not enforced strictly. 
Please note that the wrong ordering can lead to unexpected results 
for multi-staff music. The header is followed by the music itself.
The whole block is terminated at the first encountered blank line
(or the end of the file). A minimal musical block is this:

X: 1
T: Hello World
L: 1/4
M: C
K: C
CDEF | GABc |

Putting these lines into a file called "hellow.abc" and typing 
"abc2ps hellow.abc" on the command line should produce a file
called "Out.ps" with the sheet music for the C major scale.

In addition to the musical information, the input file can contain
these elements:

   Comments: all text from a single % to the end of the line
   is ignored.

   Pseudocomments: a line containing %% followed by a keyword
   contains non-musical information. This sets parameters
   which control the typesetting, audio output etc. A typical
   usage is to specify the font used for the title or the
   playback tempo. The psuedocomments are described below.
   

----- Installation -----

Abc2ps is a single C program. The source code is split over different 
.c files, as listed above. The main program is in abc2ps.c and the 
general macros are defined in abc2ps.h. To compile abc2ps, try 
typing "make" using the supplied Makefile. If this does not work,
adapt the Makefile to your system. For example, you might want to 
change the line "CC = cc" to "CC = gcc".

It is also possible to compile the sources separately:

   cc -c abc2ps.c
   cc -c buffer.c
    ...
   cc -c wav.c

and link them using

   cc -lm -o abc2ps *.o

to make executable abc2ps.


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

   ./abc2ps sample 

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

For Windows user: simply copy the compiled executable file 
(this is probably abc2ps-<version>.exe) to a suitable location 
(such as abc2ps.exe) on your system and run it from a DOS prompt. 
It is useful to add the directory containing the executable to the path.


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

Program abc2ps is strictly a command-line affair. This means, it is 
invoked by typing "abc2ps" followed by arguments and flags and then 
hitting the <Enter> key. This is not as exciting as using a program 
with a graphical user interface, but it is platform independent. 
After a while it is a lot faster too.

Basically, the usage is:   

   abc2ps <abc_file> 

where <abc_file> is a file with ending .abc or .txt containing the 
abc code for one or more pieces of music. This will write PostScript 
with the typeset music for all the pieces to file Out.ps. 

More general usage is as follows:

   abc2ps [flags] <file1> <file2> ... 

Here the input is taken from all specified input files. 
Actually, flags and file names can be interspersed freely.

The operation  of the program can be modified using the various flags. 
The flags are used for these main purposes:

 - select specific tunes out of the file(s) for processing.

 - set parameters which control the typesetting.

 - control other functions, such as playback or transposition.

 - get help information.


In a typical unix fashion, flags are specified as the character '-' 
followed by an identifier, which in most cases is a single letter.
Upper- and lowercase letters refer to different flags. A flag can have
a parameter following it. This is separated by a space. In most
cases it can also follow the flag directly.

For an overview of all flags, type "abc2ps -h" or "abc2ps" without 
any arguments.


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

The most frequently occuring case is to probably to select tunes 
by xref number. For example, we could first list all entries in
file sample.abc:

/abc/src> abc2ps -L sample.abc
sample.abc:
  1    C     C     Scale - Second Title - Third Title
  3    C     C     Short and Long Notes, Beams, N-tuplets
  4    A     C     Key signature, Accidentals and Decorations
  5    D     6/8   Bars and Rests
  6    D     9/8   Chords, Unions, First and Second Endings
  7    Ebm   C|    Slurs and Ties - Title with funny chars
  8    G     6/8   Changing Time or Key Signatures, Guitar Chords
  9    C     C     Strange tuplet cases
  10   G     6/8   Chords with many accidentals
  11   C     C     Horizontal Beams, Bar Labels
  12   D     C     Gracenotes, Bar Numbers
  13   F     C|    Vocals
Selected 12 titles of 12

Next we restrict the list to selected tunes:

/abc/src> abc2ps -L sample.abc 1-3,5,8
sample.abc:
  1    C     C     Scale - Second Title - Third Title
  3    C     C     Short and Long Notes, Beams, N-tuplets
  5    D     6/8   Bars and Rests
  8    G     6/8   Changing Time or Key Signatures, Guitar Chords
Selected 4 titles of 12

Then we generate output for these tunes:

/abc/src> abc2ps sample.abc 1-3,5,8
sample.abc: [1] Scale - Short and Long Notes, Beams, N-tuplets 
- Bars and Rests - Changing Time or Key Signatures, Guitar Chords - 
Output written on Out.ps (1 page, 4 titles, 28922 bytes)


Selection can also be done in a more flexible way. In general,
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. With -L, 
this will list the selected tunes found in the files. Without -L,
PostScript output is generated for the selected tunes.

Examples:

To list all the tunes in a file book1.abc:
      abc2ps -L book1

To list selected tunes (in an unrealistically complex case): 

      abc2ps -L 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*'

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 -e Jig

This will select tunes 1-3 from file1 and the tunes with 'Jig' in the
title 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. 

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 

Finally, a selection by string match is done for the title by default,
but can also be done for the composer, rhythm, and source fields.
To do this, append a letter directly after -e as follows:

  -et    select on Title field, case insensitive
  -ec    select on Composer field, case insensitive
  -er    select on Rhythm field, case insensitive
  -es    select on Source field, case insensitive

  -eT    select on Title field, respects case
  -eC    select on Composer field, respects case 
  -eR    select on Rhythm field, respects case
  -eS    select on Source field, respects case

Thus: 
   -er jig      will match "Jig" or "jig" or "JIG" etc, but
   -eR Jig      only matches "Jig".

The default function of the -e flag is "-et".

The Composer, Rhythm, and Source fields are normally not displayed 
with flag -L. However, the selected field will be shown in the list 
when -e is used with an appended letter. 
 


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

Thes following flags change the output appearance. Note that most of these 
can also be modified using pseudocomment format directives in the file.
   
   -x      includes the xref numbers in the tune titles.

   -1      writes every tune on a separate page.

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

   -N      write page numbers

   -k n    number every n-th bar, or at staff start if n is zero.
           If 'c' is appended, count through 1st/2nd endings.

   -l      make output in landscape mode

   -p      generates pretty output, with more whitespace between tunes,
           larger fonts for titles, and larger music symbols. 

   -P      use a second predefined pretty format.

   -s xxx  scale the music output by factor xxx.
           Note: xxx=1.0 corresponds to 6 point between staff lines.

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

   -m mmm  sets the left margin to mmm points.

   -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.

   -Z aaa  add an annotation "zzz" in each top left-hand corner.
           Useful to indicate transposition to a Bb or Eb, say.
           The annotation can have several words if is enclosed 
           in quotes, e.g. -Z "B intruments". 

   -S kkk  set the default key to "kkk". This is useful to print
           out music for an instrument using say bass or alto key,
           without editing the file. Examples: "-S bass+8" or "-S alto".
            

The next flag probably won't be used very much by a typical user:

   -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.


----- Bar numbers and bar labels -----

Bar numbering is switched on with the flag "-kn" (see above) 
or the pseudocomment "%%barnumbers n" (see below). If n is 0, 
the bar number is written at the start of each bar. If n greater 
than 0, the bar number is written for every n-th bar. 

To write a bar label, put a string in double quotes directly before
the bar, e.g. "A" or "D.C. al Fine". This will write the string above 
the bar symbol. Note that the syntax is the same as for guitar chords. 
The difference is that it is applied to a bar instead of a note or rest. 
If the label contains "$" a segno is written and "@" writes the "target" 
symbol. Normally, the label is centered above the bar. To align the 
label differently, include the character ~ somewhere in the string. 
This aligns the following character above the bar symbol.

To write a bar label at the start of a line when there is no bar line:
put in an "invisible bar line" using [|] and attach the label to that.
Invisible bar lines can be used at other places in the music also.
This will often be necessary at the end of a staff. When the last symbol 
on a staff is a bar and if this bar has a label, the label is moved 
to the start of the next staff. This somewhat mystifying behavior is 
connected with automatic line breaking and might be changed in the future. 

Thus, at the end of a staff, use a construct such as
   EEA2 | EzEz | GD^C2 "D.S. al Coda~"[|] :|
And at the start of a staff:
   "A"[|] E2ED | E4 | E2ED | ^C4 | ^c2cc | 

The fonts for bar numbers and labels are set using pseudocomments, e.g.

  %%barnumberfont Times-Italic 12
  %%barlabelfont Times-Bold 18

Bar labels are sometimes made more conspicious by drawing a rectangle 
around them. This can be done using a font definition such as
  %%barlabelfont Times-Bold 18 box
or
  %%barlabelfont * *  box
to request the box without changing the font.

The "box" option can be used for most other font definitions as well.

Bar numbering tries to handle first and second endings correctly.
The program remembers the bar number at the start of the first ending,
then returns to that number at the start of the second ending. 
This behavior can be switched off by appending "c" to the -k flag
(for example "-k2c" or "-k0c") or by using flag "-kc" by itself. 
The same effect is obtained by pseudocomment %%barnumsclassical.
This produces simple "classical" style counting, where bars are just 
counted through. 

In some cases, it might be necessary to set the bar number explicitly. 
To do this, make a bar label which includes "&n" for the relevant bar,
where n is the desired number. Bar numbers will count onward from 
this value for subsequent bars.


----- Tranpsosing and writing abc output -----

Flag -t is used to tranpose the music before it is written to
the output file. Tranposition can either be specified by the
number of halftones to transpose or by giving the target key. 

   -t n     Transpose the music by n halftones. Value n is optionally
            preceeded by '^' to transpose upward  or by '_' to
            transpose down. Thus, "-t-3" "-t_3" "-t _3" all transpose 
            down by three halftones. Starting from music for a C
            instrument, useful cases are
               -t^2 or -t_10   to transpose for a Bb instrument
               -t_3 or _t^9    to transpose for an Eb instrument.
            Guitar chords are also translated to the transposed key.
            To see what is going on, use verbosity 4 or greater.

   -t XX    This alternative form specifies the root of the target key 
            directly. By default this shifts either up or down, depending
            on which case leads to a smaller shift. By preceeding XX
            with '^' or '_', the direction can be forced to up or down.
            Examples: -tBb -t^G -t_A#.

Used as described, transposition will be applied to all voices.
However, in some cases it is useful to transpose only selected voices,
or to transpose different voices to different keys. To restrict
the transposition to selected voices, append "=" and a list of the 
relevant voices. The list can be of the form 2,3,4 or 3-4 or some 
combination such as "1,4-5". 

Example:  -t^2=1,3

This will transpose only voices 1 and 3 upward by two halftones.

To transpose different voices differently, use several occurrences
of the -t flag. If a voice matches the selection list in more than
one of these flags, the last will be applied. 

Example:  -t^2 -t_3=3-4

This will transpose all voices up 2 halftones, except that voices 3 and 4 
are transposed downward by 3 halftones.

The result of the tranposition can be saved in abc format.
This gives abc2ps the capability to tranpose abc files.
To do this, use flag "-T" to tell abc2ps to write a text file
with abc code. The output file is called <name>_out.abc when 
the input file was called <name>.abc. If no transposition is done, 
the two files will be identical. If only some tunes were selected,
only these will be written to the text file. If some or all clefs
were changed using -S, these changes are reflected in the output file.


----- Playback -----

Flags "-a" and "-A" request abc2ps to generate an audio file 
together with the PostScript output. This file is either in .wav 
or .au format (depending on the setting in abc2ps.h at compile time) 
and will be called Abc.wav or Abc.au, respectively. Flag "-a" 
outputs the melody, "-A" adds an accompaniement using guitar chords.
By default, the audio output plays the voices in a piano style with 
rather low quality (8000 samples per second, 8 bits per sample). 
This saves computing time, since the generation of audio output 
requires vastly more computation than typesetting the music. 
It also reduces the file size (to about 8 kB per second, 
as opposed to 180 kB for CD quality output).

To test this, generate audio output for file sound.abc with
   abc2ps -A sound.abc
and listen to file Abc.wav (or Abc.au on a Sun workstation).

The audio output can be modified by the following flags:

   -W      switch between .wav and .au audio format

   -C      make CD quality output: 44100 samples per second, 
           16 bits per sample, two (identical) channels. 
           Flag -C implies -a and -A.

   -Q xx   set the playback tempo to xx beats per minute

   -q m/m  set audio qualities for the voices/acc (m=pafcog)
           The default is piano for all voices and accompaniement.

   -X m-n  play bars m through n only. These bars will be marked using
           red bar numbers in the PostScript output.

   -Ax     add an accompaniement based on the guitar chords (see below).
           The argument is optional but must follow '-A' immediately,
           without a space. Flag -A implies -a.

   -G      play only the accompaniment.

   -i      forbid chord inversions in the accompaniement.


The audio qualities are made from modified sine, sawtooth, 
and triangle waves. They are somewhat along the lines of piano, 
accordion, flute, cembalo, organ, and guitar, as specified by 
the letters p a f c o g. They are not very realistic; the playback 
function is intended for debugging melodies or harmonies, or to get
a quick impression of a piece. Piano, organ, and cembalo are not too 
bad, flute and accordeon sound artificial. Using different qualities
is useful to separate voices in multi-voice music. Select qualities 
using flag -q. Hereby everything before / selects the qualities 
for the voices in sequence, after / applies to the accompaniement. 
Flag -v5 shows detailed information about the selected qualities.

To add an accompaniement derived from the guitar chords, use -A.
Flag -A without an argument or with argument 0 will choose a
pattern depending on the meter. Alternatively, -A can be followed 
by a character which selects a specific pattern. Thus, for a piece
in 4/4 meter, -A will select the default stride pattern, -Ab uses
a more latin style, -AF will play the full chord on each beat. 
By typing "abc2ps -a -hh" all defined patterns are displayed, 
in a format which will make sense after some inspection.

Flag -X restricts the playback to selected bars. This is useful 
when going through a piece of music in smaller sections, checking 
or setting out a few bars at a time.

Examples for playback generation:

   abc2ps -o infile           - makes Postscript only, as usual.
   abc2ps -a infile           - makes both Abc.au and Postscript
   abc2ps -a infile -Q 160    - does the same with tempo Q=160
   abc2ps -a infile -qcap     - uses audio quality c, a, p 
   abc2ps -A infile           - includes guitar chord accompaniement
   abc2ps -C infile -G        - play only the harmonies, suitable for
                                burning onto a CD.


The playback tempo, audio qualities, accompaniement pattern, and
bar selection can also be set using pseudcomments such as
   %%playtempo 160
   %%auquality cap
   %%accomp J
   %%playbars 21-24

On the subject of guitar chords: it is sometimes required to place 
guitar chords where there is no note in the music. To support this,
a chord can shifted relative to the note it is associated with.
Syntax: each dot in the guitar chord string shifts by one quarter note.
More than one chord can appear in one string, separated by dots.

Examples: 
   |"Bm7..E7"E4|      Bm7 and E7 each get two beats over a full note.

   |"C6..Bb6.B6"c4|   C6 gets beats 1 and 2, Bb6 and B6 beat 3 and 4.



----- 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.
           Together with -a or -A, it shows the default audio format.
           In that case, the effect of flags -C and -W is shown.

   -hh     shows the version number. Together with -a or -A, it shows
           the different accompaniement patterns. 

   -H      shows the values of the format parameters which can 
           be set using pseudocomments. In connection with "-p"
           or "-P", show the values for these formats.
           The result can be used as prototype for a .fmt file.

   -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.

Useful information could also be found in the Changes file.


----- Pseudocomments and format files -----

Pseudocomments are lines starting with "%%" followed by a keyword
in the input file. These are used to set various parameters, 
of which many are also influenced by command line flags. 
Pseudocomments outside any tune apply to all following tunes. 
Those inside a tune apply only to it. 

When setting a parameter, 

 - Dimensions can be given using "pt", "cm", or "in". 

 - Logical values can be "1" or "0" or "yes" or "no" or "true" or "false".

 - A font specification can be followed by "box" to draw rectangles
   around the text.

A list of the pseudocomments used to set parameters, together 
with their predefined settings in the standard format, is as follows:

  pageheight       29.70cm
  staffwidth       17.40cm
  topmargin        1.00cm
  botmargin        1.00cm
  leftmargin       1.80cm
  topspace         0.80cm
  titlespace       0.20cm
  subtitlespace    0.10cm
  composerspace    0.30cm
  musicspace       0.20cm
  partsspace       0.30cm
  wordsspace       0.00cm
  textspace        0.50cm
  vocalspace       23.0pt
  staffsep         46.0pt
  sysstaffsep      40.0pt
  systemsep        55.0pt
  scale            0.70
  maxshrink        0.65
  strictness1      0.50
  strictness2      0.80
  indent           0.0pt
  titlefont        Times-Bold 16.0
  subtitlefont     Times-Roman 12.0
  composerfont     Times-Roman 10.0
  partsfont        Times-Roman 11.0
  tempofont        Times-Bold 10.0
  vocalfont        Times-Bold 13.0
  gchordfont       Helvetica 12.0
  textfont         Times-Roman 12.0
  wordsfont        Times-Roman 12.0
  voicefont        Times-Roman 12.0
  barnumberfont    Times-Italic 12.0
  barlabelfont     Times-Bold 18.0
  indexfont        Times-Roman 11.0
  lineskipfac      1.1
  parskipfac       0.4
  barsperstaff     0
  barnumbers       -1
  barnumsclassical no
  landscape        no
  titleleft        no
  titlecaps        no
  stretchstaff     yes
  stretchlast      no
  writehistory     no
  continueall      no
  breakall         no
  oneperpage       no
  withxrefs        no
  playtempo        120
  auquality        p
  accomp           0

This list can be generated using "abc2ps -H".

Format specifications (without %%) can be put into a separate
"format file". This file can be included using flag "-F". If the
format file has the extension .fmt, -F can be left away.
Format files allow to define standard styles which can be applied
to different abc files. The output of "abc2ps -H" is a template
for such a format file.

Example:  abc fly_me.abc fbook.fmt    


In addition, there are other pseudocomments with special 
functionality. These are:

%%vskip <dimension>
 - skip vertically on the page

%%sep <space_above> <space_below> <width>
 - draw a separator. The parameters are optional.

%%text <text>
 - write a line of text

%%center <text>
 - write a centered line of text

%%begintext <how>
%%<first line>
%%<second line>
  ...
%%endtext
 - write a block of text, where the optional <how> can be "obeylines",
   "align", "skip", or "ragged".
   
%%playbars <start_bar>-<end_bar>
 - select bars for audio output

%%annotate text..
 - This writes an annotation in the top-left corner, exactly as flag -Z.


----- Customization -----

1. There are a few macros in the main include file abc2ps.h
which can be adapted. These are in the block called "general macros".
They mainly set the defaults for various parameters:

   PAGEHEIGHT      height of paper in cm
   PAGEWIDTH       width of paper in cm
   VERBOSE0        how much information is shown by default
   PLAY_TEMPO      default playback tempo
   DEF_EXT         default extension, say "abc" or ".txt".   
   WAV_IS_DEFAULT  select default audio format (wav or au)
   LIL_ENDIAN      machine endianess, needed for audio output

The last two should both be 0 for a Sun workstation and 1 for 
an Intel PC (Linux or Windows).

2. There are two predefined output style which are selected using
flags -p or -P. They are defined in file format.c in functions 
set_pretty_format and set_pretty2_format and can be modified.

3. The horizontal layout of the notes can be changed extensively. 
This is described in "layout.txt".  

4. New guitar chords for playback can be defined in au_interp_gchrest
in file playback.c.


----- Summary of command line flags -----

Flags can be given in any order, interspersed arbitrarily between
the input file names. With a few exceptions, a flag consists of 
a hyphen followed by a single letter. It may or may not require
an argument. Generally an argument can be stuck to the flag itself
if desired. Thus, "-v5" and "-v 5" are both allowed. Flag -A
only works with a sticky argument (since the argument is optional).

The various flags have the following functions:

General flags:

   -o       Write PostScript output. This is the default. If not set
            explicitly using -O, the output file will be called Out.ps.

   -L       List the contents of the file(s) without writing PostScript.
            If tunes were selected using -e, list only the selected tunes.
            Combined with -ec, -er or -es, show the Composer, Rhythm,
            or Source fields.

   -e       Indicates that the next arguments are selectors, used to 
            filter some tunes out of the input file for processing.
            -et, -ec, -er, -es selects by the Title (default), 
            Composer, Source, or Rhythm field. -eT -eC -eR -eS 
            does the same but is case sensitive.

   -f       Indicates that the next arguments are file names. This flag 
            is used to add another abc file after "-e" has been used.

   -E       Produce a separate encapsulated Postscript file for each
            tune. By default these are named Out001.eps, Out002.eps...

   -O aa    Set the output file name to aa.ps. 

   -O =     Set the output file name using the input file name
            (i.e. "test.abc" produces "test.ps"). Together with -E, 
            the name of each output file derives from the tune name.
           
   -I       Also write an index to file Ind.ps.

   -F foo   Read format parameters from file "foo.fmt".
            If the extension ".fmt" is included explicitly, the program
            recognizes that it is a format file and -F can be left
            away. See section "Pseudocomments".

   -D bar   Look for format files in directory "bar".

   -T       Write abc code to file <name>_out.abc, where <name>.abc
            is the input file. The code will be transposed (if flag 
            "-t" was used) and will only contain the selected tunes.


Flags for getting information:

   -v n     Set the verbosity level to n. This controls the amount of
            output to the screen while the program is running.
            Hereby -v0 gives very little, -v1, v2, v3.. show successively 
            more information. Level 5 is a good choice to see 
            usful information without too much output. Levels 
            10 and above are mainly for debugging. For example, 
            a table with the parsed list of symbols is printed.

   -h       Show a command summary. This is equivalent to typing "abc2ps" 
            without any arguments. Together with flag -a, -h shows
            information about current settings for the audio output. 

   -hh      Show the version. When used together with flag -a or -A, show
            the available patterns for accompaniment during playback.
            
   -H       Show the current values for all the format parameters.
            The output will reflect the modifications due to other
            flags on the command line. If the output is directed 
            to a file, this can be used as a template for a 
            format file (see above).


Flags to modify the music typesetting:

   -p       Use the first "pretty" predefined style.
            You can modify function set_pretty_format in format.c 
            to adapt this style.

   -P       Use the second "pretty" predefined style.
            You can modify function set_pretty2_format in format.c 
            to adapt this style.

   -s xx    Set the overall scale factor for symbol sizes to xx. 
            A typical value is 0.70 for readable output.

   -w xx    Set the staff width. The size can be given in points,
            centimeter, or inches, eg. 400pt, 15cm, 6in.
            If no unit is given, points are assumed.

   -m xx    Set the left margin (in cm/in/pt).

   -d xx    Set the staff separation (in cm/in/pt)

   -x       Include the xref numbers in in the title of eacbh tune.

   -k n     Write bar numbers. If n is 0, a number is written at 
            the start of each bar. If n greater than 0, every
            n-th bar is numbered.

   -n       Include the "notes" and "history" fields in the output.

   -N       Write page numbers.

   -1       Start each tune on a new page.

   -l       Output in landscape mode.

   -V str   Select specific voices out of multi-voice music. 
            The format is as in this example: -V 1,4-5 to select
            voices 1, 4, and 5.

   -S kkk   Set the clef to kkk. This is useful to output music quickly 
            for (say) bass or alto instruments without having to edit 
            the input file. Useful values are "bass", "alto", "treble" 
            and "tenor". To shift up or down an octave, append
            "+8" or "-8" as in the example "-S alto+8". To undo
            a shift by +8 or -8 in the input file, use "treble+0" etc.
            To restrict the operation to some voices, append '='
            and a list, e.g. "-S bass=1-2,5".

   -Z aa    Add a text annotation "aa" in the top left corner of each page. 
            One useful application is to label music which has been 
            transposed for a Bb or Eb instrument.

   -b       Make a line break at each line end, i.e., ignore
            any continuations using a trailing \ in the input file.

   -c       Continue all line ends. This turns the input into
            one long sequence which is broken into lines as the program
            sees fit. Effectively, this gives automatic line breaking.

   -B n     Put line break every n bars. This is useful to see quickly 
            if the output looks good for different choices. It will
            probably not give nice results for cases such as first 
            and second endings.

   -g xx    Set glue mode to shrink|space|stretch|fill. This is
            only useful when twiddling the parameters which control 
            the horizontal layout.


Flags for transposing:

   -t n     Transpose the music by n halftones. Value n can be
            preceeded by '^' to transpose up (the default) or by '_' 
            to transpose down. Thus, "-t-3" "-t_3" "-t _3" all transpose 
            down by three halftones. Starting from music for a C
            instrument, useful cases are
               -t^2 or -t_10   to transpose for a Bb instrument
               -t_3 or _t^9    to transpose for an Eb instrument.
            Guitar chords are also translated to the transposed key.
            To see what is going on, use verbosity 4 or greater.

   -t XX    This alternative form specifies the root of the target key 
            directly. By default this shifts either up or down, depending
            on which case leads to a smaller shift. By preceeding XX
            with '^' or '_', the direction can be forced to up or down.
            Examples: -tBb -t^G -t_A#.

            To restrict the tranposition to selected voices in multi-voice
            music, append "=" and a list of the relevant voices.
            The list can be of the form 2,3,4 or 3-4 or some combination.
            Several occurences of the flag "-t" are allowed.


Flags for allocation:

   -maxs n  Set the maximal number of symbols. Use this if the program
            stops because the symbol table is full.

   -maxv n  Set the maximal number of voices. Use this if the program
            stops because the built-in maximum is exceeded.




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

Any suggestions for improvement or bug reports are welcome.

Michael Methfessel (msm at ihp hyphen ffo dot de), Jan 2007.


