1 Process this file with rst2man from python‐docutils
2 to generate a nroff manual page
3======= abcm2ps =======
5‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐ translate ABC
7music notation to PostScript or SVG
8‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐
9SYNOPSIS ========
11 ‘‘abcm2ps‘‘ [global_options] ABC_file [file_options] ...
13DESCRIPTION ===========
15‘‘abcm2ps‘‘ translates tunes written in the ABC music notation
17format to customary sheet music scores in PostScript or SVG. It
18is based on ‘‘abc2ps‘‘ 1.2.5 and was developed mainly to print
19Baroque organ scores that have independent voices played on mul‐
20tiple keyboards and a pedal‐board. The program has since been ex‐
21tended to support various other notation conventions in use for
22sheet music.
23Options given immediately after the command name apply to the run
25as a whole; options given after an ABC file name apply to that
26file.
27Formatting parameters can also be set in "format files" and in
29the ABC files themselves.
30OPTIONS =======
32The list of the command line options may be known running::
34 abcm2ps ‐h
36The options may be grouped when they have no argument, but the
38last one (ex: ‘‘‐lnGI20‘‘).
39The options may be disabled when starting with ’+’ or ending with
41’‐’ (ex: ‘‘+MT1‘‘ is the same as ‘‘‐MT1‐‘‘).
42The general output format is the last found in the command line.
44It may be:
45‐E for Encapsulated PostScript, one file per tune
47‐g for SVG, one file per tune
49‐v for SVG, one file per page
51‐X for XHTML+SVG
53‐z for (X)HTML+SVG with (X)HTML+ABC input
55(see below for more information)
57List of the options ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐
59−
61 Read the abc file from stdin.
62−‐<format> <value>
64 Set the <format> parameter to <value>.
65 This has the same effect as a format parameter
67 directly in the source file.
68‐a <float>
70 Maximal horizontal compression when staff breaks are
71 chosen automatically. Must be a float between 0 and 1.
72 This correspond to the ‘‘%%maxshrink‘‘
74 formatting parameter (default: 0.65).
75‐A
77 This option inserts reference elements in the PostScript
78 or SVG output.
79‐B <int>, +B
81 Try to typeset <int> bars on each staff line.
82 This corresponds to the ‘‘%%barsperstaff‘‘ formatting parame‐
84ter.
85‐b <int>
87 Start measure numbering at <int>.
88 This corresponds to the ‘‘%%measurefirst‘‘ formatting parame‐
90ter.
91‐c, +c
93 The continuation symbol is implicitly appended to each
94 music line. This amounts to automatic line breaking.
95 This corresponds to the ‘‘%%continueall‘‘ formatting parame‐
97ter.
98‐D <dir>
100 Search the format files in the directory <dir>.
101‐d <unit>
103 Set the vertical interstaff space to <unit>.
104 This corresponds to the ‘‘%%staffsep‘‘ formatting parameter
106 (default: 46pt).
107‐E
109 Produce EPS output instead of simple PS.
110 In this mode, each tune goes to a different file which
112 name is "<name>nnn.eps" or "<title>.eps" (see option ’‐O’)
113 ‐ ’nnn’ is a sequence number incremented at each tune
115 Output to stdout is forbidden.
117 EPS files are normally embedded into Postscript documents,
119 but they may be a way to generate graphical images. For
120 example, using GhostScript::
121 abcm2ps voices ‐Ee7
123 gs ‐sDEVICE=pngmono ‐r80 ‐g590x174 ‐dBATCH
124‐dNOPAUSE ‐sOutputFile=quitolis.png Out001.eps
125 e values for ‐g are the values of the bounding box in
127 the .eps, multiplied by (80 / 72), where 80 is the value
128 for ‐r, and 72 is the default resolution)
129‐e [ <tune index list> ] [ <regular expression> ]
131 Select which tunes from an ABC file to print.
132 <tune index list> is either a comma‐separated list of tune
134 numbers (as per the ‘‘X:‘‘ header), or a regular expression
135 which will be matched against the tune headers as a whole.
136 The ‘‘‐e‘‘ option must occur after an ABC file
137 name and applies to that file.
138 Ranges of tune numbers may be specified like ‘‘<t1>‐<t2>‘‘;
140 <t2> may be omitted which means
141 "all remaining tunes until the end of file". Note that
142 filtering may cause problems, e.g., with global (non‐tune)
143 definitions in the ABC file.
144 This corresponds to the ‘‘%%select‘‘ formatting parameter.
146‐F <file>, +F
148 Read the format (or PostScript) file <file>.
149 When omitted, the default type of a format file is ’.fmt’.
151 In the form ’+F’, the default format file (’default.fmt’) is
153not
154 read.
155‐f
157 Enable flat beams (useful for bagpipe tunes).
158 This corresponds to the ‘‘%%flatbeams‘‘ formatting parameter.
160‐G, +G
162 Omit slurs on grace notes.
163 This corresponds to the ‘‘%%graceslurs‘‘ formatting parameter.
165‐g
167 Produce SVG output instead of EPS.
168 In this mode each tune goes to a different file which name
170 is ’Outnnn.svg’ (see option ’‐O’).
171 If the output is stdout (option ’‐O‐’), all the SVG images
173 are output without XML header.
174‐H
176 Display the current format values.
177‐h
179 Quick help, equivalent to "abcm2ps" without any arguments.
180 This also shows the default settings for some parameters.
182‐I <unit>
184 Indent the first line of the tune by <unit> (default: 0).
185 This corresponds to the ‘‘%%indent‘‘ formatting parameter.
187‐i, +i
189 Insert a red cercle around the errors in the PostScript out‐
190put.
191‐j <int>[b], +j
193 Output a measure number every <int> measures.
194 If <int> is 0, the measure number appears at the left of each
196staff.
197 The trailing ‘‘b‘‘ causes a box to be drawn
198 around each measure number (default: no measure numbering).
199 This corresponds to the ‘‘%%measurenb‘‘ formatting parameter.
201‐k <int>
203 Set the size of the PostScript output buffer in Kibytes.
204 Setting this value to a higher value permits the
206 generation of big tunes with ‐E or ‐g. The default value is
20764.
208‐l, +l
210 Generate landscape output.
211 This corresponds to the ‘‘%%landscape‘‘ formatting parameter.
213‐M, +M
215 Suppress lyrics.
216 See the ‘‘%%writefields w‘‘ formatting parameter.
218‐m <unit>
220 Set the left margin to <unit> (default: 1.8cm).
221 This corresponds to the ‘‘%%leftmargin‘‘ formatting parameter.
223‐N <int>, +N
225 Number the pages.
226 <int> indicates the mode:
228 0
230 no page numbers
231 1
232 at top left
233 2
234 at top right
235 3
236 at top left on even pages, top right on odd pages
237 4
238 at top right on even pages, top left on odd pages
239 For compatibility with previous versions, ’+N’ is the same as
241 ’‐N0’, and ’‐N’ is the same as ’‐N2’.
242 If a header is defined ("%%header"), this option is ignored.
244‐n, +n
246 Include notes and history from ABC tune ‘‘N:‘‘ fields.
247 See the ‘‘%%writehistory N‘‘ formatting parameter.
249‐O [ <directory> ] [ <name> ], +O
251 Define the output file directory and/or name.
252 The directory must end with the directory separator
254 (’/’ for unix/windows, ’\’ for mac).
255 By default, the output file goes to the current directory
257 with the name:
258 ’Out.ps’ for PS,
260 ’Outnnn.eps’ for EPS (see option ’‐E’),
262 ’Outnnn.svg’ for SVG (see options ’‐g’ and ’‐v’) or
264 ’Out.xhtml’ for XHTML+SVG (see options ’‐X’ and ’‐z’).
266 ’nnn’ is a sequence number.
268 When <name> is present, it is the name of the file, or it
270 replaces "Out" in the file name.
271 If <name> is ’=’, it is replaced by the name of the ABC
273 source file (not for ’‐z’).
274 If <name> is ’‐’, the result is output to stdout (not for
276EPS).
277 ’+O’ resets the output file directory and name to their de‐
278faults.
279‐p
281 Bagpipe format.
282 When present, format output for bagpipe regardless of key.
284‐q
286 Quiet mode.
287 When present, only the errors are shown.
289‐s <float>
291 Set the page scale factor to <float>. Note that the header
292 and footer are not scaled (default: 0.75).
293 This corresponds to the ‘‘%%scale‘‘ formatting parameter.
295‐S
297 Secure mode.
298 When present, file inclusion (%%format and %%EPS) and Post‐
300Script
301 injection (%%beginps and %%postscript) are disabled.
302‐T <int> [ <voice> ], +T [ <int> [<voice> ] ]
304 Activate or deactivate tablature drawing.
305 ‐ <int> is the tablature number as defined in ‘‘%%tablature‘‘.
307 There may be only 8 different tablatures.
308 ‐ <voice> is the voice name, full name or subname as found in
310V:.
311 When absent, apply to all voices.
312 Up to 4 such commands may be defined.
314 Ex: ’‐T1flute +T2’
316‐V
318 Show the version number.
319‐v
321 Produce SVG output instead of simple PS.
322 In this mode each page goes to a different file which name
324 is ’Outnnn.svg’ (see option ’‐O’).
325‐w <unit>
327 Adjust the right margin such that the staff width
328 is <unit> (default: none).
329 This corresponds to the ‘‘%%staffwidth‘‘ formatting parameter.
331‐X
333 Produce XML+SVG output instead of simple PS.
334 The default file name is ’Out.xhtml’ (see option ’‐O’).
336‐x, +x
338 Include the ‘‘X:‘‘ tune number in the title.
339 This corresponds to the ‘‘%%writefields‘‘ formatting parame‐
341ter.
342‐z
344 Produce SVG images from ABC embedded in markup language files
345 (HTML, XHTML..).
346 The source file is copied to the output file and the ABC se‐
348quences
349 are converted to SVG images.
350 The ABC sequences start by either ‘‘%abc..‘‘ or ‘‘X:..‘‘
351 and stop on the first markup tag (‘‘<..‘‘).
352 The generation creates one image per block, i.e. a music line
354 or a text block. For a same rendering as the other SVG genera‐
355tion
356 (‐g, ‐v or ‐X), don’t forget to set the line space to null,
357for
358 example enclosing the ABC sequences by::
359 <div style="line‐height:0"> .. </div>
361 There can be only one output file.
363 Note that the default output file is ’Out.xhtml’, so, don’t
365 forget to change the file type if you generate HTML (.html)
366 or XML (.xml) files.
367 See "sample8.html" for a source example.
369‐0, +0
371 Split tunes across page breaks if necessary.
372 This corresponds to the ‘‘%%splittune‘‘ formatting parameter.
374‐1, +1
376 Output one tune per page.
377 This corresponds to the ‘‘%%oneperpage‘‘ formatting parameter.
379ADDITIONAL FEATURES ===================
381Clefs
383 Clefs can be given in ‘‘K:‘‘ and ‘‘V:‘‘ headers.
384 The full syntax is::
385 clef=<type><line>[+8|‐8]
387 "clef=" can be omitted when the <type> is a clef name.
389 <type> denotes the clef type. It may be:
391 ‐ A note pitch (‘‘G‘‘, ‘‘C‘‘, or ‘‘F‘‘)
393 The pitch indicates which clef is meant:
395 ‘‘G‘‘ is the treble clef,
396 ‘‘C‘‘ the alto clef and
397 ‘‘F‘‘ the bass clef.
398 It also gives the name of the note that appears
399 on the clef’s line.
400 ‐ A clef name
402 The available clef names are
404 ‘‘treble‘‘ (clef gives the pitch for ‘‘G‘‘),
405 ‘‘alto‘‘ or ‘‘tenor‘‘ (‘‘C‘‘), and
406 ‘‘bass‘‘ (‘‘F‘‘).
407 ‐ ‘‘perc‘‘ or ‘‘P‘‘
409 In percussion mode, accidentals change the glyphs used for
411 note heads. By default, sharp notes are drawn as "x" and
412 flat notes as circled "x".
413 This may be changed by redefining the PostScript functions
414 ‘‘pshhd‘‘ and ‘‘pflhd‘‘.
415 ‐ ‘‘none‘‘
417 No clef will be displayed.
419 The <line> gives the number of
421 the line within the staff that the base clef will be written
422 on. The default values are 2 for the treble clef, 3 for the
423 alto clef, and 4 for the tenor and bass clefs.
424 The "+8" and "‐8"
426 options draw an 8 above or below the staff, respectively.
427 When no clef is specified, clef changes
429 between "bass"
430 and "treble" will be inserted
431 automatically.
432Multi‐voice typesetting
434 Multiple voices may be defined within the header or the
435 tune using::
436 V:<name> <definition> ...
438 where <name> is a word consisting of letters and digits only
440 (like "violin1"). In the tune body, the
441 following notes refer to this voice until
442 another "V:" is encountered.
443 A <definition> can be one of:
445 * "clef="...
447 See above
449 * "name="<name> or "nm="<name>
451 The <name> will be
453 displayed at the beginning of the first staff. It can
454 contain "\n" sequences
455 which will force line breaks. If it contains
456 whitespace it must be double‐quoted.
457 * "subname="<name> or "snm="<name>
459 The <name> will be displayed at the beginning of all staves
461 except for the first. It can
462 contain "\n" sequences
463 which will force line breaks. If it contains
464 whitespace it must be double‐quoted.
465 * "merge"
467 The voice goes on the same staff as the previous voice.
469 * "up" or "down"
471 Forces the direction of the stems for the voice.
473 * "dyn=up" or "dyn=down" or "dyn=auto"
475 Forces positioning of dynamic marks (above or
477 below the staff) or reverts to automatic positioning
478 (the default).
479 * "gstem=up" or "gstem=down" or "gstem=auto"
481 Forces the direction of the stems of grace
483 notes (always up or always down) or reverts to
484 automatic positioning (the default).
485 * "stem=auto"
487 Reverts to automatic positioning of note stems
489 (up or down) (the default).
490 * "lyrics=up" or "lyrics=down" or "lyrics=auto"
492 Places lyrics above or below the staff or
494 reverts to automatic positioning (the default)
495 * "gchord=up" or "gchord=down"
497 Places guitar chords above (the default) or below the
499staff.
500 * "stafflines="<value>
502 Sets the number of lines on the staff in question. (de‐
504fault: 5)
505 * "staffscale="<value>
507 Sets the scale of the associated staff up to 3. (default:
5091)
510 All other definitions are ignored.
512Definition of the staff system
514 By default, each voice goes on its own
515 staff. The ‘‘%%staves <definition>‘‘
516 pseudo‐comment can be used to control staff
517 assignment. The <definition>
518 consists of voice names (from ‘‘V:‘‘) and pairs of
519 parentheses, braces or brackets.
520 ‐ When a voice name is not within a pair of
522 special characters, it goes on a separate staff.
523 ‐ For voice names enclosed in brackets, a bracket
525 is displayed at the beginning of each line that joins
526 the staves of the voices in question.
527 ‐ For voice names enclosed in braces, all the
529 voices go on two staves (keyboard score). There can be
530 at most four voices between a single pair of braces.
531 ‐ For voice names enclosed in parentheses, all the
533 voices appear on a single staff.
534 The ‘‘|‘‘ character prevents measure bars from
536 being drawn between two staves.
537 If ‘‘%%staves‘‘ occurs in a tune, all the
538 voices not mentioned will not be output at all.
539 The ‘‘%%score‘‘ directive occurs in the ABC
541 draft 2.0 standard and is similar to
542 the ‘‘%%staves‘‘ specification described
543 above. The rules are:
544 ‐ Voice names within parentheses form a "voice
546 group" and go on a single staff. A voice name that is
547 not within parentheses forms its own voice group and
548 goes on a staff by itself.
549 ‐ Voice groups within braces form a "voice block"
551 and are preceded by a big brace in the output. This is
552 especially useful for keyboard music.
553 ‐ Voice groups or voice blocks within brackets
555 form a "voice block" and will be preceded by a big
556 bracket in the output.
557 ‐ If a ‘‘|‘‘ character occurs between two
559 voice groups or voice blocks, the bar lines in all of
560 the associated staves will be continuous.
561 ‐ A single voice surrounded by two voice groups
563 can be preceded by an asterisk to make it into a
564 "floating" voice. This means that, for each note of the
565 voice, a separate decision is made whether it is printed
566 on the preceding or the following voice group’s staff.
567 ‐ Voices that appear in the tune body but not in
569 the ‘‘%%score‘‘ directive will not be output at
570 all. If there is no ‘‘%%score‘‘ directive, each
571 voice will be output on its own staff.
572 ‐ A ‘‘%%score‘‘ directive inside a tune
574 resets the mechanism so voices can be removed or added.
575Voice overlay
577 You can add notes to a staff without introducing a
578 complete extra voice by using the ampersand
579 (‘‘&‘‘). A single measure can be split into two voices like::
580 |F2A2Bc&F2c2bc|
582 The ‘‘(&...&...&)‘‘ construction allows splitting multiple
584 measures::
585 |!f!(&GG<G|GG F=E| E2 E(_D/E)|_D D C D |C4‐ |C
587 &DC<C|CC_D C|=B,2_B,B, |_A,A,(G,/A,/)B,|F,4‐|F,&)zzD=E|
588 A double ampersand (‘‘&&‘‘) will allow
590 overlaying more than two lines of music but this feature has
591 not yet been implemented.
592Lyrics
594 Aligned lyrics under a staff are written as a
595 ‘‘w:‘‘ line directly below the staff line. For example::
596 edc2 edc2|
598 w:Three blind mice, three blind mice
599 Each word in the ‘‘w:‘‘ line (delimited by
601 blanks) is associated with one note, in sequence. The
602 following special symbols modify this behaviour:
603 ‘‘*‘‘
605 Skips one note.
606 ‘‘‐‘‘
608 Splits a word into two syllables which are
609 associated with two adjacent notes. A "‐" is drawn
610 between them.
611 ‘‘|‘‘
613 Advances to the next bar line.
614 ‘‘~‘‘
616 Is output as a space, but unites two words so
617 they appear under a single note.
618 ‘‘_‘‘
620 Draws a thin underscore from the previous note
621 to the next.
622 To include more than one line of lyrics, use
624 multiple ‘‘w:‘‘ lines. To include hyphens without
625 splitting a word over multiple notes,
626 use ‘‘−‘‘.
627 If a word starts with a digit, this is interpreted as a
629 stanza number and outdented a bit to the left.
630Slurs and ties
632 The direction of slurs and ties may be controlled using
633 the "(," / "(’" and "‐," / "‐’" constructions.
634Microtone pitches
636 Microtone pitches are indicated by a fraction after an
637 accidental, as in ‘‘^3/4c‘‘. When omitted, the
638 numerator defaultes to 1 and the denominator to 2
639 (so ‘‘^/c‘‘ is the same as ‘‘^1/2c‘‘). The
640 numerator and denominator values may not exceed 256. There
641 is built‐in support for quarter‐tone accidentals (1/2 and
642 3/2 sharps and flats); for other values, rendering functions
643 must be defined using ‘‘%%postscript‘‘.
644EPS inclusion
646 EPS files may be included inside tunes using the
647 pseudo‐comment ‘‘%%EPS <file>‘‘.
648SEE ALSO ========
650A brief introduction referencing further documentation is in‐
652stalled in <docdir>/abcm2ps/README.md.
653The ABC music notation is at http://abcnotation.com/.
655Especially, you may find a discussion of differences with the ABC
657standard at http://moinejf.free.fr/abcm2ps‐doc/features.xhtml and
658a list of formatting options at http://moinejf.free.fr/abcm2ps‐
659doc/.
660AUTHOR ======
662‘‘abcm2ps‘‘ was written by Jean‐François Moine <http://moine‐
664jf.free.fr/> starting from ‘‘abc2ps‘‘ by Michael Methfessel.
665Parts of this manual have been written by Anselm Lingnau <ling‐
667nau@debian.org> for the ‘‘Debian‘‘ system.
668Permission is granted to copy, distribute and/or modify this doc‐
670ument as long as its origin is not misrepresented.
671