% \iffalse meta-comment % -*- LaTeX -*-
% rcsid = @(#)$Id: songbook.dtx,v 1.16 2010-04-12 18:10:15 rathc Exp $
%
%
% songbook.sty - Generic SongBook style.
%
% Version 4.5, 30 April, 2010
%
% Copyright 1992--2010 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{2341}
%% \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.}
% \changes{v4.3}{2007/02/03}{Corrected problem with xlatn environment introduced in v4.2
% and added a new songTranslation environment.}
% \changes{v4.4}{2010/03/30}{At Donald Arseneau's request, added language to state that
% conditionals.sty is public domain.}
% \changes{v4.5}{2010/04/30}{Added a |compactsong| option to the |song| environment;
% which allows per-song use of |compactsong| formatting.}
%\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.5}}
% \author{Christopher Rath\\
% {\small$<$\texttt{Christopher@Rath.ca}$>$}}
% \date{2010/04/30}
% \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.5}
% What's new in version~4.5:
% \begin{itemize}
% \item Added a |compactsong| option to the |song| environment; which
% allows per-song use of |compactsong| formatting.
% \end{itemize}
%
% \section*{Preface to version 4.4}
% What's new in version~4.4:
% \begin{itemize}
% \item there are no functional changes
% \item at Donald Arseneau's request, added language to state that
% conditionals.sty is public domain
% \end{itemize}
%
% \section*{Preface to version 4.3}
% What's new in version~4.3:
% \begin{itemize}
% \item found a problem with the optional parameter to the xlatn environment
% added in Release 4.2; that optional parameter has been removed
% \item a new songTranslation environment added to provide the required
% capability for the Artist index option
% \item added a new song to the sample songbook to act as a test case
% for translation
% \end{itemize}
%
% \section*{Preface to version 4.2}
% What's new in version~4.2:
% \begin{itemize}
% \item added a new Artist index option
% \item added a new optional parameter to the xlatn environment; in
% support of the 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.
%
% \changes{v4.5}{2010/04/30}{Added |compactsong| documentation.}
% \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 Optional format string (Include song? / Compact song mode?);
% \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 optional format string parameter allows per-song control of certain
% typesetting attributes. Each of the attributes is optional, and a single
% attribute, or multiple attributes, may be used. The available values
% are:
% \begin{description}
% \item[|Y| or |N|] These two characters tell \Songbook{} whether to
% include the song in the songbook. This ``Include this song?'' option
% is referred to within this documentation as ``\meta{Include?}''. If
% you don't specify a value (and you typically will not), then it behaves
% as though you provided a value of ``\texttt{Y}''. When a value of
% ``\texttt{N}'' then the song is excluded from the current songbook;
% however, a table of contents record is written to a separate file
% (\textit{jobname}|.tocS|).
%
% \item[|C| or |F|] These two characters tell \Songbook{} whether the
% song should be presented in |compactsong| mode or full size presention
% mode (|chordbk| formatting only).
% \end{description}
%
% \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{songTranslation}{|\meta{1}|}|\ \ldots|{|\meta{4}|}|\ \meta{\ldots
% the translation\ldots}|\end{songTranslation}|\DescribeEnv{songTranslation}
% is the new song translation environment. The parameter list is defined
% as:
% \begin{enumerate}
% \item \ Translation language;
% \item \ Translated song title (in the foreign language);
% \item \ Translation permission;
% \item \ Who performed the translation.
% \end{enumerate}
% The |songTranslation| 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 |songTranslation|
% environment to occur within a song environment, because the |songTranslation|
% environment inherits the song environment's |\everypar| definition.
%
% \item |\begin{xlatn}{|\meta{1}|}|\ \ldots|{|\meta{3}|}|\ \meta{\ldots
% the translation\ldots}|\end{xlatn}|\DescribeEnv{xlatn}
% is the old song translation environment---this environment is
% considered obsolete and will be removed in a future relase of the
% \Songbook{} macros; it has been replaced by the |songTranslation|
% 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 |\SBBaseLang| \DescribeMacro{\SBBaseLang} tag is the name of the
% language of all songs not specified within an |songTranslation| environment, and
% also as the default value of the |songTranslation| environment's optional song language
% parameter. The default value for this is ``|English|''.
%
% \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}}
%
% \changes{v4.5}{2010/04/30}{Added new dependency: \texttt{xstring.sty}.}
% \section{Dependencies}
% The \Songbook{} style is dependent upon four other \LaTeX2e{} styles:
% \texttt{conditionals.sty}, \texttt{calc.sty}, \texttt{ifthen.sty},
% \texttt{multicol.sty}, and \texttt{xstring.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. \texttt{xstring.sty} is available
% from CTAN.
%
% 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).
%
% I am grateful to Adam Fletcher for prodding me to add the per-song
% |compactsong| implementation; which took many years more than it
% should have taken for me to get it coded.
%
% \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.16 2010-04-12 18:10:15 rathc Exp $
%%
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{songbook}[2010/04/30 v4.5 All purpose Songbook style]
\typeout{Document Subclass: songbook 2010/04/30 v4.5 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.
%
% \changes{v4.5}{2010/04/30}{Added new |CompanAllMode| boolean.}
% \begin{macrocode}
\newif\ifCompactAllMode \CompactAllModefalse
\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}
%
% \changes{v4.5}{2010/04/30}{Added |compactsong| fonts.}
% \subsubsection{Compact Song Fonts}
% Downsized fonts to allow song to fit into half the space (i.e.,
% two column mode) for |compactsong| printing; although the title
% will not be reset since it will be presented unchanged from normal
% chordbk mode.
%
% \begin{macro}{\ChBassFontCS}
% \begin{macro}{\ChFontCS}
% \begin{macro}{\ChBkFontCS}
% \begin{macro}{\SBDefaultFontCS}
% \begin{macro}{\SBOccursBrktFontCS}
%
% \begin{macrocode}
\newcommand{\ChBassFontCS}{\small\bf\sf} % = cmss12 at 11.0pt
\newcommand{\ChFontCS}{\normalsize\fontfamily{\sfdefault}%
\fontseries{sbc}\fontshape{n}\selectfont} % = cmssbc12 at 12.0pt
\newcommand{\ChBkFontCS}{\ChFont\fontseries{m} %
\selectfont} % = cmssm12 at 12.0pt
\newcommand{\SBDefaultFontCS}{\normalsize} % = cmr12 at 12.0pt
\newcommand{\SBOccursBrktFontCS}{\large\bf\sf} % = cmss10 at 10.9pt
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \changes{v4.5}{2010/04/30}{Added variables to save fonts for |compactsong| mode.}
% \subsubsection{Fonts Saving Variables}
% Variables in which to save the current fonts before
% we make changes for compactsong mode. We'll use them restore
% the original values again after leaving compact song mode.
%
% \begin{macro}{\ChBassFontSav}
% \begin{macro}{\ChFontSav}
% \begin{macro}{\ChBkFontSav}
% \begin{macro}{\SBDefaultFontSav}
% \begin{macro}{\SBOccursBrktFontSav}
% \begin{macro}{\SBFontSavVar}
%
% \begin{macrocode}
\newcommand{\ChBassFontSav}{\relax}%
\newcommand{\ChFontSav}{\relax}%
\newcommand{\ChBkFontSav}{\relax}%
\newcommand{\SBDefaultFontSav}{\relax}%
\newcommand{\SBOccursBrktFontSav}{\relax}%
\newcommand{\SBFontSavVar}{\relax}%
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \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 a few of them
% 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}
%
% \begin{macro}{\textwidthSav}
% \begin{macro}{\evensidemarginSav}
% \begin{macro}{\marginparwidthSav}
% \begin{macro}{\marginparsepSav}
% \begin{macro}{\chSpaceToleranceSav}
% \begin{macro}{\HangAmtSav}
% \begin{macro}{\LeftMarginSBChorusSav}
% \begin{macro}{\LeftMarginSBSectionSav}
% \begin{macro}{\LeftMarginSBVerseSav}
% The |\textwidthSav|, |\evensidemarginSav|, |\marginparwidthSav|,
% |\chSpaceToleranceSav|, |\HangAmtSav|, |\LeftMarginSBChorusSav|,
% |\LeftMarginSBSectionSav|, and |\LeftMarginSBVerse| lengths are
% used in |compactsong| processing; to save and then restore values
% from.
% \begin{macrocode}
\newlength{\textwidthSav}
\newlength{\evensidemarginSav}
\newlength{\marginparsepSav}
\newlength{\marginparwidthSav}
\newlength{\chSpaceToleranceSav}
\newcommand{\HangAmtSav}{}
\newcommand{\LeftMarginSBChorusSav}{}
\newcommand{\LeftMarginSBSectionSav}{}
\newcommand{\LeftMarginSBVerseSav}{}
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \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}
%
% \changes{v4.5}{2010/04/30}{Added new compactallsongs option.}
% \subsubsection{Compactallsongs Option}
%
% This option tells the \Songbook{} style to present all the songs in a
% compact form, regardless of what has been specified in each song. 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
% |compactallsongs| option. Like the papersize options, the
% |compactallsongs| processing here simply sets a flag; the actual code
% required to implement |compactallsongs| mode is embedded below inside
% the three core options.
%
% \begin{macrocode}
%%=======================================================%
%% C O M P A C T A L L S O N G S O P T I O N %
%%=======================================================%
% \end{macrocode}
% \begin{macro}{compactallsongs}
% \begin{macrocode}
\DeclareOption{compactallsongs}{%
%%%
% Set flag to indicate the user wants compact song mode
% for all songs.
\CompactAllModetrue
}
% \end{macrocode}
% \end{macro}
%
% \changes{v4.5}{2010/04/30}{Removed compactsong option.}
% \subsubsection{Compactsong Option}
%
% This option has been replaced with the combination of
% a new |compactallsongs| option and per-song specification
% of |compactsong| mode (see the documentation for the |song|
% environmnet.
%
% So, we now stop processing and print an error message telling
% the user that the option has been removed.
%
% \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}{%
\errmessage{The compactsong Songbook option has been
removed and replaced with a combination of a global
compactallsongs Songbook option and a per-song
environment compactsong option. See the song
environment's documentation}
}
% \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}
% \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 |compactallsongs| flag back to false; to ensure that
% no |compactallsongs| processing occurs. We take time to print a
% warning message for the user to remind them that the |compactallsongs|
% option will not have any effect at this time.
%
% \begin{macrocode}
\ifCompactAllMode
\typeout{``compactallsongs'' mode not implemented for Wordbk mode.}
\CompactAllModefalse
\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 compactallsongs processing, which at this time is nothing except
% resetting the |compactallsongs| flag back to false; to ensure that
% no |compactallsongs| processing occurs. We take time to print a
% warning message for the user to remind them that the |compactallsongs|
% option will not have any effect at this time.
%
% \begin{macrocode}
\ifCompactAllMode
\typeout{``compactallsongs'' mode not implemented for Overhead mode.}
\CompactAllModefalse
\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}
%
% \changes{v4.5}{2010/04/30}{\texttt{multicol.sty} is now always required.}
% We load Christian Tellechea's |xtring| package to enable the new
% optional song format string available for the |song| environment.
% This style is available on CTAN.
%
% \begin{macrocode}
\RequirePackage{xstring}
% \end{macrocode}
%
% \changes{v4.5}{2010/04/30}{New dependency on \texttt{xtring.sty}.}
% We load Frank Mittelbach's |multicol| package to enable use of
% |compactsong| mode. 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}
\RequirePackage{multicol}[1999/05/25]
% \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}{\SBBaseLang}
% The |\SBBaseLang| tag is the name of the language of all songs
% not specified within an |songTranslation| environment, and also as the
% default value of the |songTranslation| environment's optional song language
% parameter.
% The default value for this is ``|English|''.
%
% \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{\SBBaseLang} {English}
\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}
% \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}{\theXlatnLang}
% |\theXlatnLang| is the language the song has been translated into.
%
% \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{\theXlatnLang}{the Language}
\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}
% \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.}
% \changes{v4.5}{2010/04/30}{Added |compactsong| 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}] Song format string (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{Song Format String (options)}
% The first parameter is optional and its default value is
% ``\texttt{YF}''. Each letter in the format string controls one aspect
% of a song's formating. The format string options are:
% \begin{ParameterList}
% \item[|Y| |N|]: Include song in book; specify ``\texttt{Y}'' or
% ``\texttt{N}''?
% \item[|C| |F|]: |compactsong| or not (full size); specify ``\texttt{C}''
% or ``\texttt{F}''?
% \end{ParameterList}
%
% \subparagraph{YN: Include Song in Book?}
% When the value of \meta{YN: Include Song in Book?} is ``\texttt{Y}'' then all
% processing is done normally. If the value of \meta{YN: Include Song in Book?}
% is ``\texttt{N}'' 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}
%
% If both ``\texttt{Y}'' and ``\texttt{N}'' are specified, then ``\texttt{Y}''
% is taken as the specified value. Don't forget that a value of ``\texttt{N}''
% will be overridden by the global |printallsongs| option.
%
% 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.
%
% \subparagraph{CF: Compactsong or Full Size?}
% When the value of \meta{CF: Compactsong or Full Size?} is ``\texttt{F}''
% then all processing is done normally. If the value is ``\texttt{C}''
% then the song is printed in |compactsong| mode. If both ``\texttt{F}''
% and ``\texttt{F}'' are specified, then ``\texttt{F}''
% is taken as the specified value. Don't forget that a value of ``\texttt{F}''
% will be overridden by the global |compactallsongs| option.
%
% \begin{macrocode}
\newenvironment{song}[7][YF]{ % Comment markers to negate
\IfSubStr{\uppercase{#1}}{N}{\ExcludeSongtrue}{\relax}% newlines.
\IfSubStr{\uppercase{#1}}{Y}{\ExcludeSongfalse}{\relax}%
\ifPrintAllSongs\ExcludeSongfalse\fi %
\IfSubStr{\uppercase{#1}}{C}{\CompactSongModetrue}{\relax}% newlines.
\IfSubStr{\uppercase{#1}}{F}{\CompactSongModefalse}{\relax}%
\ifCompactAllMode\CompactSongModetrue\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 |songTranslation| 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{\theXlatnLang}{\SBBaseLang} %
\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}
%
% \paragraph{CompactSong Font 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{\ChBassFontSav}{\ChBassFont} %
\renewcommand{\ChFontSav}{\ChFont} %
\renewcommand{\ChBkFontSav}{\ChBkFont} %
\renewcommand{\SBDefaultFontSav}{\SBDefaultFont} %
\renewcommand{\SBOccursBrktFontSav}{\SBOccursBrktFont}%
%
\renewcommand{\ChBassFont}{\ChBassFontCS} %
\renewcommand{\ChFont}{\ChFontCS} %
\renewcommand{\ChBkFont}{\ChBkFontCS} %
\renewcommand{\SBDefaultFont}{\SBDefaultFontCS} %
\renewcommand{\SBOccursBrktFont}{\SBOccursBrktFontCS}%
%
% Multicol specific changes.
% \begin{macrocode}
\setlength{\columnsep}{0.25in}
% \end{macrocode}
%
% Remove side-margin, since marginal notes are not allowed when
% using multicol.sty; but, we save their values before changing
% them.
%
% \begin{macrocode}
\setlength{\textwidthSav} {\textwidth}
\setlength{\evensidemarginSav}{\evensidemargin}
\setlength{\marginparsepSav} {\marginparsep}
\setlength{\marginparwidthSav}{\marginparwidth}
%
\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{\chSpaceToleranceSav}{\chSpaceTolerance}
%
\setlength{\chSpaceTolerance}{1.0mm}
% \end{macrocode}
%
% Remove the extra space before Verses, etc.
%
% \begin{macrocode}
\renewcommand{\HangAmtSav} {\HangAmt}
\renewcommand{\LeftMarginSBChorusSav} {\LeftMarginSBChorus}
\renewcommand{\LeftMarginSBSectionSav}{\LeftMarginSBSection}
\renewcommand{\LeftMarginSBVerseSav} {\LeftMarginSBVerse}
%
\renewcommand{\HangAmt} {1.5em}
\renewcommand{\LeftMarginSBChorus} {2em}
\renewcommand{\LeftMarginSBSection}{\LeftMarginSBChorus}
\renewcommand{\LeftMarginSBVerse} {\LeftMarginSBChorus}
\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. For |CompactSongMode|
% we need to restore the fonts and lengths.
%
% \begin{macrocode}
{\ifSamepageMode%
\end{samepage}%
\fi%
\ifCompactSongMode
\renewcommand{\ChBassFont}{\ChBassFontSav} %
\renewcommand{\ChFont}{\ChFontSav} %
\renewcommand{\ChBkFont}{\ChBkFontSav} %
\renewcommand{\SBDefaultFont}{\SBDefaultFontSav} %
\renewcommand{\SBOccursBrktFont}{\SBOccursBrktFontSav}%
%
\setlength{\textwidth} {\textwidthSav}
\setlength{\evensidemargin}{\evensidemarginSav}
\setlength{\marginparsep} {\marginparsepSav}
\setlength{\marginparwidth}{\marginparwidthSav}
%
\renewcommand{\HangAmt} {\HangAmtSav}
\renewcommand{\LeftMarginSBChorus} {\LeftMarginSBChorusSav}
\renewcommand{\LeftMarginSBSection}{\LeftMarginSBSectionSav}
\renewcommand{\LeftMarginSBVerse} {\LeftMarginSBVerseSav}
%
\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 old 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 is considered obsolete and will be removed from
% a future release of the \Songbook{} macros.
%
% 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}{songTranslation}
% |songTranslation|\parm{1}\parm{2}\parm{3} is the song-translation environment.
% \begin{ParameterList}
% \item[\meta{1}] Language of translated song.
% \item[\meta{2}] Title of the translated song.
% \item[\meta{3}] Translation permission.
% \item[\meta{4}] Who performed the translation.
% \end{ParameterList}
%
% The |songTranslation| environment always occurs within a |song| environment.
% We reset the verse counter then cause the title and other
% parameter information to be displayed.
%
% The |xlatn| environment was the original song translation environment, but
% with the addition of an additional parameter (the ``Language of translated
% song.'' parameter) it made most sense to create a new environment which
% simply deals with the new parameter and then calls the old environment. At
% some point in the future, when the |xlatn| environment is removed, the |xlatn|
% code will be moved here.
%
% \begin{macrocode}
\newenvironment{songTranslation}[4]{% Comment marker negates the newline.
\renewcommand{\theXlatnBy}{#4}%
\begin{xlatn}{#2}{#3}{#4}%
}{\end{xlatn}}
% \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}
%
% The |xlatn| environment is obsolete, but for the sake of
% code-clarity the code has not been moved into the
% Obsolete Macros section of this document.
%
% \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: