&dhucpackage; &dhsection;

&dhpackage;

translate ABC music notation to PostScript

          &dhpackage;

          options
          abc-file file-options ...

          &dhpackage;
          -h

## DESCRIPTION

`&dhpackage;` translates tunes written in the ABC music notation format to customary sheet music scores in PostScript. It is based on `abc2ps` 1.2.5 and was developed mainly to print Baroque organ scores that have independent voices played on multiple keyboards and a pedal-board. The program has since been extended to support various other notation conventions in use for sheet music.

Options given immediately after the command name apply to the run as a whole; options given after an ABC file name apply to that file.

Formatting parameters can also be set in `format files' and in the ABC files themselves.

## OPTIONS

`-0`

- Split tunes across page breaks if necessary.

`+0`

- Start a new page if a tune doesn't fit on the current one (default).

`-1`

- Output one tune per page.

`+1`

- Output multiple tunes per page (default).

`-a `a``

- Maximal horizontal compression when staff breaks are chosen automatically. Must be between 0 and 1. This corresponds to the ``%%maxshrink` `a`' formatting parameter (default: 0.65)

`-A`

- This option inserts reference elements in the PostScript or SVG output.

`-B `b``

- Try to typeset `b` bars on each staff line. This corresponds to the ``%%barsperstaff` `b`' formatting parameter.

`+B`

- Don't try to typeset a fixed number of bars on each staff line (default). This corresponds to the ``%%barsperstaff` `0`' formatting parameter.

`-b `b``

- Start measure numbering at `b`.

`-c`

- The continuation symbol is implicitly appended to each music line. This amounts to automatic line breaking.

`+c`

- Automatic line breaking is turned off (default).

`-D `directory``

- Search format files in `directory`.

`-d `length``

- Set the vertical interstaff space to `length`. This corresponds to the ``%%staffsep` `length`' formatting parameter (default: 46pt)

`-E`

- Output is generated in EPS format, one file per page.

`-e `list``

- Select which tunes from an ABC file to print. `list` is either a comma-separated list of tune numbers (as per the `X:' header), or a regular expression which will be matched against the tune headers as a whole. The `-e` option must occur after an ABC file name and applies to that file.

  Ranges of tune numbers may be specified like `t1`-`t2`; `t2` may be omitted which means `all remaining tunes until the end of file'. Note that filtering may cause problems, e.g., with global (non-tune) definitions in the ABC file.

`-F `file``

- Read the format file `file`.fmt.

`+F`

- Do not read the default format file.

`-f`

- Enable flat beams (useful for bagpipe tunes). This corresponds to the ``%%flatbeams` `1`' formatting parameter.

`-G`

- Omit slurs on grace notes. This corresponds to the ``%%graceslurs` `0`' formatting parameter.

`+G`

- Draw slurs on grace notes (default). This corresponds to the ``%%graceslurs` `1`' formatting parameter.

`-g`

- Produce SVG output instead of EPS. In this mode, each tune goes to a separate file whose name is `Out`nnn`.svg' (see option `-O`).

  If output is directed to stdout (``-O-`'), all SVG images are output without an XML header.

`-H`

- Display the current values of the formatting parameters.

`-h`

- Display program usage hints and quit.

`-I `length``

- Indent the first line of the tune by `length` (default: 0). This corresponds to the ``%%indent` `length`' formatting parameter.

`-i`, `+i`

- Insert a red circle around errors in the PostScript output.

`-j`b``b``

- Output a measure number every `b` measures. If `b` is 0, the measure number appears at the left of each staff. The trailing `b` causes a box to be drawn around each measure number (default: no measure numbering). This corresponds to the `%%measurenb` formatting parameter.

`+j`

- Don't output measure numbers. This corresponds to the ``%%measurenb` `-1`' formatting parameter.

`-k`

- Sets the size of the PostScript output buffer in kibibytes. Specifying a higher value permits the generation of big tunes with `-E` or `-g` (default: 64).

`-l`

- Generate landscape output. This corresponds to the ``%%landscape` `1`' formatting parameter.

`+l`

- Generate portrait output (default). This corresponds to the ``%%landscape` `0`' formatting parameter.

`-M`

- Suppress lyrics. See the `%%writefields` formatting parameter.

`+M`

- Include lyrics (default). See the `%%writefields` formatting parameter.

`-m `length``

- Set the left margin to `length` (default: 1.8cm). This corresponds to the ``%%leftmargin` `length`' formatting parameter.

`-N`mode``

- Number pages according to the `mode`:

  `0`

- no page numbers

`1`

- page numbers at top left of page

`2`

- page numbers at top right of page

`3`

- page numbers at top left of even-numbered pages, top right of odd-numbered pages

`4`

- page numbers at top right of even-numbered pages, top left of odd-numbered pages

For compatibility, `-N` is equivalent to `-N2` (default: `-N0`).

If a header is defined using ``%%header`', this option is ignored.

`+N`

- Equivalent to `-N0` (no page numbering).

`-n`

- Include notes and history from ABC tune `N:' fields. See the `%%writefields` formatting parameter.

`+n`

- Omit notes and history from ABC tune `N:' fields (default). See the `%%writefields` formatting parameter.

`-O `name``

- Define the output file name. By default, the output file name is `Out.ps' for PostScript output, `Out`nnn`.eps' for EPS output (see `-E`), or `Out`nnn`.svg' for SVG output (see `-g`), where `nnn` is a sequence number. If this option is given, the output name will be `name` (for PostScript output), or `name` will replace `Out' in the output file name (for EPS and SVG output), respectively. If `name` is `=', the output file name will be the name of the ABC source file with the extension `.ps', `.eps', or `.svg'. If `name` is `-', the output is written to stdout.

`+O`

- Revert to the default output file name (`Out.ps' or `Out`nnn`.eps')

`-q`

- Quiet mode, only error messages will be shown.

`-S`

- Secure mode; disables file inclusion via `%%format` and `%%EPS` and disallows direct PostScript injection via `%%beginps` and `%%postscript`.

`-s `scale``

- Set the page scale factor to `scale`. Note that the header and footer are not scaled (default: 0.75). This corresponds to the ``%%scale` `scale`' formatting parameter.

`-T`n``voice``, `+T`n``voice``

- Activate (or deactivate) tabulature drawing. `n` is the tabulature number as defined in `%%tabulature` (up to a maximum of 8 tabulatures), and `voice` is the voice name, full name or subname as found in `V:`. When this is absent, the option applies to all voices. Up to 4 such options may be given. See also `format.txt`.

`-V`

- Output version number and quit.

`-v`

- Produce SVG output instead of simple PS. In this mode, each page goes to a separate output file called `Out`nnn`.svg' (see option `-O`).

`-w `length``

- Adjust the right margin such that the staff width is `length` (default: none). This corresponds to the ``%%staffwidth` `length`' formatting parameter.

`-X`

- Produce XML+SVG output instead of simple PS. The default file name is `Out.xhtml' (see option `-O').

`-x`

- Include the `X:' tune number in the title. See the `%%writefields` formatting parameter.

`+x`

- Do not include the `X:' tune number in the title (default). See the `%%writefields` formatting parameter.

## FORMATTING PARAMETERS

Abcm2ps supports a vast number of formatting parameters that govern the appearance of the typeset output. Please refer to the `/usr/share/doc/abcm2ps/format.txt` file or the formatting parameter documentation on the official abcm2ps web site.

## ADDITIONAL FEATURES

### Clefs

Clefs can be given in `K:` and `V:` headers. The full syntax is

    clef=typeline+8|-8 middle=pitch

The ``clef=`' can be omitted when the `type` is a clef name.

`type` denotes the clef type. It may be:

A note pitch (`G`, `C`, or `F`)

- The pitch indicates which clef is meant: `G` is the treble clef, `C` the alto clef and `F` the bass clef. It also gives the name of the note that appears on the clef's line.

A clef name

- The available clef names are `treble` (clef gives the pitch for `G`), `alto` or `tenor` (`C`), and `bass` (`F`)

`perc` or `P`

- In percussion mode, accidentals change the glyphs used for note heads. By default, sharp notes are drawn as `x' and flat notes as circled `x'. This may be changed by redefining the PostScript functions `pshhd` and `pflhd`.

`none`

- No clef will be displayed.

The `line` gives the number of the line within the staff that the base clef will be written on. The default values are 2 for the treble clef, 3 for the alto clef, and 4 for the tenor and bass clefs.

The `+8` and `-8` options draw an 8 above or below the staff, respectively. ``middle=``pitch`' (or ``m=``pitch`', for short) is an alternative way of defining the line number of the clef: The `pitch` indicates what note will be displayed on the middle line of the staff.

When no clef is specified, clef changes between `bass` and `treble` will be inserted automatically.

### Multi-voice typesetting

Multiple voices may be defined within the header or the tune using

    V:name definition ...

where `name` is a word consisting of letters and digits only (like `violin1`). In the tune body, the following notes refer to this voice until another `V:` is encountered. A `definition` can be one of:

`clef=`...

- See above

`name=``name` or `nm=``name`

- The `name` will be displayed at the beginning of the first staff. It can contain `\\n` sequences which will force line breaks. If it contains whitespace it must be double-quoted.

`subname=``name` or `snm=``name`

- The `name` will be displayed at the beginning of all staves except for the first. It can contain `\\n` sequences which will force line breaks. If it contains whitespace it must be double-quoted.

`merge`

- The voice goes on the same staff as the previous voice.

`up` or `down`

- Forces the direction of the stems for the voice.

`dyn=up` or `dyn=down` or `dyn=auto`

- Forces positioning of dynamic marks (above or below the staff) or reverts to automatic positioning (the default)

`gstem=up` or `gstem=down` or `gstem=auto`

- Forces the direction of the stems of grace notes (always up or always down) or reverts to automatic positioning (the default)

`stem=auto`

- Reverts to automatic positioning of note stems (up or down) (the default)

`lyrics=up` or `lyrics=down` or `lyrics=auto`

- Places lyrics above or below the staff or reverts to automatic positioning (the default)

`gchord=up` or `gchord=down`

- Places guitar chords above (the default) or below the staff.

`stafflines=``value`

- Sets the number of lines on the staff in question. (default: 5)

`staffscale=``value`

- Sets the scale of the associated staff up to 3. (default: 1)

All other definitions are ignored.

By default, each voice goes on its own staff. The `%%staves `definition`' pseudo-comment can be used to control staff assignment. The `definition` consists of voice names (from `V:`) and pairs of parentheses, braces or brackets.

- When a voice name is not within a pair of special characters, it goes on a separate staff.

- For voice names enclosed in brackets, a bracket is displayed at the beginning of each line that joins the staves of the voices in question.

- For voice names enclosed in braces, all the voices go on two staves (keyboard score). There can be at most four voices between a single pair of braces.

- For voice names enclosed in parentheses, all the voices appear on a single staff.

The ``|`' character prevents measure bars from being drawn between two staves.

If `%%staves' occurs in a tune, all the voices not mentioned will not be output at all.

### The `%%score` directive

The `%%score` directive occurs in the ABC draft 2.0 standard and is similar to the `%%staves` specification described earlier. The rules are:

- Voice names within parentheses form a "voice group" and go on a single staff. A voice name that is not within parentheses forms its own voice group and goes on a staff by itself.

- Voice groups within braces form a "voice block" and are preceded by a big brace in the output. This is especially useful for keyboard music.

- Voice groups or voice blocks within brackets form a "voice block" and will be preceded by a big bracket in the output.

- If a ``|`' character occurs between two voice groups or voice blocks, the bar lines in all of the associated staves will be continuous.

- A single voice surrounded by two voice groups can be preceded by an asterisk to make it into a `floating' voice. This means that, for each note of the voice, a separate decision is made whether it is printed on the preceding or the following voice group's staff.

- Voices that appear in the tune body but not in the `%%score` directive will not be output at all. If there is no `%%score` directive, each voice will be output on its own staff.

- A `%%score` directive inside a tune resets the mechanism so voices can be removed or added.

### Voice overlay

You can add notes to a staff without introducing a complete extra voice by using the ampersand (`&`). A single measure can be split into two voices like

    |F2A2Bc&F2c2bc|

The `(&...&...&)` construction allows splitting multiple measures:

    |!f!(&GG<G|GG F=E| E2  E(_D/E)|_D D  C      D |C4- |C
         &DC<C|CC_D C|=B,2_B,B,   |_A,A,(G,/A,/)B,|F,4-|F,)zzD=E|

A double ampersand (`&&`) will allow overlaying more than two lines of music but this feature has not yet been implemented.

### Lyrics

Aligned lyrics under a staff are written as a `w:` line directly below the staff line. For example:

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

Each word in the `w:` line (delimited by blanks) is associated with one note, in sequence. The following special symbols modify this behaviour:

`*`

- Skips one note.

`-`

- Splits a word into two syllables which are associated with two adjacent notes. A `-' is drawn between them.

`|`

- Advances to the next bar line

`~`

- Is output as a space, but unites two words so they appear under a single note.

`_`

- Draws a thin underscore from the previous note to the next.

To include more than one line of lyrics, use multiple `w:` lines. To include hyphens without splitting a word over multiple notes, use `\-`.

If a word starts with a digit, this is interpreted as a stanza number and outdented a bit to the left.

### Slurs and ties

The direction of slurs and ties may be controlled using the `(,` and `('`, and `-,` and `-'`, constructions.

### Microtone pitches

Microtone pitches are indicated by a fraction after an accidental, as in `^3/4c`. When omitted, the numerator defaultes to 1 and the denominator to 2 (so `^/c` is the same as `^1/2c`). The numerator and denominator values may not exceed 256. There is built-in support for quarter-tone accidentals (1/2 and 3/2 sharps and flats); for other values, rendering functions must be defined using `%%postscript` (see `features.txt`).

### EPS inclusion

EPS files may be included inside tunes using the pseudo-comment `%%EPS `file`'.

## SEE ALSO

The original documentation can be found in files `features.txt`, `format.txt`, and `options.txt`, which on a Debian system are in `/usr/share/doc/abcm2ps`.

## AUTHOR

This manual page was written by &dhusername; <&dhemail;> for the &debian; system (but may be used by others). Permission is granted to copy, distribute and/or modify this document as long as its origin is not misrepresented.