next up previous contents index
Next: Other utilities Up: abctab2ps User's Guide Previous: Tablature   Contents   Index


Format fine tuning

Some layout parameter can be set by command line options (see the man page of abctab2ps or for details), but most are set via pseudo comments. Pseudo comments are lines beginning with two percentage signs %%. The syntax of a pseudo comment is
%%<parameter> <value>
This changes the layout parameter <parameter> to <value> in subsequent lines.

These layout settings may also be collected in a format file with the extension ".fmt", which can be included with the command line option -F. This is useful eg. for a songbook because the layout of all songs can be maintained in a single file. Layout parameter in a format file must not start with %%. A line consisting of the word "end" in a fmt file skips the rest of the file.

To see the settings for all the parameters, use flag -H. When used in conjunction with other flags such as -p, -P, or -F, the corresponding parameters are shown. If you redirect the output to a file and edit out the header line, you immediately have a prototype fmt file which specifies all the parameters.

There are some parameters which can also be set in the E: info field. These are

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.

Staff breaking

Generally one line of abc notation will produce one line of music, although if the music is too long it will overflow onto the next line. You can counteract this by changing either the note spacing with the E: field or break the line of abc notation. If, however, you wish to use two lines of input to generate one line of music then simply put a backslash (\) at the end of the first line.

The best output is usually obtained if the staff breaks are chosen explicitly by suitable line breaks in the input file. In this standard usage, the program tries to set the music as well as possible for each line separately. The symbols "*" and "**" at the end of a line are ignored, as well as the field "E:" for the elementary length.

If a line is too long to fit onto one staff, the overhang is spilled onto the next staff in this version. This makes it possible to get reasonable output even when the input is one long logical line. In practice, this is equivalent to automatic line breaking.

To control line breaking, the following command line options to abctab2ps are available:

-b break at all line ends, even if they end with the continuation symbol "\".
-c consider the input as one long line, ie., implicitly append a backslash to every line of music.
-B n try to typeset with n bars on each line.
-a $\alpha$ set the maximal amount of permitted shrinking to $\alpha$, where $\alpha$ lies between 0 and 1.


Fonts are specified in pseudo comments of the form
%%<itemfont> <postscript font> <size>
<postscript font> must be a valid postscript font. The standard postscript fonts that are supported by all postscript devices are: AvantGarde-Demi, AvantGarde-DemiOblique, AvantGarde-Book, AvantGarde-BookOblique, Bookman-Light, Bookman-LightItalic, Bookman-Demi, Bookman-DemiItalic, Courier, Courier-Oblique, Courier-Bold, Courier-BoldOblique, Helvetica, Helvetica-Oblique, Helvetica-Bold, Helvetica-BoldOblique, Helvetica-Narrow, Helvetica-NarrowOblique, Helvetica-NarrowBold, Helvetica-NarrowBoldOblique, NewCenturySchlbk-Roman, NewCenturySchlbk-Italic, NewCenturySchlbk-Bold, NewCenturySchlbk-BoldItalic, Palatino-Roman, Palatino-Italic, Palatino-Bold, Palatino-BoldItalic, Symbol, Times-Roman, Times-Italic, Times-Bold, Times-BoldItalic, ZapfChancery-MediumItalic, ZapfDingbats.

<size> is the font size in points (eg. 14). Note however that the font size (like the size of the music) will be effected by the parameter scale (see next section); eg. if scale is set to 0.7 (which is the default) a font size of 14 will actually result in a $0.7 * 14{\rm pt} \approx 10{\rm pt}$ font.

<itemfont> specifies the scope of the font like title, guitar chords etc. It can be any of the following values (values without explanation are deemed obvious):

partsfont for part labels (P: filed)
tempofont for tempo marks (Q: filed)
vocalfont for lyrics or vocals under a staff (w: field)
gchordfont for guitar chords
textfont for text under the tune, or between tunes
wordsfont for words under the tune (W: field)
voicefont for voice names (V: field)
In printed music, the 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 switch on the box without changing the font style and/or size, the character * can be used, as in:
%%titlefont * * box

Because ISO fonts are needed for special characters and accents, all fonts must be known when the header of the PS file is written. The program tries to be as clever as it can about this, but a font might be undefined if it is invoked for the first time further down in a file. For this reason, a line like this can be put into the fmt file:

font Palatino-Bold
or alternatively at the top of the abc file:
%%font Palatino-Bold
Either of these will define the corresponding ISO font in the header. To make things even easier, the program always looks for a file "fonts.fmt" and loads it if it exists. So, the often-used fonts can be defined there once and for all.

Page layout parameters

Page layout parameter are usually specified by pseudo comments. Beside dimensionless factors (decimals) or integer values, the parameter value can be of the type "logical" or "dimension". Logicals must be one of 1, yes, true for "true" or one of 0, no, false for "false"; if nothing is specified, this is equivalent to true. Dimensions can be given in mm, cm, in, or pt, where pt is the default. Examples:
%%pageheight 29cm             % height of page
%%staffwidth 5in              % width of staff
%%leftmargin 1.8cm            % left margin
%%titlespace 1cm              % vertical space before the title
%%scale 0.9                   % size of musical symbols
%%staffsep  60pt              % space between staves
The following table lists all possible parameters and their equivalent command line option (if there is one). Parameters without explanation are deemed obvious.
Parameter Type abctab2ps option Description
pageheight dimension    
staffwidth dimension -w  
topmargin dimension    
botmargin dimension    
leftmargin dimension -m  
topspace dimension   vertical space at the top of a tune. (see remark 1.)
titlespace dimension   space before the title. (see remark 1.)
subtitlespace dimension   space before the subtitle.
composerspace dimension   space before the composer.
musicspace dimension   space between the composer and the music.
partsspace dimension   space ("up") between the "parts" and the music.
vocalspace dimension   space above a line of vocals.
wordsspace dimension   space above the words at the end of a tune.
textspace dimension -n space above the text such as history.
gchordspace dimension   space between staff and guitar chords (music only).
staffsep dimension -d separation between staves. One-half of this distance is added above and below each staff.
sysstaffsep dimension   in multi stave music separation between staves within one system.
systemsep dimension   in multi stave music separation between systems.
stafflinethickness decimal   thickness of a single music and tablature staffline.
indent dimension   amount to indent the first staff. Indentation is done at the start of the piece and after a T: field, but not after a P: field.
scale decimal -s symbol size; eg. 1.0 is used in the "pretty" output.
maxshrink decimal -a how much to compress horizontally when staff breaks are chosen automatically. Between 0 and 1.
strictness1 decimal -X strictness for single stave music.
strictness2 decimal -X strictness for multi stave music.
In multi stave music, it is often a good idea to space the notes somewhat more strictly according to their duration than in single stave music. For strictness=1, the spacings for notes with short durations is reasonably strictly proportional to their duration. For strictness=0, they are spaced about equally. Good defaults are strictness1=0.5 and strictness2=0.8.
lineskipfac decimal   factor for spacing between lines of text: 1.0 gives single-space output, 2.0 double etc.
parskipfac decimal   similar factor for space after a paragraph of text.
barsperstaff integer -B try to put as many bars per staff.
barnumbers integer -k write bar number every n-th bar. n=0 writes bar number on the first bar in each staff.
barnumberfirst integer   Start barnumbering with this number instead of 1.
landscape logical -l landscape orientation if true
titleleft logical   title flushed left if true.
titlecaps logical   title in capital letters
musiconly logical -M no lyrics if true
stretchstaff logical   stretches underfull staves across page
stretchlast logical   stretches last staff if underfull.
writehistory logical -n writes notes, history etc if true.
continueall logical -c continue all lines if true.
breakall logical -b break at all line ends.
oneperpage logical -1 each tune on separate page.
withxrefs logical -x print out X: xref number in title.
squarebrevis logical   draw square brevis (|=|) instead of round (|o|).
slurisligatura logical   draw ligatura brackets instead of slurs.
historicstyle logical   draw diamond shaped note heads music in order to emulate historic prints. Mostly used in connection with nobeams
nobeams logical   do not draw beams in music
nogracestroke logical   do not draw stroke through flag of single grace notes
printmetronome logical   set to false or no when metronome marks in Q: fields shall not be printed
endingdots logical   draw a dot after the number in first/second endings.
meterdisplay text   for printing different meter specification, eg. %%meterdisplay 3/2=3 will print ``3'' when ``M:3/2'' is given.


  1. Usually, one only sees the sum of topspace and titlespace. However, if text is written preceeding a tune, it will come after topspace and before titlespace.
  2. vocalspace, wordsspace and textspace count to the top of a line of text. That is, the relevant text size (eg. "12pt") is added.

Scope of parameters

Generally, layout parameters only affect the current tune in which they are declared. To make a layout parameter global for all tunes, declare it before the first X: field or use a separate format file.

Several parameters (eg. titlefont, barnumbers, barnumberfirst) will only have any effect when they are declared before the T: field. It is generally the safest bet to declare format parameters between the X: and T: field.

There is one notable exception from this general scope rules: tablature font settings are global and must be set before or in the first tune.

Spontaneous alignment

If you do not want to change a layout parameter, but simply want to insert some space or a page break a single position, you can use the following pseudo comments (all parameters are of the type "dimension"):
%%sep draws a short centred line as a separator
%%sep h1 h2 len draws a separator of length len with space h1 above, space h2 below.
%%vskip h adds vertical space of height h
%%newpage writes a page break

Historic layout

If you prefer the look of historic 16th century prints over modern prints, you can obtain diamond shaped note heads with %%historicstyle and suppress beaming with %%nobeams. Note that both parameters only effect music, so that it is still possible to use grid rhythm flags in tablature in combination with a historic music layout.

next up previous contents index
Next: Other utilities Up: abctab2ps User's Guide Previous: Tablature   Contents   Index
Christoph Dalitz 2011-04-26