.TH ABC2PS 1
.\" NAME should be all caps, SECTION should be 1-8, maybe w/ subsection
.\" other parms are allowed: see man(7), man(1)
.SH NAME
abc2ps \- Translate ABC format to PostScript
.SH SYNOPSIS
.B abc2ps
.I "[options] files ..."
.SH "DESCRIPTION"
The
.B 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.
.P
For a description of the abc syntax, please see the abc userguide 
which is a part of the abc2mtex package.
.P
.SS "GENERAL USAGE"
Basically, the usage is
.RS
.sp
\fBabc2ps\fR \fIfile1 file2\fR ...
.sp
.RE
where
\fIfile1, file2 ...\fR are the abc input files. This will list 
the file contents. To generate Postscript output, add option
\fB-o\fR:
.RS
.sp
\fBabc2ps\fR \fIfile1 file2\fR ... \fB-o\fR
.sp
.RE
.SS "TUNE SELECTION"
To select specific tunes from the files, use
.RS
.sp
\fBabc2ps\fR \fIfile1 file2\fR ... \fB-e\fR \fIselector1 selector2\fR ...
.sp
.RE
where each selector is a set of abc xref numbers or a pattern.
Without \fB-o\fR, 
this will list only the selected tunes found in the files. With \fB-o\fR, 
output is generated only for the selected tunes.
.P
Optionally, the search can be done on other fields using these options
in place of \fB-e\fR:
\fB-R\fR searches the `rhythm' field,
\fB-C\fR searches the `composer' field,
\fB-S\fR searches the `source' field.
\fB-T\fR searches the `title' field (this is the default for pattern
searches).
If the \fB-C\fR option is used, the composer field is also displayed when 
the file are listed. The same goes for the \fB-R\fR and \fB-S\fR options.
Option \fB-A\fR selects all tunes, overriding other selectors.
.P
To filter several files with the same set of selectors, the format is:
.RS
.sp
\fBabc2ps\fR \fIfile1 file2\fR \fB-e\fR \fIselectors\fR ...
.sp
.RE
To use a different set of selectors for the separate files,
use a command such as
.RS
.sp
\fBabc2ps\fR \fIfile1\fR \fB-e 1-3 -f\fR \fIfile2 file3\fR \fB-R Jig\fR
.sp
.RE
This will select tunes 1-3 from \fIfile1\fR and the tunes with 'Jig' in the
rhythm field from \fIfile2\fR and \fIfile3\fR.
More precisely, option \fB-f\fR indicates 
that the following arguments (up to the next \fB-e\fR option) are file names. 
Each set of selectors is applied to the files preceding it. 
As before, the flags \fB-C\fR, \fB-S\fR, \fB-R\fR
can be used in place of \fB-e\fR to change the searched field.
.P
For convenience, there are two conventions:
.IP
An argument with the extension \fI.abc\fR is always assumed to be a
file name, and is treated as if it were preceded by \fB-f\fR. 
.IP
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 \fB-e\fR. 
.P
For example, these three commands all select tunes 1-3 from A.abc
and tunes 5-7 from B.abc:
.nf
.RS
.sp
\fBabc2ps A.abc -e 1-3 -f B.abc -e 5-7\fR
\fBabc2ps A.abc -e 1-3 B.abc -e 5-7\fR
\fBabc2ps A.abc 1-3 B.abc 5-7\fR
.sp
.RE
On the other hand, this will NOT work in the expected way:
.RS
.sp
\fBabc2ps A 1-3 B 5-7 -o\fR
.sp
.RE
because the program has no way of knowing that B is an input
file name and not a pattern selector. 
.P
For complicated selections on multiple input files, it might be 
better to run the program interactively (see below).
.SS "Making PostScript Output"
By adding the \fB-o\fR option, the selected tunes are typeset and written
to the output file. To typeset all tunes in file \fBbook1.abc\fR:
.RS
.sp
\fBabc2ps book1 -o\fR
.sp
.RE
To typeset selected tunes, use a command such as
.RS
.sp
\fBabc2ps book1 -e 1-3 5,20- 'House*' Hall -o\fR
.sp
.RE
The idea is to vary the numbers and/or patterns until the desired  
titles are listed, then add \fB-o\fR to the argument list to make the
output file. 
.P
By default, all selected tunes are written into the same file, 
with suitable page breaks added. By using the \fB-E\fR option, EPSF output
is made. Each tune is then put into a separate file with a correct
bounding box and no page breaks.
.P
The \fB-O\fR option determines where the output goes.
The argument to \fB-O\fR can be
either a file name or \fB=\fR. The latter case tells \fBabc2ps\fR
to choose the name by itself.
.P
For the PS and EPS modes, the output file names are:
.TP
PS mode:
.nf
default        \fBOut.ps\fR
\fB-O\fR NAME        NAME\fB.ps\fR
\fB-O =\fR           Output for "foo.abc" is written to "foo.ps"
.fi
.TP
EPSF mode:
.nf
default        \fBOut\fInnn\fB.eps\fR, where \fInnn\fR is a running index
\fB-O\fR NAME        NAME\fInnn\fB.eps\fR
\fB-O =\fR           Outfile name is <tune_title>\fB.eps\fR
.fi
.PP
Note: an output file is overwritten if it already exists.
This will happen if two tunes have the same name and \fB-O =\fR
is used for EPSF output.
.PP
The actual output format is governed by sets of parameters
which can be put into \fIformat files\fR.
The format file can be selected using the \fB-F\fR option;
format files are usually searched both in the current directory
and the directory \fB/usr/share/abc2ps\fR.
Refer to the section \fBOutput formating\fR
in \fB/usr/share/doc/abc2ps/New.Features\fR for a detailed description
of the available parameters.

.SS "Interactive Mode"
If the command list contains the \fB-i\fR option, \fBabc2ps\fR 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.
.PP
Interactive mode is started with
.RS
.sp   
\fBabc2ps -i\fR
.sp
.RE
The program then prompts for input with the line
.RS
.sp
select tunes:
.sp
.RE
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 \fBJig*\fR should be used
instead of \fB'Jig*'\fR 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.
.PP
For example, a "session" could look like this:
.sp
.nf
      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
.fi
.PP
To make things easier, there are three special characters:
.sp
.nf
      ?   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.
.fi
.PP
This means that the same effect as above can be obtained in 
shorter form like this:
.sp
.nf   
      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
.fi
.PP
Note that the \fB-e\fR option is not needed in the line `* 1-10'
because it is clear that \fB1-10\fR is a selector (see above).
.PP
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 
.RS
.sp
\fBabc2ps -io\fR
.sp
.RE
all selected tunes are immediately written to the output file. 
The program usage is then very similar to that of \fBabc2mtex\fR. Of course, 
it is not possible to list the file contents (to help choose among
the titles) when using the program in this way.
.PP
In interactive mode, \fB-O\fR and \fB-E\fR 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. 
.SS "Differences to abc2mtex"
Essentially, all features described in the \fBabc2mtex\fR userguide 
should work. The are a few exceptions:
.IP
The slur denotation S was replaced by the syntax (...) 
(see below)
.IP
Key signatures HP and Hp probably aren't treated in exactly the right way.
.IP
There is no automatic beam checking.
.IP
There is no way to automatically transpose music in this version.
.SS "Some Extra Features"
For examples, see file
.BR /usr/share/doc/abc2ps/examples/sample.abc .
.TP
Codes for decorations.
Including the ones defined in the
standard abc syntax, the following decorations are interpreted:
.nf
.sp
   .   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
.sp
.fi
.TP
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 \fBsample.abc\fR). 
.TP
N-tuplets.
\fBabc2ps\fR can handle general n-tuplet cases using the syntax
.RS
.sp
\fB(p:q:r abcd\fR ...
.sp
.RE
.IP
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:
.RS
.sp
\fB(3::2\fR = \fB(3:2:2\fR;  \fB(3\fR = \fB(3:2:3\fR
.RE
.IP
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.
.TP      
Chords.
The program accepts the \fB+...+\fR 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:
.RS
.sp
\fB[ace][adf]\fR
.RE
.IP
in place of the \fB+...+\fR syntax.
The abc notation formally permits notes with different durations 
on the same stem: \fB[a/bc2]\fR 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., \fB[AA]\fR.
.TP
Slurs and Ties.
In place of the syntax \fBSabcSd\fR for a slur 
over notes abcd, this program uses the notation
.RS
.sp
\fB(abcd)\fR
.RE
.IP   
for a slur over the notes abcd. It permits cases such as
\fB(ab(cd))\fR  and  \fB((ab)cd)\fR  and  \fB(a(bc)d)\fR
and similar slurs-below-slurs. To connect three or four notes 
by ties (e.g., for a note held over several bars) use
\fB(a(b)c)\fR or, by ties, \fBa-b-c\fR.
.IP
The rule is that any note alone within brackets like \fB(b)\fR
terminates a previous slur and at the same time starts a new one.
.IP
Note that the slur syntax \fB(...)\fR does not interfere with the \fB(3abc\fR 
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: \fB(3abc ((3cde) ((3efg)\fR.
.IP
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 \fB(3abc)\fR instead of \fB(3abc\fR
for triplets.
.TP
Bars.
.br
The following symbols denote fat double bars 
at the start or end of a piece (without repeat dots):
\fB[|\fR produces a thick-thin bar, \fB|]\fR a thin-thick bar.
.IP
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,
\fB::\fR becomes \fB:|\fR together with \fB|:\fR on the next line,
\fB|:\fR becomes \fB|\fR together with \fB|:\fR on the next line,
\fB:|2\fR becomes \fB:|\fR  together with \fB[2\fR on the next line etc.
.TP
Field E.
This field can be used to set some parameters from within the file:
.nf
.sp
   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 \fIppp\fR    set local staff width to \fIppp\fR points.
.sp
.fi
For example, to output a single tune in a narrower format,
put \fBE:lw 400\fR 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.
.TP
Bass and alto clef.
The bass clef is selected by appending the word \fBbass\fR to the
key specification. e.g., \fBK:G bass\fR. Notes are then drawn so 
\fBC\fR is below the staff and \fBc\fR is in the third space from the top,
which is a downward shift by one line relative to the treble clef.
.IP
For in-line clef changes, use an in-line specification such as
\fB[K:G bass]\fR (was formerly \K:G bass\; this still supported). 
If the key itself does not change, it is enough to write
\fB[K:bass]\fR and similarily \fR[K:treble]\fB.
.IP
Use \fBalto\fR similarly for the alto (viola or C) clef.
.TP
Vocals.
Aligned lyrics under the staff are specified using a line directly
below the staff, starting with \fBw:\fR. For example:
.RS
.nf
.sp
\fBedc2 edc2 |
w: Three blind mice, three blind mice\fR
.fi
.RE
.IP
Each blank-delimited word in the \fBw:\fR line is associated with
one note, in sequence. The following special symbols are available
to modify this behaviour:
.nf
.sp
   \fB*\fR  skips one note
   \fB-\fR  splits a word into two syllables, associated with
      two notes, with `-' drawn between them
   \fB\\-\fR  adds a hyphen without splitting the word
   \fB|\fR  tabs forward to the next bar line.
   \fB~\fR  is drawn as a space, but contracts words to be
      written under one note. That is, \fBhey~ho\fR gives two
      words under one note.
   \fB_\fR  draws a thin `underscore' from the previous note
      to this one.
.fi
.IP
For more than one line of lyrics, just use several \fBw:\fR lines.
To draw a \fB-\fR without breaking the word there, escape it as \fB\\-\fR.
.IP
Note that \fB\\\\\fR 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.
.IP
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 
.RS
.sp
\fBw: 1.~~Three blind mice\fR
.RE
.IP
to put a number before "Three".
.TP
Multi-staff music.
Abc2ps handles music consisting of several voices. This is done using
\fBV:\fR lines, such as
.RS
.nf
.sp
V:2 name="Clarinet 2" short="Cl.2" clef=treble stems=down
.fi
.RE
.IP
(Here the \fB2\fR in \fBV:2\fR is an arbitrary string, so any single-word
identifier can be used instead.) Later on, you can switch to the voice
using only \fBV:2\fR. The various settings -- key, default length, etc. --
are maintained separately for each voice.
.IP
Guitar chords, first and second endings, and line breaks
are taken from the top voice only. Each voice can have its own vocals.
.IP
There are several parameters that control the arrangement of staves,
braces, brackets, long bar lines etc. Refer to 
\fB/usr/doc/abc2ps/changelog\fR for more information.
.IP
Individual voices can be selected from a multi-voice manuscript
using the \fB-V\fR option. For example, \fB-V 1-2,4\fR 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.

.TP
Writing text between the music.
This can be done using pseudocomments in three ways. First:
.RS
.sp
\fB%%text This is a line of text.\fR
.RE
.IP
writes one line into the output. Second, 
.RS
.sp
\fB%%center This is another line of text.\fR
.RE
.IP
again writes one line, but centers it. Finally,
.RS
.sp
.nf
\fB%%begintext
First line of text
Second line
And yet another line.
%%endtext\fR
.RE
.fi
.IP
will write a block of several lines. To avoid conflict with other
programs, the text lines themselves can also be prefaced with \fB%%\fR.
.IP
See \fB/usr/share/doc/abc2ps/New.Features\fR for more information.
.TP
Bar numbers and labels.
Use the \fB-k\fR option to enable bar numbering. For example,
\fB-k 1\fR will number every bar, \fB-k 5\fR will number every fifth bar,
etc.
The option \fB-k 0\fR will number the first bar in every staff.
Alternatively, use the \fB%%barnumbers\fR pseudo-comment.
.IP
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.
.IP
Within a single tune, bar numbers are counted across part boundaries.
However, if a \fBT:\fR title appears inside a tune, the bar number
is reset to 1. You can use an empty \fBT:\fR line to reset the bar number
without actually writing a title.
.IP
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.,
.RS
.sp
| abcd "A"| ABCD |
.RE
.IP
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, \fB[|]\fR, was introduced to denote
an `invisible' bar line.
.IP
Fonts for bar numbers and labels can be set up using the
\fB%%barnumberfont\fR and \fB%%barlabelfont\fR pseudo-comments.
.TP
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
\fBbox\fR to the font specification, e.g.,
.RS
.sp
%%barnumberfont Times-Italic 11 box
.RE
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 \fB*\fR may be used, as in
.RS
.sp
%%titlefont * * box
.RE

.SH OPTIONS
This is a brief summary of the options supported by \fBabc2ps\fR.
See the documentation in \fB/usr/share/doc/abc2ps\fR
for more detailed information.
.SS "Modes of Operation"
.TP
.B \-o
Write output for selected tunes.
.TP
.B \-E
Produce EPSF output, one tune per file.
.TP
.BI \-O " filename"
Set output file name to \fIfilename\fR (default is \fBOut.ps\fR).
If \fIfilename\fR is \fB=\fR, manufacture an output file name from
input file name or tune title (in EPSF mode).
.TP
.B \-i
Run interactively.
.TP
.BI \-v " n"
Set the verbosity for output to the screen to \fIn\fR.
0 gives very little output, 1 to 3 show successively more information.
Verbosities greater than 10 are for debugging.
.TP
.B \-h
Quick help, equivalent to `\fBabc2ps\fR' without any arguments.
This also shows the default settings for some parameters.
.TP
.B \-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 \fB\-h\fR
option.

.SS "Selection"
.TP
.B \-e
The following arguments are selectors.
.TP
.B \-f
The following arguments are file names.
.TP
.B \-T
Search the ABC Title field (default).
.TP
.B \-C
Search the ABC Composer field.
.TP
.B \-R
Search the ABC Rhythm field.
.TP
.B \-S
Search the ABC Source field.
.TP
.BI \-V " str"
Select voices, e.g., -fB\-V 1,4-5\fR.

.SS "Formatting"
These options change the output appearance:
.TP
.B \-H
Show the settings of all formatting parameters.
.TP
.B \-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 \fBpretty\fR.
.TP
.B \-P
Similar to \fB-p\fR, but uses a parameter set called \fBpretty2\fR.
.TP
.BI \-s " xxx"
Scale the music output by factor \fIxxx\fR.
.TP
.BI \-w " www"
Set the width of the staff to \fIwww\fR points, inches or centimetres.
.TP
.BI \-m " mmm"
Set the left margin to \fImmm\fR points, inches or centimetres.
.TP
.BI \-d " xxx"
Set the staff separation to \fIxxx\fR points, inches or centimetres.
.TP
.B \-x
Include cross-reference numbers (ABC X header) in output.
.TP
.BI \-k " n"
Number every \fIn\fB bars; if \fIn\fR is 0, number every first bar of a staff.
.TP
.B \-n
Include historical notes and other stuff at the bottom of each tune.
.TP
.B \-N
Output page numbers.
.TP
.B \-1
Write every tune on a separate page.
.TP
.B \-l
Operate in landscape mode.
.TP
.B \-g shrink|space|stretch|fill
Set the `glue mode'.
The default mode is \fBfill\fR, which fills the staff.
.TP
.BI \-F " format"
Read format from file \fIformat\fR.
.TP
.BI \-D " directory"
Look for format files in directory \fIdirectory\fR.
.TP
.BI \-X " x"
Set strictness for note spacing, 0 < x < 1.
.SS "Transposing"
.TP
.BI \-T " n"
Transpose by \fIn\fR semitones (use \fI_n\fR for negative number).
.TP
.BI \-T " note"
Transpose root up/down to note \fInote\fR.
.SS "Line Breaks"
.TP
.BI \-a " x"
Set the maximal allowed shrinkage to \fIx\fR, where\fIx\fR is between
0.0 and 1.0.
.TP
.B \-b
Force a staff break at the end of each line, even if the line has the
continuation symbol \\ at the end.
.TP
.B \-c
Append the continuation symbol to all music lines,
which amounts to automatic line breaking.
.TP
.BI \-B " n"
Format with \fIn\fR bars on every staff.
.SS "Resource Allocation"
.TP
.BI \-maxs " n"
Set maximal number of symbols (default 800).
.TP
.BI \-maxv " v"
Set maximal number of voices (default 4).

.SH FILES
.TP
\fB/usr/share/abc2ps/*.fmt\fR
Various sample format files.
.TP
\fB/usr/share/doc/abc2ps/examples/*\fR
Various example ABC files.

.SH "SEE ALSO"
.TP
\fB/usr/share/doc/abc2ps/ReadMe.abc2ps\fR
A more detailed version of the information contained in this manual
page.
.TP
\fB/usr/share/doc/abc2ps/New.Features\fR
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.
.TP
\fB/usr/share/doc/abc2ps/changelog\fR
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.
.TP
\fB/usr/share/doc/abc2ps/layout.txt\fR
A description of the typesetting algorithm used in \fBabc2ps\fR.

.SH AUTHOR
This manual page was written by Anselm Lingnau <lingnau@debian.org>,
for the Debian GNU/Linux system.