% \iffalse meta-comment % -*- LaTeX -*-
%       rcsid = @(#)$Id: songbook.dtx,v 1.12 2006/10/15 15:49:50 rathc Exp $
%
%
%       songbook.sty - Generic SongBook style.
%
%       Version 4.2, 13 October, 2006
%
%       Copyright 1992--2006 Christopher Rath <christopher@rath.ca>
%
%       This package is free software; you can redistribute it and/or
%       modify it under the terms of version 2.1 of the GNU Lesser 
%       General Public License as published by the Free Software 
%       Foundation.
%
%       This package is distributed in the hope that it will be
%       useful, but WITHOUT ANY WARRANTY; without even the implied
%       warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
%       PURPOSE.  See the GNU Lesser General Public License for more
%       details.
%
% \fi
%
% \CheckSum{2178}
%% \CharacterTable
%%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%%
%\iffalse    This is a METACOMMENT
%           Everything up to the next `\ fi' (without a blank) will
%           be ignored.  This is necessary because `%' may no longer
%           be a comment mark when this file is read in.
%           
% Version:     Date:     Changes:
%
%  4.0 and earlier...    are not documented in this file.
%  \changes{v4.1}{2003/08/31}{Added an optional parameter to the \textsf{song}
%                       environment along with a corresponding usepackage option.}
%  \changes{v4.1a}{2003/09/22}{Corrected a bug whereby the new exclude song mode
%                       was throwing an error when the \textsf{SBRef} and
%                       \textsf{SBMargNote} commands were used.}
%  \changes{v4.2}{2006/10/13}{Added abilty to create an index by song artist.}
%\fi
%
% \hyphenation{make-index}
% 
% \DoNotIndex{\@,\@@par,\@beginparpenalty,\@empty}
% \DoNotIndex{\@flushglue,\@gobble,\@input}
% \DoNotIndex{\@makefnmark,\@makeother,\@maketitle}
% \DoNotIndex{\@namedef,\@ne,\@spaces,\@tempa}
% \DoNotIndex{\@tempb,\@tempswafalse,\@tempswatrue}
% \DoNotIndex{\@thanks,\@thefnmark,\@topnum}
% \DoNotIndex{\@@,\@elt,\@forloop,\@fortmp,\@gtempa,\@totalleftmargin}
% \DoNotIndex{\",\/,\@ifundefined,\@nil,\@verbatim,\@vobeyspaces}
% \DoNotIndex{\|,\~,\ ,\active,\advance,\aftergroup,\begingroup,\bgroup}
% \DoNotIndex{\mathcal,\csname,\def,\documentstyle,\dospecials,\edef}
% \DoNotIndex{\egroup}
% \DoNotIndex{\else,\endcsname,\endgroup,\endinput,\endtrivlist}
% \DoNotIndex{\expandafter,\fi,\fnsymbol,\futurelet,\gdef,\global}
% \DoNotIndex{\hbox,\hss,\if,\if@inlabel,\if@tempswa,\if@twocolumn}
% \DoNotIndex{\ifcase}
% \DoNotIndex{\ifcat,\iffalse,\ifx,\ignorespaces,\index,\input,\item}
% \DoNotIndex{\jobname,\kern,\leavevmode,\leftskip,\let,\llap,\lower}
% \DoNotIndex{\m@ne,\next,\newpage,\nobreak,\noexpand,\nonfrenchspacing}
% \DoNotIndex{\obeylines,\or,\protect,\raggedleft,\rightskip,\rm,\sc}
% \DoNotIndex{\setbox,\setcounter,\small,\space,\string,\strut}
% \DoNotIndex{\strutbox}
% \DoNotIndex{\thefootnote,\thispagestyle,\topmargin,\trivlist,\tt}
% \DoNotIndex{\twocolumn,\typeout,\vss,\vtop,\xdef,\z@}
% \DoNotIndex{\,,\@bsphack,\@esphack,\@noligs,\@vobeyspaces,\@xverbatim}
% \DoNotIndex{\`,\catcode,\end,\escapechar,\frenchspacing,\glossary}
% \DoNotIndex{\hangindent,\hfil,\hfill,\hskip,\hspace,\ht,\it,\langle}
% \DoNotIndex{\leaders,\long,\makelabel,\marginpar,\markboth,\mathcode}
% \DoNotIndex{\mathsurround,\mbox,\newcount,\newdimen,\newskip}
% \DoNotIndex{\nopagebreak}
% \DoNotIndex{\parfillskip,\parindent,\parskip,\penalty,\raise,\rangle}
% \DoNotIndex{\section,\setlength,\TeX,\topsep,\underline,\unskip,\verb}
% \DoNotIndex{\vskip,\vspace,\widetilde,\\,\%,\@date,\@defpar}
% \DoNotIndex{\[,\{,\},\]}
% \DoNotIndex{\count@,\ifnum,\loop,\today,\uppercase,\uccode}
% \DoNotIndex{\baselineskip,\begin,\tw@}
% \DoNotIndex{\a,\b,\c,\d,\e,\f,\g,\h,\i,\j,\k,\l,\m,\n,\o,\p,\q}
% \DoNotIndex{\r,\s,\t,\u,\v,\w,\x,\y,\z,\A,\B,\C,\D,\E,\F,\G,\H}
% \DoNotIndex{\I,\J,\K,\L,\M,\N,\O,\P,\Q,\R,\S,\T,\U,\V,\W,\X,\Y,\Z}
% \DoNotIndex{\1,\2,\3,\4,\5,\6,\7,\8,\9,\0}
% \DoNotIndex{\!,\#,\$,\&,\',\(,\),\+,\.,\:,\;,\<,\=,\>,\?,\_}
% \DoNotIndex{\discretionary,\immediate,\makeatletter,\makeatother}
% \DoNotIndex{\meaning,\newenvironment,\par,\relax,\renewenvironment}
% \DoNotIndex{\repeat,\scriptsize,\selectfont,\the,\undefined}
% \DoNotIndex{\arabic,\do,\makeindex,\null,\number,\show,\write,\@ehc}
% \DoNotIndex{\@author,\@ehc,\@ifstar,\@sanitize,\@title,\everypar}
% \DoNotIndex{\if@minipage,\if@restonecol,\ifeof,\ifmmode}
% \DoNotIndex{\lccode,\newtoks,\onecolumn,\openin,\p@,\SelfDocumenting}
% \DoNotIndex{\settowidth,\@resetonecoltrue,\@resetonecolfalse,\bf}
% \DoNotIndex{\clearpage,\closein,\lowercase,\@inlabelfalse}
% \DoNotIndex{\selectfont,\mathcode,\newmathalphabet,\rmdefault}
% \DoNotIndex{\bfdefault}
% \DoNotIndex{\^}
%
% \MakeShortVerb{\|}
% \setcounter{StandardModuleDepth}{1}
% \renewcommand{\partname}{Part}
%
% {\catcode`\p=12 \catcode`\t=12 ^^A hack used later on to print
% \gdef\dimenvalue#1pt{$#1$pt}}  ^^A a register value with a - sign
%
% \newcommand{\Songbook}{\textrm{Song$\flat$ook}}
% \GetFileInfo{songbook.dtx}
%
% \title{The \Songbook{} Package\\
%        {\large Version 4.2}}
% \author{Christopher Rath\\
%         {\small$<$\texttt{Christopher@Rath.ca}$>$}}
% \date{2006/10/10}
% \maketitle
% 
% \begin{abstract}
%   This package provides an all purpose songbook style for \LaTeX2e.
%   The package allows for three types of output from a single input
%   file: words and chords books for the musicians to play from, words
%   only songbooks for the congregation to sing from, and overhead
%   transparency masters for congregational use.  The style will also
%   print a table of contents, an index sorted by title and first line,
%   and an index sorted by key.  It attempts to handle songs in multiple
%   keys, as well as songs in multiple languages.
% \end{abstract}
% 
% {\parskip 0pt                ^^A We have to reset \parskip
%                              ^^A (bug in \LaTeX)
% \tableofcontents
% }
% 
% \section*{Preface to version 4.2}
% What's new in version~4.2:
% \begin{itemize}
%  \item added a new Artist index option
% \end{itemize}
%
% \section*{Preface to version 4.1a}
% What's new in version~4.1a:
% \begin{itemize}
%  \item Corrected a bug whereby the new exclude song mode was throwing 
%   an error when either the |\SBRef| or |\SBMargNote| commands were used
% \end{itemize}
% 
% \section*{Preface to version 4.1}
% 
% What's new in version~4.1:
% \begin{itemize}
%  \item a new optional \meta{Include?} parameter has been added to 
%   the |song| environment; that parameter allows you to have a song omitted 
%   from the printed songbook yet still have the song counter incremented 
%   and the song's table of contents entry written to a separate TOC file 
%   (see the description of the |song| environment, below, for more details)
%
%  \item to go along with the new optional \meta{Include?} parameter 
%   is a new |\usepackage{}| option, |printallsongs|, which overrides the
%   individual song option declarations and prints all the songs in the
%   songbook
%  
%  \item the song ``My Sun and My Shield'' was removed from the sample songbook;
%   it turns out that this is a Ted Sandquist song and is not in the public
%   domain
%
%  \item |chordbk|'s |compactsong| option is still experimental
% \end{itemize}
% 
% \section*{Preface to version 4.0}
% What's new in version~4.0:
% \begin{itemize}
%  \item the \Songbook{} style has now completed its
%   transition to \LaTeX2e (I \emph{think}): there is now a single \texttt{.sty} file
%   which accepts options in order to invoke the different songbook
%   styles.  The \Songbook{} style now also accepts and produces
%   reasonable output for all of \LaTeX2e's standard papersize options.
% 
%  \item the song title block (where the title, copyright info., etc.
%   are listed) has been changed, use of the |\centerline| macro has
%   been replaced with a |center| environment.  This change is \emph{not
%     compatible} with previous versions of \texttt{songbook.sty} and
%   requires you to re-verify all page breaks (mostly in words-only
%   mode).  The reason for making the change is to allow long song
%   titles to line-wrap (instead of hanging off the edge of the page),
%   and this means that the definition of the following macros has been
%   changed: |\STitle|, |\CpyRt|, |\WAndM|, and |\ScriptRef|.  The
%   centering of these lines is now also done within a center
%   environment; in each the centering may now be disabled by adding an
%   optional first parameter (any value except `|Y|')
% 
%  \item since the change to the title block invalidated pagination of
%   the previous version I have taken the opportunity to fine tune the
%   value of |\SpaceAfterSong|, a value that is used primarily in
%   words-only mode: the inter-song gap has been decreased to
%   |\vspace{0ex| |plus10ex| |minus3ex}| (from |\vspace{0ex| |plus15ex|
%     |minus0ex}|)
% 
%  \item a new space command, |\SpaceAfterTitleBlk|, has been created to
%   allow the space between a song's title block and its versicles to be
%   tuned by the user; this was a previously hardcoded value
%
%  \item a bug in the |SBBracket| environment has been corrected: long
%   lines were not always exhibiting their hanging indentation
%
%  \item the style now supports all of \LaTeX2e's standard papersizes.
%   While the output will not be ideal for all papersizes, it does
%   produce sane and usable results for all papersizes.  I would be most
%   appreciative if European users would send me page layout corrections
%   for the A4, A5, and B5 sizes
% 
%  \item added a new environment, |SBOpGroup| (i.e., ``an open group''),
%   serves to group the lines of a verse or chorus together, but not
%   indent or label them.  Use of this environment allows for better
%   control of font changes, proper indentation of wrapped lines, and
%   automatic spacing of open groups which follow one another.  I
%   strongly suggest that |SBOpGroup| be used to enclose any set of
%   lines which don't otherwise end up in one of the songbook
%   environments when typsetting with this package
% 
%  \item |chordbk| mode now supports one variation: |compactsong|.  In
%   |compactsong| mode the songs are laid out in two columns; note that
%   the song title block spans the two columns.  The songs are set in a
%   smaller typeface to allow them to fit into the smaller space two
%   column mode supplies.  This mode should be considered experimental
%   for the present time; see its description, below, for more details
% 
%  \item |conditionals.sty| has been updated with more current
%   information and macros, as supplied by Donald Arseneau
% 
%  \item all of the verse-like environments now have their |\baselineskip|
%   amount expressly calculated just prior to laying out their lines.
%   This has been done in order to overcome the problem all previous
%   versions of the songbook style had which was that linespacing
%   differed based upon whether a particular line contained chords.  Now
%   all lines are spaced the same, regardless of whether they contain a
%   chord.  I consider the previous behaviour---where linespacing
%   varied---to be a bug.  If you really must retain the old behaviour
%   this can be done by inserting the following code into the preamble
%   of your document:
%   \begin{verbatim}
%     \renewcommand{\sbSetsbBaselineSkipAmt}
%       {\setlength{\sbBaselineSkipAmt} {\baselineskip}}
%   \end{verbatim}
% 
%  \item the |\SBDefaultFont| command no longer needs to be specified at
%   the top of each songbook
%
%  \item fixed a bug that was inhibiting the \Songbook{} style from 
%   detecting blank and empty |song| parameters
% 
%  \item the commands which had previously been listed as deprecated
%   (i.e., to be removed in some future release) have all been removed
% 
%  \item the following commands have been moved from the ``Obsolete
%   Macros'' section into ``Deprecated Macros'' section and will be
%   removed in the next major release of the \Songbook{} style:
%   |\False|, |\True|, |\ChordBk|, |\Overhead|, |\SongEject|, |\WordBk|,
%   and |\WordsOnly|
% \end{itemize}
% 
% A few minor changes were made during release testing of version~4.0.
% The following changes occured between version~4.0pre2 and~4.0:
% \begin{itemize}
%  \item the spacing around the |SBBracket| environment has been
%   \emph{tuned}:\\
%   |\SpaceAfterSBBracket| has been increased, and a new\\
%   |\SpaceBeforeSBBracket| amount has been added
%
%  \item added missing space around the |SBBracket*| environment; using\\
%   |\SpaceBeforeSBBracket| and |\SpaceAfterSBBracket|
%
%  \item removed unused length, |\SBBracketHangAmt|
%
%  \item added a new |\LeftMarginSBBracket| length and rewrote the part
%   of the |SBBracket| environment that creates the tag and left indents
%   the versicle.  The |SBBracket| environment now left aligns its words
%   with those of the |SBVerse| and |SBChorus| versicles.
% \end{itemize}
% 
% \part{High Level Documentation}
% \section{Description}
% 
% The \Songbook{} document style provides a core set of functions for
% the production of songbooks.  Three pre-defined songbook formats and
% one variation are provided (and they are invoked via options to the
% |\usepackage{songbook}| command) and they are typically used along
% with \LaTeX's |book| class.  One of the following options \emph{must}
% be specified or the \Songbook{} style will throw an error: |chordbk|,
% |wordbk|, or |overhead|.
% 
% An empty minimal songbook looks like the following:
% \begin{verbatim}
%   \documentclass{book}
%   \usepackage[chordbk]{songbook}
% 
%   \begin{document}
%     \begin{song}{}{}{}{}{}{}
%     \end{song}
%   \end{document}
% \end{verbatim}
% 
% We'll start by explaining the |\usepackage[]{songbook}| options:
% \begin{description}
%  \item[|chordbk|\ ] \DescribeMacro{chordbk} a songbook suitable for
%   musicians which gives both lyrics and words (this is the default
%   mode of the \Songbook{} document style)---one variation to this
%   style is offered, compact song mode (see below).  This option is
%   specified as |\usepackage[chordbk]{songbook}|
% 
%  \item[|wordbk|\ ] \DescribeMacro{wordbk} a words-only songbook
%   suitable for mass distribution to those singing but not playing
%   an instrument.  This option is specified as\\ 
%   |\usepackage[wordbk]{songbook}|
% 
%  \item[|overhead|\ ] \DescribeMacro{overhead} to produce overhead
%   transparencies from songbook source files.  This option is specified
%   as |\usepackage[overhead]{songbook}|
% \end{description}
% 
% Other additional options supported by the \Songbook{} style include
% all \LaTeX's standard papersize options, and:
% \begin{description}
%  \item[|compactsong|\ ] \DescribeMacro{compactsong} this option only
%   takes effect along with |chordbk|.  It causes the songs to be set in
%   two columns, where the song title information spans the both
%   columns.  It is specified as\\
%   |\usepackage[chordbk,compactsong]{songbook}|
%
%   The version of |compactsong| provided in this release should be 
%   considered experimental!  The formatting produced in this mode 
%   is not always desirable.  An outstanding question to be answered
%   is whether or not new songs title blocks should span both columns,
%   and whether each song should generate a page break; in other words,
%   should this feature set be implemented as two pieces: compactsong
%   and compactbook.  The idea would be to provide a compactsong
%   environment, which could be judiciously used on a per song basis,
%   and a compactbook mode which would result in a compressed songbook,
%   where the words and chords book would look very much like a words
%   only songbook (but with chords).
%
%  \changes{v4.1}{2003/08/31}{Added |printallsongs| documentation.}
%  \item[|printallsongs|\ ] \DescribeMacro{printallsongs} this option
%   causes all songs in a songbook to be printed, regardless of what
%   \meta{Include?} option may have been specified on each
%   individual |song| environment
% \end{description}
% 
% \section{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 \textit{Commands\/} section a
% couple of times before it makes complete sense.
% 
% This reference section will present terse command and environment
% descriptions; more detailed descriptions, along with examples, may be
% found in the implementation detail section at the bottom of this
% document.
% 
% Note that each subsection's descriptions are presented in alphabetical
% order; while this doesn't make the sections quite as easy to read, it
% makes them much more useful for reference purposes.
% 
% \subsection{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 is
% indented.
% 
% \begin{description}
%  \item |\begin{SBBracket}{|\meta{bracket tag}|}|\meta{\ldots stuff to
%       enbracket\ldots}\\ |\end{SBBracket}|
%   \DescribeEnv{SBBracket} is the environment used to mark certain
%   lines 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:
%   \begin{verbatim}
%          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}
%   \end{verbatim}
%   This is very similar to the |SBOccurs| environment, the difference
%   being how the section of the song is marked.
%   
%   \DescribeEnv{SBBracket*} 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.
% 
%   At present, |\SBBracket| and |\SBBracket*| are fragile and are not
%   compatible with |SBVerse|, |SBChorus|, or any other environment; 
%   with the exception of the |song| environment.
%   
%  \item |\begin{SBChorus}|\meta{\ldots the
%       chorus\ldots}|\end{SBChorus}| \DescribeEnv{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 by redefining the |\HangAmt|
%   command.
%   
%   \DescribeEnv{SBChorus*} The |SBChorus*| version of this
%   command indents but does not place a |\SBChorusTag| before the
%   chorus.
%   
%  \item |\begin{SBExtraKeys}{|\meta{song content}|}\end{SBExtraKeys}|
%   \DescribeEnv{SBExtraKeys} is the environment used when you
%   wish to list the song again in another key.  Typically, this
%   environment is used along with an |\STitle| command.  For example:
%   \begin{verbatim}
%       \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}
%   \end{verbatim}
%   
%  \item |\begin{SBOccurs}{|\meta{the occurrence}|}|\meta{\ldots stuff
%       to group\ldots}|\end{SBOccurs}|
%   \DescribeEnv{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:
%   \begin{verbatim}
%          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}
%   \end{verbatim}
%   
%  \item |\begin{SBOpGroup}|\meta{\ldots stuff to
%       group\ldots}|\end{SBOpGroup}| \DescribeEnv{SBOpGroup} is
%   the environment in which unmarked versicles are placed; so called
%   ``open groups''.
%   
%  \item |\begin{SBSection}|\meta{\ldots the
%       section\ldots}|\end{SBSection}| \DescribeEnv{SBSection}
%   is 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 using 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.
%   
%   \DescribeEnv{SBSection*} The |SBSection*| version of this
%   command indents but doesn't place an |\SBSectionCnt| before the
%   chorus.  Similar to \LaTeX's |\section*| command, the section
%   counter is not incremented either.
%   
%  \item |\begin{SBVerse}|\meta{\ldots the chorus\ldots}|\end{SBVerse}|
%   \DescribeEnv{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.
%   
%   \DescribeEnv{SBVerse*} The |SBVerse*| version of this
%   environment indents but down not place an |\SBVerseCnt| before the
%   chorus; similar to \LaTeX's |\section*| command, the verse counter
%   is not incremented either.
%   
%  \item |\begin{song}[|\meta{1}|]{|\meta{2}|}|\ \ldots|{|\meta{7}|}|\ \meta{\ldots
%       the song\ldots}|\end{song}| \DescribeEnv{song} is the
%   environment which each song resides within.  The parameter list is
%   quite long, and is defined as:
%   \begin{enumerate}
%    \item Include this song? (optional);
%    \item Song title;
%    \item Key song is written in;
%    \item Copyright information;
%    \item Name(s) of composer and lyricist;
%    \item Scripture reference for the song;
%    \item Copyright licensing information.
%   \end{enumerate}
%   The |song| environment takes care of making index entries,
%   incrementing |\SBSongCnt| and page generation (if necessary).
%   Note, this environment makes use of |\everypar|.  See the
%   \textit{Example\/} section, below, for a sample one-song songbook
%   document.
%    
%   The ``Include this song?'' parameter is optional; the parameter is referred
%   to within this documentation as ``\meta{Include?}''.  If you don't specify
%   it (and you typically do not), then it behaves as though you provided
%   a value of ``\texttt{Y}''.  If you specify any other value then the
%   song is excluded from the current songbook; however, a table of
%   contents record is written to a separate file
%   (\textit{jobname}|.tocS|).
%
%   \DescribeMacro{\CBExcl}\DescribeMacro{\OHExcl}\DescribeMacro{\WBExcl}
%   \DescribeMacro{\WOExcl}Some predefined macros have been provided
%   which allow conditional exclusion of a song (they are used in the 
%   optional parameter): |\CBExcl|, |\OHExcl|, |\WBExcl|, and |\WOExcl|;
%   respectively, these correspond to exclude in |chordbk| mode,
%   |overhead| mode, |wordbk| mode, and when in words-only (i.e., not in
%   |chordbk|) mode.
%
%   As an organisation's songbook grows, and time passes, it is not 
%   uncommon for the songbook to become overly large.  The \meta{Include?}
%   parameter allows for a songbook's songs to be easily removed
%   and re-added, without requiring old songbooks to be destroyed or
%   overhead transparencies renumbered.
%   
%   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.
%   
%  \item |\begin{xlatn}{|\meta{1}|}|\ \ldots|{|\meta{3}|}|\ \meta{\ldots
%       the translation\ldots}|\end{xlatn}|\DescribeEnv{xlatn}
%   is the song translation environment.  The parameter list is defined
%   as:
%   \begin{enumerate}
%    \item \ Translated song title (in the foreign language);
%    \item \ Translation permission;
%    \item \ Who performed the translation.
%   \end{enumerate}
%   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.
% \end{description}
% 
% \subsection{Primary \Songbook{} Macros}
% Along with the \Songbook{} environments, these are the macros you will
% most often use when constructing a songbook (of any style).
% 
% \begin{description}
%  \item |\CBPageBrk| \DescribeMacro{\CBPageBrk} forces a new page if
%   |\ifChordBk| is true.
%   
%  \item |\Ch{|\meta{chord}|}{|\meta{syllable}|}| \DescribeMacro{\Ch}
%   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 \meta{chord} parameter is left-justified over the
%   \meta{syllable} parameter.  Any `\#' or `b' characters in the
%   \meta{chord} parameter are replaced with `$\sharp$' and `$\flat$'
%   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 \meta{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:
%   \begin{verbatim}
%       \renewcommand{\SBChordRaise}{\SBOldChordRaise}
%   \end{verbatim}
%   
%  \item |\Chr{|\meta{chord}|}{|\meta{syllable}|}| \DescribeMacro{\Chr}
%   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 |\SBRuleRaiseAmount| 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 \textit{Usage Guidelines} section of this document, below,
%   for a more detailed explanation.
%   
%  \item |\ChX{|\meta{chord}|}{|\meta{syllable}|}| \DescribeMacro{\ChX}
%   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 \textit{Usage Guidelines} section of this
%   document, below, for a more detailed explanation.
%   
%  \item |\CSColBrk| \DescribeMacro{\CSColBrk} generates a column break
%   here if we're in |compactsong| mode.
%   
%  \item |\makeArtistIndex| \DescribeMacro{\makeArtistIndex} starts creation
%   of an index of songs by artist (composer).  If you need to add your
%   own information to this index use the |\artistIndex[][]| command, 
%   documented in the \textit{Detailed Documentation} section, below.
%
%  \item |\makeKeyIndex| \DescribeMacro{\makeKeyIndex} starts creation of
%   an index of songs by key.  If you need to add your own information
%   to this index use the |\keyIndex[][]| command, documented in the
%   \textit{Detailed Documentation} section, below.
%   
%  \item |\makeTitleContents| \DescribeMacro{\makeTitleContents} starts
%   creation of a table of contents.  If you need to add your own
%   information to this index use the |\titleContents[][]| command,
%   documented in the \textit{Detailed Documentation} section, below.
%   
%  \item |\makeTitleContentsSkip| \DescribeMacro{\makeTitleContentsSkip} starts
%   creation of a table of contents of songs exluded from the current 
%   songbook.  This macro operates in the same manner as |\makeTitleContents|.
%   
%  \item |\makeTitleIndex| \DescribeMacro{\makeTitleIndex} starts
%   creation of a title and first line index.  If you need to add your
%   own information to this index use the |\titleIndex[][]| command,
%   documented in the \textit{Detailed Documentation} section, below.
%   
%  \item |\NotWOPageBrk| \DescribeMacro{\NotWOPageBrk} forces a new page
%   if |\ifWordsOnly| is false.
%   
%  \item |\OHContPgFtr| \DescribeMacro{\OHContPgFtr} prints a page
%   heading continuation footer on overheads; this macro must be
%   manually inserted where needed.  |\OHContPgHdr| is a no-op, except when
%   |\ifOverhead| is true.
%   
%  \item |\OHContPgHdr| \DescribeMacro{\OHContPgHdr} prints a page
%   heading continuation header on overheads; this macro must be
%   manually inserted where needed.  |\OHContPgHdr| is a no-op, except when
%   |\ifOverhead| is true.
%   
%  \item |\OHPageBrk| \DescribeMacro{\OHPageBrk} forces a new page if
%   |\ifOverhead| is true.
%   
%  \item |\SBBridge{|\meta{the bridge}|}| \DescribeMacro{\SBBridge}
%   is used to encapsulate a bridge: it causes \meta{the bridge} to be
%   set with |\SBBridgeTag|, using in the |\SBBridgeTagFont| font.  In
%   words-only mode this command is a no-op.
%   
%  \item |\SBEnd[|\meta{use in words-only}|]{|\meta{the ending}|}|
%   \DescribeMacro{\SBEnd} is used to encapsulate a song ending: it
%   causes \meta{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:
%   \begin{description}\item
%     \emph{This will cause the ending to be printed in words-only mode.  Note
%     how the parameter is specified in square brackets!}
%    \begin{verbatim}
%       \SBEnd[Y]{Give \Ch{F}{thanks,} \ldots}
%    \end{verbatim}
% 
%    \emph{In this case the ending is a no-op in words-only mode.}
%    \begin{verbatim}
%       \SBEnd{\Ch{A}{} \Ch{B/A}{} \Ch{D}{}}
%    \end{verbatim}
%   \end{description}
%   
%  \item |\SBIntro[|\meta{use in words-only}|]{|\meta{the
%       introduction}|}| \DescribeMacro{SBIntro} is used to encapsulate
%   any introduction to a song: it causes \meta{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:
%   \begin{description}\item
%     \emph{This will cause the ending to be printed in words-only mode.
%       Note how the parameter is specified in square brackets!}
%    \begin{verbatim}
%      \SBIntro[Y]{\Ch{D}{} \Ch{C}{} Ooooh}
%    \end{verbatim}
% 
%    \emph{In this case the ending is a no-op in words-only mode.}
%    \begin{verbatim}
%      \SBIntro{{\SBLyricNoteFont Guitar and drums}}
%    \end{verbatim}
%   \end{description}
%   
%  \item |\SBMargNote{|\meta{marginal note}|}|
%   \DescribeMacro{\SBMargNote} 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.
%   
%  \item |\SBRef{|\meta{book title}|}{|\meta{page or song number}|}|
%   \DescribeMacro{\SBRef} 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|.
%   
%  \item |\SBem| \DescribeMacro{\SBem} prints an \textit{em-dash} (i.e.,
%   ``---'') when |\WordsOnly| is |\False.| See |\SBen|.
%   
%  \item |\SBen| \DescribeMacro{\SBen} prints an \textit{en-dash} (i.e.,
%   ``--'') 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:
%   \begin{verbatim}
%       ...flows like a ri\Ch{B/A}{\SBen ver,} flows...
%   \end{verbatim}
%   
%  \item |\STitle{|\meta{song title}|}{|\meta{key}|}|
%   \DescribeMacro{\STitle} prints the \meta{song title}, preceded by
%   the current |\SBSongCnt| value and followed by the \meta{key} the
%   song is given in.  |\STitle| is most often used along with the
%   |SBExtraKeys| environment.  This command resets the |\SBVerseCnt|
%   and |\SBSectionCnt| counters.
%   
%  \item |\WBPageBrk| \DescribeMacro{\WBPageBrk} forces a new page if
%   |\ifWordBk| is true.
%   
%  \item |\WOPageBrk| \DescribeMacro{\WOPageBrk} forces a new page if
%   |\ifWordsOnly| is true.
% \end{description}
% 
% \subsection{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.
% 
% \begin{description}
%  \item |\CpyRt{|\meta{copyright info.}|}| \DescribeMacro{\CpyRt}
%   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.
%   
%  \item |\FLineIdx{|\meta{first line}|}| \DescribeMacro{\FLineIdx} make
%   an entry in the \textit{Title \& First Line Index\/} file,
%   ``\texttt{\textit{jobname}}|.tIdx|.''
% 
%  \item |\SBChorusMarkright| \DescribeMacro{\SBChorusMarkright} hook to
%   allow |\SBSection|'s |\markright| to be overridden.
%   
%  \item |\SBContinueMark| \DescribeMacro{\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.
%   
%  \item |\SBSectionMarkright| \DescribeMacro{\SBSectionMarkright} hook
%   to allow |\SBSection|'s |\markright| to be overridden.
%   
%  \item |\SBVerseMarkright| \DescribeMacro{\SBVerseMarkright} hook to
%   allow |\SBVerse|'s |\markright| to be overridden.
%   
%  \item |\SongMarkboth| \DescribeMacro{\SongMarkboth} hook to allow the
%   song environment's |\markboth| to be overridden.
%   
%  \item |\STitleMarkboth| \DescribeMacro{\STitleMarkboth} hook to allow
%   |\STitle|'s |\markboth| to be overridden.
%   
%  \item |\ScriptRef{|\meta{scripture address}|}|
%   \DescribeMacro{\ScriptRef} 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.
%   
%  \item |\WAndM{|\meta{lyricist \& composer}|}| \DescribeMacro{\WAndM}
%   prints a line telling who wrote the words and music for this song.
%   The string ``W\&M:'' precedes the listing of the \meta{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.
% \end{description}
% 
% \subsection{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.
% \begin{description}
%  \item |\ifSBinSongEnv| \DescribeMacro{\ifSBinSongEnv} is true if we
%   are inside of a song environment.
% 
%  \item |\ifChordBk| \DescribeMacro{\ifChordBk} is true if we are
%   processing a |chordbk| document.
% 
%  \item |\ifOverhead| \DescribeMacro{\ifOverhead} is true if we are
%   processing an |overhead| document.
% 
%  \item |\ifWordBk| \DescribeMacro{\ifWordBk} are we processing a
%   |wordbk| document?
% 
%  \item |\ifWordsOnly| \DescribeMacro{\ifWordsOnly} is true when we are
%   typesetting a words-only document (i.e., no chords).
% 
%  \item |\ifNotWordsOnly| \DescribeMacro{\ifNotWordsOnly} is true if we
%   are processing a document that displays chords.
% 
%  \item |\ifCompactSongMode| \DescribeMacro{\ifCompactSongMode} is set
%   to true if you want songs presented in a compact mode?  It is
%   initially set to false. Set this to true or false using the
%   |\CompactSongModetrue| and |\CompactSongModefalse| commands,
%   respectively.
% 
%  \item |\ifSongEject| \DescribeMacro{\ifSongEject} is set to true if we
%   want a new page generated at the end of every |song| environment?  A
%   value of true means eject after every |song| environment (default
%   value is true).
% \end{description}
%
% Papersize tests have been provided in order to detect if a
% particular papersize has been specified.  These are only documented
% in the \textit{Detailed Documentation} section, below, since they
% are not generally needed.
% 
% 
% \subsection{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.
% \begin{description}
%  \item |\theSBSongCnt| \DescribeMacro{\theSBSongCnt} 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.
% 
%  \item |\theSBSectionCnt| \DescribeMacro{\theSBSectionCnt} the section
%   counter is used for numbering sections as they occur within a song.
% 
%  \item |\theSBVerseCnt| \DescribeMacro{\theSBVerseCnt} the verse
%   counter is used for numbering verses as they occur within a song.
% \end{description}
% 
% 
% \subsection{Spacing Commands}
% These commands define the amount of space to leave in various
% situations.  Change their values via \LaTeX's |\renewcommand| command.
% 
% All of these spaces are defined as \LaTeX{} commands to overcome
% limitations in \LaTeX{} 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 \LaTeX{} commands
% instead of lengths.
% 
% \begin{description}
%  \item |\HangAmt| \DescribeMacro{\HangAmt} amount to indent when a
%   line wraps.
% 
%  \item |\LeftMarginSBBracket| \DescribeMacro{LeftMarginSBBracket} is
%   the amount of left margin to leave when the |\SBBracket| environment
%   is in effect.
% 
%  \item |\LeftMarginSBChorus| \DescribeMacro{\LeftMarginSBChorus} is
%   the amount of left margin to leave when the |\SBChorus| environment
%   is in effect.
% 
%  \item |\LeftMarginSBSection| \DescribeMacro{LeftMarginSBSection} is
%   the amount of left margin to leave when the |\SBSection| environment
%   is in effect.
% 
%  \item |\LeftMarginSBVerse| \DescribeMacro{\LeftMarginSBVerse} is the
%   amount of left margin to leave when the |\SBVerse| environment is in
%   effect.
% 
%  \item |\SBChordRaise| \DescribeMacro{\SBChordRaise} the distance to
%   raise the chords above the baseline of the text they sit over.
% 
%  \item |\SBRuleRaiseAmount| \DescribeMacro{\SBRuleRaiseAmount} the
%   distance to raise the rule (as specified by\\
%   |\SBIntersyllableRule|) which fills the space between adjoining
%   syllables.
% 
%  \item |\SpaceAboveSTitle| \DescribeMacro{\SpaceAboveSTitle} is the
%   amount of vertical space left by the |STitle| command before it
%   prints the song title line.
% 
%  \item |\SpaceAfterTitleBlk| \DescribeMacro{\SpaceAfterTitleBlk} is
%   the space inserted by the song environment between the
%   \emph{title block} and the versicles.
%
%  \item |\SpaceAfterChorus| \DescribeMacro{\SpaceAfterChorus} is the
%   vertical space to leave after an |SBChorus|.
% 
%  \item |\SpaceAfterOpGroup| \DescribeMacro{\SpaceAfterOpGroup} is the
%   vertical space to leave after an |SBOpGroup|.
% 
%  \item |\SpaceAfterSection| \DescribeMacro{\SpaceAfterSection} is the
%   vertical space to leave after an |SBSection|.
% 
%  \item |\SpaceAfterSBBracket| \DescribeMacro{\SpaceAfterSBBracket} is the
%   vertical space to leave after an |SBBracket|.
% 
%  \item |\SpaceAfterSong| \DescribeMacro{\SpaceAfterSong} is the
%   vertical space to leave after a |song|.
% 
%  \item |\SpaceAfterVerse| \DescribeMacro{\SpaceAfterVerse} is the
%   vertical space to leave after an |SBVerse|.
%
%  \item |\SpaceBeforeSBBracket| \DescribeMacro{\SpaceBeforeSBBracket} is the
%   vertical space to leave before an |SBBracket|.
% 
% \end{description}
% 
% It is worth noting that the |\SpaceAfterChorus|, |\SpaceAfterOpGroup|,\\
% |\SpaceAfterSection|, and |\SpaceAfterSong|, |\SpaceAfterVerse|
% 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:
% \begin{verbatim}
%     \renewcommand{\SpaceAfterChorus} {\vspace{0ex}}
%     \renewcommand{\SpaceAfterOpGroup}{\vspace{0ex}}
%     \renewcommand{\SpaceAfterSection}{\vspace{0ex}}
%     \renewcommand{\SpaceAfterSong}   {\vspace{0ex}}
%     \renewcommand{\SpaceAfterVerse}  {\vspace{0ex}}
% \end{verbatim}
% 
% 
% \subsection{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.
% \begin{description}
%  \item |\OHContPgFtrTag| \DescribeMacro{\OHContPgFtrTag} tag is inserted
%   by the |\OHContPgFtr| command.  The default value for this is 
%   ``|continued on next page\ldots|''.
%
%  \item |\OHContPgHdrTag| \DescribeMacro{\OHContPgHdrTag} tag is inserted
%   by the |\OHContPgHdr| command.  The default value for this is 
%   ``|\theSBSongCnt\ --- \theSongTitle, continued\ldots|''.
%
%  \item |\SBBridgeTag| \DescribeMacro{\SBBridgeTag} the Bridge Tag to
%   insert before the start of a bridge.  The default value for this is
%   ``|Bridge:|''.
% 
%  \item |\SBChorusTag| \DescribeMacro{\SBChorusTag} the Chorus Tag to
%   insert before the first line of a chorus.  The default value for
%   this is ``|Ch:|''.
% 
%  \item |\SBContinueTag| \DescribeMacro{\SBContinueTag} the Continue Tag
%   to insert in an\\ |\SBContinueMark|.  The default value for this is
%   ``|cont\ldots|''.
% 
%  \item |\SBEndTag| \DescribeMacro{\SBEndTag} the End Tag to insert
%   before the start of an ending (in an |\SBEnd| command).  The default
%   value for this is ``|End:|''.
% 
%  \item |\SBIntersyllableRule| \DescribeMacro{\SBIntersyllableRule} the
%   command(s) to draw the rule between adjoining syllables.
% 
%  \item |\SBIntroTag| \DescribeMacro{\SBIntroTag} the Intro Tag to
%   insert before the start of an introduction (in an |\SBIntro|
%   command).  The default value for this is ``|Intro:|''.
% 
%  \item |\SBPubDom| \DescribeMacro{\SBPubDom} the string to insert
%   which indicates song is in the public domain.  The default value for
%   this is ``|Public Domain|''.  If you 
%   want to localize this string in the song title block, be sure to use
%   this public interface: the |\CpyRt| macro uses |\SBPubDom| to
%   determine whether or not to print the copyright symbol (\copyright).
% 
%  \item |\SBUnknownTag| \DescribeMacro{\SBUnknownTag} the WAndM string
%   to insert when either the author/artist or the copyright holder is
%   unknown.  The default value for this is ``|Unknown|''.
% 
%  \item |\SBWAndMTag| \DescribeMacro{\SBWAndMTag} the tag to insert
%   before the words and music entry printed in the song header.  The
%   default value for this is ``|W\&M:|''.
% \end{description}
% 
% 
% \subsection{Font Handling}
% 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.
% 
% \begin{description}
%  \item |\ChBassFont| \DescribeMacro{\ChBassFont} sets the font for the
%   bass note in chords as printed by the |\Ch|, |\Chr| and |\ChX|
%   commands.
% 
%  \item |\ChBkFont| \DescribeMacro{\ChBkFont} sets the font for square
%   brackets typeset inside |\Ch| commands (and its variants).
% 
%  \item |\ChFont| \DescribeMacro{\ChFont} sets the font for chords as
%   printed by the |\Ch|, |\Chr|, and |\ChX| commands.
% 
%  \item |\CpyRtFont| \DescribeMacro{\CpyRtFont} sets the font used to
%   print the copyright line produced by the |\CpyRt| command.
% 
%  \item |\CpyRtInfoFont| \DescribeMacro{\CpyRtInfoFont} sets the font
%   used to print the \meta{copyright licensing information} parameter
%   of the |song| environment; which appears after the \meta{copyright
%     information} parameter under the \meta{song title.}
% 
%  \item |\SBBracketTagFont| \DescribeMacro{\SBBracketTagFont} sets the
%   font used to create the tag for an |SBBracket| environment.
% 
%  \item |\SBBridgeTagFont| \DescribeMacro{\SBBridgeTagFont} sets the
%   font used to create the tag for an |SBBridge| environment.
% 
%  \item |\SBChorusTagFont| \DescribeMacro{\SBChorusTagFont} sets the
%   font used to print the chorus tag, |\SBChorusTag|.
% 
%  \item |\SBDefaultFont| \DescribeMacro{\SBDefaultFont} sets the
%   default font for the songbook.  As of version~4.0 there is no need
%   for you to specify this command yourself.
% 
%  \item |\SBEndTagFont| \DescribeMacro{\SBEndTagFont} sets the font
%   used to print the tag, |\SBEndTag|, for the |\SBEnd| command.
% 
%  \item |\SBIntroTagFont| \DescribeMacro{\SBIntroTagFont} sets the
%   font used to print the introduction tag, |\SBIntroTag|.
% 
%  \item |\SBLyricNoteFont| \DescribeMacro{\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.
% 
%  \item |\SBMargNoteFont| \DescribeMacro{\SBMargNoteFont} sets the font
%   used in the marginal reference printed by the |\SBMargNote| command.
% 
%  \item |\SBOccursBrktFont| \DescribeMacro{\SBOccursBrktFont} sets the
%   font used to create the large left and right square brackets which
%   delimit an |SBOccurs| environment.
% 
%  \item |\SBOccursTagFont| \DescribeMacro{\SBOccursTagFont} sets the
%   font used to create the |\SBOccurs| tag.
% 
%  \item |\SBRefFont| \DescribeMacro{\SBRefFont} sets the font used in
%   the marginal reference printed by the |\SBRef| command.
% 
%  \item |\SBVerseNumberFont| \DescribeMacro{\SBVerseNumberFont} sets the
%   font used to print the |\SBVerseCnt| in front of verses in an
%   |SBVerse| environment.
% 
%  \item |\SBSectionNumberFont| \DescribeMacro{\SBSectionNumberFont} sets
%   the font used to print the |\SBSectionCnt| in front of sections in
%   an |SBSection| environment.
% 
%  \item |\STitleFont| \DescribeMacro{\STitleFont} sets the font used to
%   print the song title, as generated by the |\STitle| command.
% 
%  \item |\STitleKeyFont| \DescribeMacro{\STitleKeyFont} sets the font
%   used to print the key a song is written in, as generated by the
%   |\STitle| command.
% 
%  \item |\STitleNumberFont| \DescribeMacro{\STitleNumberFont} sets the
%   font used to print the |\SBSongCnt| in front of the song title, as
%   generated by the |\STitle| command.
% 
%  \item |\ScriptRefFont| \DescribeMacro{\ScriptRefFont} sets the font
%   used to print the scripture reference generated by the |\ScriptRef|
%   command.
% 
%  \item |\WandMFont| \DescribeMacro{\WandMFont} sets the font used to
%   print the lyricist and composer line generated by the |\WandM|
%   command.
% \end{description}
% 
% 
% \subsection{Deprecated Commands}
% The following commands will be discontinued in some future release of
% the \Songbook{} style:
% \begin{description}
%  \item |\ChordBk| is set to |\True| if we're producing words
%   and chord books.  Set to |\False|, otherwise.  Superceded by the
%   |\ifChordBk| if.
% 
%  \item |\False| is a constant used in \TeX\ |\if| expressions.
%   This command is now unnecessary.
% 
%  \item |\Overhead| is set to |\True| if we're producing
%   overhead transparencies.  Set to |\False|, otherwise.  Superceded by
%   the |\ifOverhead| if.
% 
%  \item |\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.
% 
%  \item |\True| is a constant used in \TeX\ |\if| expressions.
%   This command is now unnecessary.
% 
%  \item |\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.
% 
%  \item |\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.
% \end{description}
% 
% 
% \section{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 450 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.
% \begin{enumerate}
% 
%  \item 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.
% 
%  \item Use of the |\Ch| command:
%   \begin{itemize}
%    \item 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:
%     \begin{description}
%      \item[Do:] |\Ch{G}{Halle}luia|
%      \item[Don't:] |\Ch{G}{Hall}eluia|
%     \end{description}
%    \item Always include punctuation along with a syllable that has
%     been included in a |\Ch| command.  For example:
%     \begin{description}
%      \item[Do:] |\Ch{G}{Lord!}|
%      \item[Don't:] |\Ch{G}{Lord}!|
%     \end{description}
%    \item Only place a single chord within a |\Ch| command.  For
%     example:
%     \begin{description}
%     \item[Do:] |\Ch{[}{}\Ch{G}{} \Ch{D}{}\Ch{]}{}|
%      \item[Don't:] |\Ch{[G D]}{}|
%     \end{description}
%   \end{itemize}
% 
%  \item Extension of syllables.  Syllables may be extended at either/or
%   both ends.  Each end should be done in a different way:
%   \begin{enumerate}
%    \item 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.
%     \begin{description}
%      \item[Do:] |\Chr{G\#m7/C}{Ho}\Ch{C}{ly}|
%      \item[Don't:] |\Ch{G\#m7/C}{Ho\SBem}\Ch{C}{ly}|
%     \end{description}
%    \item Extending the beginning (i.e., delaying the start) of a
%     syllable is generally required because the chord change needs to
%     occur \emph{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.
%     \begin{description}
%      \item[Do:] |none Ho\Ch{D}{\SBen ly}|
%     \end{description}
%   \end{enumerate}
% 
%  \item Typographic conventions.  \LaTeX{} 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|.
%   \begin{description}
%    \item[Do:] |\Ch{C}{diffi}cult|
%    \item[Don't:] |\Ch{C}{dif}ficult|
%   \end{description}
% 
%  \item Ordering of songs in the songbook.  In order to allow \LaTeX2e{}
%   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.
% 
%  \item 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:
%   \begin{verbatim}
%       \OHContPgFtr
%       \OHPageBrk
%       \OHContPgHdr
%   \end{verbatim}
% \end{enumerate}
% 
% 
% \section{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
% early \Songbook{} releases, and it produces \emph{very} usable output!
% 
% \subsection{Table of Contents Generation}
% Steps to follow in order to produce a table of contents:
% \begin{enumerate}
% 
%  \item Add a |\makeTitleContents| command to the preamble of your
%   songbook.
% 
%  \item Run \LaTeX2e{} on the songbook source.
% 
%  \item Make your own copy of \texttt{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.
% 
%  \item Run \LaTeX2e{} on your copy of \texttt{sampleToc.tex}.
% \end{enumerate}
% 
% \subsection{Title \& First Line Index Generation}
% Steps to follow in order to produce a title and first line index:
% \begin{enumerate}
% 
%  \item Add a |\makeTitleIndex| command to the preamble of your
%   songbook.
% 
%  \item Run \LaTeX2e{} on the songbook source.
% 
%  \item Run the \texttt{./mksbtdx} shell script on the \texttt{.tIdx}
%   file that was produced by the previous step.  Do this by typing
%   ``\texttt{mksbtdx} \textit{jobname}'' at a UNIX command line.  For
%   example, the index file for \texttt{sample-sb.tex} was produced by
%   typing ``\texttt{mksbtdx sample-sb}''.
% 
%  \item Make your own copy of \texttt{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.  (\texttt{./mksbtdx} told you this file's name).
% 
%  \item Run \LaTeX2e{} on your copy of \texttt{sampleTdx.tex}.
% \end{enumerate}
% 
% \subsection{Song Key Index Generation}
% Steps to follow in order to produce a song key index:
% \begin{enumerate}
% 
%  \item Add a |\makeKeyIndex| command to the preamble of your
%   songbook.
% 
%  \item Run \LaTeX2e{} on the songbook source.
% 
%  \item Run the \texttt{./mksbkdx} shell script on the \texttt{.kIdx}
%   file that was produced by the previous step.  Do this by typing
%   ``\texttt{mksbkdx} \textit{jobname}'' at a UNIX command line.  For
%   example, the key index file for \texttt{sample-sb.tex} was produced
%   by typing ``\texttt{mksbkdx sample-sb}''.
% 
%  \item Make your own copy of \texttt{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. (\texttt{./mksbkdx} told you this file's name).
% 
%  \item Run \LaTeX2e{} on your copy of \texttt{sampleKdx.tex}.
% \end{enumerate}
% 
% \subsection{Song Artist Index Generation}
% To produce an index by song artist (composer) follow the same steps as
% for song key index generation, above, with the following exceptions:
% \begin{itemize}
%
%  \item use |\makeArtistIndex| instead of |\makeKeyIndex|.
%
%  \item use \texttt{./mksbadx} instead of \texttt{./mksbkdx}.
%
%  \item use \texttt{sampleAdx.tex} instead of \texttt{sampleKdx.tex}.
% \end{itemize}
% 
% \section{Example}
% Here is an example songbook; where the the songbook contains exactly
% one song.
% {\small\begin{verbatim}
% \documentstyle[12pt]{book}
% \usepackage[chordbk]{songbook}                %% Words & Chords edition.
% 
% %%
% % 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.
% \makeArtistIndex        %% Index by Artist.
% 
% \begin{document}
% %%
% % Songbook begins.
% %%
% \begin{song}{What A Mighty God We Serve}{C}
%   {\SBPubDom}
%   {\SBUnknownTag}
%   {Isaiah 9:6}
%   {\NotCCLIed}
% 
%   \renewcommand{\RevDate}{February~11,~1993}
%   \SBRef{Give Thanks}{Hosanna! Music Tape HM-7}
%   \SBRef{Hosanna! Music Book~I}{\#93}
% 
%   \begin{SBOpGroup}
%     \Ch{C}{What} a mighty God we serve,
% 
%     What a mighty God we \Ch{G7}{serve},
% 
%     \Ch{C}{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{]}{}
%   \end{SBOpGroup}
% 
%   \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}
% 
% \CBPageBrk
%   \begin{SBExtraKeys}{%
%     \STitle{What A Mighty God We Serve}{D}
% 
%     \begin{SBOpGroup}
%       \Ch{D}{What} a mighty God we serve,
% 
%       What a mighty God we \Ch{A7}{serve},
% 
%       \Ch{D}{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{]}{}
%     \end{SBOpGroup}
% 
%     \begin{SBVerse}
%       O \Ch{D}{Zion,} O \Ch{G}{Zion,} that \Ch{A7}{bring}est good \Ch{D}{tid}ings,
% 
%       Get thee \Ch{G}{up} to 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
% \end{verbatim}}
% 
% 
% \section{Dependencies}
% The \Songbook{} style is dependent upon four other \LaTeX2e{} styles:
% \texttt{conditionals.sty}, \texttt{calc.sty}, \texttt{ifthen.sty}, and
% \texttt{multicol.sty}.
% \texttt{Conditionals.sty} is supplied with this package.
% \texttt{Calc.sty}, \texttt{ifthen.sty}, and \texttt{multicol.sty} are
% part of the \LaTeX2e{} distribution.
% 
% Embedding guitar chord fingering charts within a songbook can be 
% accomplished with the \texttt{texchord.sty} package; which is supplied 
% in the contrib directory of the \Songbook{} distribution.
% 
% 
% \section{Files}
% \begin{description}
%   \item[conditionals.sty] Donald Arseneau's conditional tests; included
%     with Donald's kind permission.
%   \item[mksbadx] A shell script around makeindex to sort the song
%     artist index.
%   \item[mksbkdx] A shell script around makeindex to sort the song
%     key index.
%   \item[mksbtdx] A shell script around makeindex to sort the
%     title \& first line index.
%   \item[relnotes.txt] The \Songbook{} package release notes.
%   \item[sample-sb.tex] A sample songbook.
%   \item[sampleAdx.tex] Song artist index for the sample songbook.
%   \item[sampleKdx.tex] Song key index for the sample songbook.
%   \item[sampleTdx.tex] Title \& first line index for the sample
%   songbook.
%   \item[sampleToc.tex] TOC for the sample songbook.
%   \item[songbook.ist] The \Songbook{} package makeindex \texttt{.ist} file.
%   \item[songbook.dtx] The base style file.
%   \item[songbook.inx] The install script used to create 
%    \texttt{songbook.sty}.
% \end{description}
% 
% \section{See Also}
% Some resources you will find helpful when coding songbooks:
% \begin{itemize}
%   \item \textit{\LaTeX{} A Document Preparation System,} by Leslie Lamport
%
%   \item \textit{The \LaTeX{} Companion,} by Goossens, Mittlebach, \&~Samarin
%
%   \item The \Songbook{} homepage, at URL \texttt{http://rath.ca/Misc/Songbook/}
% 
%   \item \textit{The \TeX{} book,} by Donald Knuth
% \end{itemize}
% 
% \changes{v4.1}{2003/08/31}{Added the Contributed Resources subsection.}
% \subsection{Contributed Resources}
% A couple of \Songbook{} users have created additional resources intended to 
% be used with the \Songbook{} style.  If you have written anything which you
% would like to contribute to \Songbook{} style's distribution, please let
% me know.
% \def\LyX{L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\spacefactor1000}
% \begin{description}
%  \item[CarolBook] a \Songbook{} formatted book containing words for all the
%    Christmas songs I've been able to find where the words are now in the
%    public domain.  PDF versions of the file are included for quick
%    and easy use.
%
%  \item[crd2sb] a perl script which converts Chord files into Songbook files.
%    Contributed by Abel Chow $<$\texttt{abel@g2networks.com}$>$.  Note that
%    a postscript formatter for Chord songs can be ftp'ed from:\\
%    \texttt{ftp://ftp.uu.net/doc/music/guitar/resources/misc/CHORD/}.
%
%  \item[modulate] a perl script for modulating a song from one key to another.
%    Contributed by Christopher Rath $<$\texttt{christopher@rath.ca}$>$.
%
%  \item[\LyX{} Integration] files for use of the \Songbook style with \LyX. 
%   Christian Ridderstr\"{o}m $<$\texttt{chr@md.kth.se}$>$ has put together the 
%   necessary files to allow \Songbook{}s to be edited using \LyX.  While 
%   these files are not distributed in the \Songbook{}'s \texttt{contrib} 
%   files, they are available from \\
%   \texttt{http://www.md.kth.se/\~{}chr/lyx/songbook/Songbook.shtml}.
%
%  \item[texchord.sty] \LaTeX{} macros for printing guitar fingering charts.
%    Contributed by Joel M. Hoffman $<$\texttt{joel@wam.umd.edu}$>$.  Note, 
%    this style is \emph{no longer} actively supported by Joel.
% \end{description}
%
% \subsection{Other Similar 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 \LaTeX2e packages (of which the author is aware) include:
% \begin{description}
%  \item[chord.sty] a song formatting package based on \LaTeX{}'s article
%   style; written by Olivier Biot (\texttt{http://www.biot.yucom.be/}).
%   
%  \item[Chordpack] a utility for typesetting \emph{chordpro} chord
%   files in TeX; written by Daniel Polansky
%   (\texttt{http://www.fi.muni.cz/\~{}xpolansk/home.html}) and\\ available
%   at \texttt{http://www.fi.muni.cz/\~{}xpolansk/chordpack}.
%   
%  \item[gchords.sty] a TeX packages for typesetting guitar chord
%   diagrams; written by Kasper Peeters
%   (\texttt{http://www.damtp.cam.ac.uk/user/kp229/}) and available at
%   \texttt{http://www.damtp.cam.ac.uk/user/kp229/gchords/}.
%   
%  \item[Guitar.sty] \LaTeX{} macros for typesetting guitar chords over
%   song texts; written by Martin Väth
%   (\texttt{http://www.mathematik.uni-wuerzburg.de/\~{}vaeth/}) and
%   available from\\
%   \texttt{http://www.mathematik.uni-wuerzburg.de/\~{}vaeth/download/}.
%   
%  \item[GuitarTeX] a graphical tool for editing \emph{chordpro} chord
%   files and printing them in TeX; written by Joachim Miltz and
%   available from\\ \texttt{http://www.rz-home.de/\~{}jmiltz/guitartex/}.
%   
%  \item[song.sty] a song formatting package based on \LaTeX{}'s book
%   style; written by Jens T.~Berger Thielemann
%   (\texttt{http://www.stud.ifi.uio.no/\~{}jensthi/}).
% \end{description}
% 
% \section{Bugs}
% In the specific case where a |\Ch|, |\Chr|, or |\ChX| macro begins a
% paragraph that isn't inside one of \Songbook{}'s versicle environments,
% 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 best way to avoid this problem is through
% use of the |\SBOpGroup| environment.  If that isn't possible, the
% problem may often be overcome by starting
% such lines with an |\mbox{}| command; this inserts an empty (i.e., zero
% width) mbox at the start of the line.  For example:
% \begin{verbatim}
%     \mbox{}\Ch{G}{Great} is the Lord \Ch{A}{even} beyond the
%       \Ch{D}{borders} of I\Chr{F#m}{srae}\Ch{Bm7}{l;}
% \end{verbatim}
% 
% The |\emph| macro is not completely compatible with |\Ch| and its friends.
% The specific problem is that sharps can not be specified via `\#' within
% an |\emph| macro.  The following snippet,
% \begin{verbatim}
%     \emph{for the \Ch{G/A}{King} of \Ch{F#}{kings.}}
% \end{verbatim}
% will fail with the \LaTeX2e{} message,
% \begin{verbatim}
%   ! Illegal parameter number in definition of \\reserved\@a.
%   <to be read again>
% \end{verbatim}
% 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:
% \begin{verbatim}
%     \emph{for the \Ch{G/A}{King} of} \Ch{F#}{\emph{kings.}}
% \end{verbatim}
% 
% \section{Special Thanks}
% Thanks to Donald Arseneau for writing the \texttt{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
% $<$\texttt{herbert@fh-wedel.de}$>$ for noting that |SBVerse*| and its
% cousins were missing from the \texttt{.sty} file, and then coding up
% an acceptable |SBVerse*| which I could quickly use as a model for the
% other two missing environments.
%
% For version~4.1, I am grateful to Mark Wooding for suggesting the 
% method I ultimately used for implementing the |song| environment's
% \meta{Include?} option (although I did not use his preferred
% method).
% 
% \section{Author}
% Christopher Rath
%   \hskip 1cm \texttt{christopher@rath.ca}
%   \hskip 1cm (613)~824-4584\\
% 1371 Major Rd.\\
% Orleans, ON\\
% Canada \hskip .5cm K1E 1H3
% 
% \StopEventually{
%   ^^A \PrintIndex
%   ^^A \PrintChanges
%
% } ^^A end \StopEventually
%
% \newpage
%
% \section{\texttt{.dtx} Documentation Driver}
% There is one last administrative detail to take care of before 
% beginning the detailed review: the insertion of the documentation
% driver (i.e., the code that builds the documentation \texttt{.dvi}
% file.
%
%    \begin{macrocode}
%<*driver>
\documentclass{ltxdoc} \RequirePackage{calc} \EnableCrossrefs
\CodelineIndex
\RecordChanges                  % Gather update information
 %\OnlyDescription % comment out for implementation details
 %\OldMakeindex     % use if your MakeIndex is pre-v2.9
\setlength\hfuzz{15pt}  % dont make so many
\hbadness=7000          % over and under full box warnings
\def\MacroFont{\fontencoding\encodingdefault
  \fontfamily\ttdefault
  \fontseries\mddefault
  \fontshape\updefault
  \footnotesize}%

\voffset=-1.00in
\topmargin=0.5in
\headheight=0.0in
\headsep=0.20in
\textheight=9.4in
\footskip=0.4in

\newenvironment{ParameterList}
  {\par\hskip 1.5em Parameters:\begin{list}{}
    {\setlength{\topsep}{0pt}
      \setlength{\parsep}{0pt}
      \setlength{\itemsep}{0pt}
      \setlength{\leftmargin}{\leftmargin + 1.5em}
      \setlength{\parsep}{0pt}
    }
  }
  {\end{list}\vskip 0.5ex
  }
\newcommand{\parm}[1]{\texttt{[}\meta{#1}\texttt{]}}
\begin{document}
   \setcounter{IndexColumns}{1}
   \DocInput{songbook.dtx}
\end{document}
%</driver>
%    \end{macrocode} 
%
% \newpage
%
% \part{Detailed Documentation}
% This section contains style implementation details
% along with the detailed descriptions and documentation for the
% \Songbook{} commands and environments.  It is strongly recommended
% that these detailed descriptions be reviewed at least once as part
% of becoming familiar with the \Songbook{} style.
%
% This coding style has been structured in a top down fashion which assume
% that macros and environments must be declared before they are first used.
% \TeX{} doesn't require this to be so, but since I've been coding software
% this way for 20+ years, it's easier for me to also maintain this structure 
% here too.
%
% \section{Identification Part}
% The first section in \texttt{songbook.sty} is what \LaTeX2e{} calls
% the \textit{Implementation Part}.  This is where \Songbook{} 
% identifies itself to the outside world.  As part of this section
% an RCS ``Id:'' variable has been included as a \TeX{} comment; the
% intent is that this may assist with reporting problems later.
%
%    \begin{macrocode}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%                                                      %%
%%        I D E N T I F I C A T I O N   P A R T         %%
%%                                                      %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% rcsid = @(#)$Id: songbook.dtx,v 1.12 2006/10/15 15:49:50 rathc Exp $
%%
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{songbook}[2006/10/13 v4.2 All purpose Songbook style]
\typeout{Document Subclass: songbook 2006/10/13 v4.2 All purpose Songbook style}
%    \end{macrocode}
%
% \section{Initial Code Part}
% The next section is called the \textit{Initial Code Part.}  This 
% is where any dependencies in the early sections of
% \texttt{songbook.sty} has are contained.  In the case of
% the \Songbook{} style we must declare our dependence on
% \texttt{calc.sty} here because some of \Songbook{}'s 
% declarative sections themselves contain calculations.  In
% this section we also declare the |\if| constructs used
% in the package.
%
%    \begin{macrocode}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%                                                      %%
%%          I N I T I A L   C O D E   P A R T           %%
%%                                                      %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%========================================================
%%  E A R L Y   P A C K A G E   D E P E N D E N C I E S  %
%%========================================================
%    \end{macrocode}
%
% Page layout calculations have become overly complex and 
% so as of version~4.0 we now require \texttt{calc.sty} to make
% them readable once again.  In every instance we could probably 
% find a way to get along without \texttt{calc.sty}; however,
% since the package is a part of the \LaTeX2e Base there is no
% logical reason to avoid its use.
%
%    \begin{macrocode}
\RequirePackage{calc}

%    \end{macrocode}
%
% \subsection{If Constructs}
% Most of these |\if| contructs are needed for use in the \textit{Delaration
% Of Options} section of \texttt{songbook.sty}.  In each case, we create
% the if statement (a.k.a. the flag) and then immediately set it to a
% known value.  Where there are several flags which act as sort of radio
% buttons, all of the flags are set so that none of them is selected; 
% which has been done so that if we forget to deal with them properly
% in the \textit{Declaration Of Options} code it will eventually manifest
% itself as an error.
%
% Since the majority of the |\if|s have to be declared in this section,
% we will go ahead and declare the remaining |\if|s as well.  It's 
% simpler to maintain them when they are all in one place.
%
%    \begin{macrocode}
%%========================================================
%%              I F   C O N S T R U C T S                %
%%========================================================
%    \end{macrocode}
%
% \subsubsection{\Songbook{} Types}
% At any time, only one of 
% |\ifChordBk|, |\ifOverhead|, or |\ifWordBk| may be true.
% These |\if|s correspond directly to the |chordbk|, |overhead|,
% and |wordbk| options; one of which \emph{must} be used in the 
% |\usepackage{}| statement used to invoke the \Songbook{} style.
% All three flags are set to |\false|, and this fact is use later
% in order to confirm that the user had specified one of the 
% 3~options in their document.
%
% \begin{macro}{\ifChordBk}
%   |\ifChordBk| is true if the user specified the |chordbk| option.
%
% \begin{macro}{\ifOverhead}
%   |\ifOverhead| is true if the user specified the |overhead| option.
%
% \begin{macro}{\ifWordBk}
%   |\ifWordBk| is true if the user specified the |wordbk| option.
%
%    \begin{macrocode}
\newif\ifChordBk        \ChordBkfalse
\newif\ifOverhead       \Overheadfalse
\newif\ifWordBk         \WordBkfalse
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \subsubsection{\Songbook{} Subtypes}
% A pair of |\if|s are declared to indicate
% whether we are only typesetting words on the page (i.e., the flag is
% false if we are typesetting words \emph{and} chords).  We are in words
% only mode when the user has declared either the |overhead| or |wordbk|
% options.  When these flags are first declared they are set to the same
% value, false.
%
% \begin{macro}{\ifWordsOnly}
%   |\ifWordsOnly| is true if we're in words-only mode.
%
% \begin{macro}{\ifNotWordsOnly}
%   |\ifNotWordsOnly| always has a value oposite the of
%   |\ifWordsOnly|.  |\ifNotWordsOnly| is false if we are in words-only 
%   mode.
%
%    \begin{macrocode}
\newif\ifWordsOnly      \WordsOnlyfalse
\newif\ifNotWordsOnly   \NotWordsOnlyfalse
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \subsubsection{Song Indicator}
% \begin{macro}{\ifSBinSongEnv}
%   The |\ifSBinSongEnv| flag is provided to the style
%   or a songbook's author to detect if the current text is inside of a |song|
%   environment.  This flag hasn't proven to be useful, but it doesn't hurt
%   anything to leave it around; so, it hasn't been removed---who knows, there
%   may well be a user somewhere making use of it!  The |song| environment
%   takes care of setting this flag's status.
%
%    \begin{macrocode}
\newif\ifSBinSongEnv    \SBinSongEnvfalse
%    \end{macrocode}
% \end{macro}
%
% \subsubsection{Behaviour Flags}
% There are three flags which can be set in order
% to effect certain behaviours from the \Songbook{} style.  They are not
% related to one another but have been grouped together since they are
% they all |\if|s used to control \Songbook{} behaviour.
%
% \begin{macro}{\ifCompactSongMode}
%   |\ifCompactSongMode| is set to true if you want
%   songs presented in a compact mode.  It is initially set to false.
%   This flag will \emph{only} be set to true by the user; the style
%   itself does not toggle this flag.  Set this to true by specifying
%   the |compactsong| option in the |\usepackage| statement.
%
% \changes{v4.1}{2003/08/31}{Added \\ifExcludeSong construct.}
% \begin{macro}{\ifExcludeSong}
%   |\ifExcludeSong| is set to true if you want to have the current
%   song excluded from the songbook.  It is initially set to false,
%   and would only be set to true inside a |song| environment, during
%   processing of a song to be excluded.  Its value is set to true
%   when you pass a value of ``\texttt{N}'' as the first (optional)
%   parameter to a |song| environment.
%
% \changes{v4.1}{2003/08/31}{Added \\ifPrintAllSongs construct.}
% \begin{macro}{\ifPrintAllSongs}
%   |\ifPrintAllSongs| is set to true if you want to have \Songbook{}
%   print all a songbook's songs regardless of what option may have been
%   specified in each song.
%
% \begin{macro}{\ifSamepageMode}
%   |\ifSamepageMode| 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.  Important note: this command has \emph{not}
%   been documented in the \textit{High Level Documentation} section, above; 
%   |\ifSamepageMode| is
%   very unreliable.  The \LaTeX2e{} page breaking algorithms are not
%   happy when this mode is used.  The the |song| environment description,
%   below, for a further explanation.
%
% \begin{macro}{\ifSongEject}
%   |\ifSongEject| is set to true if we
%   want a new page generated 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.
%
%    \begin{macrocode}
\newif\ifCompactSongMode\CompactSongModefalse
\newif\ifExcludeSong    \ExcludeSongfalse
\newif\ifPrintAllSongs  \PrintAllSongsfalse
\newif\ifSamepageMode   \SamepageModefalse
\newif\ifSongEject      \SongEjecttrue
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \subsubsection{Papesize Indicators}
% This next set of flags are needed to track
% the papersize specified by the user in then processed in the
% \textit{Declaration Of Options} section.  This set of |\if|s are
% mutually exclusive and only one of them should be true at any one time.
% They are all initially set to false; setting of a default value is done
% via an |\ExecuteOptions{}| clause, below.  These flags were created for
% use by the \Songbook{} style itself, but have been made part of the 
% public interface to simplify page layout coding related to paper
% handling in a user's own songbook.
%
% \begin{macro}{\ifSBpaperA4}
%   |\ifSBpaperA4| is true if papersize is A4.
% \begin{macro}{\ifSBpaperA5}
%   |\fSBpaperA5| is true if papersize is A5.
% \begin{macro}{\ifSBpaperB5}
%   |\ifSBpaperB5| is true if papersize is B5.
% \begin{macro}{\ifSBpaperLtr}
%   |\ifSBpaperLtr| is true if papersize is US~Letter.
% \begin{macro}{\ifSBpaperLgl}
%   |\ifSBpaperLgl| is true if papersize is US~Legal.
% \begin{macro}{\ifSBpaperExc}
%   |\ifSBpaperExc| is true if papersize is US~Executive Letter.
%
%    \begin{macrocode}
\newif\ifSBpaperAfour   \SBpaperAfourfalse
\newif\ifSBpaperAfive   \SBpaperAfivefalse
\newif\ifSBpaperBfive   \SBpaperBfivefalse
\newif\ifSBpaperLtr     \SBpaperLtrfalse
\newif\ifSBpaperLgl     \SBpaperLglfalse
\newif\ifSBpaperExc     \SBpaperExcfalse
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \subsection{Fonts}
% Fonts are specified up-front in this section in order to simplify
% the |\DeclareOption{}| clauses that follow (i.e., those clauses
% need only make changes against these baseline settings).  The fonts
% sizes and selections initially declared herein are those necessary
% for |chordbk| songbooks.
%
% Fonts are handled by way of \LaTeX2e{} commands defined using the
% |\newcommand| command.  This was done specifically so that traditional
% \LaTeX2e{} font selection occurs in the context the \Songbook{}
% font command is used.  I may have completely misunderstood how 
% \LaTeX2e{} does its font selection, in which case my implementation
% choice here is pointless; however, until proven otherwise\ldots here
% it is.\footnote{Given that \texttt{doc.dtx} uses fonts in this fashion,
% I feel I'm in pretty good company.}  Change these font specifiers via
% \LaTeX2e's |\renewcommand.|
%
%    \begin{macrocode}
%%========================================================
%%                      F O N T S                        %
%%========================================================
%    \end{macrocode}
%
% \subsubsection{Chord Fonts}
% These font selectors are used to determine how
% chords are printed in words and chords songbooks:
%
% \begin{macro}{\ChBassFont}
%   |\ChBassFont| sets the font for the bass note
%   in chords as printed by the |\Ch|, |\Chr|, and |\ChX| commands.
%
% \begin{macro}{\ChBkFont}
%   |\ChBkFont| sets the font for square brackets
%   typeset by |\Ch|, |\Chr|, and |\ChX| commands.
%
% \begin{macro}{\ChFont}
%   |\ChFont| sets the font for chords as printed
%   by the |\Ch|, |\Chr|, and |\ChX| commands.  This used to be set to
%   |\bf\sf| (i.e., cmss12 at 14.4pt).
%
%    \begin{macrocode}
\newcommand{\ChBassFont}{\normalsize\bf\sf}     % = cmss12 at 12.0pt
\newcommand{\ChFont}{\large\fontfamily{\sfdefault}%
  \fontseries{sbc}\fontshape{n}\selectfont}     %=cmssbc12 at 14.4pt
\newcommand{\ChBkFont}{\ChFont\fontseries{m}    %
  \selectfont}                                  % =cmssm12 at 14.4pt
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \subsubsection{Title Block Fonts}
% These font selectors are used to select
% the fonts used in the Title Block that occurs that the start of
% each song:
%
% \begin{macro}{\CpyRtFont}
%   |\CpyRtFont| sets the font used to print the
%   copyright symbol produced by the |\CpyRt| command.
%
% \begin{macro}{\CpyRtInfoFont}
%   |\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.
%
% \begin{macro}{\STitleFont}
%   |\STitleFont| sets the font used to print the
%   song title, as generated by the |\STitle| command.
%
% \begin{macro}{\STitleKeyFont}
%   |\STitleKeyFont| sets the font used to print
%   the key a song is written in, as generated by the |\STitle|
%   command.
%
% \begin{macro}{\STitleNumberFont}
%   |\STitleNumberFont| sets the font used to
%   print the |\SBSongCnt| in front of the song title, as generated by
%   the |\STitle| command.  This is one of two \Songbook{} font commands
%   that are implemented using a real \LaTeX2e{} |\font| command; this
%   turned out to be the easiest manner in which to obtain the desired
%   fonts.  In order to make the |\STitleNumberFont|'s behaviour the
%   the same as the other \Songbook{} font commands, the implementation
%   is done indirectly; whereby the |\font| command is inserted into
%   the |\STitleNumberFont| command so that it may be changed by the
%   user in the same way as the other font commands in this package.
%
% \begin{macro}{\ScriptRefFont}
%   |\ScriptRefFont| sets the font used to print
%   the scripture reference generated by the |\ScriptRef| command.
%
% \begin{macro}{\WandMFont}
%   |\WandMFont| sets the font used to print the
%   lyricist and composer line generated by the |\WandM| command.
%
%    \begin{macrocode}
\newcommand{\CpyRtFont}{\footnotesize}          % = cmr10  at 10pt
\newcommand{\CpyRtInfoFont}{\tiny}              % = cmss8  at  8pt
\newcommand{\STitleFont}{\large\bf\sf}          % = cmss12 at 14.4pt
\newcommand{\STitleKeyFont}{\large}             % = cmr12  at 14.4pt
\font\STNFont=cmtt12 at 20pt
\newcommand{\STitleNumberFont}{\STNFont}        % = cmtt12 at 20pt
\newcommand{\ScriptRefFont}{\footnotesize}      % = cmr10  at 10pt
\newcommand{\WandMFont}{\footnotesize}          % = cmr10  at 10pt
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \subsubsection{Versicle Tag Fonts}
% These font selectors are used to select
% the fonts used to tag verses, choruses, bridges, and other elements
% with which a song is constructed (e.g., verse numbers, ``Ch:''
% chorus indicator, etc.):
%
% \begin{macro}{\SBBracketTagFont}
%   |\SBBracketTagFont| sets the font used to
%   create the tag for an |SBBracket| environment.
%
% \begin{macro}{\SBBridgeTagFont}
%   |\SBBridgeTagFont| sets the font used to
%   create the tag for an |SBBridge| environment.
%
% \begin{macro}{\SBChorusTagFont}
%   |\SBChorusTagFont| sets the font used to
%   print the chorus tag, |\SBChorusTag|.
%
% \begin{macro}{\SBEndTagFont}
%   |\SBEndTagFont| sets the font used to
%   print the tag, |\SBEndTag|, for the |\SBEnd| command.
%
% \begin{macro}{\SBIntroTagFont}
%   |\SBIntroTagFont| sets the font used to
%   print the introduction tag, |\SBIntroTag|.
%
% \begin{macro}{\SBOccursBrktFont}
%   |\SBOccursBrktFont| sets the font used to
%   create the large left and right square brackets used to delimit the
%   |\SBOccurs| environment.
%
% \begin{macro}{\SBOccursTagFont}
%   |\SBOccursTagFont| sets the font used to
%   create the |\SBOccurs| tag.
%
% \begin{macro}{\SBVerseNumberFont}
%   |\SBVerseNumberFont| sets the font used to
%   print the |\SBVerseCnt| in front of verses in an |SBVerse| environment.
%
% \begin{macro}{\SBSectionNumberFont}
%   |\SBSectionNumberFont| sets the font used to
%   print the |\SBSectionCnt| in front of sections in an |SBSection|
%   environment.
%
%    \begin{macrocode}
\newcommand{\SBBracketTagFont}{\small\bf\sf}    % = cmss10 at 10.0pt
\newcommand{\SBBridgeTagFont}{\SBEndTagFont}    % = cmss10 at 10.9pt
\newcommand{\SBChorusTagFont}{\small\bf\sf}     % = cmss10 at 10.9pt
\newcommand{\SBEndTagFont}{\small\bf\sf}        % = cmss10 at 10.9pt
\newcommand{\SBIntroTagFont}{\SBEndTagFont}     % = cmss10 at 10.9pt
\font\SBOBFont=cmss17 at 30pt
\newcommand{\SBOccursBrktFont}{\SBOBFont}       % = cmss17 at 30pt
\newcommand{\SBOccursTagFont}{\small\bf\sf}     % = cmss10 at 10.0pt
\newcommand{\SBVerseNumberFont}{\small\bf\sf}   % = cmss10 at 10.9pt
\newcommand{\SBSectionNumberFont}{\small\bf\sf} % = cmss10 at 10.9pt

%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \subsubsection{Marginal Notes Fonts}
% These font selectors are used to select
% the fonts used when \Songbook{} commands make notations in the 
% margin of the songbook:
%
% \begin{macro}{\SBMargNoteFont}
%   |\SBMargNoteFont| sets the font used in the
%   marginal reference printed by the |\SBMargNote| command.
%
% \begin{macro}{\SBRefFont}
%   |\SBRefFont| sets the font used in the
%   marginal reference printed by the |\SBRef| command.
%
%    \begin{macrocode}
\newcommand{\SBMargNoteFont}{\scriptsize}       % = cmti8  at  8pt
\newcommand{\SBRefFont}{\SBMargNoteFont}        % = cmti8  at  8pt
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \subsubsection{Song Body Fonts}
% These font selector command are used to 
% select fonts which are used within the body of songs:
%
% \begin{macro}{\SBDefaultFont}
%   |\SBDefaultFont| sets the default font for
%   the songbook.  We will insert an occurrence of this command at the
%   top of the songbook using the |\AtBeginDocument{}| clause, below.
%
% \begin{macro}{\SBLyricNoteFont}
%   |\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:
%   \begin{verbatim}
%      {\SBLyricNoteFont (Cantor)} Give thanks to the Lord.
%
%      {\SBLyricNoteFont (All)} His love endures forever.
%   \end{verbatim}
%
%    \begin{macrocode}
\newcommand{\SBDefaultFont}{\fontfamily{\rmdefault}%
  \large}                                       % = cmr12  at 14.4pt
\newcommand{\SBLyricNoteFont}{\footnotesize\sf} % = cmss10 at 10pt
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \subsubsection{Other Fonts}
% The remaining font selector commands:
%
% \begin{macro}{\SBOHContTagFont}
%   |\SBOHContTagFont| sets the font used to
%   print the |\OHContPgFtr| and |\OHContPgHdr|.
% 
%    \begin{macrocode}
\newcommand{\SBOHContTagFont}{\small\bf\sf\itshape} % = cmss10 at 10.9pt

%    \end{macrocode}
% \end{macro}
%
% \subsection{Configurable Dimensions}
% In this section we define the spaces to leave in various situations.
%
% All of these spaces are defined as \LaTeX2e{} commands to overcome
% limitations in length evaluation.  For example, if
% |\LeftMarginSBVerse| were to be defined as a length, and then
% immediately set to |4em|s the specific length would be evaluated with
% respect to the current font.  This is not be what is desired;
% instead a length evaluated with respect to the font in place at the
% start of an |SBVerse| is what is desired.  This can only be done by
% making these lengths \LaTeX2e{} commands.
%
%    \begin{macrocode}
%%========================================================
%%    C O N F I G U R A B L E   D I M E N S I O N S      %
%%========================================================
%    \end{macrocode}
%
% \subsubsection{Published Dimensions}
% While the bulk of the declared dimensions have been created to make
% the \Songbook{} style more user configurable, there are also some dimensions
% which were created for internal use.  This first section describes the
% user configurable dimensions:
%
% \begin{macro}{\HangAmt}
%   |\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.
%
% \begin{macro}{\LeftMarginSBBracket}
%   |\LeftMarginSBBracket| is the amount of
%   left margin left in front of |SBBracket|s and |SBBracket*|s in
%   the songbook.  The value for this variable has been chosen such
%   that the song-words for |SBVerse|s, |SBChorus|es, and |SBBracket|s
%   all align against the same left margin when printing standard
%   words \&~chords songbooks.
%
% \begin{macro}{\LeftMarginSBChorus}
%   |\LeftMarginSBChorus| is the amount of
%   left margin left in front of named choruses in the songbook.
%   In most cases |\LeftMarginSBChorus|, |\LeftMarginSBSection|, and
%   |\LeftMarginSBVerse| should all be the same value.
%
% \begin{macro}{\LeftMarginSBSection}
%   |\LeftMarginSBSection| is the amount of
%   left margin left in front of sections in the songbook.
%
% \begin{macro}{\LeftMarginSBVerse}
%   |\LeftMarginSBVerse| is the  amount of left 
%   margin left in front of verses in the songbook.
%
% \begin{macro}{\SBChordRaise}
%   |\SBChordRaise| is the  distance to raise 
%   the chords above the baseline of the text they sit over.
%
% \begin{macro}{\SBRuleRaiseAmount}
%   |\SBRuleRaiseAmount| is the  distance to 
%   raise the rule (as specified by\\ |\SBIntersyllableRule|) which 
%   fills the space between adjoining syllables.
%
% \begin{macro}{\SpaceAboveSTitle}
%   |\SpaceAboveSTitle| is the  space skipped 
%   by the |\STitle| macro before it prints the song title.
%
% \begin{macro}{\SpaceAfterTitleBlk}
%   |\SpaceAfterTitleBlk| is the space inserted by the song environment
%   between the \emph{title block} and the versicles.
%
% \begin{macro}{\SpaceAfterChorus}
%   |\SpaceAfterChorus| is the  vertical space 
%   to leave after an |SBChorus| environment.
%
% \begin{macro}{\SpaceAfterOpGroup}
%   |\SpaceAfterOpGroup| is the  vertical space 
%   to leave after an |SBOpGroup| environment.
%
% \begin{macro}{\SpaceAfterSBBracket}
%   |\SpaceAfterSBBracket| is the vertical space to leave after an
%   |SBBracket| environment.  This has proven troublesome to choose
%   (see also |\SpaceBeforeSBBracket| because the |list| environment
%   that produces the versicle inside of the |SBBracket| environment is
%   itself enclosed inside of a math construct (which requires the
%   |list| to have its vertical spacing supressed---otherwise the
%   vertical line forming the left bracket encloses unnecessary
%   whitespace).  The vertical spacing around a list is created by way
%   of some nontrivial macros and can't simply be copied into some other
%   context.  Thus, the choice of values for |\SpaceAfterSBBracket|
%   and |\SpaceBeforeSBBracket| have been rather arbitrarily chosen.
%
% \begin{macro}{\SpaceAfterSection}
%   |\SpaceAfterSection| is the  vertical space 
%   to leave after an |SBSection| environment.
%
% \begin{macro}{\SpaceAfterSong}
%   |\SpaceAfterSong| is the  vertical space to 
%   leave after a song.
%
% \begin{macro}{\SpaceAfterVerse}
%   |\SpaceAfterVerse| is the  vertical space to 
%   leave after an |SBVerse| environment.
%
% \begin{macro}{\SpaceBeforeSBBracket}
%   |\SpaceBeforeBBracket| is the vertical space to leave before an
%   |SBBracket| environment.  None of the other versicles have an
%   extra space inserted before them.  See |\SpaceAfterSBBracket|
%   for further explanation.
%
%    \begin{macrocode}
\newcommand{\HangAmt}            {1.5em}
\newcommand{\LeftMarginSBBracket}{2.85em}
\newcommand{\LeftMarginSBChorus} {4em}
\newcommand{\LeftMarginSBSection}{\LeftMarginSBChorus}
\newcommand{\LeftMarginSBVerse}  {\LeftMarginSBChorus}
\newcommand{\SBChordRaise}       {2.25ex}
\newcommand{\SBOldChordRaise}    {2.90ex}
\newcommand{\SBRuleRaiseAmount}  {0.57ex}
\newcommand{\SpaceAboveSTitle}   {0.5in}
\newcommand{\SpaceAfterTitleBlk} {-1.75ex}
\newcommand{\SpaceAfterChorus}   {\vspace{0ex plus0ex  minus3ex}}
\newcommand{\SpaceAfterOpGroup}  {\vspace{0ex plus0ex  minus3ex}}
\newcommand{\SpaceAfterSBBracket}{\vspace{2ex plus1ex  minus1ex}}
\newcommand{\SpaceAfterSection}  {\vspace{0ex plus0ex  minus3ex}}
\newcommand{\SpaceAfterSong}     {\vspace{0ex plus10ex minus3ex}}
\newcommand{\SpaceAfterVerse}    {\vspace{0ex plus0ex  minus3ex}}
\newcommand{\SpaceBeforeSBBracket}{\vspace{1ex plus1ex  minus1ex}}

%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \subsubsection{Internal Dimensions}
% These variables are used internally within \Songbook{} macros.  They are
% not part of the published \texttt{songbook.sty} interface; but can be used
% to tune some of its functions.
%
% \begin{macro}{\chSpaceTolerance}
% \begin{macro}{\chMiniSpace}
%   The |\chSpaceTolerance| and |\chMiniSpace| lengths are used in the |\Chr| macro.
%
% \begin{macro}{\sbBaselineSkipAmt}
%   |\sbBaselineSkipAmt| is used internally in |SBVerse|, |SBChorus|, and all the
%   other versicle environments; where hanging indentation has been accomplished
%   using a specially defined list environment.  The value of |\sbBaselineSkipAmt|
%   is recalculated immediately before each being used in each \emph{hanging indent}
%   list.
%
%    \begin{macrocode}
\newlength{\chSpaceTolerance}   \setlength{\chSpaceTolerance}{1.5mm}
\newlength{\chMiniSpace}        \setlength{\chMiniSpace}     {0.3mm}
\newlength{\sbBaselineSkipAmt}  \setlength{\sbBaselineSkipAmt}{0pt}

%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \subsection{Declaration Of Non-Core Options}
% In the \textit{Declaration Of Options} section of the \texttt{.sty}
% file we deal with the various options which a user may specify in
% the options part of the |\usepackage{songbook}| command.  Since the
% \Songbook{} style accepts standard \LaTeX2e{} papersize options, we
% deal with those in addition to the style's own options.  The
% documentation of these options is broken into two parts: the core
% options (|chordbk|, |wordbk|, \& |overhead|), and the non-core
% options (all the rest).
%
% The \LaTeX2e{} documentation specifies that the options will be
% processed in the order in which they are listed in the \texttt{.sty}
% file.  We take advantage of this fact and cause all of the options
% except the core three (|chordbk|, |wordbk|, \& |overhead|) to
% simply set flags which indicate they were user-specified.  The core
% options then do all the work.
%
%    \begin{macrocode}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%                                                      %%
%%     D E C L A R A T I O N   O F   O P T I O N S      %%
%%                                                      %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%    \end{macrocode}
%
% \subsubsection{Papersize Options}
% Paper selection options inherited from Book Class.  We process
% these first in order to remember what paper size the user has
% selected; before processing the \Songbook's own options.
%
% The code in each of these |\DeclareOption{}| clauses sets
% the |\SBpaper|\ldots{} flags to unambiguously indicate which
% papersize the user specified.
%
%    \begin{macrocode}
%%=======================================================%
%%          P A P E R S I Z E   O P T I O N S            %
%%=======================================================%
%    \end{macrocode}
%
% \begin{macro}{a4paper}
%    \begin{macrocode}
\DeclareOption{a4paper}{% Paper size: 210mm x 297mm
  \SBpaperAfourtrue
  \SBpaperAfivefalse
  \SBpaperBfivefalse
  \SBpaperLtrfalse
  \SBpaperLglfalse
  \SBpaperExcfalse
}

%    \end{macrocode}
% \begin{macro}{a5paper}
%    \begin{macrocode}
\DeclareOption{a5paper}{% Paper size: 148mm x 210mm
  \SBpaperAfourfalse
  \SBpaperAfivetrue
  \SBpaperBfivefalse
  \SBpaperLtrfalse
  \SBpaperLglfalse
  \SBpaperExcfalse
}

%    \end{macrocode}
% \begin{macro}{b5paper}
%    \begin{macrocode}
\DeclareOption{b5paper}{% Paper size: 176mm x 250mm
  \SBpaperAfourfalse
  \SBpaperAfivefalse
  \SBpaperBfivetrue
  \SBpaperLtrfalse
  \SBpaperLglfalse
  \SBpaperExcfalse
}

%    \end{macrocode}
% \begin{macro}{letterpaper}
%    \begin{macrocode}
\DeclareOption{letterpaper}{% Paper size: 8.5in x 11in
  \SBpaperAfourfalse
  \SBpaperAfivefalse
  \SBpaperBfivefalse
  \SBpaperLtrtrue
  \SBpaperLglfalse
  \SBpaperExcfalse
}

%    \end{macrocode}
% \begin{macro}{legalpaper}
%    \begin{macrocode}
\DeclareOption{legalpaper}{% Paper size: 8.5in x 14in
  \SBpaperAfourfalse
  \SBpaperAfivefalse
  \SBpaperBfivefalse
  \SBpaperLtrfalse
  \SBpaperLgltrue
  \SBpaperExcfalse
}

%    \end{macrocode}
% \begin{macro}{executivepaper}
%    \begin{macrocode}
\DeclareOption{executivepaper}{% Paper size: 7.25in x 10.5in
  \SBpaperAfourfalse
  \SBpaperAfivefalse
  \SBpaperBfivefalse
  \SBpaperLtrfalse
  \SBpaperLglfalse
  \SBpaperExctrue
}

%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \subsubsection{Compactsong Option}
%
% This option tells the \Songbook{} style to present the songs in a
% compact form.  For |chordbk| mode this means presenting the songs in
% two columns per page using a smaller font.  When I can figure out
% what this option should mean for the other modes I'll code them up.
% In the mean time, |wordbk| and |overhead| modes simply ignore the
% |compactsong| option.  Like the papersize options, the |compactsong|
% processing here simply sets a flag; the actual code required to
% implement |compactsong| mode is embedded below inside the three core
% options.
%
%    \begin{macrocode}
%%=======================================================%
%%         C O M P A C T S O N G   O P T I O N           %
%%=======================================================%
%    \end{macrocode}
% \begin{macro}{compactsong}
%    \begin{macrocode}
\DeclareOption{compactsong}{%
  %%%
  % Set flag to indicate the user wants compact song mode.
  \CompactSongModetrue
}

%    \end{macrocode}
% \end{macro}
%
% \changes{v4.1}{2003/08/31}{Added |printallsongs| option processing.}
% \subsubsection{Printallsongs Option}
%
% This option tells the \Songbook{} style to print all songs in the
% songbook, regardless of what has been specified in each song.  
% Like the papersize options, the |printallsongs|
% processing here simply sets a flag; the actual code required to
% implement |printallsongs| mode is embedded below inside the |song|
% environment.
%
%    \begin{macrocode}
%%=======================================================%
%%       P R I N T A L L S O N G S   O P T I O N         %
%%=======================================================%
%    \end{macrocode}
% \begin{macro}{printallsongs}
%    \begin{macrocode}
\DeclareOption{printallsongs}{%
  %%%
  % Set flag to indicate the user wants to print all songs.
  \PrintAllSongstrue
}

%    \end{macrocode}
% \end{macro}
%
% \subsection{Declaration Of Core Options}
% Now we deal with the Options which set up the songbook instances
% appropriately; i.e., a ``words-only'', ``chords \& words'', or
% ``overhead master'' book (|wordbk|, |chordbk|, \& |overhead|).
% These option declarations take advantage of the fact that we have
% already been told what paper size to design for.
%
% The style has been constructed on the underlying assumption that the
% user \emph{must} specify one of the core options.  To that end, we
% will later throw an error if none of these three options was
% executed (done at |\AtBeginDocument| time, see the top of the
% \textit{Main Code Part} for details).
%
%    \begin{macrocode}
%%=======================================================%
%%      S O N G B O O K   C O R E   O P T I O N S        %
%%=======================================================%
%    \end{macrocode}
%
% \subsubsection{\texttt{chordbk} Option}
% \begin{macro}{chordbk}
%   The |chordbk| option is executed here.
%
%   Each of the core options is structured similarly.  As as result,
%   the documentation for the first one, |chordbk|, will be more 
%   detailed, and the other two subsections will refer to this one.
%
%    \begin{macrocode}
\DeclareOption{chordbk}{%
%    \end{macrocode}
%
%   Set flags to indicate that we \emph{are} in |chordbk| mode.
%   Set flags to indicate we are \emph{not} in words-only mode.
%   Indicate that we \emph{do} want a page eject after every song.
%    \begin{macrocode}
  \ChordBktrue
  \WordBkfalse
  \Overheadfalse
  \WordsOnlyfalse
  \NotWordsOnlytrue
  \SongEjecttrue

%    \end{macrocode}
%
%   \paragraph{Page Layout}
%   This first part specifies the page layout considerations.
%  
%   Page layout usage recommendation: copy the appropriate page layout
%   commands to the preamble of your own document and customize them
%   appropriately.  This will over-ride the default layout specified
%   herein.  Use a structure like this one to handle the three
%   songbook types automatically for your songbooks:
%   \begin{verbatim}
%     \ifChordBk
%       <page layout for Words & Chords books>
%     \else\ifWordBk
%       <page layout for Words-Only books>
%     \else\ifOverhead
%       <page layout for Overhead masters>
%     \fi\fi\fi
%   \end{verbatim}
%
%   The only way I found to get these page layouts successfully built
%   was to draw the various frames in a drawing package and then use a
%   combination of page measurements and hand calculations to ensure I
%   had everything done correctly.  One of the key concepts that had
%   not been evident to me until just recently was that on even pages
%   the |\marginparsep| and |\marginparwidth| variables exist \emph{inside}
%   the |\evensidemargin|; this fact is not explicitly mentioned in
%   any \LaTeX{} manual I have read, not even in ``The \LaTeX{} Companion''!
%  
%   The negative |\hoffset| and |\voffset| are to overcome the DVI
%   driver default left and top margins of 1in, and all page layout
%   commands herein assume these offsets have been ``unset'' in this
%   fashion.
%
%    \begin{macrocode}
  \voffset=-1.00in
  \hoffset=-1.00in

%    \end{macrocode}
%
%   Papersize-dependant processing.  In general we don't change
%   anything except the page layout, however for smaller page
%   sizes the some of the fonts are reduced to ensure that the
%   songs fit reasonably onto the page.
%
%    \begin{macrocode}
  \ifSBpaperAfour
    \topmargin=0.5in
    \headheight=0.21in
    \headsep=0.2in
    \textheight=10.0in
    \footskip=0.19in
    %
    \oddsidemargin=0.618in
    \evensidemargin=1.4in
    \textwidth=6.25in
    \marginparsep=0.2in
    \marginparwidth=0.8in
  \else\ifSBpaperAfive
    \topmargin=6.0mm
    \headheight=5.334mm
    \headsep=2.666mm
    \textheight=185.17mm
    \footskip=4.826mm
    %
    \oddsidemargin=12.0mm
    \evensidemargin=30.0mm
    \textwidth=106.0mm
    \marginparsep=3.68mm
    \marginparwidth=20.32mm
%    \end{macrocode}
%
%   Downsize the fonts to allow song to fit into the smaller A5
%   papersize.
%
%    \begin{macrocode}
    \renewcommand{\ChBassFont}{\small\bf\sf}        % = cmss12 at 11.0pt
    \renewcommand{\ChFont}{\normalsize\fontfamily{\sfdefault}%
      \fontseries{sbc}\fontshape{n}\selectfont}     %=cmssbc12 at 12.0pt
    \renewcommand{\ChBkFont}{\ChFont\fontseries{m}  %
      \selectfont}                                  % =cmssm12 at 12.0pt
    \renewcommand{\SBDefaultFont}{\normalsize}      % = cmr12  at 12.0pt
    \renewcommand{\SBOccursBrktFont}{\large\bf\sf}  % = cmss10 at 10.9pt
  \else\ifSBpaperBfive
    \topmargin=10.0mm
    \headheight=5.334mm
    \headsep=5.0mm
    \textheight=214.84mm
    \footskip=4.826mm
    %
    \oddsidemargin=20.0mm
    \evensidemargin=34.0 mm
    \textwidth=122.0mm
    \marginparsep=3.68mm
    \marginparwidth=20.32mm
%    \end{macrocode}
%
%   Downsize the fonts to allow song to fit into the smaller B5
%   papersize.
%
%    \begin{macrocode}
    \renewcommand{\ChBassFont}{\small\bf\sf}        % = cmss12 at 11.0pt
    \renewcommand{\ChFont}{\normalsize\fontfamily{\sfdefault}%
      \fontseries{sbc}\fontshape{n}\selectfont}     %=cmssbc12 at 12.0pt
    \renewcommand{\ChBkFont}{\ChFont\fontseries{m}  %
      \selectfont}                                  % =cmssm12 at 12.0pt
    \renewcommand{\SBDefaultFont}{\normalsize}      % = cmr12  at 12.0pt
    \renewcommand{\SBOccursBrktFont}{\large\bf\sf}  % = cmss10 at 10.9pt
  \else\ifSBpaperLtr
    \topmargin=0.5in
    \headheight=0.21in
    \headsep=0.20in
    \textheight=9.4in
    \footskip=0.19in
    %
    \oddsidemargin=0.75in
    \evensidemargin=1.5in
    \textwidth=6.25in
    \marginparsep=0.2in
    \marginparwidth=0.8in
  \else\ifSBpaperLgl
    \topmargin=0.5in
    \headheight=0.21in
    \headsep=0.20in
    \textheight=12.4in
    \footskip=0.19in
    %
    \oddsidemargin=0.75in
    \evensidemargin=1.5in
    \textwidth=6.25in
    \marginparsep=0.2in
    \marginparwidth=0.8in
  \else\ifSBpaperExc
    \topmargin=0.25in
    \headheight=0.21in
    \headsep=0.165in
    \textheight=9.435in
    \footskip=0.19in
    %
    \oddsidemargin=0.5in
    \evensidemargin=1.25in
    \textwidth=5.5in
    \marginparsep=0.2in
    \marginparwidth=0.8in
  \fi\fi\fi\fi\fi\fi

%    \end{macrocode}
%
%   Enable ragged bottom.
%
%    \begin{macrocode}
  \raggedbottom

%    \end{macrocode}
%
%   \paragraph{CompactSong Processing}
%
%   Downsize fonts to allow song to fit into half the space (i.e., 
%   two column mode); although the title will not be reset since
%   it will be presented unchanged from normal chordbk mode.
%
%    \begin{macrocode}
  \ifCompactSongMode
    \renewcommand{\ChBassFont}{\small\bf\sf}        % = cmss12 at 11.0pt
    \renewcommand{\ChFont}{\normalsize\fontfamily{\sfdefault}%
      \fontseries{sbc}\fontshape{n}\selectfont}     %=cmssbc12 at 12.0pt
    \renewcommand{\ChBkFont}{\ChFont\fontseries{m}  %
      \selectfont}                                  % =cmssm12 at 12.0pt
    \renewcommand{\SBDefaultFont}{\normalsize}      % = cmr12  at 12.0pt
    \renewcommand{\SBOccursBrktFont}{\large\bf\sf}  % = cmss10 at 10.9pt

%    \end{macrocode}
%
%   Multicol specific changes.
%
%    \begin{macrocode}
    \setlength{\columnsep}{0.25in}

%    \end{macrocode}
%
%   Remove side-margin, since marginal notes are not allowed when
%   using multicol.sty.
%
%    \begin{macrocode}
    \addtolength{\textwidth}     {\marginparsep + \marginparwidth}
    \addtolength{\evensidemargin}{-\marginparsep - \marginparwidth}
    \setlength  {\marginparsep}  {0in}
    \setlength  {\marginparwidth}{0in}

%    \end{macrocode}
%
%   Reduce minimum spacing amount used in |\Chr| macro (since we're
%   now using a smaller font for lyrics and chords.
%
%    \begin{macrocode}
    \setlength{\chSpaceTolerance}{1.0mm}

%    \end{macrocode}
%
%   Remove the extra space before Verses, etc.
%
%    \begin{macrocode}
    \renewcommand{\HangAmt}            {1.5em}
    \renewcommand{\LeftMarginSBChorus} {2em}
    \renewcommand{\LeftMarginSBSection}{\LeftMarginSBChorus}
    \renewcommand{\LeftMarginSBVerse}  {\LeftMarginSBChorus}
  \fi
}

%    \end{macrocode}
% \end{macro}
%
% \subsubsection{\texttt{wordbk} Option}
% \begin{macro}{wordbk}
%   The |wordbk| option is executed here.
%
%    \begin{macrocode}
\DeclareOption{wordbk}{%
%    \end{macrocode}
%
%   Set flags to indicate we \emph{are} in wordbk mode.
%   Set flags to indicate we \emph{are} in words-only mode.
%   Indicate that we do \emph{not} want a page eject after every song.
%
%    \begin{macrocode}
  \ChordBkfalse
  \WordBktrue
  \Overheadfalse
  \WordsOnlytrue
  \NotWordsOnlyfalse
  \SongEjectfalse

%    \end{macrocode}
%
%   Set fonts for |wordbk| use.
%
%    \begin{macrocode}
  \renewcommand{\SBDefaultFont}{\normalsize}
  \font\mySTNFont=cmtt12 at 17pt
  \renewcommand{\STitleNumberFont}{\mySTNFont}
  \renewcommand{\CpyRtFont}{\scriptsize}
  \renewcommand{\WandMFont}{\scriptsize}
  \renewcommand{\ScriptRefFont}{\scriptsize}
  \renewcommand{\SBOccursBrktFont}{\large\bf\sf}

%    \end{macrocode}
%
%   Reset a few of the song spacing amounts.
%
%    \begin{macrocode}
  \renewcommand{\SpaceAboveSTitle}   {0.25in}
  \renewcommand{\LeftMarginSBChorus} {1.5em}
  \renewcommand{\LeftMarginSBSection}{\LeftMarginSBChorus}
  \renewcommand{\LeftMarginSBVerse}  {\LeftMarginSBChorus}

%    \end{macrocode}
%
% See the page layout comment in the |\DeclareOption{chordbk}|
% section, above, for usage recommendations w.r.t. page layout
% commands.
%
% The negative |\hoffset| and |\voffset| are to overcome the DVI driver
% default left and top margins of 1in, and all page layout commands
% herein assume these offsets have been ``unset'' in this fashion.
%
%    \begin{macrocode}
  \voffset=-1.00in
  \hoffset=-1.00in

%    \end{macrocode}
%
%   Papersize-dependant processing.
%
%    \begin{macrocode}
  \ifSBpaperAfour
    \topmargin=0.5in
    \headheight=0.21in
    \headsep=0.2in
    \textheight=10.0in
    \footskip=0.19in
    %
    \oddsidemargin=0.618in
    \evensidemargin=0.4in
    \textwidth=7.25in
    \marginparsep=0.0in
    \marginparwidth=0.0in
  \else\ifSBpaperAfive
    \topmargin=6.0mm
    \headheight=5.334mm
    \headsep=2.666mm
    \textheight=185.17mm
    \footskip=4.826mm
    %
    \oddsidemargin=12.0mm
    \evensidemargin=6.0mm
    \textwidth=130.0mm
    \marginparsep=0.0mm
    \marginparwidth=0.0mm
  \else\ifSBpaperBfive
    \topmargin=10.0mm
    \headheight=5.334mm
    \headsep=5.0mm
    \textheight=214.84mm
    \footskip=4.826mm
    %
    \oddsidemargin=20.0mm
    \evensidemargin=10.0mm
    \textwidth=146.0mm
    \marginparsep=0.0mm
    \marginparwidth=0.0mm
  \else\ifSBpaperLtr
    \topmargin=0.5in
    \headheight=0.21in
    \headsep=0.10in
    \textheight=9.4in
    \footskip=0.29in
    %
    \oddsidemargin=0.75in
    \evensidemargin=0.5in
    \textwidth=7.25in
    \marginparsep=0.0in
    \marginparwidth=0.0in
  \else\ifSBpaperLgl
    \topmargin=0.5in
    \headheight=0.21in
    \headsep=0.20in
    \textheight=12.4in
    \footskip=0.19in
    %
    \oddsidemargin=0.75in
    \evensidemargin=0.5in
    \textwidth=7.25in
    \marginparsep=0.0in
    \marginparwidth=0.0in
  \else\ifSBpaperExc
    \topmargin=0.25in
    \headheight=0.21in
    \headsep=0.165in
    \textheight=9.435in
    \footskip=0.19in
    %
    \oddsidemargin=0.5in
    \evensidemargin=0.25in
    \textwidth=6.5in
    \marginparsep=0.0in
    \marginparwidth=0.0in
  \fi\fi\fi\fi\fi\fi

%    \end{macrocode}
%
%   Set ragged-right margins.
%
%    \begin{macrocode}
  \raggedright

%    \end{macrocode}
%
%   Do CompactSong processing, which at this time is nothing except
%   resetting the |compactsong| flag back to false; to ensure that
%   no |compactsong| processing occurs.  We take time to print a
%   warning message for the user to remind them that the |compactsong|
%   option will not have any effect at this time.
%
%    \begin{macrocode}
  \ifCompactSongMode
    \typeout{``compactsong'' mode not implemented for Wordbk mode.}
    \CompactSongModefalse
  \fi
}

%    \end{macrocode}
% \end{macro}
%
% \subsubsection{\texttt{overhead} Option}
% \begin{macro}{overhead}
%   The |wordbk| option is executed here.
%
%    \begin{macrocode}
\DeclareOption{overhead}{%
%    \end{macrocode}
%
%   Set flags to indicate we \emph{are} in overhead mode.
%   Set flags to indicate we \emph{are} in words-only mode.
%   Indicate that we \emph{do} want a page eject after every song.
%
%    \begin{macrocode}
  \ChordBkfalse
  \WordBkfalse
  \Overheadtrue
  \WordsOnlytrue
  \NotWordsOnlyfalse
  \SongEjecttrue

%    \end{macrocode}
%
%   Set fonts for |overhead| use.  Before doing any font stuff,
%   change the regular sans serif font to demi-bold condensed.
%
%    \begin{macrocode}
  \def\@mss{cmssdc10}
  \renewcommand{\SBDefaultFont}{\LARGE\bf\sf}
  \renewcommand{\STitleNumberFont}{\Large\sf}
  \renewcommand{\STitleFont}{\LARGE\sf}
  \renewcommand{\CpyRtFont}{\normalsize\rm}
  \renewcommand{\CpyRtInfoFont}{\normalsize\rm}
  \renewcommand{\WandMFont}{\normalsize\rm}
  \renewcommand{\ScriptRefFont}{\normalsize\rm}
  \renewcommand{\SBLyricNoteFont}{\normalsize\rm}
  \renewcommand{\SBChorusTagFont}{\Large\sf}
  \renewcommand{\SBVerseNumberFont}{\Large\sf}
  \renewcommand{\SBSectionNumberFont}{\Large\sf}
  \renewcommand{\SBOccursTagFont}{\Large\sf}
  \renewcommand{\SBOccursBrktFont}{\huge\sf}
  \renewcommand{\SBBracketTagFont}{\Large\sf}
  \renewcommand{\SBOHContTagFont}{\Large\sf\itshape}

%    \end{macrocode}
%
%   Reset a few of the song spacing amounts.
%
%    \begin{macrocode}
  \renewcommand{\SpaceAboveSTitle}   {0.25in}
  \renewcommand{\LeftMarginSBBracket}{2.25em}
  \renewcommand{\LeftMarginSBChorus} {1.5em}
  \renewcommand{\LeftMarginSBSection}{\LeftMarginSBChorus}
  \renewcommand{\LeftMarginSBVerse}  {\LeftMarginSBChorus}

%    \end{macrocode}
%
%   Reset the \baselinestretch.  For some reason I'm not getting good
%   results with the default value.
%
%    \begin{macrocode}
  \renewcommand{\baselinestretch}{.9}

%    \end{macrocode}
%
%   See the page layout comment in the |\DeclareOption{chordbk}|
%   section, above, for usage recommendations w.r.t. page layout
%   commands.
%
%   General note re: |\textwidth| and overhead tranparencies: it is my
%   personal experience that with font sizes used in overhead mode,
%   a |\textwidth| of greater than 6in produces too wide an image for
%   use in all situations.  Depending upon how you intend to use
%   your overheads, you may be able to use a wider image, however
%   if you are uncertain I strongly recommend you stick with the 6in
%   |\textwidth| that is specified herein.
%
%   The negative |\hoffset| and |\voffset| are to overcome the DVI driver
%   default left and top margins of 1in, and all page layout commands
%   herein assume these offsets have been ``unset'' in this fashion.
%
%    \begin{macrocode}
  \voffset=-1.00in
  \hoffset=-1.00in

%    \end{macrocode}
%
%   Papersize-dependant processing.
%
%    \begin{macrocode}
  \ifSBpaperAfour
    \topmargin=0.25in
    \headheight=0.25in
    \headsep=0.0in
    \textheight=10.3in
    \footskip=0.2in
    %
    \oddsidemargin=1.134in
    \evensidemargin=1.134in
    \textwidth=6.0in
    \marginparsep=0.0in
    \marginparwidth=0.0in
  \else\ifSBpaperAfive
    \topmargin=0.0mm
    \headheight=5.334mm
    \headsep=0.0mm
    \textheight=193.666mm
    \footskip=4.826mm
    %
    \oddsidemargin=9.0mm
    \evensidemargin=9.0mm
    \textwidth=130.0mm
    \marginparsep=0.0mm
    \marginparwidth=0.0mm
  \else\ifSBpaperBfive
    \topmargin=0.666mm
    \headheight=5.334mm
    \headsep=0.0mm
    \textheight=229.0mm
    \footskip=4.826mm
    %
    \oddsidemargin=15.0mm
    \evensidemargin=15.0mm
    \textwidth=146.0mm
    \marginparsep=0.0mm
    \marginparwidth=0.0mm
  \else\ifSBpaperLtr
    \topmargin=0.25in
    \headheight=0.25in
    \headsep=0.0in
    \textheight=9.75in
    \footskip=0.2in
    %
    \oddsidemargin=1.25in
    \evensidemargin=1.25in
    \textwidth=6.0in
    \marginparsep=0.0in
    \marginparwidth=0.0in
  \else\ifSBpaperLgl
    \topmargin=0.25in
    \headheight=0.25in
    \headsep=0.0in
    \textheight=12.8in
    \footskip=0.2in
    %
    \oddsidemargin=1.25in
    \evensidemargin=1.25in
    \textwidth=6.0in
    \marginparsep=0.0in
    \marginparwidth=0.0in
  \else\ifSBpaperExc
    \topmargin=0.25in
    \headheight=0.21in
    \headsep=0.0in
    \textheight=9.6in
    \footskip=0.19in
    %
    \oddsidemargin=0.625in
    \evensidemargin=0.625in
    \textwidth=6.0in
    \marginparsep=0.0in
    \marginparwidth=0.0in
  \fi\fi\fi\fi\fi\fi

%    \end{macrocode}
%
%   Set ragged-botton and ragged-right margins.
%
%    \begin{macrocode}
  \raggedright
  \raggedbottom

%    \end{macrocode}
%
%   Do CompactSong processing, which at this time is nothing except
%   resetting the |compactsong| flag back to false; to ensure that
%   no |compactsong| processing occurs.  We take time to print a
%   warning message for the user to remind them that the |compactsong|
%   option will not have any effect at this time.
%
%    \begin{macrocode}
  \ifCompactSongMode
    \typeout{``compactsong'' mode not implemented for Overhead mode.}
    \CompactSongModefalse
  \fi
}

%    \end{macrocode}
% \end{macro}
%
% \subsection{Execution Of Options}
% Here we tell the the \Songbook{} style to execute the user's
% declared options.
%
% First set up a default paper size, just in case the user didn't
% specify one.  Then process the user specified options.  It is
% mandatory for one of the songbook type options to be declared,
% but rather than delare a default we will throw an error (see
% below at the top of the \textit{Main Code Part}).
%
%    \begin{macrocode}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%                                                      %%
%%       E X E C U T I O N   O F   O P T I O N S        %%
%%                                                      %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ExecuteOptions{letterpaper}
\ProcessOptions

%    \end{macrocode}
%
% \subsection{Package Loading Part}
% In this section of the style we load the remaining styles 
% upon which the \Songbook{} style is dependant.
%
%    \begin{macrocode}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%                                                      %%
%%       P A C K A G E   L O A D I N G   P A R T        %%
%%                                                      %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%    \end{macrocode}
%
% Donald Arseneau's \texttt{conditionals.sty}.  This style
% is bundled with the \Songbook{} style (Donald has often posted
% the macros to the USENET comp.text.tex newsgroup, but they
% haven't been formally submitted to CTAN.
%
%    \begin{macrocode}
\RequirePackage{conditionals}

%    \end{macrocode}
%
% Leslie Lamport's \& David Carlilse's \texttt{ifthen.sty}.  This
% style is part of the \LaTeX2e{} distribution.
%
%    \begin{macrocode}
\RequirePackage{ifthen}

%    \end{macrocode}
%
% If we are in |compactsong| mode then load Frank Mittelbach's
% |multicol| package.  We specify the date of the 1.5u release;
% since we make use of the |\columnbreak| command which was only
% added in 1.5u.
%
%    \begin{macrocode}
\ifCompactSongMode
  \RequirePackage{multicol}[1999/05/25]
\fi

%    \end{macrocode}
%
% \subsection{Main Code Part}
% The \textit{Main Code Part} is the main part of the style.  All
% of the ``hard working'' macros are detailed below.
%
%    \begin{macrocode}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%                                                      %%
%%              M A I N   C O D E   P A R T             %%
%%                                                      %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%    \end{macrocode}
%
% The user \emph{must} specify at least one of the |chordbk|, |wordbk|,
% or |overhead| options; otherwise we throw an error.  This 
% bit of code performs that check at the start of the users
% document.
%
% We check to see if at least one of the core options have
% been specified by the user by populating an |\hbox{}| with
% the digit ``1'' if an option was specified.  If no core
% option was specified then the |\hbox{}| will be empty and
% we throw an error.
%
% \begin{macro}{\AtBeginDocument}
%    \begin{macrocode}
\AtBeginDocument{%
  \setbox0=\hbox{}
  %
  \ifChordBk\setbox0=\hbox{1}\fi
  \ifWordBk\setbox0=\hbox{1}\fi
  \ifOverhead\setbox0=\hbox{1}\fi
  %
  \ifthenelse{\wd0 = 0}
    {\errmessage{No songbook option (i.e., type) specified.  
        Specify a songbook mode in your usepackage
        statement; one of: [chordbk], [wordbk], or [overhead]}}
    {\relax}

%    \end{macrocode}
%
% If the user had specified one of the required options then we
% continue with setting things up.  At present, the only housekeeping
% item that needs attention is to set the default font for the 
% songbook.  We do this by inserting the |\SBDefaultFont| here;
% this lifts from the user the burden of having to remember to
% specifying inside the songbook.
%
%    \begin{macrocode}
  \SBDefaultFont
}

%    \end{macrocode}
% \end{macro}
%
% \subsubsection{Constants \& Variables}
% Define Counters used herein.
%
%    \begin{macrocode}
%%========================================================
%%      C O N S T A N T S   &   V A R I A B L E S        %
%%========================================================

%    \end{macrocode}
%
% \begin{macro}{\theSBSongCnt}
%   The |\theSBSongCnt| 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.
%
% \begin{macro}{\theSBSectionCnt}
%   The |\theSBSectionCnt| counter is used for numbering
%   sections as they occur within a song.
%
% \begin{macro}{\theSBVerseCnt}
%   The |\theSBVerseCnt| counter is used for numbering
%   verses as they occur within a song.
%
%    \begin{macrocode}
\newcounter{SBSongCnt}
\newcounter{SBSectionCnt}
\newcounter{SBVerseCnt}
%    \end{macrocode}
%
% \end{macro}
% \end{macro}
% \end{macro}
%    \begin{macrocode}

%    \end{macrocode}
%
% \paragraph{String Constants}
% Declare 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.
%
% \begin{macro}{\OHContPgFtrTag}
%   The |\OHContPgFtrTag| tag is inserted by the |\OHContPgFtr| command.
%   The default value for this is ``|continued on next page\ldots|''.
%
% \begin{macro}{\OHContPgHdrTag}
%   The |\OHContPgHdrTag| tag is inserted by the |\OHContPgHdr| command.
%   The default value for this is 
%   ``|\theSBSongCnt\ --- \theSongTitle, continued\ldots|''.
%
% \begin{macro}{\SBBridgeTag}
%   The |\SBBridgeTag| tag is inserted before the start of a bridge.
%   The default value for this is ``|Bridge:|''.
%
% \begin{macro}{\SBChorusTag}
%   The |\SBChorusTag| tag is inserted before the first line of a
%   chorus.  The default value for this is ``|Ch:|''.
%
% \begin{macro}{\SBContinueTag}
%   The |\SBContinueTag| tag is inserted in an |\SBContinueMark|.
%   The default value for this is ``|cont\ldots|''.
%
% \begin{macro}{\SBEndTag}
%   The |\SBEndTag| tag is inserted before the start of an
%   ending (in an |\SBEnd| command).  The default value for this
%   is ``|End:|''.
%
% \begin{macro}{\SBIntersyllableRule}
%   The |\SBIntersyllableRule| tag is actually the command(s) used
%   to draw the rule between adjoining syllables.
%
% \begin{macro}{\SBIntroTag}
%   The |\SBIntroTag| tag is inserted before the start of an
%   introduction (in an |\SBIntro| command).  The default value
%   for this is ``|Intro:|''.
%
% \begin{macro}{\SBPubDom}
%   The |\SBPubDom| tag is used to indicate that a song is in the public
%   domain.  The default value for this is ``|Public Domain|''.  If you 
%   want to localize this string in the song title block, be sure to use
%   this public interface: the |\CpyRt| macro uses |\SBPubDom| to
%   determine whether or not to print the copyright symbol (\copyright).
%
% \begin{macro}{\SBUnknownTag}
%   The |\SBUnknownTag| tag is used with the |\WAndM| command and is the
%   string to insert when either the author/artist or the copyright holder
%   is unknown.  The default value for this is ``|Unknown|''.
%
% \begin{macro}{\SBWAndMTag}
%   The |\SBWAndMTag| the tag is insert before the words and music
%   entry printed in the song header.  The default value for this is
%   ``|W&M:|''.
%
% \begin{macro}{\Songbook}
%   The macro used to print this style's name.  The `b' in the word
%   songbook has been replace with a flat ($\flat$).
%
%    \begin{macrocode}
\newcommand{\OHContPgFtrTag}     {continued on next page\ldots}
\newcommand{\OHContPgHdrTag}     {\theSBSongCnt\ --- \theSongTitle, continued\ldots}
\newcommand{\SBBridgeTag}        {Bridge:}
\newcommand{\SBChorusTag}        {Ch:}
\newcommand{\SBContinueTag}      {cont\ldots}
\newcommand{\SBEndTag}           {End:}
\newcommand{\SBIntersyllableRule}{\hrulefill}
\newcommand{\SBIntroTag}         {Intro:}
\newcommand{\SBPubDom}           {Public Domain}
\newcommand{\SBUnknownTag}       {Unknown}
\newcommand{\SBWAndMTag}         {W\&M:}
\newcommand{\Songbook}           {\textrm{Song$\flat$ook}}

%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \paragraph{Internal Song Variables}
% Declare song attribute variables.
%
% These variables are intended for consumption within the songbook
% style itself, so they will \emph{not} be documented in the 
% \textit{High Level Documentation} section, above.
%
% \begin{macro}{\theSongComposer}
%   |\theSongComposer| is the composer and lyricist of the last song.
%
% \changes{v4.2}{2006/10/13}{Added new |theSongComposerU| variable.}
% \begin{macro}{\theSongComposerU}
%   |\theSongComposerU| takes the value of |\theSongComposer| except 
%   when the song composer parameter was left empty in the songbook;
%   in which case this variable will be assigned the value of 
%   |\SBUnknownTag|.
%
% \begin{macro}{\theSongKey}
%   |\theSongKey| is the key of the last song.  This variable must be
%   reset within the |\STitle| command, as well as at the
%   start of the song environment, because of the way in
%   which extra keys are handled.
%
% \begin{macro}{\theSongLicense}
%   |\theSongLicense| is the copyright license info.
%
% \begin{macro}{\theSongTitle}
%   |\theSongTitle| is the title of the last song.
%
% \begin{macro}{\theCopyRtInfo}
%   |\theCopyRtInfo| is the copyright information of the last song.
%   This includes the copyright licensing information.
%
% \begin{macro}{\theScriptureRef}
%   |\theScriptureRef| is the scripture reference of the last song.
%
% \begin{macro}{\theXlatnBy}
%   |\theXlatnBy| is who translated the song.
%
% \begin{macro}{\theXlatnPerm}
%   |\theXlatnPerm| is the permission details for the last song
%   translation.  This variable is reset to an empty
%   string at the start of each song environment.
%
% \begin{macro}{\theXlatnTitle}
%   |\theXlatnTitle| is the title of the last song-translation.  This
%   variable is reset to an empty string at the start of
%   each song environment.
%
%    \begin{macrocode}
\newcommand{\theSongComposer}{the Composer}
\newcommand{\theSongComposerU}{the ComposerU}
\newcommand{\theSongCopyRt}{the Copyright}
\newcommand{\theSongKey}{the Key}
\newcommand{\theSongLicense}{the License}
\newcommand{\theSongScriptRef}{the Scripture}
\newcommand{\theSongTitle}{the Title}
\newcommand{\theXlatnBy}{the Translator}
\newcommand{\theXlatnPerm}{the Permission}
\newcommand{\theXlatnTitle}{the Translation Title}

%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \subsubsection{Special Characters}
% Some macros to ease the entry of special characters in songbooks.
%
%    \begin{macrocode}
%%=======================================================%
%%          S P E C I A L   C H A R A C T E R S          %
%%=======================================================%

%    \end{macrocode}
%
% \begin{macro}{\SBem}
%   |\SBem| --- em-dash macro definition.
%   \begin{ParameterList}
%     \item None.
%   \end{ParameterList}
%
% Generate an em-dash within a songbook.  This macro is used to place
% in em-dash within text when we're \emph{not} in words-only mode.  This
% allows us to place dashes within text in order place a chord earlier 
% than a sylable; yet, that dash will not appear in the words-only book. 
% The words-only version of this macro is a no-op.  Example of intended 
% use:
%
%    \begin{macrocode}
\newcommand{\SBem}{\ifWordsOnly\relax\else---\fi}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SBen}
%   |\SBen| --- en-dash macro definition.
%   \begin{ParameterList}
%     \item None.
%   \end{ParameterList}
%
%   Generate an en-dash within a songbook.  This macro is used to place
%   in en-dash within text when we're \emph{not} in words-only mode; just like
%   |\SBem|.  The words-only version of this macro is a no-op.
%
%    \begin{macrocode}
\newcommand{\SBen}{\ifWordsOnly\relax\else--\fi}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SBContinueMark}
%   |\SBContinueMark| --- conditionally produce a continuation symbol.
%   \begin{ParameterList}
%     \item None.
%   \end{ParameterList}
%
%   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.
%%%
%    \begin{macrocode}
\newcommand{\SBContinueMark}{%
  \setbox0=\hbox{\rightmark}
  \ifthenelse{\lengthtest{\wd0 = 0pt}}
  {\relax}%
  {\SBContinueTag}%
  }

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\OHContPgFtr}
%   |\OHContPgFtr| --- macro to print page footing continuation 
%   headers on overheads.
%   \begin{ParameterList}
%     \item None.
%   \end{ParameterList}
%
%   This macro must be manually inserted where needed.  It is
%   generally used in conjunction with the |\OHPageBrk| and |\OHPageHdr|
%   macros.  |\OHContPgFtr| is a no-op, except when |\ifOverhead| is true.
%
%    \begin{macrocode}
\newcommand{\OHContPgFtr}{%
  \ifOverhead
    \vskip .25in
    \centerline{\SBOHContTagFont\OHContPgFtrTag}
  \else%
    \relax%
  \fi}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\OHContPgHdr}
%   |\OHContPgHdr| --- macro to print page heading continuation
%   headers on overheads.
%   \begin{ParameterList}
%     \item None.
%   \end{ParameterList}
%
%   This macro must be manually inserted where needed.  It is
%   generally used in conjunction with the |\OHPageBrk| macro.
%   |\OHContPgHdr| is a no-op, except when |\ifOverhead| is true.
%
%    \begin{macrocode}
\newcommand{\OHContPgHdr}{%
  \ifOverhead
    \centerline{\SBOHContTagFont\OHContPgHdrTag}
    \vskip .25in
  \else%
    \relax%
  \fi}

%    \end{macrocode}
% \end{macro}
%
% \subsubsection{Table Of Contents \& Indices}
% The macros used to create the \textit{Key Index}, the 
% \textit{Title \& First Line Index}, and the \texttt{Table
% Of Contents}.  Planned enhancements are the addition of
% a \textit{Scripture Index} and a \textit{Artist Index};
% i.e., an index of the |\ScriptRef{}| and |\WandM{}|
% entries, respectively.
%
% Most of the specific code involved in managing the index files
% and writing the entries was copied from \texttt{latex.tex} (version~2.09)
% and then modified to suit our purposes here.
%
%    \begin{macrocode}
%%=======================================================%
%%          T A B L E   O F   C O N T E N T S            %
%%                                                       %
%%                A N D   I N D I C E S                  %
%%=======================================================%
%    \end{macrocode}
%
% \changes{v4.2}{2006/10/13}{Added |makeArtistIndex| and necessary children.}
% \begin{macro}{\makeArtistIndex}
%   |\makeArtistIndex| starts the creation of an index of artists.
%   \begin{ParameterList}
%     \item None.
%   \end{ParameterList}
%
%    \begin{macrocode}
\def\makeArtistIndex{\if@filesw \newwrite\@artistIndexfile
  \immediate\openout\@artistIndexfile=\jobname.aIdx
  \def\artistIndex{\@bsphack\begingroup
             \def\protect####1{\string####1\space}\@sanitize
             \@wrArtistIndex}\typeout
  {Writing index file \jobname.aIdx }\fi}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\artistIndex}
%   |\artistIndex|\parm{1}\parm{2} makes an entry in the index of songs
%   by artist.
%   \begin{ParameterList}
%     \item[\meta{1}] Song artist.
%     \item[\meta{2}] Song title and number.
%   \end{ParameterList}
%
%    \begin{macrocode}
\def\@wrArtistIndex#1#2{\let\thepage\relax
   \xdef\@gtempa{\write\@artistIndexfile{\string
      \indexentry{#1}{#2}}}\endgroup\@gtempa
   \if@nobreak \ifvmode\nobreak\fi\fi\@esphack}

\def\artistIndex{\@bsphack\begingroup \@sanitize\@artistIndex}

\def\@artistIndex#1#2{\endgroup\@esphack}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\makeKeyIndex}
%   |\makeKeyIndex| starts the creation of an index of songs 
%   by key.
%   \begin{ParameterList}
%     \item None.
%   \end{ParameterList}
%
%    \begin{macrocode}
\def\makeKeyIndex{\if@filesw \newwrite\@keyIndexfile
  \immediate\openout\@keyIndexfile=\jobname.kIdx
  \def\keyIndex{\@bsphack\begingroup
             \def\protect####1{\string####1\space}\@sanitize
             \@wrKeyIndex}\typeout
  {Writing index file \jobname.kIdx }\fi}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\keyIndex}
%   |\keyIndex|\parm{1}\parm{2} makes an entry in the index of songs
%   by key.
%   \begin{ParameterList}
%     \item[\meta{1}] Song key and title.
%     \item[\meta{2}] Song number.
%   \end{ParameterList}
%
%    \begin{macrocode}
\def\@wrKeyIndex#1#2{\let\thepage\relax
   \xdef\@gtempa{\write\@keyIndexfile{\string
      \indexentry{#1}{#2}}}\endgroup\@gtempa
   \if@nobreak \ifvmode\nobreak\fi\fi\@esphack}

\def\keyIndex{\@bsphack\begingroup \@sanitize\@keyIndex}

\def\@keyIndex#1#2{\endgroup\@esphack}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\makeTitleIndex}
%   |\makeTitleIndex| starts creation of a title \& first line index.
%   \begin{ParameterList}
%     \item None.
%   \end{ParameterList}
%
%    \begin{macrocode}
\def\makeTitleIndex{\if@filesw \newwrite\@titleIndexfile
  \immediate\openout\@titleIndexfile=\jobname.tIdx
  \def\titleIndex{\@bsphack\begingroup
             \def\protect####1{\string####1\space}\@sanitize
             \@wrTitleIndex}\typeout
  {Writing index file \jobname.tIdx }\fi}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\titleIndex}
%   |\titleIndex|\parm{1}\parm{2} makes an entry in the title \&
%   first line index.
%   \begin{ParameterList}
%     \item[\meta{1}] Song title or first line.
%     \item[\meta{2}] Song number.
%   \end{ParameterList}
%
%    \begin{macrocode}
\def\@wrTitleIndex#1#2{\let\thepage\relax
   \xdef\@gtempa{\write\@titleIndexfile{\string
      \indexentry{#1}{#2}}}\endgroup\@gtempa
   \if@nobreak \ifvmode\nobreak\fi\fi\@esphack}

\def\titleIndex{\@bsphack\begingroup \@sanitize\@titleIndex}

\def\@titleIndex#1#2{\endgroup\@esphack}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\makeTitleContents}
%   |\makeTitleContents| starts creation of a table of contents.
%   \begin{ParameterList}
%     \item None.
%   \end{ParameterList}
%
%    \begin{macrocode}
\def\makeTitleContents{\if@filesw \newwrite\@titleContentsfile
  \immediate\openout\@titleContentsfile=\jobname.toc
  \def\titleContents{\@bsphack\begingroup
             \def\protect####1{\string####1\space}\@sanitize
             \@wrTitleContents}\typeout
  {Writing table of contents file \jobname.toc }\fi}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\titleContents}
%   |\titleContents|\parm{1}\parm{2} makes an entry in the table
%   of contents file.
%   \begin{ParameterList}
%     \item[\meta{1}] Song number.
%     \item[\meta{2}] Song title.
%   \end{ParameterList}
%
%    \begin{macrocode}
\def\@wrTitleContents#1#2{\let\thepage\relax
   \xdef\@gtempa{\write\@titleContentsfile{\string
       \item\ \theSBSongCnt. #1\protect\hbox{, \thepage}}}\endgroup\@gtempa
   \if@nobreak \ifvmode\nobreak\fi\fi\@esphack}

\def\titleContents{\@bsphack\begingroup \@sanitize\@titleContents}

\def\@titleContents#1#2{\endgroup\@esphack}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SBtocSEntry}
%   |\SBtocSEntry| is the macro that encloses each skipped song TOC entry.
%   The intent is that when you format your skipped TOC list you redefine
%   |\SBtocSEntry| appropriately (assuming you are not happy with the
%   default value).
%   \begin{ParameterList}
%     \item[\meta{1}] Song number.
%     \item[\meta{2}] Song title.
%     \item[\meta{3}] Page number.
%   \end{ParameterList}
%
%    \begin{macrocode}
\newcommand{\SBtocSEntry}[3]{#1. \textit{#2}\hbox{, #3}}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\makeTitleContentsSkip}
%   |\makeTitleContentsSkip| starts creation of a table of contents
%   of songs excluded from the songbook.
%   \begin{ParameterList}
%     \item None.
%   \end{ParameterList}
%
%    \begin{macrocode}
\def\makeTitleContentsSkip{\if@filesw \newwrite\@titleContentsSkipfile
  \immediate\openout\@titleContentsSkipfile=\jobname.tocS
  \def\titleContentsSkip{\@bsphack\begingroup
             \def\protect####1{\string####1\space}\@sanitize
             \@wrTitleContentsSkip}\typeout
  {Writing table of contents (skipped) file \jobname.tocS }\fi}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\titleContentsSkip}
%   |\titleContentsSkip|\parm{1}\parm{2} makes an entry in the table
%   of contents file.
%   \begin{ParameterList}
%     \item[\meta{1}] Song number.
%     \item[\meta{2}] Song title.
%   \end{ParameterList}
%
%    \begin{macrocode}
\def\@wrTitleContentsSkip#1#2{\let\thepage\relax
   \xdef\@gtempa{\write\@titleContentsSkipfile{\string
       \item\ \protect\SBtocSEntry{\theSBSongCnt}{#1}{\thepage}}}\endgroup\@gtempa
   \if@nobreak \ifvmode\nobreak\fi\fi\@esphack}

\def\titleContentsSkip{\@bsphack\begingroup \@sanitize\@titleContentsSkip}

\def\@titleContentsSkip#1#2{\endgroup\@esphack}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\FLineIdx}
%   |\FLineIdx|\parm{1} adds a first line of song entry to
%   the song \& title index file~(\texttt{.idx}).
%   \begin{ParameterList}
%     \item[\meta{1}] First line of song.
%   \end{ParameterList}
%
%    \begin{macrocode}
\newcommand{\FLineIdx}[1]{\titleIndex{#1@{\it #1\/}}{\theSBSongCnt}}

%    \end{macrocode}
% \end{macro}
%
% \subsubsection{Some Other Hooks}
% The macros have been provided to allow the user additional control
% of songbooks created by the \Songbook{} package.
%
%    \begin{macrocode}
%%=======================================================%
%%           S O M E   O T H E R   H O O K S             %
%%=======================================================%

%    \end{macrocode}
%
% \begin{macro}{\SBChorusMarkright}
%   The |\SBChorusMarkright|\parm{1} hook to allow |\SBSection|'s |\markright|
%   to be overridden.
%
%    \begin{macrocode}
\newcommand{\SBChorusMarkright}[1]{\markright{#1}}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SBVerseMarkright}
%   The |\SBVerseMarkright|\parm{1} hook to allow |\SBVerse|'s |\markright|
%   to be overridden.
%
%    \begin{macrocode}
\newcommand{\SBVerseMarkright}[1]{\markright{#1}}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SBSectionMarkright}
%   The |\SBSectionMarkright|\parm{1} hook to allow |\SBSection|'s |\markright|
%   to be overridden.
%
%    \begin{macrocode}
\newcommand{\SBSectionMarkright}[1]{\markright{\alph{#1}}}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SongMarkboth}
%   The |\SongMarkboth|\parm{1}\parm{2} hook to allow the song environment's |\markboth|
%   to be overridden.
%
%    \begin{macrocode}
\newcommand{\SongMarkboth}[2]{\markboth{#1}{#2}}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\STitleMarkboth}
%   The |\STitleMarkboth|\parm{1}\parm{2} hook to allow |\Stitle|'s |\markboth| to be
%   overridden.
%
%    \begin{macrocode}
\newcommand{\STitleMarkboth}[2]{\markboth{#1}{#2}}

%    \end{macrocode}
% \end{macro}
%
% \subsubsection{Miscellaneous Macros}
% This section contains a few miscellaneous macros used by the
% main macros that then follow.
%
%    \begin{macrocode}
%%=======================================================%
%%       M I S C E L L A N E O U S   M A C R O S         %
%%=======================================================%

%    \end{macrocode}
%
% \begin{macro}{\CpyRt}
%   The |\CpyRt|\parm{1}\parm{2}\parm{3} copyright info. macro definition.
%   \begin{ParameterList}
%     \item[\meta{1}] Centre this line Y/N? (optional)
%     \item[\meta{2}] Copyright information.
%     \item[\meta{3}] Copyright licensing information.
%   \end{ParameterList}
%
% This command is not usually explicitly used in a songbook.  It is
% called by the |song| environment and will normally only be used
% there.
%
% The first parameter to this macro is optional and is used to surpress
% the centering of the Scripture reference (i.e., if the parameter is
% specified, and that value is \emph{not} `\texttt{Y}' then the center
% environment will not be created around the reference.
%
%    \begin{macrocode}
\newcommand{\CpyRt}[3][Y]{%
  \if#1Y\begin{center}\fi
    \if\blank{#2}%
      \if\blank{#3}%
        {\CpyRtFont\copyright \SBUnknownTag{} \CpyRtInfoFont}%
      \else
        {\CpyRtFont\copyright \SBUnknownTag{} \CpyRtInfoFont #3}%
      \fi%
    \else%
      \ifthenelse{\equal{#2}{\SBPubDom}}
      {%then
        {\CpyRtFont #2 \CpyRtInfoFont #3}%
      }{%else
        {\CpyRtFont\copyright #2 \CpyRtInfoFont #3}%
      }%fi
    \fi%
  \if#1Y\end{center}\fi
}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ScriptRef}
%   The |\ScriptRef|\parm{1}\parm{2} macro indicates a scripture reference.
%   \begin{ParameterList}
%     \item[\meta{1}] Centre this line Y/N? (optional)
%     \item[\meta{2}] Address of scripture reference for the song.
%   \end{ParameterList}
%
% Used to indicate a scripture reference for the song.  May either be
% the scripture being quoted in the song, or a scripture which
% supports the theology presented in the song.
%
% The first parameter to this macro is optional and is used to surpress
% the centering of the Scripture reference (i.e., if the parameter is
% specified, and that value is \emph{not} `\texttt{Y}' then the center
% environment will not be created around the reference.
%
%    \begin{macrocode}
\newcommand{\ScriptRef}[2][Y]{%
  \if#1Y\begin{center}\fi
    {\ScriptRefFont #2}%
  \if#1Y\end{center}\fi
}

%    \end{macrocode}
% \end{macro}

%
% \begin{macro}{\WAndM}
%   The |\WAndM|\parm{1}\parm{2} macro indicates Words and Music authorship.
%   \begin{ParameterList}
%     \item[\meta{1}] Centre this line Y/N? (optional)
%     \item[\meta{2}] Name(s) of the composer and lyricist.
%   \end{ParameterList}
%
% This command is not usually explicitly used in a songbook.  It is
% called by the song environment and will normally only be used
% there.
%
% The first parameter to this macro is optional and is used to surpress
% the centering of the composer \& lyricist (i.e., if the parameter is
% specified, and that value is \emph{not}~`\texttt{Y}' then the center environment will
% not be created around the composer \& lyricist.
%
%    \begin{macrocode}
\newcommand{\WAndM}[2][Y]{%
  \if#1Y\begin{center}\fi
    \if\blank{#2}%
      {\WandMFont\SBWAndMTag ~\SBUnknownTag}%
    \else
      {\WandMFont\SBWAndMTag ~#2}%
    \fi
  \if#1Y\end{center}\fi
}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\sbSetsbBaselineSkipAmt}
%   |\sbSetsbBaselineSkipAmt| sets the |\sbBaselineSkipAmt| length.
%   \begin{ParameterList}
%     \item None.
%   \end{ParameterList}
%
% This command is only used internally within the songbook style.  It 
% is invoked just prior to any use of the sbBaselineSkipAmt length and
% it calculated the proper value based upon all the fonts chosen at that
% particular moment in time.  It does this by creating an |\hbox{}| that
% contains one letter with a chord overtop of it; the height and depth 
% of that |\hbox{}| added together then become the baseline skip.
%
%    \begin{macrocode}
\newcommand{\sbSetsbBaselineSkipAmt}{
  \ifChordBk%
    \setbox0=\hbox{\strut\raise\SBChordRaise\hbox{\ChFont\sbChord{}A\relax\strut}A}%
    \setlength{\sbBaselineSkipAmt}{\ht0 + \dp0}%
  \else%
    \setlength{\sbBaselineSkipAmt}{\baselineskip}%
  \fi%
}

%    \end{macrocode}
% \end{macro}
%
% \subsubsection{Primary Songbook Macros}
% The macros in this section comprise those most often used by
% \Songbook{} users.
%
%    \begin{macrocode}
%%=======================================================%
%%    P R I M A R Y   S O N G B O O K   M A C R O S      %
%%=======================================================%

%    \end{macrocode}
%
% \begin{macro}{\STitle}
%   |\STitle|\parm{1}\parm{2}\parm{3} is the song title macro.
%   \begin{ParameterList}
%     \item[\meta{1}] Centre this line Y/N? (optional)
%     \item[\meta{2}] Song's title.
%     \item[\meta{3}] Song's Key.
%   \end{ParameterList}
%
%   Before printing the title we reset the |\SBVerseCnt| and |\SBSectionCnt|
%   counters back to zero.  This is for songs which are printed in more
%   than one key, because the verse count always begins at~``\texttt{1.}''
%   for each key.
%
%   The first parameter to this macro is optional and is used to surpress
%   the centering of the title (i.e., if the parameter is specified, and 
%   that value is \emph{not}~`\texttt{Y}' then the center environment will not be created
%   around the title.
%
%   This macro also makes an entry in the key index file; except in the case
%   where a song is not being included, in which case no entry is made.
%
%   \changes{v4.1}{2003/08/31}{Added code to not write entries for excluded songs.}
%%%
%    \begin{macrocode}
\newcommand{\STitle}[3][Y]{%
  \setcounter{SBVerseCnt}{0}%
  \setcounter{SBSectionCnt}{0}%
  \ifExcludeSong\relax%
    \else\keyIndex{{\protect\sbChord#3\protect\relax} -- #2}{\theSBSongCnt}\fi%
  \vspace{\SpaceAboveSTitle}%
  \if#1Y\begin{center}\fi
    {\STitleNumberFont\theSBSongCnt}{\STitleFont\ --- #2}%
    \ifWordsOnly\relax\else{\STitleKeyFont\ [{\sbChord#3\relax}]}\fi%
  \if#1Y\end{center}\fi
  \STitleMarkboth{#2}{\relax}%
  }

%    \end{macrocode}
% \end{macro}
%
% \changes{v4.1}{2003/08/31}{Added $[$\meta{Include?}$]$ option code.}
% \begin{macro}{song}
%   |song|\parm{1}\ldots\parm{7} is the environment within which a song
%   is entered.
%   \begin{ParameterList}
%     \item[\meta{1}] Include song in book? (optional)
%     \item[\meta{2}] Title of song.
%     \item[\meta{3}] Key song is written in.
%     \item[\meta{4}] Copyright information.
%     \item[\meta{5}] Name(s) of composer and lyricist.
%     \item[\meta{6}] Scripture reference for the song.
%     \item[\meta{7}] Copyright licensing information.
%   \end{ParameterList}
%
%   The song environment encapsulates a song, including multiple
%   appearances for multiple keys and translations.  We increment
%   the song counter and then cause the title and other parameter
%   information to be displayed.
%
%   \paragraph{Include Song In Book? (optional)}
%   The first parameter is optional and its default value is
%   ``\texttt{Y}''.  For simplicity this description refers to the field
%   as \meta{Include?}.  When the value of \meta{Include?} is ``\texttt{Y}'' then all
%   processing is done normally.  If the value of \meta{Include?} is (not ``\texttt{Y}'')
%   then:
%   \begin{itemize}
%     \item the songcounter is incremented;
%     \item a TOC index entry is written
%      to a skipped-entry files, with each entry bracketted by some extra
%      code (compared to the non-skipped-entry files);
%     \item consider making \meta{Include?} look for several values to allow
%      exclusions/inclusions to only happen for certain types of
%      songbooks.
%   \end{itemize}
%   
%   The skipped-entry TOC file is named \texttt{*.tocS}.  The purpose of creating
%   a separate file is twofold: (1)~to allow normal songbook
%   processing to simply omit these not-included files; (2)~to allow the
%   skipped entries to be easily added back into the TOC processing
%   process through simple appending of the files to the standard TOC
%   file.
%
%    \begin{macrocode}
\newenvironment{song}[7][Y]{                    % Comment markers to negate
  \if#1Y\ExcludeSongfalse\else\ExcludeSongtrue\fi% the newline.
  \ifPrintAllSongs\ExcludeSongfalse\fi          %
  \SongMarkboth{\relax}{\relax}                 % 
  \SBinSongEnvtrue                              %
  \renewcommand{\SBinSongEnv}{\True}            %
  \ifWordsOnly                                  %
    \setlength{\parindent}{0pt}                 %
  \fi                                           %
%    \end{macrocode}
%
%   Store each of the parameters in a macro to make them easily accessible
%   later.  This isn't as useful as it should be due to my inability to 
%   properly detect in the title block macros whether or not the parameter
%   is nil or blank when one of these |\the| macros is passed instead of
%   the native parameter itself.
%
%   We \emph{clear} the translation macros now, since the |xlatn| environment
%   is only valid inside a |song| environment, and we are now declaring a new
%   |song|.
%
%    \begin{macrocode}
  \renewcommand{\theSongComposer}{#5}           %
  \if\blank{#5}                                 %
    \renewcommand{\theSongComposerU}{\SBUnknownTag}%
  \else                                         %
    \renewcommand{\theSongComposerU}{#5}        %
  \fi                                           %
  \renewcommand{\theSongCopyRt}{#4}             %
  \renewcommand{\theSongKey}{#3}                %
  \renewcommand{\theSongLicense}{#7}            %
  \renewcommand{\theSongScriptRef}{#6}          %
  \renewcommand{\theSongTitle}{#2}              %
  \renewcommand{\theXlatnBy}{}                  %
  \renewcommand{\theXlatnPerm}{}                %
  \renewcommand{\theXlatnTitle}{}               %
  %
  \addtocounter{SBSongCnt}{1}                   %
  %
%    \end{macrocode}
%
%   \changes{v4.1}{2003/08/31}{Changes index invocation to match
%                       \meta{Include?} directive.}
%   \changes{v4.2}{2006/10/13}{Added invocation for artist index.}
%
%   Write table of contents and index entries in reponse to the user's
%   \meta{Include?} directive.
%
%    \begin{macrocode}
  \ifExcludeSong                                %
    \titleContentsSkip{\theSongTitle}{\theSongKey}%
  \else                                         %
    \titleIndex{\theSongTitle}{\theSBSongCnt}   %
    \titleContents{\theSongTitle}{\theSongKey}  %
    \artistIndex{\theSongComposerU+\theSongTitle}{\theSBSongCnt}%
  \fi                                           %
%    \end{macrocode}
%
%   \changes{v4.1}{2003/08/31}{Implemented \meta{Include?} parameter through use
%                       of \TeX's |box2|.}
%
%   Now we deal with the user's \meta{Include?} directive.  If \meta{Include?} is
%   ``\texttt{Y}'' then we will cause normal songbook processing to occur;
%   otherwise we'll simply insert a |\relax| macro.  I have implemented this
%   feature using a memory hungry method: when excluding a song, put the
%   lyrics into |box2| and then discard it without using it.  Although Mark
%   Wooding suggested using this method, he also provided a pointer to 
%   a more robust method: using the |sverb| package that is part of 'mdwtools'
%   collection (specifically, the |\ignoreenv{}| command).
%
%    \begin{macrocode}
  \ifExcludeSong\setbox2=\vbox\bgroup\fi%
%    \end{macrocode}
%
%   Try to keep the song title and all its contents on the same page;
%   if that is what is desired.
%
%    \begin{macrocode}
  \ifSamepageMode%
    \begin{samepage}%
  \fi%
%    \end{macrocode}
%
%   Whereever you see a parameter used directly, and not the parameter macro
%   just set, above, it is because I haven't figured out how the receiving
%   macro can deal with accepting its input via a macro (and not via the
%   native parameter).  In general this is because the receiving macro is
%   attempting to detect and empty or blank parameter.
%
%   The second parameter is used directly here when |\STitle| is invoked
%   (instead of |\theSongKey|), because I can't figure out how to cause the
%   sharp and flat substitution to occur within the context of the
%   |\renewcommand| statement, above.
%
%    \begin{macrocode}
  \begin{center}
    \STitle[N]{\theSongTitle}{#3}\\
    \vspace{-.5ex}
    \CpyRt[N]{#4}{#7}\\
    \vspace{-.5ex}
    \WAndM[N]{#5}\\
    \if\given{#6}%
      \vspace{-.75ex}
      \ScriptRef[N]{\theSongScriptRef}\\
    \fi%
  \end{center}%
  \vspace{\SpaceAfterTitleBlk}
%    \end{macrocode}
%
%   If we're in |compactsong| mode then put us into |multicols{2}| mode.
%
%    \begin{macrocode}
  \ifCompactSongMode
    \begin{multicols*}{2}
      \raggedcolumns
  \fi
  \SBDefaultFont%
  }%
%    \end{macrocode}
%
%   This brings the |song| environment's open clause to a close.
%
%   The close clause now starts.  We begin by closing out the |SamepageMode|
%   and |CompactSongMode| environments, as applicable.
%
%    \begin{macrocode}
{\ifSamepageMode%
    \end{samepage}%
  \fi%
  \ifCompactSongMode
    \end{multicols*}
  \fi
  \ifSongEject%
    \vfill\pagebreak%
  \else%
    \SpaceAfterSong\pagebreak[1]%
  \fi%
%    \end{macrocode}
%
%   Here's where we close out the \meta{Include?} if-then-else.  Note that we
%   immediately clear |box2| before proceding (an attempt to free up the
%   memory we've just consumed).
%
%    \begin{macrocode}
  \ifExcludeSong\egroup\setbox2=\hbox{}\fi%
  \renewcommand{\SBinSongEnv}{\False}%
  \SBinSongEnvfalse%
  }

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\CBExcl}
% \begin{macro}{\OHExcl}
% \begin{macro}{\WBExcl}
% \begin{macro}{\WOExcl}
%   The |\CBExcl|, |\OHExcl|, |\WBExcl|, and |\WOExcl| macros exist to be
%   passed as parameters to the |song| environment's \meta{Include?} 
%   parameter.  The parameters cause the song to be excluded when processing the
%   particular \Songbook{} type:
%   \begin{description}
%      \item[|CBExcl|\ ] Exclude the song when in |chordk| mode
%      \item[|OHExcl|\ ] Exclude the song when in |overhead| mode
%      \item[|WBExcl|\ ] Exclude the song when in |wordbk| mode
%      \item[|WOExcl|\ ] Exclude the song when in either |wordbk| or
%        |overhead| mode
%   \end{description}
%
%   Here's an example usage which shows a song to be excluded when in
%   |chordbk| mode:
%   \begin{verbatim}
%     \documentclass{book}
%     \usepackage[chordbk]{songbook}
% 
%     \begin{document}
%       \begin{song}[\CBExcl]{title}{}{}{}{}{}
%         some lyrics
%       \end{song}
%     \end{document}
%   \end{verbatim}
%
%    \begin{macrocode}
\newcommand{\CBExcl}{\ifChordBk N\else Y\fi}
\newcommand{\OHExcl}{\ifOverhead N\else Y\fi}
\newcommand{\WBExcl}{\ifWordBk N\else Y\fi}
\newcommand{\WOExcl}{\ifWordsOnly N\else Y\fi}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{xlatn}
%   |xlatn|\parm{1}\parm{2}\parm{3} is the song-translation environment.
%   \begin{ParameterList}
%     \item[\meta{1}] Title of the translated song.
%     \item[\meta{2}] Translation permission.
%     \item[\meta{3}] Who performed the translation.
%   \end{ParameterList}
%
%   The xlatn environment always occurs within a song environment.
%   We reset the verse counter then cause the title and other
%   parameter information to be displayed.
%
%    \begin{macrocode}
\newenvironment{xlatn}[3]{% Comment marker negates the newline.
        \renewcommand{\theXlatnBy}{#3}%
        \renewcommand{\theXlatnPerm}{#2}%
        \renewcommand{\theXlatnTitle}{#1}%
        %
        \titleIndex{\theXlatnTitle}{\theSBSongCnt}%
        \titleContents{\theXlatnTitle}{\theSongKey}%
        %
        \begin{center}
          \STitle[N]{\theXlatnTitle}{\theSongKey}\\
          \CpyRt[N]{\theSongCopyRt}{\theSongLicense}\\
          \if\nil{#2}%
            \relax%
          \else%
            \vspace{-.5ex}
            {\CpyRtFont\theXlatnPerm}\\
          \fi
          \if\nil{#3}%
            \relax%
          \else%
            \vspace{-.5ex}
            {\CpyRtFont\theXlatnBy}\\
          \fi
        \end{center}%
        %
        \setcounter{SBVerseCnt}{0}%
        \setcounter{SBSectionCnt}{0}%
}{\relax}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\sbChord}
%   |\sbChord| changes a sequence of characters into a chord.
%   \begin{ParameterList}
%     \item[\meta{1}] Chord.
%   \end{ParameterList}
%
%   The original version of this function was written by Philip
%   Hirschhorn $<$\texttt{psh@math.mit.edu}$>$ or 
%   $<$\texttt{phirschhorn@lucy.wellesley.edu}$>$.
%
%   Scan the sequence of characters in Chord.  Replace `\texttt{\#}' characters
%   with $\sharp$'s and `\texttt{b}' characters with $\flat$.  This produces more
%   realistic looking chord symbols (which also take up less space than
%   their phoney counterparts).  We also look for `\texttt{/}' characters, and
%   insert a |\ChBassFont| command into the stream when a `\texttt{/}' is found.
%   This makes the bass note of the chord to appear in a smaller font.
%
%    \begin{macrocode}
\def\sbChord#1{%
  \ifx#1\relax%
    \let\next=\relax%
  \else%
    \ifx#1##% double sharp because we're inside a \def
      $\sharp$%
    \else%
      \ifx#1b%
        $\flat$%
      \else%
        \ifx#1/%
          \ChBassFont /%
        \else%
          \ifx#1[%
            \bgroup\ChBkFont [\egroup%
          \else%
            \ifx#1]%
              \bgroup\ChBkFont ]\egroup%
            \else%
              #1%
            \fi%
          \fi%
        \fi%
      \fi%
    \fi%
    \let\next=\sbChord%
  \fi%
  \next%
}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\Ch}
% \begin{macro}{\ChX}
% \begin{macro}{\Chr}
%   |\Ch|\parm{1}\parm{2} is the chord over lyrics macro.\\
%   |\ChX| is the Chord over lyrics macro, but deleting trailing spaces.\\
%   |\Chr| is the Chord over lyrics macro, but inserting a rule, when necessary.
%   \begin{ParameterList}
%     \item[\meta{1}] Chord.
%     \item[\meta{2}] Syllable that chord is to be left justified over.
%   \end{ParameterList}
%
%   The words-only style file turns off the chord generation and just
%   prints the second parameter.
%
%   The |\ChX| version of this macro is used for the benefit of the words-only
%   style to ensure that spaces following the macro are removed.  For
%   example, an interword space containing a couple of extra chords would
%   be written as (this is not usually necessary, but sometimes there is no
%   other way to elliminate spurious white space from a words-only songbook):
%   \begin{verbatim}
%               \ChX{D7}{ing} \ChX{E}{} \ChX{D}{} \Ch{A}{You}
%   \end{verbatim}
%
%   The |\Chr| version of this macro inserts a rule, at the height specified
%   by the |\SBRuleRaiseAmount| 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.  More details about the
%   |\Chr| command follow below, just preceeding its definition.
%
%   This code is based on macros from Olivier Biot's
%   (\texttt{http://www.biot.yucom.be/}) \texttt{chord.sty} file.  Changes made by me:
%   \begin{itemize}
%     \item removed annoying space between |\SBIntersyllableRules| when they butt
%      up against one another
%     \item changed the default |\ChordRaise| value to something closer to what my
%      previous version of the |\Ch| command used to set
%     \item renamed the commands: |\@| to |\Ch|, and |\@@| to |\Chr|
%     \item renamed the variables used to adjust |\Ch|'s behaviour, to ensure no
%      conflict exists with Olivier's macro.
%   \end{itemize}
%%%
%    \begin{macrocode}
\newcommand{\Ch}[2]{{%
  \ifChordBk%
    \setbox1=\hbox{\ChFont\sbChord#1\relax\strut}%
    \setbox0=\hbox{#2}%
    \ifdim\wd1<\wd0%
      \strut\raise\SBChordRaise\copy1\kern-\wd1\copy0%
    \else%
      \strut\copy0\kern-\wd0\strut\raise\SBChordRaise\copy1%
    \fi%
  \else%
    #2%
  \fi}}

%    \end{macrocode}
% \end{macro}
%
% The |\ChX| code.
%
%    \begin{macrocode}
\newcommand{\ChX}[2]{%
  \ifWordsOnly%
    \if\nil{#2}%
      \ignorespaces%
    \else%
      #2%
    \fi%
  \else%
    \Ch{#1}{#2}%
  \fi}

%    \end{macrocode}
% \end{macro}
%
%   The |\Chr| code and a detailed macro description \& definition.
%
%   We start with some internal scratch variables.  Any value they
%   have prior to |\Chr|'s execution will be discarded each time.
%
%    \begin{macrocode}
\newlength{\chCriticDim}
\newlength{\chSpaceDim}
%    \end{macrocode}
%
%   \begin{verbatim}
%    DEF\Chr#1#2
%    BEGIN
%      \box1 == \hbox{... #1 --> Chord ...}
%      \box0 == \hbox{... #2 --> Syllable ...}
%      \chCriticDim == \wd0 - \chSpaceTolerance - 2 \chMiniSpace
%      IFF \wd1 > \chCriticDim
%        \chCriticDim == \wd1 - \wd0 - \chSpaceTolerance - 2 \chMiniSpace
%        IFF \chCriticDim > 0mm
%          \chSpaceDim == \wd1 - \wd0 + \chSpaceTolerance
%        ELSE
%          \chSpaceDim == \chSpaceTolerance
%        FFI
%        \chCriticDim == \chSpaceDim - 2 \chSpaceTolerance
%        \raise \SBChordRaise \copy1 \kern - \wd1
%        IFF \wd0 == 0mm
%          \kern - 2 \chMiniSpace
%        FFI
%        \copy0
%        \hbox to \chCriticDim{\hss\raise\SBRuleRaiseAmount
%                            \hbox to \chSpaceDim{\SBIntersyllableRule}\hss}
%      ELSE
%        \raise \SBChordRaise \copy1 \kern - \wd1 \copy0
%      FFI
%    END
%   \end{verbatim}
%
%    \begin{macrocode}
\newcommand{\Chr}[2]{{%
  \ifChordBk
    \setbox1=\hbox{\ChFont\sbChord#1\relax\strut}%
    \setbox0=\hbox{#2}%
    \setlength{\chCriticDim}{\wd0 - \chSpaceTolerance}%
    \advance\chCriticDim by 2\chMiniSpace%
    \ifdim\wd1>\chCriticDim%
      \chCriticDim \wd1%
      \advance\chCriticDim by -\wd0%
      \advance\chCriticDim by -\chSpaceTolerance%
      \advance\chCriticDim by -2\chMiniSpace%
      \ifdim\chCriticDim>0mm%
        \chSpaceDim \wd1%
        \advance\chSpaceDim by -\wd0%
        \advance\chSpaceDim by \chSpaceTolerance%
      \else%
        \chSpaceDim\chSpaceTolerance%
      \fi%
      \chCriticDim \chSpaceDim%
      \advance\chCriticDim by 2\chMiniSpace%
      \strut\raise\SBChordRaise\copy1\kern-\wd1\ifdim\wd0=0mm\kern-2\chMiniSpace\fi%
      \copy0\hbox to\chCriticDim{\hss%
        \raise\SBRuleRaiseAmount\hbox to\chSpaceDim{\SBIntersyllableRule}\hss}%
    \else%
      \strut\raise\SBChordRaise\copy1\kern-\wd1%
      \copy0%
    \fi%
  \else%
    #2%
  \fi}%
}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SBMargNote}
%   |\SBMargNote|\parm{1} creates a \Songbook{} marginal note.
%   \begin{ParameterList}
%     \item[\meta{1}] Text of note to place in margin.
%   \end{ParameterList}
%
% Used to place a note of some kind in the margin of a songbook, or within
% a footnote when in |CompactSong| mode.  In words-only mode this macro is a 
% no-op.
%
%   If we are excluding a song then we have |\SBMargNote| take no action.  
%   We do this to be sure that no footnotes are generated, and to prevent 
%   the error that will occur from attempting to use the |\marginpar| command
%   within a |\vbox{}|.
%   \changes{v4.1a}{2003/09/22}{Added an \textsf{ifExcludeSong} clause to avoid the 
%                       conflict with \textsf{marginpar}}
%
%    \begin{macrocode}
\newcommand{\SBMargNote}[1]{%
  \ifExcludeSong%
    \relax%
  \else\ifWordsOnly%
    \relax%
  \else\ifCompactSongMode%
    \footnote{{\SBMargNoteFont{#1}}}%
  \else%
    \marginpar{{\begin{flushleft}\SBRefFont{#1}\end{flushleft}}}%
  \fi\fi\fi}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SBRef}
%   |\SBRef| creates a song reference in the margin.
%   \begin{ParameterList}
%     \item[\meta{1}] Songbook/CD/tape name.
%     \item[\meta{2}] Page/Song number within book referenced by \meta{1},
%                       or tape/CD publisher info.
%   \end{ParameterList}
%
%   Used to indicate a source for the full SATB music for this song, or 
%   what CD/cassette the song can be found on.  In words-only mode this 
%   macro is a no-op.  This normally appears in the margin of the songbook,
%   but in |CompactSong| mode the information appears in a footnote that is
%   always numbered `\texttt{0}' (even if there is more than one reference in a 
%   song.
%
%   If we are excluding a song then we have |\SBRef| take no action.  We do
%   this to be sure that no footnotes are generated, and to prevent the
%   error that will occur from attempting to use the |\marginpar| command
%   within a |\vbox{}|.
%   \changes{v4.1a}{2003/09/22}{Added an \textsf{ifExcludeSong} clause to avoid the 
%                       conflict with \textsf{marginpar}}
%
%    \begin{macrocode}
\newcommand{\SBRef}[2]{%
  \ifExcludeSong%
    \relax%
  \else\ifWordsOnly%
    \relax%
  \else\ifCompactSongMode%
    \footnotetext[0]{{\SBRefFont{\em #1}, {#2}.}}%
  \else%
    \marginpar{{\begin{flushleft}\SBRefFont{\em #1}, {#2}.\end{flushleft}}}%
  \fi\fi\fi}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{SBVerse}
% \begin{macro}{SBVerse*}
%   The |SBVerse| and |SBVerse*| environments encapsulate a verse.
%   \begin{ParameterList}
%     \item None.
%   \end{ParameterList}
%
%   Very much like \LaTeX{}'s verse environment, except that here the
%   verses are numbered.  The indent amount for lines that are too long
%   is set with the |\HangAmt| command (see the constant definitions at
%   the top of this document).
%
%   A version of this command which indents but down not place an
%   |\SBVerseCnt| before the chorus is available as |SBVerse*|.
%   Similar to \LaTeX{}'s |\section*| command, the verse counter is not
%   incremented either.
%
%    \begin{macrocode}
\newenvironment{SBVerse}{%
  \sbSetsbBaselineSkipAmt%
  \bgroup%
  \addtocounter{SBVerseCnt}{1}%
  \SBVerseMarkright{\theSBVerseCnt}%
  \begin{list}{{\SBVerseNumberFont\theSBVerseCnt .}}
    {\setlength {\leftmargin}   {\LeftMarginSBVerse + \HangAmt}
      \setlength{\itemindent}   {-\HangAmt}
      \setlength{\listparindent}{-\HangAmt}
      \setlength{\parsep}       {0pt}
      \setlength{\baselineskip} {\sbBaselineSkipAmt}
    }%
    \item}
{\end{list}%
 \egroup%
 \SpaceAfterVerse}

%    \end{macrocode}
% \end{macro}
%
%   The |SBVerse*| code.  Coding of this environment courtesy of Herbert
%   Martin Dietze $<$\texttt{herbert@fh-wedel.de}$>$.
%
%    \begin{macrocode}
\newenvironment{SBVerse*}{%
  \sbSetsbBaselineSkipAmt%
  \bgroup%
  \begin{list}{{\SBVerseNumberFont }}
    {\setlength {\leftmargin}   {\LeftMarginSBVerse + \HangAmt}
      \setlength{\itemindent}   {-\HangAmt}
      \setlength{\listparindent}{-\HangAmt}
      \setlength{\parsep}       {0pt}
      \setlength{\baselineskip} {\sbBaselineSkipAmt}
      }%
    \item}
{\end{list}%
 \egroup%
 \SpaceAfterVerse}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{SBSection}
% \begin{macro}{SBSection*}
%   The |SBSection| and |SBSection*| environments encapsulate a section.
%   \begin{ParameterList}
%     \item None.
%   \end{ParameterList}
%
%   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 (see the constant definitions at
%   the top of this file).
%
%   A version of this command which indents but doesn't place an
%   |\SBSectionCnt| before the chorus is available as |SBSection*|.
%   Similar to \LaTeX's |\section*| command, the section counter is not
%   incremented either.
%
%    \begin{macrocode}
\newenvironment{SBSection}{%
  \sbSetsbBaselineSkipAmt%
  \bgroup%
  \addtocounter{SBSectionCnt}{1}%
  \SBSectionMarkright{SBSectionCnt}
  \begin{list}{{\SBSectionNumberFont\alph{SBSectionCnt})}}
    {\setlength {\leftmargin}   {\LeftMarginSBSection + \HangAmt}
      \setlength{\itemindent}   {-\HangAmt}
      \setlength{\listparindent}{-\HangAmt}
      \setlength{\parsep}       {0pt}
      \setlength{\baselineskip} {\sbBaselineSkipAmt}
      }%
    \item}
{\end{list}%
 \egroup%
 \SpaceAfterSection}

%    \end{macrocode}
% \end{macro}
%
%   The |SBSection*| code.  Coding of this environment courtesy of Herbert
%   Martin Dietze $<$\texttt{herbert@fh-wedel.de}$>$.
%
%    \begin{macrocode}
\newenvironment{SBSection*}{%
  \sbSetsbBaselineSkipAmt%
  \bgroup%
  \begin{list}{{\SBSectionNumberFont }}
    {\setlength {\leftmargin}   {\LeftMarginSBSection + \HangAmt}
      \setlength{\itemindent}   {-\HangAmt}
      \setlength{\listparindent}{-\HangAmt}
      \setlength{\parsep}       {0pt}
      \setlength{\baselineskip} {\sbBaselineSkipAmt}
      }%
    \item}
{\end{list}%
 \egroup%
 \SpaceAfterSection}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SBChorus}
% \begin{macro}{\SBChorus*}
%   The |SBChorus| and |SBChorus*| environments encapsulate a chorus.
%   \begin{ParameterList}
%     \item None.
%   \end{ParameterList}
%
%   Very much like \LaTeX{}'s verse environment, except that here a
%   |\SBChorusTag| tag is inserted to demark the start of the chorus.
%   The indent amount for lines that are too long is set with the
%   |\HangAmt| command (see the constant definitions at the top of
%   this file).
%
%   A version of this command which indents but does not place a
%   |\SBChorusTag| before the chorus is available as |SBChorus*|.
%
%    \begin{macrocode}
\newenvironment{SBChorus}{%
  \sbSetsbBaselineSkipAmt%
  \bgroup%
  \SBChorusMarkright{\SBChorusTag}
  \begin{list}{{\SBChorusTagFont\SBChorusTag}}
    {\setlength {\leftmargin}   {\LeftMarginSBChorus + \HangAmt}
      \setlength{\itemindent}   {-\HangAmt}
      \setlength{\listparindent}{-\HangAmt}
      \setlength{\parsep}       {0pt}
      \setlength{\baselineskip} {\sbBaselineSkipAmt}
      }%
    \item}
{\end{list}%
 \egroup%
 \SpaceAfterChorus%
}

%    \end{macrocode}
% \end{macro}
%
%   The |SBChorus*| code.  Coding of this environment courtesy of Herbert
%   Martin Dietze $<$\texttt{herbert@fh-wedel.de}$>$.
%
%    \begin{macrocode}
\newenvironment{SBChorus*}{%
  \sbSetsbBaselineSkipAmt%
  \bgroup%
  \begin{list}{{\SBChorusTagFont }}
    {\setlength {\leftmargin}   {\LeftMarginSBChorus + \HangAmt}
      \setlength{\itemindent}   {-\HangAmt}
      \setlength{\listparindent}{-\HangAmt}
      \setlength{\parsep}       {0pt}
      \setlength{\baselineskip} {\sbBaselineSkipAmt}
      }%
    \item}
{\end{list}%
 \egroup%
 \SpaceAfterChorus}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SBOpGroup}
%   |\SBOpGroup| identifies an open chorus/verse.
%   \begin{ParameterList}
%     \item None.
%   \end{ParameterList}
%
%   This environment is akin to SBChorus, except that no tag and no
%   indentation is performed.  This environment serves two purposes:
%   \begin{enumerate}
%     \item Identify a verse or chorus that is unmarked (by way of a tag)
%      and the left margin of the block is not indented.
%     \item Puts the verse or chorus in a list environment so that wrapping
%      lines are properly indented.
%   \end{enumerate}
%%%
%    \begin{macrocode}
\newenvironment{SBOpGroup}{%
  \sbSetsbBaselineSkipAmt%
  \bgroup%
  \begin{list}{\hbox{}}
    {\setlength {\leftmargin}   {\HangAmt}
      \setlength{\itemindent}   {-\HangAmt}
      \setlength{\listparindent}{-\HangAmt}
      \setlength{\topsep}       {0pt}
      \setlength{\parsep}       {0pt}
      \setlength{\labelwidth}   {0pt}
      \setlength{\labelsep}     {0pt}
      \setlength{\baselineskip} {\sbBaselineSkipAmt}
      }%
    \item}
{\end{list}%
 \egroup%
 \SpaceAfterOpGroup}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SBBridge}
%   |\SBBridge|\parm{1} identifies a bridge.
%   \begin{ParameterList}
%     \item[\meta{1}] The Bridge.
%   \end{ParameterList}
%
%   This command is used to encapsulate a bridge that occurs in a song.  In
%   words-only mode this command is a no-op.
%
%    \begin{macrocode}
\newcommand{\SBBridge}[1]{%
  \ifWordsOnly%
    \relax%
  \else%
    \sbSetsbBaselineSkipAmt%
    \bgroup%
    \begin{list}{{\SBBridgeTagFont\SBBridgeTag}}
      {\setlength {\leftmargin}  {\LeftMarginSBChorus}%
        \setlength{\parsep}      {0pt}
        \setlength{\baselineskip}{\sbBaselineSkipAmt}
        }%
      \item #1
    \end{list}%
    \egroup\par
  \fi}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SBEnd}
%   |\SBEnd|\parm{1}\parm{2} identifies a song ending.
%   \begin{ParameterList}
%     \item[\meta{1}] Display in words-only? (optional)
%     \item[\meta{2}] The Ending.
%   \end{ParameterList}
%
%   This command is used to encapsulate the ending of a song.  If
%   the first parameter is not specified, or if it is~`\texttt{N}',
%   then in words-only mode this command is a no-op.
%
%    \begin{macrocode}
\newcommand{\SBEnd}[2][N]{%
  \ifthenelse{\equal{\ifWordsOnly Y\fi}{Y}
    \and \equal{N}{#1}}%
  {\relax}%
  {\sbSetsbBaselineSkipAmt%
   \bgroup%
    \begin{list}{{\SBEndTagFont\SBEndTag}}
      {\setlength {\leftmargin}  {\LeftMarginSBChorus}
        \setlength{\parsep}      {0pt}
        \setlength{\baselineskip}{\sbBaselineSkipAmt}
        }%
    \item #2
    \end{list}%
    \egroup\par}
  }

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SBIntro}
%   |\SBIntro|\parm{1}\parm{2} identifiesd an introduction.
%   \begin{ParameterList}
%     \item[\meta{1}] Display in words-only? (optional)
%     \item[\meta{2}] The Introduction.
%   \end{ParameterList}
%
%   This command is used to encapsulate an introduction to a song.  If
%   the first parameter is not specified, or if it is~`\texttt{N}', then in 
%   words-only mode this command is a no-op.
%
%    \begin{macrocode}
\newcommand{\SBIntro}[2][N]{%
  \ifthenelse{\equal{\ifWordsOnly Y\fi}{Y}
    \and \equal{N}{#1}}%
  {\relax}%
  {\sbSetsbBaselineSkipAmt%
   \bgroup%
    \begin{list}{{\SBIntroTagFont\SBIntroTag}}%
      {\setlength {\leftmargin}  {\LeftMarginSBChorus}%
        \setlength{\parsep}      {0pt}
        \setlength{\baselineskip}{\sbBaselineSkipAmt}
        }%
      \item #2
      \vspace{-\topsep}%\vspace{-\partopsep}%
    \end{list}%
    \egroup\par}%
  }

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{SBBracket}
% \begin{macro}{SBBracket*}
%   The |SBBracket|\parm{1} and |SBBracket|\parm{1} environments encapsulates
%   a bracketed versicle.
%   \begin{ParameterList}
%     \item[\meta{1}] Some tag is inserted before the bracket to indicate
%                   the significance of the bracketed area.  
%   \end{ParameterList}
%
%    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.
%
%    This is a more versatile, and better formatted version of |SBBridge|, 
%    |SBOccurs|, etc.; and it is recommended that this be used in the others 
%    place.
%
%    Starting in version~4.0 of the style, the left-hand indentation of
%    this environment has been chosen such that the |SBVerse|, |SBChorus|, and
%    |SBBracket| song-words all align against the same left margin when printing
%    standard words \&~chords songbooks.
%
%    \begin{macrocode}
\newenvironment{SBBracket}[1]{%
  \SpaceBeforeSBBracket
  \sbSetsbBaselineSkipAmt%
  \setbox0=\hbox to \LeftMarginSBBracket{\parbox{\LeftMarginSBBracket}%
    {\flushright{\hspace{0pt}\SBBracketTagFont #1}}}%
  \hbox\bgroup%
    \rightskip=\LeftMarginSBBracket%
    $\raisebox{1.25ex}{\copy0}%
    \left\lbrack%
      \vcenter\bgroup%
        \begin{list}{\hbox{}}%                          %
          {\setlength {\leftmargin}   {\HangAmt + 0.5em}% This list
            \setlength{\rightmargin}  {\LeftMarginSBBracket}%
            \setlength{\itemindent}   {-\HangAmt}%      % been copied
            \setlength{\listparindent}{-\HangAmt}%      % verbatim from
            \setlength{\topsep}       {0pt}%            % the SBOpGroup
            \setlength{\parsep}       {0pt}%            % environment,
            \setlength{\labelwidth}   {0pt}%            % above and then
            \setlength{\labelsep}     {0pt}%            % modified slightly.
            \setlength{\baselineskip} {\sbBaselineSkipAmt}%
            }%                                          %
          \item%
}{%
        \end{list}%
      \egroup%
    \right.$%
    \rightskip=0pt
  \egroup
  \SpaceAfterSBBracket
}

%    \end{macrocode}
% \end{macro}
%
%   The |SBBracket*| code.
%
%    \begin{macrocode}
\newenvironment{SBBracket*}[1]{%
  \SpaceBeforeSBBracket
  \sbSetsbBaselineSkipAmt%
  \ifNotWordsOnly
    \setbox0=\hbox to \LeftMarginSBBracket{\parbox{\LeftMarginSBBracket}%
      {\flushright{\hspace{0pt}\SBBracketTagFont #1}}}%
    \hbox\bgroup%
      \rightskip=\LeftMarginSBBracket%
      $\raisebox{1.25ex}{\copy0}%
      \left\lbrack%
        \vcenter\bgroup%
  \fi
        \begin{list}{\hbox{}}%                          %
          {\setlength {\leftmargin}   {\HangAmt + 0.5em}% This list
            \setlength{\rightmargin}  {\LeftMarginSBBracket}%
            \setlength{\itemindent}   {-\HangAmt}%      % been copied
            \setlength{\listparindent}{-\HangAmt}%      % verbatim from
            \setlength{\topsep}       {0pt}%            % the SBOpGroup
            \setlength{\parsep}       {0pt}%            % environment,
            \setlength{\labelwidth}   {0pt}%            % above and then
            \setlength{\labelsep}     {0pt}%            % modified slightly.
            \setlength{\baselineskip} {\sbBaselineSkipAmt}%
            }%                                          %
          \item%
}{%
        \end{list}%
  \ifNotWordsOnly
        \egroup%
      \right.$%
      \rightskip=0pt
    \egroup
  \fi
  \SpaceAfterSBBracket
}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{SBOccurs}
%   The |SBOccurs|\parm{1} environment encapsulates an occurance.
%   \begin{ParameterList}
%     \item[\meta{1}] Occurance number(s).  For example ``\texttt{1,3}'' would
%                   designate that this passage applies to the 1$^{st}$ and
%                   3$^{rd}$ occurances.
%   \end{ParameterList}
%
%    \begin{macrocode}
\newenvironment{SBOccurs}[1]{%
  {\SBOccursTagFont #1\SBOccursBrktFont [}
  }
{{\SBOccursBrktFont ]}}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{SBExtraKeys}
%   The |SBExtraKeys|\parm{1} environment encapsulates extra song keys.
%   \begin{ParameterList}
%     \item[\meta{1}] This parameter actually is used to either pass or
%       not pass all the content of the environment on to
%       the \LaTeX processor.
%   \end{ParameterList}
%
%   Songs are frequently listed in more than one key.  This is ok for
%   books with chords, however the words-only edition should only print
%   one occurance of a song.  So, any extra keys are placed in a
%   |SBExtraKey| environment.  This allows them to be \emph{shut off} when
%   they're not needed.
%
%   This was coded some years ago and I probably wouldn't do it this way
%   again; however, it works so I'm not inclined to \emph{better} it.
%
%    \begin{macrocode}
\newenvironment{SBExtraKeys}[1]{%
  \ifWordsOnly%
    \relax%
  \else%
    #1
  \fi}
{}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\CBPageBrk}
%   |\CBPageBrk|\parm{1} generates a page break here if we're in Chordbk mode.
%   \begin{ParameterList}
%     \item[\meta{1}] Take effect in CompactSong mode too? (optional)
%   \end{ParameterList}
%
%   When we're also in CompactSong mode we will only execute the page
%   break if a parameter other than~`\texttt{N}' has been passed.
%
%    \begin{macrocode}
\newcommand{\CBPageBrk}[1][N]{%
  \ifChordBk%
    \ifCompactSongMode
      \ifthenelse{\equal{#1}{N}}
      {\relax}
      {\vfill\pagebreak}
    \else
      \vfill\pagebreak
    \fi
  \fi}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\CSColBrk}
%   |\CSColBrk| generates a column break here if we're in |compactsong|  mode.
%   \begin{ParameterList}
%     \item None.
%   \end{ParameterList}
%
%    \begin{macrocode}
\newcommand{\CSColBrk}{%
  \ifCompactSongMode%
    \columnbreak%
  \fi}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\NotWOPageBrk}
%   |\NotWOPageBrk| generates a page break here if we're \emph{not} in words-only mode.
%   \begin{ParameterList}
%     \item None.
%   \end{ParameterList}
%
%    \begin{macrocode}
\newcommand{\NotWOPageBrk}{%
  \ifWordsOnly%
    \relax%
  \else%
    \pagebreak
  \fi}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\OHPageBrk}
%   |\OHPageBrk| generates a page break here if we're in |overhead| mode.
%   \begin{ParameterList}
%     \item None.
%   \end{ParameterList}
%
%    \begin{macrocode}
\newcommand{\OHPageBrk}{%
  \ifOverhead%
    \pagebreak
  \fi}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\WBPageBrk}
%   |\WBPageBrk| generates a page break here if we're in |workbk| mode.
%   \begin{ParameterList}
%     \item None.
%   \end{ParameterList}
%
%    \begin{macrocode}
\newcommand{\WBPageBrk}{%
  \ifWordBk%
    \pagebreak
  \fi}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\WOPageBrk}
%   |\WOPageBrk| generates a page break here if we're in words-only mode.
%   \begin{ParameterList}
%     \item None.
%   \end{ParameterList}
%
%    \begin{macrocode}
\newcommand{\WOPageBrk}{%
  \ifWordsOnly%
    \pagebreak
  \fi}

%    \end{macrocode}
% \end{macro}
%
% \subsubsection{Obsolete Macros}
% The macros in this section are no longer recommended, but will
% continue to exist in the next version of the style.  Existing
% users of this style should upgrade their source files to make
% use of the new, replacement, mechanisms offered by the style.
%
%    \begin{macrocode}
%%=======================================================%
%%            O B S O L E T E   M A C R O S              %
%%=======================================================%

%    \end{macrocode}
%
% There are no obsolete macros in this release.
%
% \subsubsection{Deprecated Macros}
%
% The macros in this section will be deleted in the next version of
% the style.  Where these old macros conflict with new ones they have
% been renamed by placing a lowercase `o' at the start of each macro
% name; this makes them easily accessible yet out of the way.
%
%    \begin{macrocode}
%%=======================================================%
%%          D E P R E C A T E D   M A C R O S            %
%%=======================================================%

%    \end{macrocode}
%
% \paragraph{Boolean Contants} In the early releases, before I \emph{knew}
% about \LaTeX's |\newif| command I had coded |\if|s using these contants.
% These should have been removed some time ago, but I had neglected placing
% them into this \textit{Deprecated Macros} section and so hadn't given proper
% notice.  Consider this \textit{notice}.
% \begin{macro}{\False}
% \begin{macro}{\True}
% \begin{macro}{\ChordBk}
% \begin{macro}{\Overhead}
% \begin{macro}{\SongEject}
% \begin{macro}{\WordBk}
% \begin{macro}{\WordsOnly}
% \begin{macro}{\SBinSongEnv}
%   |\False| is defined for use in |\if| macro contructs and the other
%                constants in this style.\\
%   |\True| is defined for use in |\if| macro contructs and the other
%                constants in this style.\\
%   |\ChordBk| tells if we are processing a \texttt{chordbk.sty} document.\\
%   |\Overhead| tells if we are processing an \texttt{overhead.sty} document.\\
%   |\SongEject| specifies if we want to end the current page at the end of
%               every |song| environment.  A value of |\True| means
%               eject after every |song| environment.\\
%   |\WordBk| tells if we are processing a \texttt{wordbk.sty} document\\
%   |\WordsOnly| is equal to |\True| if we're in words-only mode.
%               The default value will be |\False|, as that is how all of
%               the commands in this file will act.\\
%   |\SBinSongEnv| tells if we are inside of a song environment.  This is
%               re-defined as we enter and exit the song environment.
%%%
%    \begin{macrocode}
\newcommand{\False}{0}
\newcommand{\True}{1}
\newcommand{\ChordBk}{\False}
\newcommand{\Overhead}{\False}
\newcommand{\SongEject}{\True}
\newcommand{\WordBk}{\False}
\newcommand{\WordsOnly}{\False}
\newcommand{\SBinSongEnv}{\False}

%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% End of songbook.sty file.
%
%    \begin{macrocode}
\endinput

%    \end{macrocode}
%
% \Finale
% \PrintIndex \PrintChanges
\endinput

TODO:

Make the index sorted in the order of the keys (i.e. Bb should come
before B).  I have some ideas about this one, but they involve rather
more work that I may have time for.

Chord macro that places [] around optional chords.

Allow chords to be centered over the sylables.  Re: request by "Tobias
Weidelt" <tobias@weidelt.de>.

% Local Variables:
%   LaTeX-item-indent:      -1
%   LaTeX-indent-level:     2
%   TeX-brace-indent-level: 2
%   TeX-auto-untabify:      nil 
%   TeX-style-local:        "../style/"
% End:
