abc2ps - Translate ABC format to PostScript
abc2ps [options] files ...
The abc2ps program 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.
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 option -o:
abc2ps file1 file2 ... -o
TUNE SELECTION
To select specific tunes from the files, use
abc2ps file1 file2 ... -e selector1 selector2 ...
where each selector is a set of abc 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.
Optionally, the search can be done on other fields using these options
in place of -e: -R searches the ‘rhythm’ field, -C searches the
‘composer’ field, -S searches the ‘source’ field. -T searches the
‘title’ field (this is the default for pattern searches). If the -C
option is used, the composer field is also displayed when the file are
listed. The same goes for the -R and -S options. Option -A selects all
tunes, overriding other selectors.
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, option -f indicates
that the following arguments (up to the next -e option) are file names.
Each set of selectors is applied to the files preceding 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:
An argument with the extension .abc is always assumed to be a
file name, and is treated as if it were preceded by -f.
An argument which is obviously a set of xref numbers is assumed
to be a selector, and is treated as if it were preceded by -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 the -o option, 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 -E option, EPSF output is
made. Each tune is then put into a separate file with a correct
bounding box and no page breaks.
The -O option determines where the output goes. The argument to -O can
be either a file name or =. 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 mode:
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 -O = is used for EPSF
output.
The actual output format is governed by sets of parameters which can be
put into format files. The format file can be selected using the -F
option; format files are usually searched both in the current directory
and the directory /usr/share/abc2ps. Refer to the section Output
formating in /usr/share/doc/abc2ps/New.Features for a detailed
description of the available parameters.
Interactive Mode
If the command list contains the -i option, 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 option 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, -O and -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.
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 /usr/share/doc/abc2ps/examples/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
T ’tr’ above note
u up-bow
v down-bow
k >-like accent
K ^-like accent
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-tuplet 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),
e.g., [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): [| produces a thick-thin bar,
|] a thin-thick bar.
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.
Bass and alto clef.
The bass clef is selected by appending the word bass to the key
specification. e.g., 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].
Use alto similarly for 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
- splits a word into two syllables, associated with
two notes, with ‘-’ drawn between them
\- adds a hyphen without splitting the word
| 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".
Multi-staff music.
Abc2ps handles music consisting of several voices. This is done
using V: lines, such as
V:2 name="Clarinet 2" short="Cl.2" clef=treble stems=down
(Here the 2 in V:2 is an arbitrary string, so any single-word
identifier can be used instead.) Later on, you can switch to the
voice using only V:2. The various settings -- key, default
length, etc. -- are maintained separately for each voice.
Guitar chords, first and second endings, and line breaks are
taken from the top voice only. Each voice can have its own
vocals.
There are several parameters that control the arrangement of
staves, braces, brackets, long bar lines etc. Refer to
/usr/doc/abc2ps/changelog for more information.
Individual voices can be selected from a multi-voice manuscript
using the -V option. For example, -V 1-2,4 will extract the
first two voices and the fourth. Specifically, this makes it
possible to generate single-voice sheets for the use of
individual players.
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 can also be prefaced
with %%.
See /usr/share/doc/abc2ps/New.Features for more information.
Bar numbers and labels.
Use the -k option to enable bar numbering. For example, -k 1
will number every bar, -k 5 will number every fifth bar, etc.
The option -k 0 will number the first bar in every staff.
Alternatively, use the %%barnumbers pseudo-comment.
The program counts the bars automatically, trying to do the
right thing at first and second endings. Namely, it remembers
the bar number at the start of the first ending, then resets to
that value at the start of the second ending. So, if there is a
tune with 2 x 8 measures with first and second endings after the
first 8 bars, we still end up with 16 bars total.
Within a single tune, bar numbers are counted across part
boundaries. However, if a T: title appears inside a tune, the
bar number is reset to 1. You can use an empty T: line to reset
the bar number without actually writing a title.
Bar labels are large letters A, B, C, ... to mark specific
points within the music. Their syntax is similar to that of
guitar chords, but they are placed before a bar line instead of
a note or rest, e.g.,
| abcd "A"| ABCD |
places the letter A over the second bar line. In case somebody
wants a label on the first bar (which is usually not preceded by
a bar line), a new symbol, [|], was introduced to denote an
‘invisible’ bar line.
Fonts for bar numbers and labels can be set up using the
%%barnumberfont and %%barlabelfont pseudo-comments.
Boxes. In printed music, bar numbers are often made more visible by
putting a box around them. This is also possible. In fact, a
box can be put around most bits of text by adding the word box
to the font specification, e.g.,
%%barnumberfont Times-Italic 11 box
This can be done for the title, guitar chords, vocals, etc. To enable
the box without changing the font style and/or size, the character *
may be used, as in
%%titlefont * * box
This is a brief summary of the options supported by abc2ps. See the
documentation in /usr/share/doc/abc2ps for more detailed information.
Modes of Operation
-o Write output for selected tunes.
-E Produce EPSF output, one tune per file.
-O filename
Set output file name to filename (default is Out.ps). If
filename is =, manufacture an output file name from input file
name or tune title (in EPSF mode).
-i Run interactively.
-v n Set the verbosity for output to the screen to n. 0 gives very
little output, 1 to 3 show successively more information.
Verbosities greater than 10 are for debugging.
-h Quick help, equivalent to ‘abc2ps’ without any arguments. This
also shows the default settings for some parameters.
-V This option used to show the version number but is now used for
voice selection (q.v.). To display the version number, use the
-h option.
Selection
-e The following arguments are selectors.
-f The following arguments are file names.
-T Search the ABC Title field (default).
-C Search the ABC Composer field.
-R Search the ABC Rhythm field.
-S Search the ABC Source field.
-V str Select voices, e.g., -fB-V 1,4-5.
These options change the output appearance:
-H Show the settings of all formatting parameters.
-p Generate ‘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.
This uses the contents of a parameter set called pretty.
-P Similar to -p, but uses a parameter set called pretty2.
-s xxx Scale the music output by factor xxx.
-w www Set the width of the staff to www points, inches or centimetres.
-m mmm Set the left margin to mmm points, inches or centimetres.
-d xxx Set the staff separation to xxx points, inches or centimetres.
-x Include cross-reference numbers (ABC X header) in output.
-k n Number every n bars; if n is 0, number every first bar of a
staff.
-n Include historical notes and other stuff at the bottom of each
tune.
-N Output page numbers.
-1 Write every tune on a separate page.
-l Operate in landscape mode.
-g shrink|space|stretch|fill
Set the ‘glue mode’. The default mode is fill, which fills the
staff.
-F format
Read format from file format.
-D directory
Look for format files in directory directory.
-X x Set strictness for note spacing, 0 < x < 1.
Transposing
-T n Transpose by n semitones (use _n for negative number).
-T note
Transpose root up/down to note note.
Line Breaks
-a x Set the maximal allowed shrinkage to x, wherex is between 0.0
and 1.0.
-b Force 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.
-B n Format with n bars on every staff.
Resource Allocation
-maxs n
Set maximal number of symbols (default 800).
-maxv v
Set maximal number of voices (default 4).
/usr/share/abc2ps/*.fmt
Various sample format files.
/usr/share/doc/abc2ps/examples/*
Various example ABC files.
/usr/share/doc/abc2ps/ReadMe.abc2ps
A more detailed version of the information contained in this
manual page.
/usr/share/doc/abc2ps/New.Features
A description of the new features of version 1.2.4b of this
program. Some information from that file has partly been
integrated into this manual page.
/usr/share/doc/abc2ps/changelog
A description of recent changes in recent versions of this
program, including multi-voice typesetting. Some information
from that file has been integrated into this manual page.
/usr/share/doc/abc2ps/layout.txt
A description of the typesetting algorithm used in abc2ps.
This manual page was written by Anselm Lingnau <lingnau@debian.org>,
for the Debian GNU/Linux system.
ABC2PS(1)
Powered by the Ubuntu Manpage Repository generator maintained by Dustin Kirkland
© 2010 Canonical Ltd. Ubuntu and Canonical are registered trademarks of Canonical Ltd.