Provided by: abcm2ps_7.8.9-1build1_amd64 bug

NAME

       abcm2ps — translate ABC music notation to PostScript

SYNOPSIS

       abcm2ps [options]  [abc-file [file-options]]  [...]

       abcm2ps [-h]

DESCRIPTION

       abcm2ps 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 `Outnnn.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.

       -jb[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, `Outnnn.eps' for EPS output (see -E), or `Outnnn.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 `Outnnn.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.

       -Tn[voice], +Tn[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 `Outnnn.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  (link  to URL
       http://moinejf.free.fr/abcm2ps-doc/index.html) .

ADDITIONAL FEATURES

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

       [clef=]type[line][+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 Anselm Lingnau <lingnau@debian.org> 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.

                                                                                       ABCM2PS(1)