About chmap

by Michael J. Fromberger <http://www.dartmouth.edu/~sting/>
Copyright (C) 2001 Michael J. Fromberger, All Rights Reserved.

The original chmap was a C program that spit out guitar fretboard
diagrams as ASCII text.  This version is written in Perl, and writes
output as encapsulated PostScript (EPS), suitable for printing.  This
version also comes with a database of chord positions (I got these
about fifteen years ago when I was first learning how to play the
guitar).

When you run chmap, it prints out the options that are currently in
effect, then waits for you to type something.  Alternatively, you can
specify a filename to read from on the command line, or pipe input
from somewhere else.  Each line of input must have this form:

<line> := <title> ':' <specs>

The title is a descriptive string, and may consist of any characters
except a colon.  Whitespace is mostly ignored, except in <title>,
although it serves to delimit other tokens.  The character '%' denotes
epsilon, and '_' indicates a place where no whitespace is allowed.
The square brackets, except as enquoted, denote [optional] rules.  A
vertical bar ('|') denotes alternatives.  An asterisk ('*') denotes
zero or more occurrences of the preceding element, a plus ('+')
denotes one or more occurrences of the preceding element.  Elements in
single quotes ('sic') are literal characters.  Names denoted in angle
brackets (<sic>) are considered syntactic variables.  Tokens are
delimited by whitespace except where indicated by an underscore.
Parentheses indicate grouping.

The rules are:

<specs> := <spec> <specs> | %

<spec> := <attr-spec> | <pad-spec> | <label-spec>

<attr-spec> := ':' _ <name> [_ '=' _ <value>]

<pad-spec> := <pad-element>_+ [<finger>]

<pad-element> := <string-spec> | <fret-spec> | <pad-override>

<string-spec> := <number> _ [',' _ <number>]* _ 's' | 
                 <number> _ '-' _ <number> _ 's'

<fret-spec> := <number> _ 'f'

<pad-override> := '[' _ ( 'ring' | 'disc' | 'num' ) _ ']'

<finger> := <number>

<label-spec> := <number> _ [',' _ <number>]* _ '.' _ <word> |
                <number> _ '-' _ <number> _ '.' _ <word>

<number> := sequence of one or more decimal digits
<word> := sequence of one or more letters, digits, underscores
<name> is the same as <word>

The output is written to a file whose name is based upon the title.
Slashes (/) are replaced with periods (.), spaces and tabs are
replaced with underscores (_), and all letters are reduced to
lowercase.  If a file by that name already exists, a sequence number
is appended and incremented until conflict is avoided.

The only attribute currently understood is :movable.  This indicates
that the chord pattern does not have a fixed base fret, and so the
chord is drawn without a thick bar to indicate the nut, and without
any number over the lowest fret to indicate the desired position.

Labels are placed at the ends of each string, as specified.  These can
be used to indicate strings that should not be played, which string
has the root note in a movable chord, strings which are open, and so
forth.  The format for a label is "n.text" where "n" is the number of
the string and "text" is the desired label.  You can apply the same
label to multiple strings using the syntax "m-n.text" or "x,y,z.text"
as appropriate..

The circles indicating which notes should be fretted are called
"pads".  The pads may be drawn as solid black discs, hollow white
rings, or rings with finger-numbers inside.  The default is to draw
discs (override this with the --pads command line option).  You can
also override the default setting for a particular note or set of
notes.  Numbered pads are displayed as rings, if the fingering is not
indicated in the chord description.

Examples:

	Em7 in root position, no fingerings indicated

	Em7: 4-5s2f 2s3f

	Here is a breakdown of what this means:

	Em7	the title of the chord

	4-5s	strings 4 through 5 (D and A)
	2f	2nd fret

	2s	string 2 (B)
	3f	3rd fret


	D major in root position with fingerings

	D: 2s3f3 1s2f2 3s2f1 5.5 6.x

	D	the title of the chord
	2s3f3	string 2, 3rd fret, 3rd finger
	1s2f2	string 1, 2nd fret, 2nd finger
	3s2f1	string 3, 2nd fret, 1st finger
	5.5	display 5 beside string 5 (the 5th of D is A)
	6.x	display x beside string 6 (don't play E)


	A movable major scale with root on finger 2

	Scale: :movable 1-6s4f4 5,4,3,1s1f1 3-4s3f3 6s[ring]2f2 1,2,5s2f2

	Scale		the title of the chord
	:movable	means the scale has no fixed position
	1-6s4f4		strings 1-6, 4th fret, 4th finger
	5,4,3,1s1f1	strings 1, 3, 4, and 5, 1st fret, 1st finger
	3-4s3f3		strings 3-4, 3rd fret, 3rd finger
	1,2,5s2f2	strings 1, 2, and 5, 2nd fret, 2nd finger
	6s[ring]2f2	string 6, 2nd fret, 2nd finger, display as a 
			hollow ring.

It's a little esoteric, but very flexible.  You can also set the size
of the output using the command line options --width and --height,
each of which which takes a decimal value in inches.  The width
specifies how far apart each pair of frets will be; the height
specifies how far apart each pair of strings is.  The weight of the
lines is usually 1 point (about 1/72nd of an inch), but you can change
this if you are making smaller diagrams, using the --weight command
line option.  If you are making patterns for something other than a
guitar, use --strings to set the number of strings it displays.

You cannot directly control how many frets are displayed; this is
chosen by the program based on the string/fret combinations you
supply.  You can, however, set the font that is used (it defaults to
Helvetica Bold).