SONGBOOK(1L)  L^{A}TEX STYLES  SONGBOOK(1L)

NAME songbook (chordbk, wordbk, overhead) – L^{A}TEX document style to produce songbooks

SYNOPSIS

\documentstyle[12pt]{book}
\usepackage{`chordbk'|`wordbk'|`overhead'}
\begin{document}

\begin{song}{title}...other options...

⋮

\end{song}
\end{document}

DESCRIPTION The songbook document style provides a core set of functions for the production of songbooks. Three pre-defined songbook formats are provided (and they are invoked via the \usepackage{} command):

chordbk.sty a songbook suitable for guitarists which gives both lyrics and words (this is the default mode of the songbook document style);

wordbk.sty a words only songbook suitable for mass distribution to those singing along;

overhead.sty to produce overhead transparencies from songbook source files.

The songbook document style is based upon L^{A}TEX’s familiar book document style. Unsurprisingly, the songbook document style produces familiar looking output. This is one of the songbook style’s strengths.

WHAT’S NEW What’s new in version 3.1:

• removed dependance upon twocolumn.sty; this isn’t required in L^{A}TEX2e

• added an optional first parameter to \SBEnd and \SBIntro which causes the introduction or the ending to be printed in words only mode as well as in chord mode

• added the three environments that had been documented on the man page didn’t appear in the songbook.sty file (I ran out of time when implementing the changes for version 3.0, and then forgot to remove the descriptions from the man page): SBSection*, SBVerse* and SBChorus*. The definition for the SBVerse* environment was supplied by Herbert Martin Dietze <herbert@fh-wedel.de>; and this formed a model for the other two

• corrected definition of \SBBracketTagFont in overhead.sty

What’s new in version 3.0 (this list is probably not a complete list of changes):

• The song, SBVerse, SBChorus, and SBSection environments, and the \STitle macro, all set either \leftmark or \rightmark. I’ve also added a macro to make it easy to place a “Some title cont...” string in the page header.

• The song environment now handles empty copyright and W&M parameters in a special fashion: if either of these parameters is left empty, then the string “Unknown” is put in place. Also, if \SBPubDom is passed to the copyright paramter, then the copyright mark (i.e., \begin{matrix}c \\ ◯ \end{matrix}) is omitted.

• The \Ch macro has been completely re-written. The significant change is that a new command automatically draws a rule when the chord is bigger than the syllable. What would previously have been written as “\Ch{A}{one\SBen}\Ch{D}{two}” is now written as “\Chr{A}{one}\Ch{D}{two}”. The old deprecated macros, \Ch and \ChX, are available as \oCh and \oChX, respectively.

• The new \Ch maros now raise the chord a specified height above the text; rather than relying upon a \strut to determine the height. The new default raise amount is less than before. See the \Ch entry, below for instructions on setting the raise height to match version 1.x and 2.x releases of the songbook macros.

• All the \if constructs that had been defined (and used) within the songbook style are now superceded with properly defined elements (created using \newif). All the old \if stuff works as it used to… this is a pure enhancement only. However, the songbook style itself makes exclusive use of the new elements.

• The font used for chords (as defined by \ChFont) has been changed to a bold, compressed, sans serif font, cmssbc12. Hence, although the chords themselves take up a slightly smaller bit of space on the page, they are much more readable. As well, square brackets are now typeset using the \ChBkFont macro.

COMMANDS This section is broken into several subsections. Hopefully this makes the individual commands easier to understand by placing them in a meaningful context. Since some forward references exist, it may be necessary to read through the entire COMMANDS section a couple of times before it makes complete sense.

Environments The songbook style defines several new environments to make the formatting of songbooks easier and more consistent (and most of them have parameters). Unless otherwise noted, all of the environments are verse-like: wrapped lines are indented more than the first line.

\begin{SBBracket}{bracket tag}… stuff to bracket… \end{SBBracket} is the environment used to mark a given line of the song with a tag and bracket. An example usage is to mark the line of the song played to end the piece, if it is somehow different than the chords played if one were to repeat the song. For example:

              Be\Ch{Am}{cause} of \Ch{Dm7}{what} the...
           \end{SBChorus}
           \begin{SBBracket}{Ending}
              Give \Ch{F}{thanks,}\Ch{C/F}{} \Ch{Bb/F}{}...
           \end{SBBracket}

This is very similar to the SBOccurs environment, the difference being how the section of the song is marked. There are two versions of this environment: SBBracket and SBBracket*. They operate identically, except that the *’ed version doesn’t print its tag and bracket in words only modes. Note: as of version 3.1, SBBracket* is still missing from the style (a placeholder exists which doesn’t function as intended). At present, \SBBracket is fragile and is not compatible with SBVerse, SBChorus, or any other environment; with the exception of the song environment.

\begin{SBChorus}… the chorus… \end{SBChorus} is the environment to wrap around a chorus that you wish to be indented and given a chorus tag (“Ch:”). A song with one verse and one chorus, where the chorus is sung after the verse would probably use the SBChorus environment. Whereas, if the chorus was sung first, an SBVerse environment would probably be used. The indent amount for lines that are too long is set with the \HangAmt command. The SBChorus* version of this command indents but does not place a \SBChorusTag before the chorus.

\begin{SBExtraKeys}{song content}\end{SBExtraKeys} is the environment used when you wish to list the song again in another key. Typi-

cally, this environment is used along with an \STitle command. For example:

           \begin{SBExtraKeys}{
              \STitle{You Alone}{D}
              \begin{SBVerse}
                 \Ch{D}{Ho}\Ch{F#m}{ly,} \Ch{G}{Ho}\Ch{D}{ly,}
                 ...
              \end{SBVerse}
           }\end{SBExtraKeys}

\begin{SBOccurs}{the occurrence}… stuff to group… \end{SBOccurs} is the environment used to mark a given line of the song with a tag and brackets. For example ”1,3” would designate that this passage applies to the 1st and 3rd occurances. For example:

              Be\Ch{Am}{cause} of \Ch{Dm7}{what} the...
           \end{SBChorus}
           \begin{SBOccurs}{1,3}
              Give \Ch{F}{thanks,}\Ch{C/F}{} \Ch{Bb/F}{}...
           \end{SBOccurs}

\begin{SBSection}… the section… \end{SBSection} very much like LaTeX’s verse environment, except that here the sections are numbered. The indent amount for lines that are too long is set with the \HangAmt command. This environment would be used in place of the \SBVerse environment for songs which are broken into pieces/sections, in place of, or in addition to, verses. The indent amount for lines that are too long is set with the \HangAmt command The SBSection* version of this command indents but doesn’t place an \SBSectionCnt before the chorus. Similar to L^{A}TEX’s \section* command, the section counter is not incremented either.

\begin{SBVerse}… the chorus… \end{SBVerse} is the environment to wrap around a verse that you wish to be indented and given a verse number (\SBVerseCnt). A song with one chorus and one verse, where the verse is sung after the verse would probably use the SBChorus environment. Whereas, if the chorus was sung first, an SBVerse environment would probably be used. The indent amount for lines that are too long is set with the \HangAmt command. The SBVerse* version of this environment indents but down not place an \SBVerseCnt before the chorus; similar to L^{A}TEX’s \section* command, the verse counter is not incremented either.

\begin{song}{<1 >}… {<6 >}… the song… \end{song} is the environment which each song resides within. The parameter list is quite long, and is defined as:

1. Song title;

2. Key song is written in;

3. Copyright information;

4. Name(s) of composer and lyricist;

5. Scripture reference for the song;

6. Copyright licensing information.

The song environment takes care of making index entries, incrementing \SBSong-Cnt and page generation (if necessary). Note, this environment makes use of \everypar. See the EXAMPLE section, below, for a sample one-song songbook document. When the “copyright information” or “composer & lyricist” parameters are left empty then the string defined by the \SBUnknownTag macro used (instead of leaving whitespace in the song header.

\begin{xlatn}{<1 >}… {<3 >}… the translation… \end{xlatn} is the song translation environment. The parameter list is defined as:

1. Translated song title (in the foreign language);

2. Translation permission;

3. Who performed the translation.

The xlatn environment always occurs within a song environment; it resets the verse counter, causes the title and other parameter information to be displayed, and makes the appropriate index and table of contents entries. It is important for the xlatn environment to occur within a song environment, because the xlatn environment inherits the song environment’s \everypar definition.

Primary songbook Macros Along with the songbook environments, these are the macros you will most often use when constructing a songbook (of any style).

\CBPageBrk forces a new page if \ifChordBk is true.

\Ch{chord}{syllable} the chord over lyrics command definition. This is the most commonly used command in the songbook style. The words-only sub-style turns off the chord generation and just prints the second parameter. The chord parameter is left-justified over the syllable parameter. Any ‘#’ or ‘b’ characters in the chord parameter are replaced with ‘♯’ and ’♭’ characters, respectively. Also, if a bass note is specified in a chord (by way of a ‘/’ character followed by the note) then it will appear in a smaller font than the rest of the chord.

It is often desireable to typeset a chord—or set of chords—inside square brackets, to indicate that they are optional. A lighter weight font is probably desired, so that the brackets do not detract from the chord name, so any ‘[’ and ‘]’ characters are typeset with the font specified by the \ChBkFont macro.

To set the chord raise amount to a value that matches version 1.x and 2.x releases of the songbook style, insert the following command into the preamble of your document:

          \renewcommand{\SBChordRaise}{\SBOldChordRaise}

\Chr{chord}{syllable} this command performs the same function as the \Ch command with one exception: the \Chr command inserts a rule, at the height specified by the \SBRuleRaise-Amount macro, when the chord is wider than the syllable. The default value creates an extended em-dash-like rule; a value of 0pt creates an underbar-like rule. See the USAGE GUIDELINES section of this man page, below, for a more detailed explanation.

\ChX{chord}{syllable} this command performs the same function as the \Ch command with one exception: the \ChX command causes spaces trailing the command to be ignored. See the USAGE GUIDELINES section of this man page, below, for a more detailed explanation.

\makeKeyIndex start creation of an index of songs by key.

\makeTitleContents start creation of a table of contents.

\makeTitleIndex start creation of a title and first line index.

\NotWOPageBrk forces a new page if \ifWordsOnly is false.

\OHContPgHdr prints a page heading continuation header on overheads; this macro must be manually inserted where needed. It is generally used in conjunction with the \OHPage-Brk macro. \OHContPgHdr is a no-op, except when \ifOverhead is true.

\OHPageBrk forces a new page if \ifOverhead is true.

\RchBk right square bracket (to place around an optional chord). See the \LchBk macro description, above, for more detail.

\SBBridge{the bridge} is used to encapsulate a bridge: it causes the bridge to be set with \SBBridgeTag, using in the \SBBridgeTagFont font. In words only mode this command is a no-op.

\SBEnd[use in words only]{the ending} is used to encapsulate a song ending: it causes the ending to be set with the \SBEndTag, using in the \SBEndTagFont font. The first parameter is optional and if used is put in square brackets; specifying any value except ‘N’ will cause the ending to be used in words only mode. Some examples of its intended use are:

This will cause the ending to be printed in words only mode. Note how the parameter is specified in square brackets!

           \SBEnd[Y]{Give \Ch{F}{thanks,} \ldots}

In this case the ending is a no-op in words only mode.

           \SBEnd{\Ch{A}{} \Ch{B/A}{} \Ch{D}{}}

\SBIntro[use in words only]{the introduction} is used to encapsulate any introduction to a song: it causes the introduction to be set with an intro tag of “Intro:”, using in the \SBIntroTagFont font. The first parameter is optional and if used is put in square brackets; specifying any value except ‘N’ will cause the ending to be used in words only mode. Some examples of its intended use are:

This will cause the ending to be printed in words only mode. Note how the parameter is specified in square brackets!

          \SBIntro[Y]{\Ch{D}{} \Ch{C}{} Ooooh}

In this case the ending is a no-op in words only mode.

          \SBIntro{{\SBLyricNoteFont Guitar and drums}}

\SBMargNote{marginal note} is used to place a note of some kind in the margin of a songbook. In words only mode this macro is a no-op.

\SBRef{book title}{page or song number} creates a reference in the margin to another music book, or tape. This provides a method for directing people to resources they may use to learn the song. The marginal reference only prints when \WordsOnly is \False.

\SBemprints an em-space^{1} when \WordsOnly is \False. See \SBen.

\SBen prints an en-space^{2} when \WordsOnly is \False. This allows us to place a short rule within text in order place a chord earlier than a syllable; yet, that rule will not appear in the words-only book. The words-only version of this macro is a no-op. An example of its intended use is:

           ...flows like a ri\Ch{B/A}{\SBen ver,} flows...

\STitle{song title}{key} prints the song title, preceded by the current \SBSongCnt value and followed by the key the song is given in. \STitle is most often used along with the SBExtraKeys environment. This command resets the \SBVerseCnt and \SBSection-Cnt counters.

\WBPageBrk forces a new page if \ifWordBk is true.

\WOPageBrk forces a new page if \ifWordsOnly is true.

1I.e., an “—” character.

2I.e., an “–” character.

Miscellaneous Commands Not all of the commands listed here are commonly used in songbooks written using one of the songbook styles. The commands are listed alphabetically.

\CpyRt{copyright info.} prints the copyright information line. This command is not usually explicitly used in a songbook. It is called by the song environment and will normally only be used there.

\FLineIdx{first line} make an entry in the Title & First Line Index file, “\jobname.tIdx.”

\HangAmt is the amount to indent when a line wraps. This has been defined using \newcommand instead of \newlength so that any unit definitions are evaluated at the time the \HangAmt command is used.

\SBChorusMarkright hook to allow \SBSection’s \markright to be overridden.

\SBContinueMark conditionally produce a continuation symbol. If the contents of \rightmark will result in nothing being typeset, then don’t output the continuation mark; otherwise, output a continuation mark using the \SBContinueTag command.

\SBSectionMarkright hook to allow \SBSection’s \markright to be overridden.

\SBVerseMarkright hook to allow \SBVerse’s \markright to be overridden.

\SongMarkboth hook to allow the song environment’s \markboth to be overridden.

\STitleMarkboth hook to allow \STitle’s \markboth to be overridden.

\ScriptRef{scripture address} is a scripture reference for the song. This command has its name because the songbook style was written to produce songbooks for the church I am part of. This command is not usually explicitly used in a songbook. It is called by the song environment and will normally only be used there.

\WAndM{lyricist & composer} prints a line telling who wrote the words and music for this song. The string “W&M:” precedes the listing of the lyricist & composer when it is printed. This command is not usually explicitly used in a songbook. It is called by the song environment and will normally only be used there.

Ifthen Commands These if tests are used to perform formatting that is dependent upon the type of songbook you are creating. It is these if tests which allow a single source file to output the three songbook styles.

\ifChordBk are we processing a chordbk.sty document?

\ifNotWordsOnly are we processing a document that displays chords?

\ifOverhead are we processing an overhead.sty document?

\ifSBinSongEnv are we inside of a song environment? This is re-defined as we enter and exit the song environment.

\ifSamepageMode flag that indicates we want the songbook style to try and keep each song together on the same page. Set this true or false using the \SamepageModetrue and \SamepageModefalse commands, respectively.

\ifSongEject do we want to end the current page at the end of every song environment? A value of true means eject after every song environment (default value is true). Set this true or false using the \SongEjecttrue and \SongEjectfalse commands, respectively.

\ifWordBk are we processing a wordbk.sty document?

\ifWordsOnly is true when we are in words only mode. The default value will be false, as that is how all of the commands in this file will act.

Counters These are the counters used in the various environments. Although you will generally not need to use them, they do sometimes come in handy; hence, they have been documented here.

\theSBSongCnt this counter is used for numbering the songs. When a song is listed multiple times (for multiple keys) the songs number must remain the same each time.

\theSBSectionCnt the section counter is used for numbering sections as they occur within a song.

\theSBVerseCnt the verse counter is used for numbering verses as they occur within a song.

Spacing Commands These commands define the amount of space to leave in various situations. Change their values via L^{A}TEX’s \renewcommand command.

All of these spaces are defined as L^{A}TEX commands to overcome limitations in length evaluation. For example, if \LeftMarginSBVerse were to be defined as a length (i.e., using \newlength) and then immediately set to 4em’s, the specific length would be evaluated with respect to the current font. This may not be what is desired; instead a length evaluated with respect to the font in place at the start of an SBVerse is probably what is desired. This can only be done by making these lengths L^{A}TEX commands.

\HangAmt amount to indent when a line wraps.

\LeftMarginSBChorus is the amount of left margin to leave when the \SBChorus environment is in effect.

\LeftMarginSBSection is the amount of left margin to leave when the \SBSection environment is in effect.

\LeftMarginSBVerse is the amount of left margin to leave when the \SBVerse environment is in effect.

\SBChordRaise the distance to raise the chords above the baseline of the text they sit over.

\SBRuleRaiseAmount the distance to raise the rule (as specified by \SBIntersyllableRule) which fills the space between adjoining syllables.

\SpaceAboveSTitle is the amount of vertical space left by the \STitle command before it prints the song title line.

\SpaceAfterChorus is the vertical space to leave after an SBChorus.

\SpaceAfterSection is the vertical space to leave after an SBSection.

\SpaceAfterSong is the vertical space to leave after a song.

\SpaceAfterVerse is the vertical space to leave after an SBVerse.

It is worth noting that the \SpaceAfterChorus, \SpaceAfterSection, and \Space-AfterVerse macros all allow negative glue to be inserted; that is, the space may be shrunk as well as expanded. If this proves problematic (due to sections being visibly pushed into each other, the old spacing (as in versions 1.x and 2.x) can be restored by resetting these macros to 0ex. For example:

         \renewcommand{\SpaceAfterChorus} {0ex\relax}
         \renewcommand{\SpaceAfterSection}{0ex\relax}
         \renewcommand{\SpaceAfterSong}   {0ex\relax}
         \renewcommand{\SpaceAfterVerse}  {0ex\relax}

String Constants These constants are provided so that users may easily customize the appearance of formatted songs and songbooks. Use the \renewcommand command to change the value of these constants.

\SBBridgeTag the Bridge Tag to insert before the start of a bridge. The default value for this is “Bridge:”.

\SBChorusTag the Chorus Tag to insert before the first line of a chorus. The default value for this is “Ch:”.

\SBContinueTag the Continue Tag to insert in an \SBContinueMark. The default value for this is “cont\ldots”.

\SBEndTag the End Tag to insert before the start of an ending (in an \SBEnd command). The default value for this is “End:”.

\SBIntersyllableRule the command(s) to draw the rule between adjoining syllables.

\SBIntroTag the Intro Tag to insert before the start of an introduction (in an \SBIntro command). The default value for this is “Intro:”.

\SBPubDom the string to insert which indicates song is in the public domain. The default value for this is “Public Domain”.

\SBUnknownTag the WAndM string to insert when either the author/artist or the copyright holder is unknown. The default value for this is “Unknown”.

\SBWAndMTag the tag to insert before the words and music entry printed in the song header. The default value for this is “W\&M:”.

Font Handling Fonts are handled by way of L^{A}TEX commands. This was done specifically so that traditional L^{A}TEX font selection occurs; i.e., so that the font commands (like \bf, \textbf, and their friends) are interpreted within the context they are used, rather than the context their are declared within. Change these font specifiers via L^{A}TEX’s \renewcommand.

Of all the font selection songbook macros, only one is commonly used by someone writing a songbook: \SBLyricNoteFont. All the other font macros are only used by an author to over-ride default behaviour, via the \renewcommand command.

\ChBassFont sets the font for the bass note in chords as printed by the \Ch, \Chr and \ChX commands.

\ChFont sets the font for chords as printed by the \Ch, \Chr, and \ChX commands.

\ChBkFont sets the font for square brackets typeset inside \Ch commands (and its variants).

\CpyRtFont sets the font used to print the copyright line produced by the \CpyRt command.

\CpyRtInfoFont sets the font used to print the copyright licensing information parameter of the song environment; which appears after the copyright information parameter under the song title.

\SBBracketTagFont sets the font used to create the tag for an SBBracket environment.

\SBChorusTagFont sets the font used to print the chorus tag, \SBChorusTag.

\SBDefaultFont sets the default font for the songbook. For this command to be effective it should appear within the songbook itself, directly following \begin{document}.

\SBIntroTagFont sets the font used to print the introduction tag, \SBIntroTag.

\SBLyricNoteFont sets the font used in comments placed within the lyrics giving musical direction. This is the only font command commonly used by the writer of a songbook. For example, to tag a line to be sung only by the Cantor and another by everyone, one would write:

                 {\SBLyricNoteFont (Cantor)} Give thanks to the Lord.
                 {\SBLyricNoteFont (All)} His love endures forever.

\SBOccursBrktFont sets the font used to create the large left and right square brackets which delimit an SBOccurs environment.

\SBOccursTagFont sets the font used to create the SBOccurs tag, \SBOccursTag.

\SBRefFont sets the font used in the marginal reference printed by the \SBRef command.

\SBVerseNumberFont sets the font used to print the \SBVerseCnt in front of verses in an SBVerse environment.

\SBSectionNumberFont sets the font used to print the \SBSectionCnt in front of sections in an SBSection environment.

\STitleFont sets the font used to print the song title, as generated by the \STitle command.

\STitleKeyFont sets the font used to print the key a song is written in, as generated by the \STitle command.

\STitleNumberFont sets the font used to print the \SBSongCnt in front of the song title, as generated by the \STitle command.

\ScriptRefFont sets the font used to print the scripture reference generated by the \ScriptRef command.

\WandMFont sets the font used to print the lyricist and composer line generated by the \WandM command.

Deprecated Commands The following commands will be discontinued in some future release of the songbook style:

\ChordBk is set to \True if we’re producing words and chord books. Set to \False, otherwise. Superceded by the \ifChordBk if.

\False is a constant used in TEX \if expressions. This command is now unnecessary.

\lyricNoteFont the old command to set the font for a note. This is now an alias for the \SBLyric-NoteFont command.

\oCh{chord}{syllable} the \Ch command as defined in versions of the songbook style prior to v3.0. Replaced with a new \Ch command.

\oChX{chord}{syllable} the \ChX command as defined in versions of the songbook style prior to v3.0. Replaced with a new \ChX command.

\Overhead is set to \True if we’re producing overhead transparencies. Set to \False, otherwise. Superceded by the \ifOverhead if.

\SBinSongEnv is a flag indicating whether or not we are inside a song environment. It is re-defined as we enter and exit the song environment. Superceded by the \ifSBinSongEnv if.

\SongEject is a flag indicating whether or not the \song environment should end the current page when the environment ends: \True means end the page when the \song environment ends; \False means don’t end the page. Superceded by the \ifSongEject if.

\True is a constant used in TEX \if expressions. This command is now unnecessary.

\WordBk is the flag which tells us whether we’re producing a songbook with just words that is not a set of overhead masters. Superceded by the \ifWordBk if.

\WordsOnly is the flag which tells us whether we’re producing a songbook with just words, or set of overhead masters. Superceded by the \ifWordsOnly if.

USAGE GUIDELINES This section gives some guidelines for use of the commands and environments offered by the songbook style. These are not absolute standards, merely the suggestions that I have come up with after entering some 300 songs into a songbook style based songbook. These guidelines rarely justify themselves, try things out and decide for yourself whether they’re right or wrong.

1. Make each line of a song its own paragraph. This means that the songbook file is mostly double spaced. This allows the file to more easily survive encounters with users who edit the songbook source using a non-text-editor, such as WordPerfect.

2. Use of the \Ch command:

• Always try to attach a chord to a single syllable. If you need to include more than one syllable with the chord then include extra text in units of syllables (whenever possible). For example:

         Do: \Ch{G}{Halle}luia
         Don’t: \Ch{G}{Hall}eluia

• Always include punctuation along with a syllable that has been included in a \Ch command. For example:

Do: \Ch{G}{Lord!}

Don’t: \Ch{G}{Lord}!

• Only place a single chord within a \Ch command. For example:

Do: \Ch{[}{}\Ch{G}{} \Ch{D}{}\Ch{]}{} Don’t: \Ch{[G D]}{}

• Every line must contain at least one \Ch command; even if it’s an empty one. For example:

Do: Behold your God!\Ch{}{}
Don’t: Behold your God!

3. Extension of syllables. Syllables may be extended at either/or both ends. Each end should be done in a different way:

(a) One usually needs to make a syllable longer because the chord it is tied to is too long. This type of extension should be done using the \Chr command.

Do: \Chr{G#m7/C}{Ho}\Ch{C}{ly}
Don’t: \Ch{G#m7/C}{Ho\SBem}\Ch{C}{ly}

(b) Extending the beginning (i.e., delaying the start) of a syllable is generally required because the chord change needs to occur between syllables. For example, when the chord change is on the beat and the syllable is sung off-beat. Use \SBen and \SBem for this purpose.

Do: none Ho\Ch{D}{\SBen ly}

4. Typographic conventions. L^{A}TEX knows about certain ligatures; that is, it groups certain sequences of letters into a single character unit. ff is one of these ligatures and is typeset in a special way; however this cannot occur if the f’s are split by a \Ch command. Therefore, if at all possible, never split up the following character sequences with the \Ch command: ff, fi, ffi, fl, ffl.

Do: \Ch{C}{diffi}cult
Don’t: \Ch{C}{dif}ficult

5. Ordering of songs in the songbook. In order to allow L^{A}TEX to fill pages in as natural a manner as possible, it is best to order the songs within the songbook based upon a wordbk formatted songbook. In that way, the words-only songbooks will contain optimally filled columns. Start by placing the longest songs first, only inserting shorter songs to cause page breaks at logical intervals.

6. Overheads that occupy more than one page. When in overhead mode, if a song spills over onto a second page (or beyond), it is helpful to print an extra header at the top of the page identifying which song the extra page belongs to. This is accomplished with the \OHContPgHdr macro. For example, one would insert the following lines where the new page is to occur:

             \OHPageBrk
             \OHContPgHdr

INDEX/TOC GENERATION The songbook style provides facilities for title/first line index, song key index and table of contents generation. While this facility is not yet completely developed, it is much better than it was in earlier releases, and it produces very usable output!

Table of Contents Generation Steps to follow in order to produce a table of contents:

1. Add a \makeTitleContents command to the preamble of your songbook.

2. Run L^{A}TEX on the songbook source.

3. Make your own copy of sampleToc.tex and customize its header and footer definitions (so they match your songbook’s). Then change the name of the file being \input’ed to match your table of contents file.

4. Run L^{A}TEX on your copy of sampleToc.tex.

Title & First Line Index Generation Steps to follow in order to produce a title and first line index:

1. Add a \makeTitleIndex command to the preamble of your songbook.

2. Run L^{A}TEX on the songbook source.

3. Run the ./mksbtdx shell script on the .tIdx file that was produced by the previous step. Do this by typing “mksbtdx jobname” at a UNIX command line. For example, the index file for sample-sb.tex was produced by typing “mksbtdx sample-sb”.

4. Make your own copy of sampleTdx.tex and customize its header and footer definitions (so they match your songbook’s). Then change the name of the file being \input’ed to match your index file. (./mksbtdx told you this file’s name).

5. Run L^{A}TEX on your copy of sampleTdx.tex.

Song Key Index Generation Steps to follow in order to produce a song key index:

1. Add a \makeKeyIndex command to the preamble of your songbook.

2. Run L^{A}TEX on the songbook source.

3. Run the ./mksbkdx shell script on the .kIdx file that was produced by the previous step. Do this by typing “mksbkdx jobname” at a UNIX command line. For example, the key index file for sample-sb.tex was produced by typing “mksbkdx sample-sb”.

4. Make your own copy of sampleKdx.tex and customize its header and footer definitions (so they match your songbook’s). Then change the name of the file being \input’ed to match your index file. (./mksbkdx told you this file’s name).

5. Run L^{A}TEX on your copy of sampleKdx.tex.

EXAMPLE Here is an example songbook; where the the songbook contains exactly one song.

\documentstyle[12pt,chordbk]{book}     %% Songsheet with chords.
%%%
% C.C.L.I. license number definition; for copyright licensing info.
%%%
\newcommand{\CCLInumber}{\#999999}
\newcommand{\CCLIed}{(CCLI \CCLInumber)}
\newcommand{\NotCCLIed}{}
\newcommand{\PGranted}{}
\newcommand{\PPending}{(Permission Pending)}
%%%
% Turn on index and table of contents.
%%%
\makeTitleIndex         %% Title and First Line Index.
\makeTitleContents      %% Table of Contents.
\makeKeyIndex           %% Song Key Index.
\begin{document}
%%%
% Font selection for document's default font.
%%%
\SBDefaultFont
%%%
% Songbook begins.
%%%
\begin{song}{What A Mighty God We Serve}{C}
  {Public Domain}
  {Unknown}
  {Isaiah 9:6}
  {\NotCCLIed}
  \SBRef{Hosanna! Music Book~I}{\#93}
  \Ch{C#}{What} a mighty God we serve,

Version: 3.1  Last change: 13 November, 1999  17

What a mighty God we \Ch{G7}{serve},
\Ch{Cb}{An}gels bow before Him,
\Ch{C}{Hea}ven and earth adore Him,
\Ch{C}{What} a mighty \Ch{G7}{God} we \Ch{C}{serve!}\Ch{[}{}\Ch{F}{}
\Ch{C}{}\Ch{]}{}
\begin{SBVerse}
  O \Ch{C}{Zion,} O \Ch{F}{Zion,} that \Ch{G7}{bring}est good
  \Ch{C}{tid}ings,
  Get thee \Ch{F}{up} into the \Ch{G7}{High} Moun\Ch{C}{tains}
  Je\Ch{C}{ru}salem, Je\Ch{F}{ru}salem, that \Ch{G7}{bring}est good
  \Ch{C}{tid}ings
  Lift up thy \Ch{F}{voice} with \Ch{G7}{all} thy \Ch{C}{strength}
  Lift it \Ch{F}{up,} be not afraid;
  Lift it \Ch{C}{up,} be not afraid
  Say \Ch{Am}{unto} the \Ch{C}{ci}ties of \Ch{G7}{Judah,}
  ``Behold your \Ch{C}{God,}\Ch{C7}{} Behold your \Ch{F}{God,}
  Be\Ch{C}{hold} \Ch{G7}{your} \Ch{C}{God!''}
\end{SBVerse}
\begin{SBExtraKeys}{
\CBPageBrk
\STitle{What A Mighty God We Serve}{D}
\Ch{Eb}{What} a mighty God we serve,
What a mighty God we \Ch{A7}{serve},
\Ch{C#}{An}gels bow before Him,
\Ch{D}{Hea}ven and earth adore Him,
\Ch{D}{What} a mighty \Ch{A7}{God} we \Ch{D}{serve!}\Ch{[}{}\Ch{G}{}
\Ch{D}{}\Ch{]}{}
\begin{SBVerse}
  O \Ch{D}{Zion,} O \Ch{G}{Zion,} that \Ch{A7}{bring}est good
  \Ch{D}{tid}ings,

Version: 3.1  Last change: 13 November, 1999  18

    Get thee \Ch{G}{up} into the \Ch{A7}{High} Moun\Ch{D}{tains}
    Je\Ch{D}{ru}salem, Je\Ch{G}{ru}salem, that \Ch{A7}{bring}est good
    \Ch{D}{tid}ings
    Lift up thy \Ch{G}{voice} with \Ch{A7}{all} thy \Ch{D}{strength}
    Lift it \Ch{G}{up,} be not afraid;
    Lift it \Ch{D}{up,} be not afraid
    Say \Ch{Bm}{unto} the \Ch{D}{ci}ties of \Ch{A7}{Judah,}
    ``Behold your \Ch{D}{God,}\Ch{D7}{} Behold your \Ch{G}{God,}
    Be\Ch{D}{hold} \Ch{A7}{your} \Ch{D}{God!''}
  \end{SBVerse}
 }\end{SBExtraKeys}
\end{song}
\end{document}
\bye

DEPENDENCIES The songbook style is dependent upon two other L^{A}TEX styles: conditional.sty and ifthen.sty. Conditional.sty is supplied with this package, and ifthen.sty is part of the L^{A}TEX2e distribution.

Embedding chords within a songbook can be accomplished with the texchord.sty package; which is supplied in the contrib directory of the songbook distribution.

FILES chordbk.sty Words and chords substyle. conditionals.sty Donald Arseneau’s conditional tests. mksbkdx A shell script around makeindex to sort the song key index. mksbtdx A shell script around makeindex to sort the title & first line

index.

overhead.sty Overhead transparency substyle. relnotes.txt The songbook package release notes. sample-sb.tex A sample songbook. sampleKdx.tex Song key index for the sample songbook. sampleTdx.tex Title & first line index for the sample songbook. sampleToc.tex TOC for the sample songbook. sb-manpg.tex This manual page. songbook.ist The songbook package makeindex .ist file. songbook.sty The base style file. wordbk.sty Words only substyle.

SEE ALSO

The songbook homepage, at URL http://www.cyberus.ca/~crath/Misc/Songbook/

latex(1L), tex(1L), makeindex(1L) The TEXbook, by Donald Knuth L^{A}TEX A Document Preparation System, by Leslie Lamport

Competing Packages There are a number of song and songbook formatting packages available which attempt to provide similar functionality to the songbook package (although, IMHO, my package is better). Similar L^{A}TEXpackages (of which the author is aware) include:

chord.sty Olivier Biot’s (mailto:Olivier.Biot@rug.ac.be) song formatting package. This package is based upon L^{A}TEX’s article style and is available from Olivier’s homepage,

      at URL http://studwww.rug.ac.be/~obiot/.

Song.sty Jens T. Berger Thielemann’s (mailto:jensthi@ifi.uio.no) package to create songbooks. This package is based upon L^{A}TEX’s book style and is available from its author. Jens’ homepage can be found at URL http://www.ifi.uio.no/~jensthi/.

BUGS In the specific case where a \Ch, \Chr, or \ChX macro begins a paragraph, that line may not indent properly in the chordbk substyle (specifically, a long, wrapped line won’t have its extra indentation). I have been unable to identify the reason for the problem, although it is easily reproducible. The work-around to this problem is to begin such lines with a \mbox{} command; this inserts an empty (i.e., zero width) mbox at the start of the line. For example:

         \mbox{}\Ch{G}{Great} is the Lord \Ch{A}{even} beyond the
           \Ch{D}{borders} of I\Chr{F#m}{srae}\Ch{Bm7}{l;}

Due to the recent change in the the \Ch macro (and its variants), the \emph macro is no longer completely compatible with \Ch. The specific problem is that sharps can not be specified via ‘#’ within a \emph macro. The following snippet will fail with

the L^{A}TEX message, “!  Illegal parameter number in definition of \reserved@a.
<to be read again>”:
         \emph{for the \Ch{G/A}{King} of} \Ch{F#}{kings.}}

The error message can be supressed by replacing ‘#’ with ‘##’, however this results in a double-sharp being typeset. The problem can be worked-around by replacing the snippet with:

         \emph{for the \Ch{G/A}{King} of} \Ch{F#}{\emph{kings.}}

SPECIAL THANKS Thanks to Donald Arseneau for writing the conditionals.sty file, and for helping write the \Chord macro. Donald, you are one of the faithful who is always quick to reply with correct answers to questions posted to comp.text.tex. Thanks again.

Thanks also to Philip Hirschhorn whose \Chord macro I ultimately used in versions 1.0–2.3 of the songbook style, and to Olivier Boit who constructed a similar chord macro which I used to enhance Philip’s code for version 3.0

A quick thank you to Herbert Martin Dietze <herbert@fh-wedel.de> for noting that SB-Verse* and its cousins were missing from the .sty file, and then coding up an acceptable SBVerse* which I could quickly use as a model for the other two missing environments.

AUTHOR Christopher Rath mailto:crath@cyberus.ca (613) 824-4584 1371 Major Rd. Orleans, ON Canada K1E 1H3