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

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

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.

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.

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.

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

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

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

-T n

Transpose by n semitones (use _n for negative number).

-T note

Transpose root up/down to note note.

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

-maxs n

Set maximal number of symbols (default 800).

-maxv v

Set maximal number of voices (default 4).