Chordpack Documentation

# Chordpack Documentation For version 0.8.0 ### Table of contents Introduction Quick introduction to chordpro format Installation requirements Command line usage Chordpro commands Chordpack specific commands Chordpack versus Chord Credits and Copyrights ### Links Chordpack home page ### Introduction Chordpack is a utility for typesetting and manipulating chordpro chord files. These are files used by chord utility. The primary goal of Chordpack is typesetting song-books using TeX typesetting system and it's LaTeX macro package. However, Chordpack can do whatever else you might want to do with chordpro files. Chordpack can do the following tasks: Generate LaTeX source of songs/songbook Generate HTML version of songs/songbook Generate ASCII version of songs/songbook Generate ASCII version of songs/songbook omitting chords Transpose chordpro song to desired key Take ordinary ASCII notation of song with chords and output almost chordpro version. ### Quick introduction to chordpro format Chordpack understands extension of chordpro format. Chordpro is an ASCII format for marking chords. Chords are denoted in square brackets. For instance
       [G]Always [Em]look at the [Am7]bright [D7]side of [G]life [Em] [Am7] [D7]
is a notation for
       G       Em          Am7    D7      G    Em Am7 D7
       Always look at the bright side of life
Repetition marks are denoted by `[:` and `:]` (repetition marks are only part of extension of chordpro format). Besides this, chordpro format defines braced instructions (commands), most important of which is `{title:I am a Title of the Song}` . Other commands include `{subtitle:...}`, `{start_of_choir}`, `{end_of_choir}` etc. You should use at most one command per line. The important thing about chordpro format is that there are already lots of songs on the web (see Online Guitar Archive - OLGA for instance) in this format. ### Installation requirements Chordpack consists of one script written in Perl. If you want to use Chordpack, you need to have Perl installed. If you want to use chordpack for its main purpose i.e. typesetting in TeX, you need to install TeX as well. We are using teTeX distribution for Linux but there's a high chance that you will want to use some Windows distribution. ### Command line usage of chordpack The first thing to note is that the best printing result is achieved if you use chordpack to produce LaTeX source. This however requires installation of TeX and LaTeX2e macro package which some of you may find inconvenient. In that case, you should generate HTML instead. The usage is
       chordpack <SWITCHES> <TASK> FILE ...
where there are lots of SWITCHES (also called options) explained later; TASK is one of the following tex html ascii nochord transpose key-or-shift pro You can find short description in previous section. Task transpose has one parameter, namely either destination key of the song or number of half-tones by which song has to be transposed up. Switches apply to tex task only! Chordpack reads input from FILEs or from standard input and produces the result on standard output. The exception to this is option -f. The switches are -f song-list-file -l language -b -c chord-style -s font-sizes I advise to use switches -f and -b only. Other settings are better done directly in input file. The use of switch -f in combination with tex task is highly recommended. #### -f song-list-file Use song-list-file and output the result to file created from song-list-file by removing its suffix and adding tex suffix. Song-list-file is a file containing the list of song files as well as lines that are directly passed to Chordpack. The lines directly passed to Chordpack differ from filenames in that they start with space. For example: Let file songbook.list contain
     {toc}
     {album:Two is Enough}

    song-one.pro
    second-song.pro
Let file song-one.pro contain only
    {title:Just a Small Song}
    [A]Hey [Gm]hey
and file second-song.pro contain only
    {title:Not a Big One}
    [G#m]Day is [G97maj]long and
    [D#]Girls are [F]sweet
Then the result of using `chordpack -f songbook.list tex` is the same as the result of `chordpack tex songbookfile >songbook.tex` given that file `songbookfile` contains
    {toc}
    {album:Two is Enough}
    {title:Just a Small Song}
    [A]Hey [Gm]hey
    {title:Not a Big One}
    [G#m]Day is [G97maj]long and
    [D#]Girls are [F]sweet
#### -l language Sets language. Currently, this has effect on TeX typesetting and the only supported language is Czech. If you make support for more languages, send me one. #### -b This makes Chordpack transpose all songs being set to such a key so that there are as few barre chords as possible. All tablatures (text inside `{start_of_tab}` and `{end_of_tab}`) are ignored in this case, because transposition of tablatures in virtually impossible. Well, in some remote future there may be some super AI program to do that, but until then... #### -c chord-style Set the style of chord setting. There are four styles available: `jazz`, `m`, `mi` and low. The default is m. Also, the presence of `h` letter in chord-style string turns on Central-European (or at least German and Czech) style of denoting last tone of C major key (English denote it B while German H). #### -s font_sizes Sets the sizes of fonts. These can be 0,1,2,3. ### Chordpro commands Here are listed chordpro commands understood by Chordpack. Chord utility however understands more commands.
{title:...} or {t:...} | Title of the song.
{subtitle:...} or {st:...} | Subtitle of the song. It is typically author of the song. You may specify more subtitles. By default, chordpack does not set these subtitles. You can turn setting of subtitles on by {subtitles_on} command and later turn setting of them of by {subtitles_off}.
{comment:...} or {c:...} | Commentary on something. Typically set in italics.
{start_of_choir} or {soc} | Marks the beginning of choir. Choir is set by italics to distinguish from verse.
{end_of_choir} or {eoc} | Marks the end of choir.
{start_of_tab} or {sot} | Marks the start of tablature. The important thing about tablature is that is is set in non-proportional (fixed-width if you wish) font. The result is this marking does not say that there is a tablature inside. It says set me in non-proportional font. This is however mainly useful for tablatures or other tone notation.
{end_of_tab} or {eot} | Marks the end of tablature.
> ### Chordpack specific commands Chordpack has abilities that surpass those of Chord and as such it defines new commands of its own. These have to do with organization of song-book and with setting typesetting parameters as well. You should not use these commands as a part of single song files, rather they should be used to finalize the look of the song-book being set. They are best used as a part of song-list-file (see option -f). {album: ... } This is analogical to `{title: ...}` command. It marks the start of a new album. Album title is typeset. The commands has also effect on the table of contents. {subtitles_on} Turn setting of subtitles on. {subtitles_off} Turn setting of subtitles off. This is the default. {chordstyle: ... } Sets the style of chord setting (see option -b). {language: ... } Sets language (see option -l). {fontsize: ... } Sets fontsizes (see option -s). {titlestyle: ... } Sets the style of song titles. In default style song titles are set in sans serif with a rule above the song title. Style `norule` differs only in that there is no rule. Finally style `graybox` sets gray box in the background of the song title. If you add `songnewpage` to titlestyle, every song will be set on a new page (or column in two column mode). For example, you can write `{titlestyle:graybox songnewpage}`. {columns: ... } Sets the number of columns. Possible values are 1 and 2, the later being default. {songbooktitle: ... } Songbooktitle is a string of lines separated by ^. It determines the look of title page of the song-book. Each line is set on a new line and is centered. The first line is bold. For example, if you write `{songbooktitle:The Beatles^With the Beatles^Yellow Submarine}`, you will get something close to The Beatles With the Beatles Yellow Submarine Next to the title page will be set the table of contents together with alphabetical table of contents. {toc} Typesets the table of contents. This is useful if you don't want to have title page or you are user of LaTeX and want to design your own title page using LaTeX. {verbatim_tex_start: ... } or {vtexs: ... } Enters verbatim TeX mode. In this mode every line is passed directly to TeX unchanged. These lines are ignored if you do not use task `tex`. {verbatim_tex_end: ... } or {vtexe: ... } Quits verbatim TeX mode. ### Chordpack versus Chord Chordpack was written to surpass the Chord program which generates postscript from chordpro format. The main drawback was the setting of chords. Consider example typesetting of chord which looks like
> | Eb7+ | Eb75- | Eb74sus | Eb97maj | Ebm97maj | Ebm9 |
> | Finally | he | closed | his | eyes | shut.
> and compare it to chordpack's
> E | b | 7 + |
> E | b | 7 5- |
> E | b | 7 4sus |
> E | b | 9 7maj |
> E | b | m | 9 7maj |
> E | b | m | 9 |
> | Finally | he | closed | his | eyes | shut.
This just touches on the quality of chord typesetting of chordpack. However, chordpack has its weak spots as well when compared to Chord: Generates LaTeX source and not postsript (less convenient) Does not generate chord pickings ... and maybe other. The thing is I did not really want chord pickings, but they can be added, if you users desire them! The main purpose was to set chords nicely and enable easy setting of song-books. I believe that the result going out of chordpack is close to perfect and I ain't going to spell out every little annoyance I had to solve to get things looking well. ### Credits and Copyrights The Chordpack was written by Daniel Polansky, September 2000. All the hard coding and finetuning was done by me (Dan), but some of the ideas came from David Necas alias Yeti . Chordpack is distributed under GPL. Excuse my poor English.