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,
%%First line of text
%%And yet another line.
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:
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:
or alternatively at the top of the abc file:
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.
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
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".
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".