Selected Topics - Using Lilypond-book to Create Tunebooks

Original source of this file

The original source of this file is entitled "HowToUseThis.txt", and is located in the FFTunebook folder. I sometimes forget this is where I placed it, but generally stumble over it eventually. Since this set of notes is where I turn to first, I figured it might save me a bit of stumbling if I replicate the contents here.

HowToUseThis

(Or, how to create a tunebook, given that you have already created the requisite source files)

1. Open a command prompt window in the appropriate folder
2. Compile, using the following command (replacing the .lytex filename);

       lilypond-book  --output=out --pdf tFFTB_0v0.lytex
   	

   ...where the 0v0 in the filename represents a version code; the first 0 in this case means major version 0 (initial draft), the v is simply a delimiter, and the final 0 is the minor version, sometimes known as the revision.
3. The output can be turned into .pdf using either teXne Center, or;

       (cd to ./out)
       pdflatex tFFTB_0v0
         

You may need to repeat the last step if there are any cross-references (e.g. Table of Contents, Index) in the file.

Prerequisites

1. Requires that Tex and LaTeX be installed - I use MikTeX.
2. Requires that Perl is installed - for Windows XP I use ActivePerl, for Win7 I use Strawberry Perl.
3. Requires that Lilypond is installed. At the time of writing this we are at version 2.14.n

Requisite Source Files

1. Lilypond files (tunes, sets, etc.) ("tune.ly") that have been prepared appropriately (see below, and also see Issues, also below).
2. A latex source file that references the Lilypond files, and includes any title, index and formatting desired. This file has the suffix .lytex (Lilypond-book latex).
3. The lilypond files have an include file referenced ("FF_LilypondInclude.ily"), that sits two folders up - for this exercise, this means it sits at Tunebooks or Musicbooks. This provides (mainly) page formatting commands for the music, such as linewidths, etc.

Creating the Index

The Index is created by following a number of steps;

1. The makeidx package must be loaded in the .lytex file preamble with:

       \usepackage{makeidx} 
   	

2. The special indexing commands must be enabled by putting the

       \makeindex 
   	

   ...command into the input file preamble. This should be done within the preamble, since it tells LaTeX to create the files needed for indexing.
3. To tell LaTeX what to index, use;

       \index{key} 
   	

   ...where key is the index entry and does not appear in the final layout. You enter the index commands at the points in the text that you want to be referenced in the index, likely near the reason for the key.
4. To show the index within the document, merely add to the .lytex file the command;

       \printindex 
           

It is common to place the Index at the end of the document. The default index format is two columns.

The showidx package that comes with LaTeX prints out all index entries in the left margin of the text. This is quite useful for proofreading a document and verifying the index.

5. When the input file is processed with LaTeX, each \index command writes an appropriate index entry, together with the current page number, to a special file. The file has the same name as the LaTeX input file, but a different extension (.idx). This .idx file can then be processed with the makeindex program. Type in the command line;

       makeindex filename 
           

   Note that filename is without extension: the program will look for filename.idx and use that. You can optionally pass filename.idx directly to the program as an argument. The makeindex program generates a sorted index with the same base file name, but this time with the extension .ind. If now the LaTeX input file is processed again, this sorted index gets automatically included into the document at the point where LaTeX finds \printindex.

6. Everything in the ../out folder except the tFFTB_0v0.pdf file can then be deleted. (unless it is needed for debugging).

The index created by latex with the default options may not look as nice or as suitable as you would like it. To improve the looks of the index makeindex comes with a set of style files, usually located somewhere in the tex directory structure, usually below the makeindex subdirectory. To tell makeindex to use a specific style file, run it with the command line option:

    makeindex -s [style file] filename
    

For more info on indexing and styles, see http://en.wikibooks.org/wiki/LaTeX/Indexing

Issues

1. The .ly files have to have their names changed so that all " " (spaces) are removed or replaced with something else - I have used "_".
2. While this is not an issue in itself, I also add a suffix to differentiate between these and the original source files - for the FF Music Book, I use "_MB", and for the tunes book I use "_TB". This is most useful in telling them apart when I am editing them together with the original source file (esp. when doing an ediff).

LyTex File Definition

The .lytex file is essentially a script to run lilypond to create a set of latex and .pdf files in folder ../out, that are then combined using pdflatex into a single output .pdf.

See the .lytex file (or the instructions above) for how to use...

Details on updating .ly files

The .ly files aren't immediately useable - there are a number of issues that need to be fixed up. We do this by means of an include file and some text edits;

1. (deprecated)At the top of each file, add the following; (I don't need to do this anymore, because I changed the file structure, but included here for historical reasons)

       (deprecated)\include "FFLatexInclude.ily" 
       (deprecated) \sourcefileline 0 (this does not appear to be necessary, but included here for historical reasons)
           

2. In each header portion, disable the title;
   • comment out the existing title command with a "%"
   • add the following;

       title = ##f
             

3. It is worthwhile removing the midi constructs from the .ly files, since we won't need them and this saves the overhead of creating and then deleting them.
4. I've had to amke some various fixes due to updates of the lilypond versions, as well as to correct some mistakes I've made which have promugated;
1. The very first one was the insertion of '-'s in the print-all-headers command of the \paper sections
2. Next was the seeming diappearance of the "voltaOnThisStaff" and it's replacement with a '\consists "Volta_engraver"' command in the \new Chordnames section, followed by a '\remove "Volta_engraver"' command in the \layout section. (see "Cock o the North.ly")
3. The latter coincided with my discovery that I have been (incorrectly) adding '\consists "Bar_engraver"' command in the \new section.

That takes care of the generic edits - some files may need additional care to fix issues in formatting as we fit them all into one book.