New features in abc2ps 1.3.1 (M. Methfessel, July 1998)
=======================================================

The program now supports multi-stave output and has been improved
in various other ways. Please look at Changes for more information. 


New features in abc2ps 1.2.4 (M. Methfessel, Feb. 1997)
=======================================================


Please also have a look at file newfeatures.abc, which 
demonstrates many of these points. 


----- Bass clef -----

The bass clef is selected by appending the word "bass" to the
key specification. eg. "K:G bass". Notes are then drawn so 
"C" is below the staff and "c" is in the third space from the top,
which is a downward shift by one line relative to the treble clef.

For in-line clef changes, use an in-line specification such as
[K:G bass] (was formerly \K:G bass\; this still supported). 
If the key itself does not change, it is enough to write
[K:bass] and similarily [K:treble].

Added: [K:alto] makes the alto (viola or C) clef.


----- Vocals -----

Aligned lyrics under the staff are specified using a line directly
below the staff, starting with "w:". For example:

   edc2 edc2 | 
   w: Three blind mice, three blind mice

Each blank-delimited word in the "w:" line is associated with
one note, in sequence. The following special symbols are available
to modify this behaviour:

   *  skips one note
   -  split a word into two syllables, associated with two notes,
      with '-' drawn between them
   |  tabs forward to the next bar line.
   ~  is drawn as a space, but contracts words to be written under
      one note. That is, "hey~ho" gives two words under one note.
   _  draws a thin "underscore" from the previous note to this one.

For more than one line of lyrics, just use several w: lines.
To draw a '-' without breaking the word there, escape it as "\-".

Note that \\ in the abc music line now defines a staff break. This is
useful when typesetting vocals, because it is tedious to split
the line explicitly when shifting a staff break about when there
are lines with vocals.

If a word starts with a digit, this is interpreted as numbering of a
stanza and is pushed forward a bit. In other words, use something like 
   w: 1.~~Three blind mice 
to put a number before "Three".


----- Writing text between the music -----

This can be done using pseudocomments in three ways. First:

%%text This is a line of text.

writes one line into the output. Second, 

%%center This is another line of text.

again writes one line, but centers it. Finally,

%%begintext
%%First line of text
%%Second line
%%And yet another line.
%%endtext

will write a block of several lines. To avoid conflict with other
programs, the text lines themselves are (optionally) prefaced with %%.

Statement "%%begintext" can be  given a parameter to determine 
how the output is done, namely: 

%%begintext obeylines      keeps lines as they are (default)
%%begintext ragged         puts in own linebreaks to fill the line
%%begintext align          puts in own breaks and aligns right margin
%%begintext skip           skips the whole block, no output.

For "ragged" and "align", the program has to estimate the number of
lines needed in the current font, since the typesetting is done
using the PostScript "widthshow" operator by the printer. 
The estimate should be reasonably reliable for Times-Roman, but might 
be more dodgy for some other fonts. Also, note that the Ghostview fonts 
can be quite different than the fonts used by the printer.
Strangely, a 13pt font can be smaller than a 12pt font.

An empty line in a block ends a paragraph (see parskipfac below).
In any case, \\ can be used in a line of text to add line breaks.
Thus, two centered lines results from this:
%%center First line\\second line

As with the other pseudocomments (described below), the text is
associated with a specific tune if it is within that tune's block.
In that case, it will only be printed if that tune is selected. 
If the text is outside all tune blocks, it will always be printed.
The exception is if -E is used to to make a separate EPS file for 
each tune. In this case all text outside the blocks is ignored.

The font for text output is determined as described below.


----- Other pseudocomments which do something -----

%%sep              - draws a short centered line as a separator

%%sep h1 h2 len    - draws a separator of length len with space 
                     h1 above, space h2 below. 

%%vskip h          - adds vertical space of height h


%%newpage          - writes a page break


Dimensions can be given in cm, in, or pt, where pt is the default.
Examples:  "%%sep 1cm 1cm 4cm"  or  "vskip 1.5cm".


----- Output formating -----

The user can now tailor the appearance of the output page.
This is done by setting formating parameters, for example:

   pageheight 29cm             % height of page
   staffwidth 5in              % width of staff
   leftmargin 1.8cm            % left margin
   titlefont Times-Roman 14    % the font for the title
   titlespace 1cm              % vertical space before the title
   scale 0.9                   % size of musical symbols
   staffsep  60pt              % space between staves

Use abc2ps -H to see the current values of these parameters.

To specify the parameters, there are four levels:

1. By default, a predefined set called "standard" is used.
   With flag -p, an alternative "pretty" set is taken.
   With flag -P, a third set "pretty2" is used.
   Users are encouraged to make their own choices for these styles
   and change the program accordingly (see routines
   set_standard_format, set_pretty_format, set_pretty2_format
   in file format.h).

2. Commands to set the parameters can be grouped into a file
   with extension "fmt", which can then be selected by flag -F.
   For example: there should be a file landscape.fmt in the
   distribution. This changes the page orientation to landscape
   and sets the page height and width accordingly, and also changes
   the title style a bit. To output file scotland.abc in landscape,
   the command is 
      abc2ps scotland.abc -F landscape -o
      
3. An abc file can contain pseudocomments (%%..) such as:
      %%staffwidth 16cm
      %%titlespace 1.4cm
   Depending on the position, the changes to the style parameters
   are either global for the rest of the file, or local to a single
   tune. The change is global if the line is outside any tune block
   (where a tune block starts with "X:" and ends with a blank line).
   If the pseudocomment is within such a block, the parameter change 
   is only applied for this tune. 
   Note that the program cannot determine if a tune is selected
   before it knows the title, so such a local pseudocomment should
   come after the "T:" line.
   
4. Some of the command-line flags change the style parameters, eg:
      -s 0.9      (sets symbol scale)
      -m 2cm      (sets left margin) etc.
   Type "abc2ps -h" for a list of flags.

The priorities are in the sequence given above. That is, the ".fmt" 
file overrides the predefined format, pseudocomments overide that,
and a command-line flag overrides everything else.


Some more details:

1. Format files are searched in the current directory. In abc2ps.c,
   the line "#define DEFAULT_FDIR .." can be used to set a default
   directory which is searched whenever a fmt file is not local.
   Flag -D can also be used to specify this default directory.
   (The idea is, even if a PC user only has the executable available,
   he could make something like an alias to get his standard
   fmt directory into the path.)

2. To see the settings for all the parameters, use flag -H.
   When used in conjunction with other flags such as -p, -P, or -F,
   the corresponding parameters are shown. If you redirect the
   output to a file and edit out the header line, you immediately
   have a prototype fmt file which specifies all the parameters.

3. Dimensions can be specified either as pt, cm, or in. Default is pt.
   So, "%%staffwidth 20" will lead to very short lines!

4. Pseudocomments which are not recognized are ignored silently.
   The idea is that other program can define their own. 
   It also means that when things frustratingly don't seem to work,
   the reason might be a spelling mistake.

5. Because ISO fonts are needed for special characters and
   accents, all fonts must be known when the header of the PS file
   is written. The program tries to be as clever as it can
   about this, but a font might be undefined if it is invoked
   for the first time further down in a file. For this reason, 
   a line like this can be put into the fmt file:

      font Palatino-Bold

   or alternatively at the top of the abc file:

      %%font Palatino-Bold

   Either of these will define the corresponding ISO font in the header.
   To make things even easier, the program always looks for a file
   "fonts.fmt" and loads it if it exists. So, the often-used fonts
   can be defined there once and for all.
   
6. The default page dimensions are set by defines in abc2ps.c
   and then used in format.h to intialize the predefined formats.
   Change these if the standard paper will not be Din A4.
   The relevant lines in abc2ps.c are these:

#define PAGEHEIGHT      29.7     /* basic page dimensions in cm..  */
#define LEFTMARGIN       1.8     /* .. used in all default formats */
#define STAFFWIDTH      17.4

7. A line consisting of the word "end" in a fmt file skips the
   rest of the file.


----- List of format parameters -----

Parameters without explanation are deemed obvious.

  pageheight     
  staffwidth     
  topmargin      
  botmargin      
  leftmargin     
  topspace        vertical space at the top of a tune.
  titlespace      space before the title. 

      Note: Usually, one sees only the sum of these two.
      However, if text is written preceeding a tune, it
      will come after "topspace" and before "titlespace".

  subtitlespace   space before the subtitle. 
  composerspace   space before the composer.
  musicspace      space between the composer and the music.
  partsspace      space ("up") between the "parts" and the music.
  vocalspace      space above a line of vocals.
  wordsspace      space aboove the words at the end of a tune.
  textspace       space above the text such as history (flag -n).
       
      Note: these spaces count to the top of a line of text.
      That is, the relevant text size (eg. "12pt") is added.

  staffsep        separation between staves. One-half of this 
                  distance is added above and below each staff.
  scale           symbol size; eg. 1.0 is used in the "pretty" output.
  maxshrink       how much to compress horizontally when staff breaks
                  are chosen automatically. Between 0 and 1.

  titlefont       Font for title, ie: Times-Roman 14
  subtitlefont    
  composerfont   
  partsfont      
  vocalfont      for vocals under a staff (w: field)
  gchordfont     for guitar chords
  textfont       for text under the tune, or between tunes
  wordsfont      for words under the tune (W: field)
  lineskipfac    dimensionless factor for spacing between lines of text:
                 1.0 gives single-space output, 2.0 double etc.
  parskipfac     similar factor for space after a paragraph of text.
  barsperstaff   same as flag -B
  landscape      (logical) landscape orientation if true
  titleleft      (logical) title flushed left if true.
  titlecaps      (logical) title in capital letters
  musiconly      (logical) no vocals if true (equivalent to flag -M)
  stretchstaff   (logical) stretches underfull staves across page
  stretchlast    (logical) stretches last staff if underfull.
  writehistory   (logical) writes notes, history etc if true;
  continueall    (logical) continue all lines if true (same as -c).
  breakall       (logical) break at all line ends (same as -b).
  oneperpage     (logical) each tune on separate page (same as -1)
  withxrefs      (logical) print out X: xref number in title (same as -x).

Logicals can be specified as follows;
   One of: 1 yes true     gives true
   One of: 0 no  false    gives false.
If nothing is specified, this is equivalent to true.


----- Summary of tune layout -----

To summarize: the layout of a tune is done as follows. 
Starting from the current position on the page, 

   First write the header:
      go down by topspace, write text if any is specified;
      go down by titlespace, write the main title;
      for each subtitle, go down subtitlespace and write it;
      go down composerspace, write the composer lines;
      go down musicspace and go up by partsspace, write the parts.

   Next, starting from musicspace below the composer:
      For each staff:
         go down by staffsep/2;
         write the staff;
         for vocals, go down by vocalspace and write them;
         go down another staffsep/2.
   Note that everything here (including the spaces and fonts)
   are scaled by "scale". 

   Finally:
      if words are included, go down wordsspace and write them;
      if history/notes are included, go down textspace and write them.
   Hereby lineskip and parskip given by "lineskipfac" and "parskipfac".