Table of Contents

abc2ps Manual

NAME

       abc2ps - Translate ABC format to PostScript

SYNOPSIS

       abc2ps [options] files ...

DESCRIPTION

       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

OPTIONS

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

FILES

       /usr/share/abc2ps/*.fmt
              Various sample format files.

       /usr/share/doc/abc2ps/examples/*
              Various example ABC files.

SEE ALSO

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

AUTHOR

       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.