New Hampshire Country Dance Fiddle Tunes Website

About the abc Document


Ornament

The abc Document IV: File Headers & Formatting Control

One of the lesser-known but more powerful features of abc notation is the degree of formatting control that's available through use of file headers.

There are two parts to the section on abc notation. This is part of the Detail section, intended for people interested in using abc notation. Use the buttons above to navigate the abc pages.
Important Note: This page works best on a screen at least 768 pixels wide. With an iPhone or any other small screen you may find it helpful to switch between portrait and landscape orientation for best results. Please use the abc Notation menu above to navigate the abc pages.

Using File Headers:

Fine Control of the Display of Music

We looked at the tune body and the tune header earlier. In this section we are looking at how to change the appearance of the output from an abc app such as EasyABC. This often takes the form of a PDF document, but it's becoming more common to use abc notation to create HTML web pages. These changes in appearance are made through formatting commands in the file headers.

This page covers some more complex aspects of abc notation, and assumes that you've had at least some experience with abc notation and are looking for ways to improve the appearance of your tunes on screen and/or in print, or perhaps that you are looking to gain more control over what prints and what doesn't print.


Formatting and Display of Tunes

I used to think that abc notation was fairly limited in its output and that it wasn't possible to change fonts or formatting or what aspect of the music is displayed. I knew it was possible to use formatting commands to make those sorts of changes, but I thought they were for programmers, and largely ignored the documentation of formatting parameters for abc.

In preparing this web site I figured out that every one of those assumptions was wrong, and that it's not that hard to make some of the changes I wanted to make. I've gradually figured out how to get my output to look more and more as I like it to look.

Let's look at the A part of Smash the Windows. Here's the abc code. There isn't any real formatting present here. I added in a short note using the N: (Notes) field.

X:1                 % the tune number 
T:Smash The Windows % title
T:Roaring Jelly     % a second title
N:This is a jig that's often played for New England contradances.
M:6/8               % meter
L:1/8               % default note length
R:Jig               % rhythm
K:D                 % key
 A |\ 
"D" DED F2A | "D" d2f "A" ecA  | "G" G2B "D/F#"  F2A | "Em" E2F  "A7" GFE | 
"D" DED F2A | "D" d2f "D7" ecA | "G" gfe "A7" cAc    | "D"  d3 - d2 :| 


Using the default settings with EasyABC, a PDF would look about like this:

Smash the Windows (A part Unformatted)

It's worth being aware that EasyABC and most abc apps make use of helper programs to accomplish some of their purposes. If you print from the EasyABC Print command the result will be rather poor. But if you use the Export command, it calls up abcm2ps to convert the tune(s) to PDF format with vastly better results. However, abcm2ps is limited in terms of which fonts it can use easily, whereas abc2svg, a newer app written by the same person, can handle a much greater variety of fonts with ease.

Now let's take a look at the following slightly more formatted version of the tune.

Smash the Windows (A part formatted)

It's not a dramatic difference, but let's take a look at the changes. There are three: (1) The font and size of the title has changed; (2) the font and size of the subtitle has changed, and (3) the notes are printed.

Here's how we can accomplish those changes. It's actually pretty easy to do by adding in some formatting parameters. Some of them can be found in the abc Standard. But some of them are best found in the abcm2ps & abc2svg Documentation web page.

These formatting commands can go at the top of an abc document, right before the tune in a document with multiple abc tunes, or inside the tune. Let's look at the differences between these options

  • Document file header. This is an optional section that appears at the beginning of an abc document. Formatting commands in the document file header apply to all the tunes in the document.
  • Tune file header. This refers to formatting commands placed immediately before a tune. In documents containing multiple tunes, they affect only the next tune.
  • Tune header. Formatting commands can go within the tune header and even the tune body sometimes. They only affect the current tune.

Formatting parameter lines begin with %%. This is followed by the name of the formatting command, and then generally the parameters (values) of the command.

Let's add in some formatting. We'll format the title in 20-point Palatino Bold, the alternate title in 16-point Palatino Italic, and make the chords 14-point Palatino Bold. In order to use a font we have to define the fonts in use. That will be followed by commands to change fonts for specific parts of the document. There's one more command to display the notes.

I'll use the comments to explain what each line does. Here's the code for the formatting and the first half of the tune.

%%font         Palatino-Bold      % defines the fonts used 
%%font         Palatino-Italic 
%%titlefont    Palatino-Bold 20   % Font of title 
%%subtitlefont Palatino-Italic 16 % Font of second title 
%%gchordfont   Palatino-Bold 14   % Chord font 
%%writefields  N                  % Notes (N:) are printed

X:1                 % the tune number 
T:Smash The Windows % title
T:Roaring Jelly     % a second title
N:This is a jig that's often played for New England contradances.
M:6/8               % meter
L:1/8               % default note length
R:Jig               % rhythm
K:D                 % key
 A |\ 
"D" DED F2A | "D" d2f "A" ecA  | "G" G2B "D/F#"  F2A | "Em" E2F  "A7" GFE | 
"D" DED F2A | "D" d2f "D7" ecA | "G" gfe "A7" cAc    | "D"  d3 - d2 :|


Take a look at the two versions of the tunes and you should be able to see the changes that go with the formatting commands.

From my experience, it's not too hard to figure out how to customize the output. It takes a bit of searching through the abcm2ps documentation and sometimes the abc Standard documentation, but once you get used to it things become easier to find — and the range of formatting commands available is truly impressive.

Although not as complete, I'd suggest going to the Header Page if you want to learn more.

  • It's pretty well documented, and should serve as a set of formatting parameters that you can figure out to use.
  • It starts with the Header code itself. That's the file header that should be at the beginning of each abc document on this web site. Then it has a quick review of how an abc file is structured.
  • The Header code is pretty well documented, so you should be able to figure out a lot about using many of the formatting commands.

The next step beyond this would be to use abc software that makes use of abc2svg for printing. There are a couple ways to do that. One way is to use the Portable abc2svg app, downloadable from the ABC Plus Project. It's easy to install and opens in your default web browser. A second way to use it is at Jean-François Moine's abc Edit online web app page. It looks just the same but no installation is needed. And of course it can be run from the command line.

On its own abc2svg is more flexible than abcm2ps as far as font usage and many other characteristics. But it also can be used in the context of HTML code. This leads to being able to create web pages directly, or to HTML output that can be used in existing web pages. It also leads to being able to display the tunes on the screen, and to producing tunes on the screen that can be played. For more on this, take a look at the Playable Tunes section of this website.

That's the end of this section on the workings of abc notation. To learn more I'd suggest going to the abc links page and looking for informational web sites on the topic of interest.