Using Seal under Windows

Seal is written in the programming language Ruby, and converts through the type-setting environment LaTeX, so in order to use it, you need to have these installed.

Under Windows, this involves some steps that may seem complicated to the average point-and-click user, but it’s not really difficult. Below is first a quick-install routine, then a more detailed walkthrough.

Quick install

  1. Download and install Ruby and MikTeX.
  2. Download and unpack dylanchords [1] [2] and Seal.
  3. Browse to wherever you unpacked Seal.
  4. Run ruby seal-convert <path\to\dylanchords>
  5. Run ruby seal-tex --pdf to get pdf output; follow instructions along the way.
  6. Go to the subdirectory book, where you will find mbpbook.pdf

Detailed instructions

1. Preparations

1. Both Ruby and MikTeX are freely available. Ruby from

http://rubyinstaller.rubyforge.org/wiki/wiki.pl

(direct link to the installer),

and MikTeX, the Windows version of LaTeX, from

http://www.miktex.org/Default.aspx

(direct link).

These are fairly big downloads, but it’s worth it…

Once you’ve got them home, both Ruby and MikTex are one-click installers (well, you may have to double-click, but I count that as one), so click on the exe-files, choose a destination (you can for instance accept the suggestions), and sit back and wait.

You will be presented with some alternatives about what to install. E.g., if you don’t think you are ever going to look into programming with Ruby, you may unselect the documentation during the installation. One thing you should not unselect, however, is SciTE, a superb text editor which comes bundled with Ruby.

2. Then you need something to feed the Seal with: a recent copy of the chords.zip file of dylanchords, available from dylanchords.nfshost.com or dylanchords.brokenbricks.com

3. Oh yes, and you need Seal itself. The seal package is available from http://www.math.tu-dresden.de/~kuettler/seal/

4. Unpack these, using the zip handler of your choice (I can recommend Total Commander, the file manager par excellence, which also handles zip files, but any zip-utility will do – even the one that comes with Windows), to wherever you want it. The following instructions use c:\dylanchords\, but you can put it wherever you want.

Unpack chords.zip, e.g. to c:\dylanchords

Unpack seal-current.zip. If you unzip it to c:\dylanchords, it will unpack itself to the subdirectory seal-snapshot-<x> where <x> is the current version number of Seal.

2. Running Seal

When the preparations are done, you are ready to run Seal itself.

1. Open a console. The easiest way is to press the Win-key + R (for “run”), then type cmd + Enter in the windows that pops up.

2. Navigate to the directory where you put seal, e.g., at the prompt, type:

cd c:\dylanchords\seal-snapshot-<x> 

(tip: you don’t have to type it all: write a couple of letters and press TAB until the correct directory comes up, etc)

3. then type “ruby seal-convert” followed by the path to dylanchords. Ex:

ruby seal-convert c:\dylanchords

or, if you unpacked seal in c:\dylanchords\seal-current, you can do

ruby seal-convert .. 

(“..” means “parent directory”)

If ruby is correctly installed, and you’ve typed everything correctly, you should now see a lot of messages scroll by as seal converts all the html files into LaTeX files. Some of the messages may be warnings, but you can disregard that.

4. When seal-convert is done, type

ruby seal-tex --pdf

This will gather all the single .tex files into one single file, mbpbook.tex, and then convert that to a pdf file.

MikTeX, even though it’s a huge download, is only the bare bones of LaTeX. Seal uses some extra packages which are not part of the basic installation. The first time you run seal-tex, MikTeX will stop when it finds a missing package, and ask you to install it. This should proceed automatically – all you need to do is to click “install” when you are asked.

Again, you will see a lot of messages rolling by. Some of these are complaints about overfull and underfull boxes (nothing about all the wonderful boxes you will get, though, which proves that computer programs care more about numbers than about aesthetics, alternatively that computer programs belong in the pre-Kantian world, where beauty was defined in terms of numbers). Again, these can be disregarded.

5. If you’ve done everything correctly, your pdf file, called mbpbook.pdf, should be ready for you. All the output files end up in the subdirectory “book” (unless you specify a different directory), so you will find it at c:\dylanchords\seal-snapshot-<x>\book\mbpbook.pdf

6. Pick up your guitar, tune it, clear your throat and your mind, go to a random page, play and enjoy.

Further Options

The method described above is what you would do if you simply want a pdf file of the whole thing as quickly as possible. There are some other options available.

1. seal-convert has the following, general usage description:

Usage: ruby seal-convert [options] source [destination]

The options can be any of the following (or nothing at all):

-f, --[no-]force       Overwrite existing directories
-i, --[no-]interactive Ask before overwriting
-v, --[no-]verbose     Write out what is going on
-q, --[no-]quiet       Don’t write what is going on

The source is the path to wherever you have put the dylanchords files, and the destination is where you want the result. If this is left empty, the output will go to a subdirectory book in the seal folder.

A sample run with all the places filled, may look like:

ruby seal-convert -iv c:\dylanchords c:\great_stuff\seal

2. seal-tex has the following usage:

Usage: ruby seal-tex [options] [directory]

and the following options:

--pdf              Create PDF output instead of PostScript
-v, --[no-]verbose Write out what is going on
-q, --[no-]quiet   Don't write what is going on
-h, --help         Show this message
--copyright        Show copyright (revised BSD License)

If run without any arguments, ruby seal-tex will generate a postscript file, which is the format of choice in the LaTeX/Linux world.

3. Which files are included in the book, is determined by two files in the data subdirectory: albums.yaml and songs.yaml. If you just want some albums in your book, comment out the ones you don’t want (put a # in front of them), and run ruby seal-convert and ruby seal-tex -pdf again. If you also specify a different output folder, you won’t overwrite the main book. E.g., you can comment out everything except Knocked out Loaded in albums.yaml and do:

ruby seal-convert c:\dylanchords c:\dylanchords\torch-ballads

4. Seal is open-source, which means that you can open all the files in the seal folders and see what they’re doing. You can also change them if you’re confident enough about your programming skills.