Debian Codegraph @

texmf-dist/source/latex/songs/songs.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2018 Kevin W. Hamlen
4 %
5 % This program is free software; you can redistribute it and/or
6 % modify it under the terms of the GNU General Public License
7 % as published by the Free Software Foundation; either version 2
8 % of the License, or (at your option) any later version.
9 %
10 % This program is distributed in the hope that it will be useful,
11 % but WITHOUT ANY WARRANTY; without even the implied warranty of
12 % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 % GNU General Public License for more details.
14 %
15 % You should have received a copy of the GNU General Public License
16 % along with this program; if not, write to the Free Software
17 % Foundation, Inc., 51 Franklin Street, 5th Floor, Boston,
18 % MA 02110-1301, USA.
19 %
20 % The latest version of this program can be obtained from
21 % http://songs.sourceforge.net.
22 %
23 % \fi
24 %
25 % \iffalse
26 %<*driver>
27 \ProvidesFile{songs.dtx}
28 %</driver>
29 %<package>\NeedsTeXFormat{LaTeX2e}
30 %<package>\ProvidesPackage{songs}
31 %<*package>
32 [2018/09/12 v3.1 Songs package]
33 %</package>
34 %
35 %<*driver>
36 \documentclass{ltxdoc}
37
38 % This documentation compiles as part of the Songs self-installer, so it
39 % needs to work even on tiny LaTeX installations with few packages. We
40 % therefore try to be especially robust to missing package failures.
41 \newcommand\trypackage[4][]{\IfFileExists{#2.sty}{\usepackage[#1]{#2}#3}{#4}}
42 \trypackage{microtype}{\linepenalty=20 \parfillskip=0pt plus\textwidth\relax}{}
43 \trypackage{lmodern}{\usepackage[T1]{fontenc}}{}
44 \trypackage{ifpdf}{}{\expandafter\newif\csname ifpdf\endcsname\pdffalse}
45 \trypackage{color}{}{}
46 \ifpdf
47 \trypackage[bookmarks,linkbordercolor={.6 0 0}]{hyperref}{}{}
48 \fi
49 \usepackage[nopdfindex]{songs}
50
51 % Provide back-up hyperlinking and color macros that do nothing,
52 % in case the hyperref and/or color packages are absent.
53 \providecommand\href[2]{#2}
54 \providecommand\url[1]{#1}
55 \providecommand\pdfbookmark[3][]{}
56 \providecommand\hyperdef[3]{}
57 \providecommand\hyperlink[2]{#2}
58 \providecommand\texorpdfstring[2]{#1}
59 \providecommand\definecolor[3]{}
60 \providecommand\color[1]{}
61 \providecommand\textcolor[2]{#2}
62 \providecommand\microtypesetup[1]{}
63
64 % Configure the document:
65 \let\oldSE\StopEventually
66 \EnableCrossrefs
67 \CodelineIndex
68 \RecordChanges
69 %\OnlyDescription
70
71 % Create the \Songs logo, if the musix13 font is available:
72 \newcommand\Songs{\texorpdfstring{{\sffamily songs}}{songs}}
73 \newcount\imode
74 \imode=\interactionmode
75 \batchmode
76 \newfont\musicfont{musix13}
77 \interactionmode=\imode
78 \ifx\musicfont\nullfont\else
79 \newdimen\msize
80 \newcommand\wholenote{%
81 \msize4ex
82 \expandafter\ifx\csname musicfont\the\msize\endcsname\relax
83 \expandafter\newfont\csname musicfont\the\msize\endcsname
84 {musix13 at \the\msize}%
85 \fi
86 \kern.13ex
87 \raise.5ex\hbox{{\csname musicfont\the\msize\endcsname\symbol9}}%
88 \kern1.53ex
89 }
90 \renewcommand\Songs{\texorpdfstring{{\sffamily s\wholenote ngs}}{songs}}
91 \fi
92
93 % Create the logo for Christopher Rath's Songbook package:
94 \newcommand{\Rath}{{\sffamily Song$\flat$ook}}
95
96 % Colors
97 \definecolor{myred}{rgb}{0.6,0,0}
98 \definecolor{myblu}{rgb}{0,0,0.6}
99 \definecolor{mygra}{gray}{0.33}
100 \def\PrintDescribeMacro#1{\strut{\MacroFont\color{myred}\string#1}\ }
101 \let\PrintMacroName\PrintDescribeMacro
102 \def\PrintDescribeEnv#1{\strut{\MacroFont\color{myred}#1}\ }
103 \let\PrintEnvName\PrintDescribeEnv
104 {\makeatletter\gdef\verbatim@font{\normalfont\color{myblu}\ttfamily}}
105
106 % For some reason, doc.sty removes the \verbatim@font customization hook
107 % for \verb|...|. (Why??) That's not nice, so we put it back:
108 {\makeatletter
109 \gdef\verb {\relax\ifmmode\hbox\else\leavevmode\null\fi
110 \bgroup \let\do\do@noligs \verbatim@nolig@list
111 \verbatim@font \verb@eol@error \let\do\@makeother \dospecials
112 \@ifstar{\@sverb}{\@vobeyspaces \frenchspacing \@sverb}}
113 }
114
115 % Define some environments to simulate the interior of a verse,
116 % for showing samples in the documentation:
117 {\makeatletter
118 \gdef\likeverse{%
119 \SB@insongtrue\SB@inversetrue
120 \SB@loadactives
121 \global\SB@ctail\SB@cr@
122 }
123 \gdef\chordheight{\SB@setbaselineskip}
124 }
125
126 % Typeset a block of LaTeX code:
127 \newcommand\pfs{\parfillskip0pt plus1fil\relax}
128 \newenvironment{codeblock}{%
129 \medskip
130 \begingroup
131 \ifdim\parindent=0pt \parindent=20pt\fi
132 \indent\vbox\bgroup
133 \hsize\linewidth
134 \advance\hsize-\parindent
135 \rightskip=0pt plus1fil\pfs
136 \parindent=0pt
137 \color{myblu}%
138 \obeylines
139 }{%
140 \egroup\endgroup
141 \medskip
142 }
143
144 % Typeset a sample song or scripture quotation:
145 \songcolumns{0}
146 \newenvironment{sample}{%
147 \medskip
148 \noindent\hfil
149 \vbox\bgroup
150 \hsize.5\hsize
151 \advance\hsize-.5\columnsep
152 \versesep=5pt
153 \pfs
154 }{%
155 \egroup{\pfs\par}\medskip
156 }
157
158 % Typeset a sample lyric book fragment:
159 \newenvironment{lyrics}{%
160 \medskip
161 \noindent\hfil
162 \vbox\bgroup\begingroup
163 \hsize=.7\textwidth
164 \leftskip=20pt\rightskip=0pt plus1fil\pfs
165 \parindent=-20pt
166 \likeverse\obeylines
167 }{%
168 \par\endgroup\egroup
169 \hfil{\pfs\par}
170 \medskip
171 }
172
173 % Typeset a sample chord book fragment:
174 \newenvironment{chorded}{%
175 \medskip
176 \noindent\hfil
177 \vbox\bgroup\begingroup
178 \hsize=.7\textwidth
179 \leftskip=20pt\rightskip=0pt plus1fil\pfs
180 \parindent=-20pt
181 \likeverse\obeylines
182 \versesep=5pt\chordheight
183 }{%
184 \par\endgroup\egroup
185 \hfil{\pfs\par}
186 \medskip
187 }
188
189 % Typeset a "<code> produces <text>" example:
190 \newlength\prodlen
191 \setlength{\prodlen}{2.7in}
192 \newbox\prodbox
193 \newcommand{\example}{%
194 \medskip\setbox\prodbox\hbox\bgroup\begingroup\color{myblu}%
195 }
196 \newcommand{\produces}{%
197 \endgroup\egroup
198 \indent
199 \vbox{\hbox to\prodlen{\unhbox\prodbox\hfil}}
200 \ {\it produces}\quad
201 \afterassignment\prodprefix
202 \setbox\prodbox\hbox
203 }
204 \newcommand{\prodprefix}{%
205 \likeverse\chordheight
206 \aftergroup\prodsuffix
207 }
208 \newcommand{\prodsuffix}{\unhbox\prodbox{\pfs\par}\medskip}
209 \newbox\vcbox
210 \newdimen\vcadjust
211 \newcommand{\vcenterbox}[1]{%
212 \setbox\vcbox\vbox{\hbox{#1}}%
213 \vcadjust=.5\ht\vcbox
214 \advance\vcadjust by-6pt
215 \lower\vcadjust\box\vcbox
216 }
217
218 % Recode \DescribeMacro and \DescribeEnv to make nice pdfbookmark entries.
219 % Also create some \MainImpl macros that make pdfbookmarks to help the reader
220 % find the "real" implementations of important macros.
221 \newcount\seclevel
222 \newcommand\mybookmark[2]{%
223 \ifnum\value{subsection}=0 \seclevel=2
224 \else\ifnum\value{subsubsection}=0 \seclevel=3
225 \else\seclevel=4 \fi\fi
226 \setcounter{tocdepth}{4}%
227 \pdfbookmark[\the\seclevel]{#1}{#2}%
228 \setcounter{tocdepth}{3}%
229 }
230 {\makeatletter
231 \xdef\bschar{\@backslashchar}
232 \global\let\For\@for}
233 \newcommand\DescMacro[1]{%
234 \ifhmode\unskip\fi
235 \mybookmark{\bschar\bschar#1}{macdef-#1}%
236 \expandafter\DescribeMacro\expandafter{\csname#1\endcsname}%
237 \hyperdef{macro}{#1}{}\unpenalty
238 \ignorespaces
239 }
240 \newcommand\DescMacroGroup[3]{%
241 \ifhmode\unskip\fi
242 \mybookmark{\bschar\bschar#2}{macdef-#1}%
243 \expandafter\DescribeMacro\expandafter{\csname#2\endcsname}%
244 \For\temp:=#3\do{\hyperdef{macro}{\temp}{}}\unpenalty
245 \ignorespaces
246 }
247 \newcommand\MainImpl[1]{%
248 \pdfbookmark[3]{\bschar\bschar#1}{mimpl-#1}%
249 }
250 \newcommand{\DescEnv}[1]{%
251 \ifhmode\unskip\fi
252 \mybookmark{#1}{envdef-#1}%
253 \DescribeEnv{#1}%
254 \hyperdef{env}{#1}{}\unpenalty
255 \ignorespaces
256 }
257 \newcommand{\MainEnvImpl}[1]{%
258 \mybookmark{#1}{eimpl-#1}%
259 }
260
261 % Create macros to hyperlink macro and environment names to their
262 % documentation points.
263 \newcommand{\mac}[1]{{\tt\hyperlink{macro.#1}{\textcolor{myblu}{\char92 #1}}}}
264 \newcommand{\env}[1]{{\tt\hyperlink{env.#1}{\textcolor{myblu}{#1}}}}
265
266 % Defining bookmarks for definitions of active characters is a little trickier
267 % because many of these characters have special meanings either to TeX or to
268 % PDF. The only reliable way is to insert an "\ooo" escape sequence into the
269 % bookmark text, where ooo is the ascii number of the character expressed in
270 % octal. To achieve this, we use `\string<symbol> to obtain the decimal
271 % ascii number d of the symbol, then do some math (implemented in \octal)
272 % to compute and tokenize each octal digit of d into the bookmark text.
273 \newcount\cnta
274 \newcount\cntb
275 \newcommand\ooo{}
276 \newcommand\octal{%
277 \cntb\cnta
278 \divide\cnta8
279 \multiply\cnta-8
280 \advance\cntb\cnta
281 \edef\ooo{\the\cntb\ooo}%
282 \divide\cnta-8
283 }
284 \newcommand{\DescChar}[2]{%
285 \ifhmode\unskip\fi
286 \expandafter\let\csname string#1\expandafter\endcsname
287 \expandafter=\string#2%
288 \cnta\expandafter`\string#2%
289 \def\ooo{}\octal\octal\octal
290 \mybookmark{\bschar\ooo}{#1def}%
291 {\def\SpecialUsageIndex##1{}%
292 \expandafter\DescribeMacro\string#2}%
293 \hyperdef{env}{#1}{}\unpenalty
294 \ignorespaces
295 }
296 \newcommand{\refchar}[1]{{\tt\hyperlink{env.#1}{\csname string#1\endcsname}}}
297
298 % At the end of the implementation section we'll have a code line index of
299 % macro definitions and usages. To make it look a bit less ragged than the
300 % default index style and to conserve some space, we'll customize a few of
301 % the parameters:
302
303 \IndexPrologue{%
304 \subsection{Codeline Index}%
305 Underlined numbers refer to the code line where the corresponding entry
306 is defined; other numbers refer to the code lines where the entry
307 is used.}
308
309 {\makeatletter
310
311 \gdef\IndexParms{%
312 \sfcode`,=1750
313 \parindent0pt
314 \columnsep15pt
315 \parskip0pt plus1pt
316 \rightskip0pt
317 \mathsurround0pt
318 \parfillskip0pt
319 \small
320 \microtypesetup{protrusion=false}%
321 \def\@idxitem{\par\hangindent15pt}%
322 \def\subitem{\@idxitem\hspace*{15pt}}%
323 \def\subsubitem{\@idxitem\hspace*{25pt}}%
324 \def\indexspace{\par\vspace{10pt plus 2pt minus 3pt}}}
325
326 \gdef\SpecialMainOptIndex#1{%
327 \@bsphack
328 \special@index{%
329 #1\actualchar{\string\ttfamily\space#1} (option)\encapchar main}%
330 \special@index{%
331 options:\levelchar
332 #1\actualchar{\string\ttfamily\space#1}\encapchar main}%
333 \@esphack}
334 }
335
336 % Create a conditional that typesets its first argument if we're including
337 % the implementation section, otherwise typesets its second argument.
338 \newcommand\ImplOrDesc[2]{%
339 \ifx\StopEventually\oldSE#1\else#2\fi
340 }
341
342 % Hyphenating the word "choruses" looks weird. No "ruses" please!
343 \hyphenation{choruses white-space}
344
345 % An environment for describing the implementation of a package option:
346 \let\oldsmei\SpecialMainEnvIndex
347 \newenvironment{option}[1]{%
348 \let\SpecialMainEnvIndex\SpecialMainOptIndex
349 \begin{environment}{#1}%
350 \let\SpecialMainEnvIndex\oldsmei
351 }{%
352 \end{environment}%
353 \let\SpecialMainEnvIndex\oldsmei
354 }
355
356 % Describe the default setting for an option:
357 \newcommand\optdef[1]{\noindent{\it(Default: #1)}\hspace{.5cm}}
358
359 % Typeset a chord name:
360 \newcommand{\chord}[1]{{\sffamily\slshape#1}}
361
362 % Here are a few macros to produce nice syntax parameters:
363 \newcommand\Meta[1]{{\color{mygra}\meta{#1}}}
364 \newcommand\argp[1]{\Meta{arg#1}}
365 \newcommand\Metarm[1]{\textrm{\Meta{#1}}}
366 \newcommand\OR{\,$\mid$\,}
367 \newcommand\SPC{\char`\ }
368
369 % Now let's quell those annoying "Marginpar has moved" warning messages.
370 {\makeatletter
371 \global\let\oldamp=\@addmarginpar
372 \global\let\oldlwnl=\@latex@warning@no@line
373 \gdef\@addmarginpar{%
374 \let\@latex@warning@no@line\@gobble
375 \oldamp
376 \let\@latex@warning@no@line\oldlwnl
377 }
378 }
379
380 % The \eat macro just gobbles its argument. I use it to appease my syntax
381 % highlighter when it gets confused.
382 \newcommand{\eat}[1]{}
383
384 \begin{document}
385 \DocInput{songs.dtx}
386 \end{document}
387 %</driver>
388 % \fi
389 %
390 % \CheckSum{8935}
391 %
392 % \CharacterTable
393 % {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
394 % 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
395 % Digits \0\1\2\3\4\5\6\7\8\9
396 % Exclamation \! Double quote \" Hash (number) \#
397 % Dollar \$ Percent \% Ampersand \&
398 % Acute accent \' Left paren \( Right paren \)
399 % Asterisk \* Plus \+ Comma \,
400 % Minus \- Point \. Solidus \/
401 % Colon \: Semicolon \; Less than \<
402 % Equals \= Greater than \> Question mark \?
403 % Commercial at \@ Left bracket \[ Backslash \\
404 % Right bracket \] Circumflex \^ Underscore \_
405 % Grave accent \` Left brace \{ Vertical bar \|
406 % Right brace \} Tilde \~}
407 %
408 % \changes{v1.0}{2001/12/01}{Initial version}
409 % \changes{v1.1}{2005/04/03}{Change log introduced and first release of this documentation}
410 % \changes{v1.17}{2005/09/24}{Transformed the source from a class to a package}
411 % \changes{v1.18}{2005/09/29}{Verse numbering added}
412 % \changes{v2.0}{2007/06/20}{Keyval syntax and chord-replay system added}
413 %
414 % \iffalse
415 % Here we list all the macros that should not be indexed because they are:
416 % (a) too common and therefore the index would be too large if we listed them,
417 % (b) not useful in an index because they are predefined TeX macros, or
418 % (c) not really macros but rather control sequence names given to \string.
419 % \fi
420 % \DoNotIndex{\@M,\@depth,\@empty,\@firstofone,\@firstoftwo,\@gobble,\@gobbletwo,\@height,\@m,\@minus,\@ne,\@plus,\@secondoftwo,\@width,\m@ne,\p@,\thr@@,\tw@,\voidb@x,\@xpt,\z@,\z@skip}
421 % \DoNotIndex{\advance,\char,\count,\divide,\font,\fontdimen,\maxdimen,\multiply,\setcounter,\setlength,\settoheight,\settowidth,\stepcounter}
422 % \DoNotIndex{\begin,\begingroup,\bgroup,\egroup,\end,\endgroup}
423 % \DoNotIndex{\box,\copy,\dp,\hbox,\ht,\leavevmode,\lower,\null,\prevdepth,\raise,\rlap,\setbox,\unhbox,\unhcopy,\unpenalty,\unskip,\unvbox,\unvcopy,\vbox,\vtop,\wd}
424 % \DoNotIndex{\csname,\def,\edef,\endcsname,\futurelet,\gdef,\global,\let,\long,\mathchardef,\newcommand,\renewcommand,\renewenvironment,\xdef}
425 % \DoNotIndex{\@ifundefined,\@for,\do,\else,\fi,\ifcase,\ifcat,\ifdim,\iffalse,\ifhmode,\ifmmode,\ifinner,\ifnum,\ifodd,\ifvbox,\ifvmode,\ifvoid,\ifx,\loop,\or,\repeat,\undefined}
426 % \DoNotIndex{\afterassignment,\aftergroup,\expandafter,\ignorespaces,\immediate,\noexpand,\protect,\relax,\space,\string,\the}
427 % \DoNotIndex{\hfil,\hfilneg,\hskip,\hss,\indent,\kern,\nobreak,\noindent,\nointerlineskip,\offinterlineskip,\par,\penalty,\strut,\thinspace,\vadjust,\vfil,\vfilneg,\vphantom,\vskip}
428 % \DoNotIndex{\@octets,\four,\three,\two,\UTFviii@,\UTFviii@zero@octets,\0,\1,\2,\3,\4,\5,\6,\7,\8,\9,\X,\O}
429 %
430 % \GetFileInfo{songs.dtx}
431 %
432 % \title{The \Songs{} package\thanks{This manual documents
433 % \textsf{songs}~\fileversion, dated~\filedate,
434 % \copyright~2018 Kevin W.~Hamlen, and
435 % distributed under version~2 the GNU General Public License
436 % as published by the Free Software Foundation.}}
437 % \author{Kevin W. Hamlen}
438 %
439 % \maketitle
440 %
441 % \begin{abstract}
442 % The \Songs{} package produces songbooks that contain lyrics and chords
443 % (but not full sheet music).
444 % It allows lyric books, chord books, overhead slides, and digital projector
445 % slides to all be maintained and generated from a single \LaTeX{} source
446 % document.
447 % Automatic transposition, guitar tablature diagrams, handouts, and
448 % a variety of specialized song indexes are supported.
449 % \end{abstract}
450 %
451 % \section{Introduction}
452 %
453 % The \Songs{} \LaTeX{} package produces books of songs that contain lyrics and
454 % (optionally) chords.
455 % A single source document yields a lyric book for singers, a chord book for
456 % musicians, and overhead or digital projector slides for corporate singing.
457 %
458 % The software is especially well suited for churches and religious
459 % fellowships desiring to create their own books of worship songs.
460 % Rather than purchasing a fixed hymnal of songs, the \Songs{} package allows
461 % worship coordinators to maintain a constantly evolving repertoire of music
462 % to which they can add and remove songs over time.
463 % As the book content changes, the indexes, spacing, and other formatting
464 % details automatically adjust to stay consistent.
465 % Songs can also be quickly selected and arranged for specific events or
466 % services through the use of scripture indexes, automatic transposition,
467 % and handout and slide set creation features.
468 %
469 % \section{Terms of Use}
470 %
471 % \noindent
472 % The \Songs{} package is free software; you can redistribute it and/or
473 % modify it under the terms of the GNU General Public License
474 % as published by the Free Software Foundation; either version~2
475 % of the License, or (at your option) any later version.
476 % A copy of the license can be found in \S\ref{sec:license}.
477 %
478 % \medskip
479 %
480 % \noindent
481 % This program is distributed in the hope that it will be useful,
482 % but {\sc without any warranty}; without even the implied warranty of
483 % {\sc merchantability} or {\sc fitness for a particular purpose}. See the
484 % GNU General Public License in \S\ref{sec:license} for details.
485 % A copy of the license can also be obtained by writing to the
486 % Free Software Foundation, Inc., 51 Franklin Street, 5th Floor,
487 % Boston, MA 02110-1301, USA.
488 %
489 % \medskip
490 %
491 % \noindent
492 % This software is copyright \copyright~2018 Kevin W.~Hamlen.
493 % For contact information or the latest version, see the project webpage at:
494 %
495 % \vskip1.5ex
496 % \begingroup\centering\noindent
497 % \href{http://songs.sourceforge.net}{{\tt http://songs.sourceforge.net}}\par
498 % \endgroup
499 %
500 % \section{Sample Document}
501 %
502 % For those who would like to start making song books quickly, the
503 % following is a sample document that yields a simple song book with
504 % one song.
505 % Starting from this template, you can begin to add songs and customizations
506 % to create a larger book.
507 % Instructions for compiling this sample song book follow the listing.
508 %
509 % \begingroup\color{myblu}
510 % \begin{verbatim}
511 % \documentclass{article}
512 % \usepackage[chorded]{songs}
513 %
514 % \noversenumbers
515 %
516 % \begin{document}
517 %
518 % \songsection{Worship Songs}
519 %
520 % \begin{songs}{}
521 % \beginsong{Doxology}[by={Louis Bourgeois and Thomas Ken},
522 % sr={Revelation 5:13},
523 % cr={Public domain.}]
524 % \beginverse
525 % \[G]Praise God, \[D]from \[Em]Whom \[Bm]all \[Em]bless\[D]ings \[G]flow;
526 % \[G]Praise Him, all \[D]crea\[Em]tures \[C]here \[G]be\[D]low;
527 % \[Em]Praise \[D]Him \[G]a\[D]bove, \[G]ye \[C]heav'n\[D]ly \[Em]host;
528 % \[G]Praise Fa\[Em]ther, \[D]Son, \[Am]and \[G/B G/C]Ho\[D]ly \[G]Ghost.
529 % \[C]A\[G]men.
530 % \endverse
531 % \endsong
532 % \end{songs}
533 %
534 % \end{document}
535 % \end{verbatim}
536 % \endgroup\nointerlineskip\vskip-6pt plus0pt minus0pt
537 %
538 % To compile this book, run \LaTeX{} (|pdflatex| is recommended):
539 %
540 % \begin{codeblock}
541 % |pdflatex mybook.tex|
542 % \end{codeblock}
543 %
544 % \noindent
545 % (where |mybook.tex| is the name of the source document above).
546 % The final document is named |mybook.pdf| if you use |pdflatex| or
547 % |mybook.dvi| if you use regular |latex|.
548 %
549 % Note that compiling a document that includes indexes requires extra steps.
550 % See \S\ref{sec:compiling} for details.
551 %
552 % \begin{figure}
553 % \noindent\vbox{\begingroup\hsize=352pt
554 % \versesep=12pt\columnsep=7pt\parindent=20pt
555 % \def\colbotglue{0pt}\def\lastcolglue{0pt}
556 % \baselineadj=-1pt\relax
557 % \noversenumbers
558 % \setlength\textwidth{352pt}
559 % \setlength\textheight{498pt}
560 % \songcolumns{2}
561 % \vskip-3.5ex plus-1ex minus-.2ex
562 % \nointerlineskip\null\nointerlineskip
563 % \songsection*{Worship Songs}
564 % \begin{songs}{}
565 % \beginsong{Doxology}[
566 % by={Louis Bourgeois and Thomas Ken},
567 % sr={Revelation 5:13},
568 % cr={Public domain.}]
569 % \beginverse
570 % \[G]Praise God, \[D]from \[Em]Whom \[Bm]all \[Em]bless\[D]ings \[G]flow;
571 % \[G]Praise Him, all \[D]crea\[Em]tures \[C]here \[G]be\[D]low;
572 % \[Em]Praise \[D]Him \[G]a\[D]bove, \[G]ye \[C]heav'n\[D]ly \[Em]host;
573 % \[G]Praise Fa\[Em]ther, \[D]Son, \[Am]and \[G/B G/C]Ho\[D]ly \[G]Ghost.
574 % \[C]A\[G]men.
575 % \endverse
576 % \endsong\eat\]
577 % \parindent=15pt
578 % \beginscripture{Psalm 18:2-6}
579 % \Acolon The LORD is my rock and my fortress and my deliverer,
580 % \Bcolon my God, my rock, in whom I take refuge,
581 % \Bcolon my shield, and the horn of my salvation, my stronghold.
582 % \Acolon I call upon the LORD, who is worthy to be praised,
583 % \Bcolon and I am saved from my enemies.
584 % \strophe
585 % \Acolon The cords of death encompassed me;
586 % \Bcolon the torrents of destruction assailed me;
587 % \Acolon the cords of Sheol entangled me;
588 % \Bcolon the snares of death confronted me.
589 % \strophe
590 % \Acolon In my distress I called upon the LORD;
591 % \Bcolon to my God I cried for help.
592 % \Acolon From his temple he heard my voice,
593 % \Bcolon and my cry to him reached his ears.
594 % \endscripture
595 % \parindent=20pt
596 % \beginsong{A Mighty Fortress Is Our God}[
597 % by={Martin Luther},
598 % cr={Public Domain.}]
599 % \beginverse
600 % A \[A]mighty \[C#m]Fortress \[B7]is our \[E]God,
601 % A \[D]bulwark \[A]never \[E7]fail\[A]ing.
602 % Our helper \[C#m]He, a\[B7]mid the \[E]flood
603 % Of \[D]mortal \[A]ills pre\[E7]vail\[A]ing.
604 % For still our \[B7sus4]an\[B7]cient \[E]foe
605 % Doth \[A]seek to \[E/G#]work us \[F#m]woe;
606 % His craft and \[B7]pow'r are \[E]great,
607 % And, \[Bm]armed with cruel \[C#]hate,
608 % On \[D]earth is \[A]not his \[E7]e\[A]qual.
609 % \endverse
610 % \beginverse
611 % Did ^we in ^our own ^strength con^fide,
612 % Our ^striving ^would be ^los^ing.
613 % Were not the ^right Man ^on our ^side,
614 % The ^Man of ^God's own ^choos^ing.
615 % Dost ask who ^that ^may ^be?
616 % Christ ^Jesus, ^it is ^He;
617 % Lord Saba^oth His ^Name,
618 % From ^age to age the ^same;
619 % And ^He must ^win the ^bat^tle.
620 % \endverse
621 % \endsong\eat\]
622 % \end{songs}
623 % \endgroup}\par
624 % \caption{Sample page from a chord book}\label{fig:sample}
625 % \end{figure}
626 % A copy of the first page of a sample song section is shown in
627 % Figure~\ref{fig:sample}.
628 % The page shown in that figure is from a chorded version of the book.
629 % When generating a lyric version, the chords are omitted.
630 % See \S\ref{sec:options} for information on how to generate different
631 % versions of the same book.
632 %
633 % \section{Initialization and Options}\label{sec:options}
634 %
635 % Each \LaTeX{} document that uses the \Songs{} package should contain a
636 % line like the following near the top of the document:
637 %
638 % \begin{codeblock}
639 % |\usepackage[|\Meta{options}|]{songs}|
640 % \end{codeblock}
641 %
642 % \noindent
643 % Supported \Meta{options} include the following:
644 %
645 % \paragraph{Output Type.}
646 % \DescEnv{lyric}
647 % \DescEnv{chorded}
648 % \DescEnv{slides}
649 % \DescEnv{rawtext}
650 % The \Songs{} package can produce four kinds of books: lyric books, chord
651 % books, books of overhead slides, and raw text output.
652 % You can specify which kind of book is to be produced by specifying one of
653 % |lyric|, |chorded|, |slides|, or |rawtext| as an option.
654 % The |slides| and |chorded| options can be used together to create chorded
655 % slides.
656 % If no output options are specified, |chorded| is the default.
657 %
658 % Lyric books omit all chords, whereas chord books include chords and
659 % additional information for musicians (specified using \mac{musicnote}).
660 % Books of overhead slides typeset one song per page in a large font, centered.
661 %
662 % Raw text output yields an ascii text file named \Meta{jobname}|.txt|
663 % (where \Meta{jobname} is the root filename) containing lyrics without chords.
664 % This can be useful for importing song books into another program, such as a
665 % spell-checker.
666 %
667 % \DescMacro{chordson}
668 % \DescMacro{chordsoff}
669 % Chords can be turned on or off in the middle of the document
670 % by using the |\chordson| or |\chordsoff| macros.
671 %
672 % \DescMacro{slides}
673 % Slides mode can be activated in the middle of the document by using the
674 % |\slides| macro.
675 % For best results, this should typically only be done in the document
676 % preamble or at the beginning of a fresh page.
677 %
678 % \paragraph{Measure Bars.}
679 % \DescEnv{nomeasures}
680 % \DescEnv{showmeasures}
681 % \DescMacro{measureson}
682 % \DescMacro{measuresoff}
683 % The \Songs{} package includes a facility for placing measure bars in chord
684 % books (see \S\ref{sec:measures}).
685 % To omit these measure bars, use the |nomeasures| option;
686 % to display them, use the |showmeasures| option (the default).
687 % Measure bars can also be turned on or off in the middle of the document by
688 % using the |\measureson| or |\measuresoff| macros.
689 %
690 % \paragraph{Transposition.}
691 % \DescEnv{transposecapos}
692 % The |transposecapos| option changes the effect of the \mac{capo} macro.
693 % Normally, using |\capo{|\Meta{n}|}| within a song environment produces a
694 % textual note in chord books that suggests the use of a guitar capo on fret
695 % \Meta{n}.
696 % However, when the |transposecapos| option is active, these textual notes
697 % are omitted and instead the effect of |\capo{|\Meta{n}|}| is the
698 % same as for \mac{transpose}|{|\Meta{n}|}|.
699 % That is, chords between the \mac{capo} macro and the end of the song are
700 % automatically transposed up by \Meta{n} half-steps.
701 % This can be useful for adapting a chord book for guitarists to one that can
702 % be used by pianists, who don't have the luxury of capos.
703 % See \S\ref{sec:notes} and \S\ref{sec:transpose} for more information on the
704 % \mac{capo} and \mac{transpose} macros.
705 %
706 % \paragraph{Indexes.}
707 % \DescEnv{noindexes}
708 % \DescMacro{indexeson}
709 % \DescMacro{indexesoff}
710 % The |noindexes| option suppresses the typesetting of any in-document indexes.
711 % Display of indexes can also be turned on or off using the |\indexeson| and
712 % |\indexesoff| macros.
713 %
714 % \DescEnv{nopdfindex}
715 % PDF bookmark entries and hyperlinks can be suppressed with the |nopdfindex|
716 % option.
717 % For finer control of PDF indexes, see \S\ref{sec:idxcust}.
718 %
719 % \paragraph{Scripture Quotations.}
720 % \DescEnv{noscripture}
721 % \DescMacro{scriptureon}
722 % \DescMacro{scriptureoff}
723 % The |noscripture| option omits scripture quotations (see
724 % \S\ref{sec:scripture}) from the output.
725 % You can also turn scripture quotations on or off in the middle of the
726 % document by using |\scriptureon| or |\scriptureoff|, respectively.
727 %
728 % \paragraph{Shaded Boxes.}
729 % \DescEnv{noshading}
730 % The |noshading| option causes all shaded boxes, such as those that surround
731 % song numbers and textual notes, to be omitted.
732 % You might want to use this option if printing such shaded boxes causes
733 % problems for your printer or uses too much ink.
734 %
735 % \paragraph{Partial Song Sets.}
736 % \DescMacro{includeonlysongs}
737 % Often it is useful to be able to extract a subset of songs from the master
738 % document---e.g.~to create a handout or set of overhead slides for a specific
739 % worship service.
740 % To do this, you can type |\includeonlysongs{|\Meta{songlist}|}| in the
741 % document preamble (i.e., before the |\begin{document}| line), where
742 % \Meta{songlist} is a comma-separated list of the song numbers to include.
743 % For example,
744 %
745 % \begin{codeblock}
746 % |\includeonlysongs{37,50,2}|
747 % \end{codeblock}
748 %
749 % \noindent
750 % creates a document consisting only of songs 37, 50, and 2, in that order.
751 %
752 % Partial books generated with |\includeonlysongs| omit all scripture
753 % quotations (\S\ref{sec:scripture}), and ignore uses of
754 % \mac{nextcol}, \mac{brk}, \mac{sclearpage}, and \mac{scleardpage}
755 % between songs unless they are followed by a star (e.g., \mac{nextcol}|*|).
756 % To force a column- or page-break at a specific point in a partial book,
757 % add the word |nextcol|, |brk|, |sclearpage|, or |scleardpage| at the
758 % corresponding point in the \Meta{songlist}.
759 %
760 % The |\includeonlysongs| macro only reorders songs within each
761 % \env{songs} environment (see \S\ref{sec:songs}), not between different
762 % \env{songs} environments.
763 % It also cannot be used in conjunction with the \env{rawtext} option.
764 %
765 % \section{Songs}\label{sec:songs}
766 %
767 % \subsection{Beginning a Song}
768 %
769 % \paragraph{Song Sets.}
770 % \DescEnv{songs}
771 % Songs are contained within |songs| environments.
772 % Each |songs| environment begins and ends with:
773 %
774 % \begin{codeblock}
775 % |\begin{songs}{|\Meta{indexes}|}|
776 % $\vdots$
777 % |\end{songs}|
778 % \end{codeblock}
779 %
780 % \noindent
781 % \Meta{indexes} is a comma-separated list of index \Meta{id}'s
782 % (see \S\ref{sec:indexes})---one identifier for each index that is to
783 % include songs in this song set.
784 % Between the |\begin{songs}| and |\end{songs}| lines of
785 % a song section only songs (see below) or inter-song environments
786 % (see \S\ref{sec:between}) may appear.
787 % No text in a |songs| environment may appear outside of these environments.
788 %
789 % \paragraph{Songs.}
790 % \DescMacro{beginsong}
791 % \DescMacro{endsong}
792 % A song begins and ends with:
793 %
794 % \begin{codeblock}
795 % |\beginsong{|\Meta{titles}|}[|\Meta{otherinfo}|]|
796 % $\vdots$
797 % |\endsong|
798 % \end{codeblock}
799 %
800 % \noindent
801 % Songs should appear only within \env{songs} environments (see above)
802 % unless you are supplying your own page-builder (see \S\ref{sec:layout}).
803 %
804 % In the \mac{beginsong} line, \Meta{titles} is one or more song titles
805 % separated by |\\|.
806 % If multiple titles are provided, the first is typeset normally
807 % atop the song and the rest are each typeset in parentheses on
808 % separate lines.
809 %
810 % The |[|\Meta{otherinfo}|]| part is an optional comma-separated list of
811 % key-value pairs (keyvals) of the form \Meta{key}|=|\Meta{value}.
812 % The possible keys and their values are:
813 %
814 % \medskip
815 % \noindent\hfil\vbox{\halign{#\hfil&\kern2em{\it#}\hfil\cr
816 % |by={|\Meta{authors}|}|&authors, composers, and other contributors\cr
817 % |cr={|\Meta{copyright}|}|&copyright information\cr
818 % |li={|\Meta{license}|}|&licensing information\cr
819 % |sr={|\Meta{refs}|}|&related scripture references\cr
820 % |index={|\Meta{lyrics}|}|&an extra index entry for a line of lyrics\cr
821 % |ititle={|\Meta{title}|}|&an extra index entry for a hidden title\cr}}
822 % {\pfs\par}\medskip
823 %
824 % \noindent
825 % For example, a song that begins and ends with
826 %
827 % \begin{codeblock}
828 % |\beginsong{Title1 \\ Title2}[by={Joe Smith}, sr={Job 3},|
829 % | cr={\copyright~|\unskip\expandafter|\the\year|| XYZ.}, li={Used with permission.}]|
830 % |\endsong|
831 % \end{codeblock}
832 %
833 % \noindent looks like
834 %
835 % \begin{sample}
836 % \setcounter{songnum}{1}%
837 % \vskip1pt%
838 % \beginsong{Title1 \\ Title2}[by={Joe Smith}, sr={Job 3},
839 % cr={\copyright~\the\year{} XYZ.}, li={Used with permission.}]
840 % \endsong
841 % \end{sample}
842 %
843 % The four keyvals used in the above example are described in detail in the
844 % remainder of this section;
845 % the final two are documented in \S\ref{sec:ientry}.
846 % You can also create your own keyvals (see \S\ref{sec:newkey}).
847 %
848 % \paragraph{Song Authors.}
849 % \DescEnv{by=}
850 % The |by={|\Meta{authors}|}| keyval lists one or more authors,
851 % composers, translators, etc.
852 % An entry is added to each author index associated with the current
853 % \env{songs} environment for each contributor listed.
854 % Contributors are expected to be separated by commas, semicolons, or the
855 % word |and|.
856 % For example:
857 %
858 % \begin{codeblock}
859 % |by={Fred Smith, John Doe, and Billy Bob}|
860 % \end{codeblock}
861 %
862 % \noindent
863 % Words separated by a macro-space (\verb*@\ @\eat*) or tie (|~|)
864 % instead of a regular space are treated as single words by the indexer.
865 % For example, \verb*@The Vienna Boys' Choir@\eat* is indexed as
866 % ``Choir, The Vienna Boys'\thinspace'' but
867 % \verb*@The Vienna\ Boys'\ Choir@\eat* is indexed as
868 % ``Vienna Boys' Choir, The''.
869 %
870 % \paragraph{Copyright Info.}
871 % \DescEnv{cr=}
872 % The |cr={|\Meta{copyright}|}| keyval specifies the copyright-holder of the
873 % song, if any.
874 % For example:
875 %
876 % \begin{codeblock}
877 % |cr={\copyright~2000 ABC Songs, Inc.}|
878 % \end{codeblock}
879 %
880 % \noindent
881 % Copyright information is typeset in fine print at the bottom of the song.
882 %
883 % \paragraph{Licensing Info.}
884 % \DescEnv{li=}
885 % \DescMacro{setlicense}
886 % Licensing information is provided by |li={|\Meta{license}|}|, where
887 % \Meta{license} is any text.
888 % Licensing information is displayed in fine print under the song just
889 % after the copyright information (if any).
890 % Alternatively, writing |\setlicense{|\Meta{license}|}| anywhere between
891 % the \mac{beginsong} and \mac{endsong} lines is equivalent to using
892 % |li={|\Meta{license}|}| in the \mac{beginsong} line.
893 %
894 % When many songs in a book are covered by a common license, it is
895 % usually convenient to create a macro to abbreviate the licensing
896 % information.
897 % For example, if your organization has a music license from Christian
898 % Copyright Licensing International with license number 1234567, you might
899 % define a macro like
900 %
901 % \begin{codeblock}
902 % |\newcommand{\CCLI}{(CCLI \#1234567)}|
903 % \end{codeblock}
904 %
905 % \noindent
906 % Then you could write |li=\CCLI| in the \mac{beginsong} line of each song
907 % covered by CCLI.
908 %
909 % \paragraph{Scripture References.}
910 % \DescEnv{sr=}
911 % The \Songs{} package has extensive support for scripture citations and
912 % indexes of scripture citations.
913 % To cite scripture references for the song, use the keyval
914 % |sr={|\Meta{refs}|}|, where \Meta{refs} is a list of scripture
915 % references.
916 % Index entries are added to all scripture indexes associated
917 % with the current \env{songs} environment for each such reference.
918 % The |songidx| index generation script (see \S\ref{sec:compiling}) expects
919 % \Meta{refs} to be a list of references in which semicolons are used to
920 % separate references to different books, and commas are used to separate
921 % references to to different chapters and verses within the same book.
922 % For example, one valid scripture citation is
923 %
924 % \begin{codeblock}
925 % |sr={John 3:16,17, 4:1-5; Jude 3}|
926 % \end{codeblock}
927 %
928 % The full formal syntax of a valid \Meta{refs} argument is given in
929 % Figure~\ref{fig:srsyntax}.
930 % \begin{figure}
931 % \noindent\hfil\vbox{\advance\baselineskip2pt
932 % \halign{\hfil{\tt#}\,$\longrightarrow$\,&{\tt#}\hfil\cr
933 % \Metarm{refs}&\Metarm{nothing}\OR\Metarm{ref};\SPC\Metarm{ref};$\ldots$;\SPC\Metarm{ref}\cr
934 % \Metarm{ref}&\Metarm{many-chptr-book}\SPC\Metarm{chapters}\OR\Metarm{one-chptr-book}\SPC\Metarm{verses}\cr
935 % \Metarm{many-chptr-book}&Genesis\OR Exodus\OR Leviticus\OR Numbers\OR $\ldots$\cr
936 % \Metarm{one-chptr-book}&Obadiah\OR Philemon\OR 2 John\OR 3 John\OR Jude\cr
937 % \Metarm{chapters}&\Metarm{chref},\SPC\Metarm{chref},$\ldots$,\SPC\Metarm{chref}\cr
938 % \Metarm{chref}&\Metarm{chapter}\OR\Metarm{chapter}-\Metarm{chapter}\OR\Metarm{chapter}:\Metarm{verses}\OR\cr
939 % \omit&\quad\Metarm{chapter}:\Metarm{verse}-\Metarm{chapter}:\Metarm{verse}\cr
940 % \Metarm{verses}&\Metarm{vref},\Metarm{vref},$\ldots$,\Metarm{vref}\cr
941 % \Metarm{vref}&\Metarm{verse}\OR\Metarm{verse}-\Metarm{verse}\cr}}
942 % \caption{Formal syntax rules for song scripture references}\label{fig:srsyntax}
943 % \end{figure}
944 % In those syntax rules, \Meta{chapter} and \Meta{verse} stand for arabic
945 % numbers denoting a valid chapter number for the given book, and a valid
946 % verse number for the given chapter, respectively.
947 % Note that when referencing a book that has only one chapter,
948 % one should list only its verses after the book name
949 % (rather than |1:|\Meta{verses}).
950 %
951 % \subsection{Verses and Choruses}
952 %
953 % \paragraph{Starting A Verse Or Chorus.}
954 % \DescMacro{beginverse}
955 % \DescMacro{endverse}
956 % \DescMacro{beginchorus}
957 % \DescMacro{endchorus}
958 % Between the \mac{beginsong} and \mac{endsong} lines of a song can
959 % appear any number of verses and choruses.
960 % A verse begins and ends with:
961 %
962 % \begin{codeblock}
963 % |\beginverse|
964 % $\vdots$
965 % |\endverse|
966 % \end{codeblock}
967 %
968 % \noindent and a chorus begins and ends with:
969 %
970 % \begin{codeblock}
971 % |\beginchorus|
972 % $\vdots$
973 % |\endchorus|
974 % \end{codeblock}
975 %
976 % \noindent
977 % Verses are numbered (unless \mac{noversenumbers} has been used to
978 % suppress verse numbering) whereas choruses have a vertical line placed to
979 % their left.
980 %
981 % To create an unnumbered verse, begin the verse with |\beginverse*| instead.
982 % This can be used for things that aren't really verses but should be
983 % typeset like a verse (e.g.~intros, endings, and the like).
984 % A verse that starts with |\beginverse*| should still end with |\endverse|
985 % (not |\endverse*|).
986 %
987 % Within a verse or chorus you should enter one line of text for
988 % each line of lyrics.
989 % Each line of the source document produces a separate line in the resulting
990 % document (like \LaTeX's |\obeylines| macro).
991 % Lines that are too long to fit are wrapped with hanging indentation
992 % of width |\parindent|.
993 %
994 % \subsection{Chords}\label{sec:chords}
995 %
996 % \DescMacro{[}
997 % \DescChar{hash}{#}
998 % \DescChar{amp}{&}
999 % Between the \mac{beginverse} and \mac{endverse} lines, or between
1000 % the \mac{beginchorus} and \mac{endchorus} lines,
1001 % chords can be produced using the macro |\[|\Meta{chordname}|]|\eat\].
1002 % Chords only appear in chord books; they are omitted from lyric books.
1003 % The \Meta{chordname} may consist of arbitrary text.
1004 % To produce sharp and flat symbols, use |#| and |&| respectively.
1005 %
1006 % Any text that immediately follows the |\[]|\eat\] macro with no
1007 % intervening whitespace is assumed to be the word or syllable
1008 % that is to be sung as the chord is struck, and is therefore
1009 % typeset directly under the chord.
1010 % For example:
1011 %
1012 % \example|\[E&]peace and \[Am]joy|\produces{\[E&]peace and \[Am]joy}
1013 % \eat\]
1014 %
1015 % \noindent
1016 % If whitespace (a space or \Meta{return}) immediately follows,
1017 % then the chord name be typeset without any lyric text
1018 % below it, indicating that the chord is to be struck between
1019 % any surrounding words.
1020 % For example:
1021 %
1022 % \example|\[E&]peace and \[Am] joy|\produces{\[E&]peace and \[Am] joy}
1023 % \eat\]
1024 %
1025 % If the lyric text that immediately follows the chord contains
1026 % another chord, and if the width of the chord name exceeds the
1027 % width of the lyric text, then hyphenation is added automatically.
1028 % For example:
1029 %
1030 % \example|\[F#sus4]e\[A]ternal|\produces{\[F#sus4]e\[A]ternal}
1031 % \eat\]
1032 %
1033 % Sequences of chords that sit above a single word can be written
1034 % back-to-back with no intervening space, or as a single chord:
1035 %
1036 % \example|\[A]\[B]\[Em]joy|\produces{\[A]\[B]\[Em]joy}
1037 % \example|\[A B Em]joy|\produces{\[A B Em]joy}
1038 % \eat\]
1039 %
1040 % \noindent
1041 % The only difference between the two examples above is that the chords
1042 % in the first example can later be replayed separately (see
1043 % \S\ref{sec:replay}) whereas the chords in the second example can only be
1044 % replayed as a group.
1045 %
1046 % You can explicitly dictate how much of the text following a
1047 % chord macro is to appear under the chord name by using braces.
1048 % To exclude text that would normally be drawn under the chord,
1049 % use a pair of braces that includes the chord macro.
1050 % For example:
1051 %
1052 % \example|{\[G A]e}ternal|\produces{{\[G A]e}ternal}
1053 % \eat\]
1054 %
1055 % \noindent
1056 % (Without the braces, the syllables ``ternal'' would not be
1057 % pushed out away from the chord.)
1058 % This might be used to indicate that the chord transition occurs
1059 % on the first syllable rather than as the second syllable is
1060 % sung.
1061 %
1062 % Contrastingly, braces that do not include the chord itself can
1063 % be used to include text under a chord that would otherwise be
1064 % excluded.
1065 % For example:
1066 %
1067 % \example|\[Gmaj7sus4]{th' eternal}|\produces{\[Gmaj7sus4]{th' eternal}}
1068 % \eat\]
1069 %
1070 % \noindent
1071 % Without the braces, the word ``eternal'' would be pushed out away
1072 % from the chord so that the chord would appear only over
1073 % the partial word ``th'\thinspace''.
1074 %
1075 % \paragraph{Chords Without Lyrics.}
1076 % \DescMacro{nolyrics}
1077 % Sometimes you may want to write a line of chords with no lyrics in it at all,
1078 % such as for an instrumental intro or solo.
1079 % To make the chords in such a line sit on the baseline instead of raised above
1080 % it, use the |\nolyrics| macro.
1081 % For example:
1082 %
1083 % \example|{\nolyrics Intro: \[G] \[A] \[D]}|\produces{\nolyrics Intro: \[G] \[A] \[D]}
1084 % \eat\]
1085 %
1086 % \noindent
1087 % Note the enclosing braces that determine how long the effect should last.
1088 % Multiple lines can be included in the braces.
1089 % Instrumental solos should typically not appear in lyric books, so such
1090 % lines should usually also be surrounded by \mac{ifchorded} and |\fi|
1091 % (see \S\ref{sec:conditionals}).
1092 %
1093 % \paragraph{Symbols Under Chords.}
1094 % \DescMacro{DeclareLyricChar}
1095 % If you are typesetting songs in a language whose alphabet contains symbols
1096 % that \LaTeX{} treats as punctuation, you can use the |\DeclareLyricChar|
1097 % macro to instruct the \Songs{} package to treat the symbol as
1098 % non-chord-ending, so that it is included under chords by default just
1099 % like an alphabetic character.
1100 %
1101 % \begin{codeblock}
1102 % |\DeclareLyricChar{|\Meta{token}|}|
1103 % \end{codeblock}
1104 %
1105 % \noindent
1106 % Here, \Meta{token} must be a single \TeX{} macro control sequence,
1107 % active character, letter (something \TeX{} assigns catcode 11), or
1108 % punctuation symbol (something \TeX{} assigns catcode 12).
1109 % For example, by default,
1110 %
1111 % \example|\[Fmaj7]s\dag range|\produces{\[Fmaj7]s\dag range}
1112 % \eat\]
1113 %
1114 % \noindent
1115 % because |\dag| is not recognized as an alphabetic symbol;
1116 % but if you first type,
1117 %
1118 % \begin{codeblock}
1119 % |\DeclareLyricChar{\dag}|
1120 % \end{codeblock}
1121 %
1122 % \noindent
1123 % then instead you will get:
1124 %
1125 % \DeclareLyricChar{\dag}
1126 % \example|\[Fmaj7]s\dag range|\produces{\[Fmaj7]s\dag range}
1127 % \eat\]
1128 %
1129 % \noindent
1130 % \DescMacro{DeclareNonLyric}
1131 % Likewise, you can type
1132 %
1133 % \begin{codeblock}
1134 % |\DeclareNonLyric{|\Meta{token}|}|
1135 % \end{codeblock}
1136 %
1137 % \noindent
1138 % to reverse the above effect and force a token to be lyric-ending.
1139 % Such tokens are pushed out away from long chord names so that they
1140 % never fall under a chord, and hyphenation is added to the resulting gap.
1141 %
1142 % \DescMacro{DeclareNoHyphen}
1143 % To declare a token to be lyric-ending but without the added hyphenation,
1144 % use |\DeclareNoHyphen{|\Meta{token}|}| instead.
1145 % Such tokens are pushed out away from long chord names so that they never
1146 % fall under the chord, but hyphenation is not added to the resulting gap.
1147 %
1148 % \paragraph{Extending Chords Over Adjacent Words.}
1149 % \DescMacro{MultiwordChords}
1150 % The |\MultiwordChords| macro forces multiple words to be squeezed under one
1151 % chord by default.
1152 % Normally a long chord atop a short lyric pushes subsequent
1153 % lyrics away to make room for the chord:
1154 %
1155 % \example|\[Gmaj7sus4]my life|\produces{\[Gmaj7sus4]my life}
1156 % \eat\]
1157 %
1158 % \noindent
1159 % But if you first type |\MultiwordChords|, then instead you get the more
1160 % compact:
1161 %
1162 % \begingroup\MultiwordChords
1163 % \example|\[Gmaj7sus4]my life|\produces{\[Gmaj7sus4]my life}
1164 % \eat\]
1165 % \endgroup
1166 %
1167 % \noindent
1168 % Authors should exercise caution when using |\MultiwordChords| because
1169 % including many words under a single chord can often produce output that
1170 % is ambiguous or misleading to musicians.
1171 % For example,
1172 %
1173 % \begingroup\MultiwordChords
1174 % \example|\[F G Am]me free|\produces{\[F G Am]me free}\par
1175 % \eat\]
1176 % \endgroup
1177 %
1178 % \noindent
1179 % This might be misleading to musicians if all three chords are intended
1180 % to be played while singing the word ``me.''
1181 % Liberal use of braces is therefore required to make |\MultiwordChords|
1182 % produce good results, which is why it isn't the default.
1183 %
1184 % \paragraph{Accidentals Outside Chords.}
1185 % \DescMacro{shrp}
1186 % \DescMacro{flt}
1187 % Sharp and flat symbols can be produced with |#| and |&| when they appear
1188 % in chord macros, but if you wish to produce those symbols in
1189 % other parts of the document, you must use the |\shrp| and |\flt| macros.
1190 % For example, to define a macro that produces a \chord{C\shrp} chord, use:
1191 %
1192 % \begin{codeblock}
1193 % |\newcommand{\Csharp}{C\shrp}|
1194 % \end{codeblock}
1195 %
1196 % \subsection{Replaying Chords and Choruses}\label{sec:replay}
1197 %
1198 % \DescChar{hat}{^}
1199 % Many songs consist of multiple verses that use the same chords.
1200 % The \Songs{} package simplifies this common case by providing a means to
1201 % replay the chord sequence of a previous verse without having to retype
1202 % all the chords.
1203 % To replay a chord from a previous verse, type a hat symbol (|^|) anywhere
1204 % you would otherwise use a chord macro (|\[]|\eat\]).
1205 % For example,
1206 %
1207 % \begin{codeblock}
1208 % \mac{beginverse}
1209 % |\[G]This is the \[C]first \[G]verse.|\eat\]
1210 % \mac{endverse}
1211 % \mac{beginverse}
1212 % |The ^second verse ^ has the same ^chords.|
1213 % \mac{endverse}
1214 % \end{codeblock}
1215 %
1216 % \noindent produces
1217 %
1218 % \begin{chorded}\memorize
1219 % \[G]This is the \[C]first \[G]verse.\eat\]
1220 % \end{chorded}
1221 % \begin{chorded}
1222 % The ^second verse ^ has the same ^chords.
1223 % \end{chorded}
1224 %
1225 % Normal chords can appear amidst replayed chords without disrupting the
1226 % sequence of chords being replayed.
1227 % Thus, a third verse could say,
1228 %
1229 % \begin{codeblock}
1230 % \mac{beginverse}
1231 % |The ^third verse ^has a \[Cm]new ^chord.|\eat\]
1232 % \mac{endverse}
1233 % \end{codeblock}
1234 %
1235 % \noindent to produce
1236 %
1237 % \begin{chorded}
1238 % The ^third verse ^has a \[Cm]new ^chord.\eat\]
1239 % \end{chorded}
1240 %
1241 % Replaying can be used in combination with automatic transposition to produce
1242 % modulated verses.
1243 % See \S\ref{sec:transpose} for an example.
1244 %
1245 % \DescMacro{memorize}
1246 % By default, chords are replayed from the current song's first verse, but
1247 % you can replay the chords of a different verse or chorus by saying
1248 % |\memorize| at the beginning of any verse or chorus whose chords you want
1249 % to later replay.
1250 % Subsequent verses or choruses that use \refchar{hat} replay chords
1251 % from the most recently memorized verse or chorus.
1252 %
1253 % \paragraph{Selective Memorization.}
1254 % It is also possible to inject unmemorized chords into a memorized verse
1255 % so that they are not later replayed.
1256 % To suppress memorization of a chord, begin the chord's name with a hat
1257 % symbol.
1258 % For example,
1259 %
1260 % \begin{codeblock}
1261 % \mac{beginverse}\mac{memorize}
1262 % |The \[G]third \[C]chord will \[^Cm]not be re\[G]played.|\eat\]
1263 % \mac{endverse}
1264 % \mac{beginverse}
1265 % |When ^replaying, the ^unmemorized chord is ^skipped.|
1266 % \mac{endverse}
1267 % \end{codeblock}
1268 %
1269 % \noindent produces
1270 %
1271 % \begin{chorded}\memorize
1272 % The \[G]third \[C]chord will \[^Cm]not be re\[G]played.\eat\]
1273 % \vskip5pt%
1274 % When ^replaying, the ^unmemorized chord is ^skipped.
1275 % \end{chorded}
1276 %
1277 % \noindent
1278 % This is useful when the first verse of a song has something unique,
1279 % like an intro that won't be repeated in subsequent verses, but has
1280 % other chords that you wish to replay.
1281 %
1282 % \paragraph{Memorizing Multiple Chord Sequences.}
1283 % By default, the \Songs{} package only memorizes one sequence of chords
1284 % at a time and \refchar{hat} replays chords from that most recently
1285 % memorized sequence.
1286 % However, you can memorize and replay multiple independent sequences
1287 % using the macros described in the following paragraphs.
1288 %
1289 % \DescMacro{newchords}
1290 % Memorized or replayed chord sequences are stored in chord-replay registers.
1291 % To declare a new chord-replay register, type
1292 %
1293 % \begin{codeblock}
1294 % |\newchords{|\Meta{regname}|}|
1295 % \end{codeblock}
1296 %
1297 % \noindent
1298 % where \Meta{regname} is any unique alphabetic name.
1299 %
1300 % Once you've declared a register, you can memorize into that register
1301 % by providing the \Meta{regname} as an optional argument to
1302 % \mac{memorize}:
1303 %
1304 % \begin{codeblock}
1305 % \mac{memorize}|[|\Meta{regname}|]|
1306 % \end{codeblock}
1307 %
1308 % \noindent
1309 % Memorizing into a non-empty register replaces the contents of that
1310 % register with the new chord sequence.
1311 %
1312 % \DescMacro{replay}
1313 % To replay chords from a particular register, type
1314 %
1315 % \begin{codeblock}
1316 % |\replay[|\Meta{regname}|]|
1317 % \end{codeblock}
1318 %
1319 % \noindent
1320 % Subsequent uses of \refchar{hat} reproduce chords from the sequence
1321 % stored in register \Meta{regname}.
1322 %
1323 % Register contents are global, so you can memorize a chord sequence from one
1324 % song and replay it in others.
1325 % You can also use |\replay| multiple times in the same verse or chorus to
1326 % replay a sequence more than once.
1327 %
1328 % \paragraph{Replaying Choruses.}
1329 % \DescMacro{repchoruses}
1330 % When making overhead slides, it is often convenient to repeat the song's
1331 % chorus after the first verse on each page, so that the projector-operator
1332 % need not flip back to the first slide each time the chorus is to be sung.
1333 % You can say |\repchoruses| to automate this process.
1334 % This causes the first chorus in each subsequent song to be automatically
1335 % repeated after the first verse on each subsequent page of the song (unless
1336 % that verse is already immediately followed by a chorus).
1337 % If the first chorus is part of a set of two or more consecutive choruses,
1338 % then the whole set of choruses is repeated.
1339 % (A set of choruses is assumed to consist of things like pre-choruses that
1340 % should always be repeated along with the chorus.)
1341 % Choruses are not automatically inserted immediately after unnumbered
1342 % verses (i.e., verses that begin with \mac{beginverse}|*|).
1343 % Unnumbered verses are assumed to be bridges or endings that aren't
1344 % followed by a chorus.
1345 %
1346 % \DescMacro{norepchoruses}
1347 % Writing |\norepchoruses| turns off chorus repetition for subsequent songs.
1348 %
1349 % If you need finer control over where replayed choruses appear, use the
1350 % conditional macros covered in \S\ref{sec:conditionals} instead of
1351 % |\repchoruses|.
1352 % For example, to manually insert a chorus into only slide books at a
1353 % particular point (without affecting other versions of your book),
1354 % you could write:
1355 %
1356 % \begin{codeblock}
1357 % \mac{ifslides}
1358 % \mac{beginchorus}
1359 % $\vdots$
1360 % \mac{endchorus}
1361 % |\fi|
1362 % \end{codeblock}
1363 %
1364 % \noindent
1365 % and copy and paste the desired chorus into the middle.
1366 %
1367 % \subsection{Line and Column Breaks}
1368 %
1369 % \paragraph{Line Breaking.}
1370 % \DescMacro{brk}
1371 % To cause a long line of lyrics to be broken in a particular place, put the
1372 % |\brk| macro at that point in the line.
1373 % This does not affect lines short enough to fit without breaking.
1374 % For example,
1375 %
1376 % \begin{codeblock}
1377 % |\beginverse|
1378 % {\tt\frenchspacing This is a |\brk| short line.
1379 % But this is a particularly long line of lyrics |\brk| that will need to be wrapped.
1380 % } |\endverse|
1381 % \end{codeblock}
1382 %
1383 % \noindent produces
1384 %
1385 % \begin{lyrics}
1386 % This is a \brk short line.
1387 % But this is a particularly long line of lyrics \brk that will need to be wrapped.
1388 % \end{lyrics}
1389 %
1390 % \paragraph{Column Breaks Within Songs.}
1391 % To suggest a column break within a verse or chorus too long to fit in a
1392 % single column, use |\brk| on a line by itself.
1393 % If there are no |\brk| lines in a long verse, it is broken
1394 % somewhere that a line does not wrap.
1395 % (A wrapped line is never divided by a column break.)
1396 % If there are no |\brk| lines in a long chorus, it overflows the column,
1397 % yielding an overfull vbox warning.
1398 %
1399 % \paragraph{Column Breaks Between Songs.}
1400 % \DescMacro{nextcol}
1401 % \DescMacro{sclearpage}
1402 % \DescMacro{scleardpage}
1403 % To force a column break between songs, use |\nextcol|, |\brk|, |\sclearpage|,
1404 % or |\scleardpage| between songs.
1405 % The |\nextcol| macro ends the column by leaving blank space at the bottom.
1406 % The |\brk| macro ends the current column in lyric books by stretching
1407 % the preceeding text so that the column ends flush with the bottom
1408 % of the page.
1409 % (In non-lyric books |\brk| is identical to |\nextcol|.)
1410 % The |\sclearpage| macro is like |\nextcol| except that it shifts to the next
1411 % blank page if the current page is nonempty.
1412 % The |\scleardpage| macro is like |\sclearpage| except that it shifts to the
1413 % next blank even-numbered page in two-sided documents.
1414 % Column breaks usually need to be in different places in different book types.
1415 % To achieve this, use a conditional block from \S\ref{sec:conditionals}.
1416 % For example,
1417 %
1418 % \begin{codeblock}
1419 % \mac{ifchorded}|\else|\mac{ifslides}|\else\brk\fi\fi|
1420 % \end{codeblock}
1421 %
1422 % \noindent
1423 % forces a column break only in lyric books but does not affect chord books
1424 % or books of overhead slides.
1425 %
1426 % When a partial list of songs is being extracted with \mac{includeonlysongs},
1427 % |\brk|, |\nextcol|, |\clearpage|, and |\cleardpage| macros between songs
1428 % must be followed by a star to have any effect.
1429 % To force a column-break at a specific point in a partial book, add the
1430 % word |nextcol|, |brk|, |clearpage|, or |cleardpage| at the corresponding
1431 % point in the argument to \mac{includeonlysongs}.
1432 %
1433 % \subsection{Echoes and Repeats}
1434 %
1435 % \paragraph{Echo Parts.}
1436 % \DescMacro{echo}
1437 % To typeset an echo part, use |\echo{|\Meta{lyrics and chords}|}|.
1438 % Echo parts are parenthesized and italicized.
1439 % For example,
1440 %
1441 % \example|Alle\[G]luia! \echo{Alle\[A]luia!}|\produces{Alle\[G]luia! \echo{Alle\[A]luia!}}
1442 % \eat\]
1443 %
1444 % \paragraph{Repeated Lines.}
1445 % \DescMacro{rep}
1446 % To indicate that a line should be sung multiple times by all singers, put
1447 % |\rep{|\Meta{n}|}| at the end of the line.
1448 % For example,
1449 %
1450 % \example|Alleluia! \rep{4}|\produces{Alleluia! \rep{4}}
1451 %
1452 % \DescMacro{lrep}
1453 % \DescMacro{rrep}
1454 % To indicate exactly where repeated parts begin and end, use |\lrep| and
1455 % |\rrep| to create begin- and end-repeat signs.
1456 % For example,
1457 %
1458 % \example|\lrep \[G]Alleluia!\rrep \rep{4}|\produces{\lrep \[G]Alleluia!\rrep \rep{4}}
1459 % \eat\]
1460 %
1461 % \subsection{Measure Bars}\label{sec:measures}
1462 %
1463 % \DescMacro{measurebar}
1464 % \DescChar{pipe}{|}
1465 % Measure bars can be added to chord books in order to help musicians
1466 % keep time when playing unfamiliar songs.
1467 % To insert a measure bar, type either |\measurebar| or type the
1468 % vertical pipe symbol (``\verb@|@'').
1469 % For example,
1470 %
1471 % \example\verb@Alle|\[G]luia@\produces{Alle\meter{}{}\measurebar\[G]luia}
1472 % \eat\]
1473 %
1474 % \noindent
1475 % In order for measure bars to be displayed, the \env{showmeasures}
1476 % option must be enabled.
1477 % Measure bars are only displayed by default in chord books.
1478 %
1479 % \DescMacro{meter}
1480 % The first measure bar in a song has meter numbers placed above
1481 % it to indicate the time signature of the piece.
1482 % By default, these numbers are 4/4, denoting four quarter notes
1483 % per measure.
1484 % To change the default, type |\meter{|\Meta{n}|}{|\Meta{d}|}|
1485 % somewhere after the \mac{beginsong} line of the song but before the
1486 % first measure bar, to declare a time signature of \Meta{n} \Meta{d}th
1487 % notes per measure.
1488 %
1489 % \DescMacro{mbar}
1490 % You can also change meters mid-song either by using |\meter| in the
1491 % middle of the song or by typing |\mbar{|\Meta{n}|}{|\Meta{d}|}|
1492 % to produce a measure bar with a time signature of \Meta{n}/\Meta{d}.
1493 % For example,
1494 %
1495 % \begin{codeblock}
1496 % |\meter{6}{8}|
1497 % |\beginverse|
1498 % \verb@|Sing to the |heavens, ye \mbar{4}{4}saints of |old!@
1499 % |\endverse|
1500 % \end{codeblock}
1501 %
1502 % \noindent produces
1503 %
1504 % \begin{chorded}
1505 % \meter{6}{8}%
1506 % \measurebar Sing to the \measurebar heavens, ye \mbar{4}{4}saints of \measurebar old!
1507 % \end{chorded}
1508 %
1509 % \subsection{Textual Notes}\label{sec:notes}
1510 %
1511 % \DescMacro{textnote}
1512 % \DescMacro{musicnote}
1513 % Aside from verses and choruses, songs can also contain textual notes
1514 % that provide instructions to singers and musicians.
1515 % To create a textual note that is displayed in both lyric books
1516 % and chord books, use:
1517 %
1518 % \begin{codeblock}
1519 % |\textnote{|\Meta{text}|}|
1520 % \end{codeblock}
1521 %
1522 % \noindent
1523 % To create a textual note that is displayed only in chord books, use:
1524 %
1525 % \begin{codeblock}
1526 % |\musicnote{|\Meta{text}|}|
1527 % \end{codeblock}
1528 %
1529 % \noindent
1530 % Both of these create a shaded box containing \Meta{text}.
1531 % For example,
1532 %
1533 % \begin{codeblock}
1534 % |\textnote{Sing as a two-part round.}|
1535 % \end{codeblock}
1536 %
1537 % \noindent produces
1538 %
1539 % \begin{lyrics}
1540 % \textnote{Sing as a two-part round.}
1541 % \end{lyrics}
1542 %
1543 % \noindent
1544 % Textual notes can be placed anywhere within a song, either within
1545 % verses and choruses or between them.
1546 %
1547 % \paragraph{Guitar Capos.}
1548 % \DescMacro{capo}
1549 % One special kind of textual note suggests to guitarists a fret on which
1550 % they should put their capos.
1551 % Macro |\capo{|\Meta{n}|}| should be used for this purpose.
1552 % It normally has the same effect as \mac{musicnote}|{capo |\Meta{n}|}|;
1553 % however, if the \env{transposecapos} option is active then it
1554 % instead has the effect of \mac{transpose}|{|\Meta{n}|}|.
1555 % See \S\ref{sec:transpose} for more information on automatic chord
1556 % transposition.
1557 %
1558 % \subsection{Chords in Ligatures}
1559 %
1560 % This subsection covers an advanced topic and can probably be
1561 % skipped by those creating song books for non-professional use.
1562 %
1563 % The \mac{[\eat]} macro is the normal means by which chords should be inserted
1564 % into a song; however, a special case occurs when a chord falls within a
1565 % ligature.
1566 % Ligatures are combinations of letters or symbols that \TeX{} normally
1567 % typesets as a single font character so as to produce cleaner-looking
1568 % output.
1569 % The only ligatures in English are: ff, fi, fl, ffi, and ffl.
1570 % Other languages have additional ligatures like \ae{} and \oe.
1571 % Notice that in each of these cases, the letters are ``squished''
1572 % together to form a single composite symbol.
1573 %
1574 % \DescMacro{ch}
1575 % When a chord macro falls inside a ligature, \LaTeX{} fails to compact
1576 % the ligature into a single font character even in non-chorded versions of
1577 % the book.
1578 % To avoid this minor typographical error, use the |\ch| macro to typeset
1579 % the chord:
1580 %
1581 % \begin{codeblock}
1582 % |\ch{|\Meta{chord}|}{|\Meta{pre}|}{|\Meta{post}|}{|\Meta{full}|}|
1583 % \end{codeblock}
1584 %
1585 % \noindent
1586 % where \Meta{chord} is the chord text, \Meta{pre} is the text to
1587 % appear before the hyphen if the ligature is broken by auto-hyphenation,
1588 % \Meta{post} is the text to appear after the hyphen if the ligature
1589 % is broken by auto-hyphenation, and \Meta{full} is the full ligature
1590 % if it is not broken by hyphenation.
1591 % For example, to correctly typeset |\[Gsus4]dif\[G]ficult|\eat\],
1592 % in which the \chord{G} chord falls in the middle of the ``ffi''
1593 % ligature, one should use:
1594 %
1595 % \example|di\ch{G}{f}{fi}{ffi}cult|\produces{di\ch{G}{f}{fi}{ffi}cult}
1596 %
1597 % \noindent
1598 % This causes the ``ffi'' ligature to appear intact yet still correctly
1599 % places the \chord{G} chord over the second f.
1600 % To use the |\ch| macro with a replayed chord name (see \S\ref{sec:replay}),
1601 % use |^| as the \Meta{chord}.
1602 %
1603 % \DescMacro{mch}
1604 % The |\mch| macro is exactly like the \mac{ch} macro except that it
1605 % also places a measure bar into the ligature along with the chord.
1606 % For example,
1607 %
1608 % \example|di\mch{G}{f}{fi}{ffi}cult|\produces{di\mch{G}{f}{fi}{ffi}cult}
1609 %
1610 % \noindent
1611 % places both a measure bar and a \chord{G} chord after the first ``f''
1612 % in ``difficult'', yet correctly produces an unbroken ``ffi'' ligature
1613 % in copies of the book in which measure bars are not displayed.
1614 %
1615 % In the unusual case that a meter change is required within a
1616 % ligature, this can be achieved with a construction like:
1617 %
1618 % \example|\meter{6}{8}di\mch{G}{f}{fi}{ffi}cult|\produces{\meter{6}{8}di\mch{G}{f}{fi}{ffi}cult}
1619 %
1620 % \noindent
1621 % The \mac{meter} macro sets the new time signature, which appears
1622 % above the next measure bar---in this case the measure bar
1623 % produced by the |\mch| macro.
1624 %
1625 % Chords and measure bars produced with \refchar{hat} or
1626 % \refchar{pipe} are safe to use in ligatures.
1627 % Thus, |dif|\refchar{pipe}\refchar{hat}|ficult| requires
1628 % no special treatment; it leaves the ``ffi'' ligature intact when measure
1629 % bars are not being displayed.
1630 %
1631 % \section{Guitar Tablatures}\label{sec:tablatures}
1632 %
1633 % \DescMacro{gtab}
1634 % Guitar tablature diagrams can be created by using the construct
1635 %
1636 % \begin{codeblock}
1637 % |\gtab{|\Meta{chord}|}{|\Meta{fret}|:|\Meta{strings}|:|\Meta{fingering}|}|
1638 % \end{codeblock}
1639 %
1640 % \noindent
1641 % where the \Meta{fret} and \Meta{fingering} parts are both optional
1642 % (and you may omit any colon that borders an omitted argument).
1643 %
1644 % \Meta{chord} is a chord name to be placed above the diagram.
1645 %
1646 % \Meta{fret} is an optional digit from 2 to 9 placed to the
1647 % left of the diagram.
1648 %
1649 % \Meta{strings} should be a series of symbols, one for each string
1650 % of the guitar from lowest pitch to highest.
1651 % Each symbol should be one of:
1652 % |X| if that string is not to be played,
1653 % |0| (zero or the letter O) if that string is to be played open, or
1654 % one of |1| through |9| if that string is to be played on the given
1655 % numbered fret.
1656 %
1657 % \Meta{fingering} is an optional series of digits, one for each
1658 % string of the guitar from lowest pitch to highest.
1659 % Each digit should be one of:
1660 % |0| if no fingering information is to be displayed for that string (e.g., if
1661 % the string is not being played or is being played open), or
1662 % one of |1| through |4| to indicate that the given numbered finger is to be
1663 % used to hold down that string.
1664 %
1665 % Here are some examples to illustrate:
1666 %
1667 % \example|\gtab{A}{X02220:001230}|\produces{\vcenterbox{\gtab{A}{{\hphantom{4}}:X02220:001230}}}
1668 % \example|\gtab{C#sus4}{4:XX3341}|\produces{\vcenterbox{\gtab{C\shrp sus4}{4:XX3341}}}
1669 % \example|\gtab{B&}{X13331}|\produces{\vcenterbox{\gtab{B\flt}{{\hphantom{4}}:X13331:}}}
1670 %
1671 % To create a barre chord in which one finger is extended across multiple
1672 % strings, use parentheses |()| or brackets |[]| in the \Meta{strings}
1673 % argument to group the barred strings.
1674 % Each such group will draw a barre on the lowest numbered fret it contains.
1675 % For example:
1676 %
1677 % \example|\gtab{C7}{X(3535X):013140}|\produces{\vcenterbox{\gtab{C7}{{\hphantom{4}}:X(3535X):013140}}}
1678 %
1679 % \DescMacro{minfrets}
1680 % By default, tablature diagrams always consist of at least 4 fret rows
1681 % (more if the \Meta{strings} argument contains a number larger than 4).
1682 % To change the minimum number of fret rows, change the value of |\minfrets|.
1683 % For example, typing
1684 %
1685 % \begin{codeblock}
1686 % |\minfrets=1|
1687 % \end{codeblock}
1688 %
1689 % \noindent
1690 % causes tablature diagrams to have only as many rows are required to
1691 % accommodate the largest digit appearing in the \Meta{strings} argument.
1692 %
1693 % \paragraph{Tablatures Within Macros}
1694 % Macros that produce tablatures must not bury the colons that separate the
1695 % \Meta{fret}, \Meta{strings}, and \Meta{fingering} arguments within other
1696 % macros, and it's safest to always include both colons to avoid ambiguities
1697 % related to optional argument parsing.
1698 % For example,
1699 %
1700 % \begin{codeblock}
1701 % |\newcommand{\mystrings}{X4412X}|
1702 % |\newcommand{\myfingers}{X3412X}|
1703 % |\newcommand{\mychord}{|\mac{gtab}|{C|\mac{shrp}|}{:\mystrings:\myfingers}}|
1704 % \end{codeblock}
1705 %
1706 % \noindent
1707 % works as expected.
1708 % But omitting the colon before |\mystrings| in the definition of |\mychord|
1709 % confuses \mac{gtab} into thinking |\mystrings| is the \Meta{fret}
1710 % argument, and writing code like |\gtab{C\shrp}{\allargs}| with |\allargs|
1711 % defined to something with colons results in an error, because it confuses
1712 % \mac{gtab} into thinking that |\allargs| is only the \Meta{strings} argument.
1713 %
1714 % \section{Automatic Transposition}\label{sec:transpose}
1715 %
1716 % \DescMacro{transpose}
1717 % You can automatically transpose some or all of the chords in a song up by
1718 % \Meta{n} half-steps by adding the line
1719 %
1720 % \begin{codeblock}
1721 % |\transpose{|\Meta{n}|}|
1722 % \end{codeblock}
1723 %
1724 % \noindent
1725 % somewhere between the song's \mac{beginsong} line and the first chord to
1726 % be transposed.
1727 % For example, if a song's first chord is |\[D]|\eat\], and the line
1728 % |\transpose{2}| appears before it, then the chord appears as an
1729 % \chord{E} in the resulting document.
1730 % Specifying a negative number for \Meta{n} transposes subsequent chords
1731 % down instead of up.
1732 %
1733 % The |\transpose| macro affects all chords appearing after it until the
1734 % \mac{endsong} line.
1735 % If two |\transpose| macros appear in the same song, their effects are
1736 % cumulative.
1737 %
1738 % When the \env{transposecapos} option is active, the \mac{capo}
1739 % macro acts like |\transpose|.
1740 % See \S\ref{sec:notes} for more information.
1741 %
1742 % \paragraph{Enharmonics.}
1743 % \DescMacro{preferflats}
1744 % \DescMacro{prefersharps}
1745 % When using \mac{transpose} to automatically transpose the chords of a song,
1746 % the \Songs{} package code chooses between enharmonically equivalent
1747 % names for ``black key'' notes based on the first chord of the song.
1748 % For example, if |\transpose{1}| is used, and if the first chord of the
1749 % song is an \chord{E}, then all \chord{A} chords that appear in
1750 % the song are transcribed as \chord{B\flt} chords rather than
1751 % \chord{A\shrp} chords, since the key of \chord{F}-major (\chord{E}
1752 % transposed up by one half-step) has a flatted key signature.
1753 % Usually this guess produces correct results, but if not, you can use
1754 % either |\preferflats| or |\prefersharps| after the \mac{transpose} line
1755 % to force all transcription to use flatted names or sharped names
1756 % respectively, when resolving enharmonic equivalents.
1757 %
1758 % \paragraph{Modulated Verses.}
1759 % Automatic transposition can be used in conjunction with chord-replaying
1760 % (see \S\ref{sec:chords}) to produce modulated verses.
1761 % For example,
1762 %
1763 % \begin{codeblock}
1764 % \mac{beginverse}\mac{memorize}
1765 % |\[F#]This is a \[B/F#]memorized \[F#]verse. \[E&7]|\eat\]
1766 % \mac{endverse}
1767 % \mac{transpose}|{2}|
1768 % \mac{beginverse}
1769 % |^This verse is ^modulated up two ^half-steps.|
1770 % \mac{endverse}
1771 % \end{codeblock}
1772 %
1773 % \noindent produces
1774 %
1775 % \begin{chorded}\memorize
1776 % \[F#]This is a \[B/F#]memorized \[F#]verse. \[E&7]\eat\]
1777 % \vskip5pt\replay\transpose{2}%
1778 % ^This verse is ^modulated up two ^half-steps.
1779 % \transpose{-2}%
1780 % \end{chorded}
1781 %
1782 % \paragraph{Both Keys.}
1783 % \DescMacro{trchordformat}
1784 % By default, when chords are automatically transposed using \mac{transpose},
1785 % only the transposed chords are printed.
1786 % However, in some cases you may wish to print the old chords and the
1787 % transposed chords together so that musicians playing transposing and
1788 % non-transposing instruments can play from the same piece of music.
1789 % This can be achieved by redefining the |\trchordformat| macro, which
1790 % receives two arguments---the original chord name and the transposed chord
1791 % name, respectively.
1792 % For example, to print the old chord above the new chord above each lyric,
1793 % define
1794 %
1795 % \begin{codeblock}
1796 % |\renewcommand{\trchordformat}[2]{\vbox{\hbox{#1}\hbox{#2}}}|
1797 % \end{codeblock}
1798 %
1799 % \paragraph{Changing Note Names.}
1800 % \DescMacro{solfedge}
1801 % \DescMacro{alphascale}
1802 % In many countries it is common to use the solfedge names for the notes of
1803 % the scale (\chord{LA, SI, DO, RE, MI, FA, SOL\/}) instead of the
1804 % alphabetic names (\chord{A, B, C, D, E, F, G\/}).
1805 % By default, the transposition logic only understands alphabetic names, but
1806 % you can tell it to look for solfedge names by typing |\solfedge|.
1807 % To return to alphabetic names, type |\alphascale|.
1808 %
1809 % \DescMacro{notenames}
1810 % You can use other note names as well.
1811 % To define your own note names, type
1812 %
1813 % \begin{codeblock}
1814 % |\notenames{|\Meta{nameA}|}{|\Meta{nameB}|}|$\ldots$|{|\Meta{nameG}|}|
1815 % \end{codeblock}
1816 %
1817 % \noindent
1818 % where each of \Meta{nameA} through \Meta{nameG} must consist entirely of
1819 % a sequence of one or more \emph{uppercase} letters.
1820 % For example, some solfedge musicians use \chord{TI} instead of \chord{SI}
1821 % for the second note of the scale.
1822 % To automatically transpose such music, use:
1823 %
1824 % \begin{codeblock}
1825 % |\notenames{LA}{TI}{DO}{RE}{MI}{FA}{SOL}|
1826 % \end{codeblock}
1827 %
1828 % \DescMacro{notenamesin}
1829 % \DescMacro{notenamesout}
1830 % The \Songs{} package can also automatically convert one set of note names
1831 % to another.
1832 % For example, suppose you have a large song book in which chords have been
1833 % typed using alphabetic note names, but you wish to produce a book that
1834 % uses the equivalent solfedge names.
1835 % You could achieve this by using the |\notenamesin| macro to tell the
1836 % \Songs{} package which note names you typed in the input file, and then
1837 % using |\notenamesout| to tell the \Songs{} package how you want it to
1838 % typeset each note name in the output file.
1839 % The final code looks like this:
1840 %
1841 % \begin{codeblock}
1842 % |\notenamesin{A}{B}{C}{D}{E}{F}{G}|
1843 % |\notenamesout{LA}{SI}{DO}{RE}{MI}{FA}{SOL}|
1844 % \end{codeblock}
1845 %
1846 % \noindent
1847 % The syntaxes of |\notenamesin| and |\notenamesout| are identical to that
1848 % of \mac{notenames} (see above), except that the arguments of |\notenamesout|
1849 % can consist of any \LaTeX{} code that is legal in horizontal mode, not just
1850 % uppercase letters.
1851 %
1852 % To stop converting between note names, use \mac{alphascale}, \mac{solfedge},
1853 % or \mac{notenames} to reset all note names back to identical input and
1854 % output scales.
1855 %
1856 % \paragraph{Transposing Chords In Macros.}
1857 % \DescMacro{transposehere}
1858 % The automatic transposition logic does not find chord names that are hidden
1859 % inside macro bodies.
1860 % For example, if you abbreviate a chord by typing,
1861 %
1862 % \begin{codeblock}
1863 % |\newcommand{\mychord}{F|\mac{shrp}| sus4/C|\mac{shrp}|}|
1864 % \mac{transpose}|{4}|
1865 % |\[\mychord]|\eat\]
1866 % \end{codeblock}
1867 %
1868 % \noindent
1869 % then the \mac{transpose} macro fails to transpose it; the
1870 % resulting chord is still an \chord{F\shrp sus4/C\shrp} chord.
1871 % To fix the problem, you can use |\transposehere| in your macros to
1872 % explicitly invoke the transposition logic on chord names embedded in
1873 % macro bodies.
1874 % The above example could be corrected by instead defining:
1875 %
1876 % \begin{codeblock}
1877 % |\newcommand{\mychord}{\transposehere{F|\mac{shrp}| sus4/C|\mac{shrp}|}}|
1878 % \end{codeblock}
1879 %
1880 % \DescMacro{notrans}
1881 % Transposition can be suppressed within material that would otherwise be
1882 % transposed by using the |\notrans| macro.
1883 % For example, writing
1884 %
1885 % \begin{codeblock}
1886 % \mac{transposehere}|{G = \notrans{G}}|
1887 % \end{codeblock}
1888 %
1889 % \noindent
1890 % would typeset a transposed \chord{G} followed by a non-transposed
1891 % \chord{G} chord.
1892 % This does not suppress note name conversion (see \mac{notenames}).
1893 % To suppress both transposition and note name conversion, just use
1894 % braces (e.g., |{G}| instead of |\notrans{G}|).
1895 %
1896 % \paragraph{Transposing Guitar Tablatures.}
1897 % \DescMacro{gtabtrans}
1898 % The songs package cannot automatically transpose tablature diagrams
1899 % (see \S\ref{sec:tablatures}).
1900 % Therefore, when automatic transposition is taking place, only the chord
1901 % names of \mac{gtab} macros are displayed (and transposed); the diagrams
1902 % are omitted.
1903 % To change this default, redefine the |\gtabtrans| macro, whose two
1904 % arguments are the two arguments to \mac{gtab}.
1905 % For example, to display original tablatures without transposing them even
1906 % when transposition has been turned on, write
1907 %
1908 % \begin{codeblock}
1909 % |\renewcommand{\gtabtrans}[2]{|\mac{gtab}|{|\mac{notrans}|{#1}}{#2}}|
1910 % \end{codeblock}
1911 %
1912 % \noindent
1913 % To transpose the chord name but not the diagram under it, replace
1914 % \mac{notrans}|{#1}| with simply |#1| in the above.
1915 % To restore the default behavior, write
1916 %
1917 % \begin{codeblock}
1918 % |\renewcommand{\gtabtrans}[2]{|\mac{transposehere}|{#1}}|
1919 % \end{codeblock}
1920 %
1921 % \section{Between Songs}\label{sec:between}
1922 %
1923 % Never put any material directly into the top level of a \env{songs}
1924 % environment.
1925 % Doing so will disrupt the page-builder, usually producing strange page
1926 % breaks and blank pages.
1927 % To safely put material between songs, use one of the environments
1928 % described in this section.
1929 %
1930 % \subsection{Intersong Displays}\label{sec:intersong}
1931 %
1932 % \DescEnv{intersong}
1933 % To put column-width material between the songs in a \env{songs} environment,
1934 % use an |intersong| environment:
1935 %
1936 % \begin{codeblock}
1937 % |\begin{intersong}|
1938 % $\vdots$
1939 % |\end{intersong}|
1940 % \end{codeblock}
1941 %
1942 % \noindent
1943 % Material contributed in an |intersong| environment is subject to the same
1944 % column-breaking rules as songs (see \S\ref{sec:layout}), but all other
1945 % formatting is up to you.
1946 % By default, \LaTeX{} inserts interline glue below the last line of an
1947 % |intersong| environment.
1948 % To suppress this, end the |intersong| content with |\par\nointerlineskip|.
1949 %
1950 % \DescEnv{intersong*}
1951 % To instead put page-width material above a song, use an |intersong*|
1952 % environment:
1953 %
1954 % \begin{codeblock}
1955 % |\begin{intersong*}|
1956 % $\vdots$
1957 % |\end{intersong*}|
1958 % \end{codeblock}
1959 %
1960 % \noindent
1961 % This starts a new page if the current page already has column-width
1962 % material in it.
1963 %
1964 % \DescEnv{songgroup}
1965 % By default, all intersong displays are omitted when generating a partial
1966 % book with \mac{includeonlysongs}.
1967 % You can force them to be included whenever a particular song is included
1968 % by using a |songgroup| environment:
1969 %
1970 % \begin{codeblock}
1971 % |\begin{songgroup}|
1972 % $\vdots$
1973 % |\end{songgroup}|
1974 % \end{codeblock}
1975 %
1976 % \noindent
1977 % Each |songgroup| environment may include any number of \env{intersong},
1978 % \env{intersong*}, or scripture quotations (see \S\ref{sec:scripture}),
1979 % but must include exactly one song.
1980 % When using \mac{includeonlysongs}, the entire group is included in the
1981 % book if the enclosed song is included; otherwise the entire group is
1982 % omitted.
1983 %
1984 % \subsection{Scripture Quotations}\label{sec:scripture}
1985 %
1986 % \paragraph{Starting a Scripture Quotation.}
1987 % \DescMacro{beginscripture}
1988 % \DescMacro{endscripture}
1989 % A special form of intersong block typesets a scripture quotation.
1990 % Scripture quotations begin and end with
1991 %
1992 % \begin{codeblock}
1993 % |\beginscripture{|\Meta{ref}|}|
1994 % $\vdots$
1995 % |\endscripture|
1996 % \end{codeblock}
1997 %
1998 % \noindent
1999 % where \Meta{ref} is a scripture reference that is
2000 % typeset at the end of the quotation.
2001 % The \Meta{ref} argument should conform to the same syntax
2002 % rules as for the \Meta{ref} arguments passed to \mac{beginsong}
2003 % macros (see \S\ref{sec:songs}).
2004 %
2005 % The text of the scripture quotation between the |\beginscripture| and
2006 % |\endscripture| lines are parsed in normal paragraph mode.
2007 % For example:
2008 %
2009 % \begin{codeblock}
2010 % |\beginscripture{James 5:13}|
2011 % {\tt\frenchspacing%
2012 % Is any one of you in trouble? He should pray. Is anyone happy? Let him sing songs of praise.
2013 % } |\endscripture|
2014 % \end{codeblock}
2015 %
2016 % \noindent produces
2017 %
2018 % \begin{sample}
2019 % \beginscripture{James 5:13}
2020 % Is any one of you in trouble? He should pray. Is anyone happy? Let him sing songs of praise.
2021 % \endscripture
2022 % \end{sample}
2023 %
2024 % \paragraph{Tuplets.}
2025 % \DescMacro{Acolon}
2026 % \DescMacro{Bcolon}
2027 % To typeset biblical poetry the way it appears in most bibles, begin each
2028 % line with either |\Acolon| or |\Bcolon|.
2029 % A-colons are typeset flush with the left margin, while B-colons are
2030 % indented.
2031 % Any lines too long to fit are wrapped with double-width hanging indentation.
2032 % For example,
2033 %
2034 % \begin{codeblock}
2035 % |\beginscripture{Psalm 1:1}|
2036 % {\tt\frenchspacing%
2037 % |\Acolon| Blessed is the man
2038 % |\Bcolon| who does not walk in the counsel of the wicked
2039 % |\Acolon| or stand in the way of sinners
2040 % |\Bcolon| or sit in the seat of mockers.
2041 % } |\endscripture|
2042 % \end{codeblock}
2043 %
2044 % \noindent produces
2045 %
2046 % \begin{sample}
2047 % \beginscripture{Psalm 1:1}
2048 % \Acolon Blessed is the man
2049 % \Bcolon who does not walk in the counsel of the wicked
2050 % \Acolon or stand in the way of sinners
2051 % \Bcolon or sit in the seat of mockers.
2052 % \endscripture
2053 % \end{sample}
2054 %
2055 % \paragraph{Stanzas.}
2056 % \DescMacro{strophe}
2057 % Biblical poetry is often grouped into stanzas or ``strophes'',
2058 % each of which is separated from the next by a small vertical
2059 % space.
2060 % You can create that vertical space by typing |\strophe|.
2061 % For example,
2062 %
2063 % \begin{codeblock}
2064 % |\beginscripture{Psalm 88:2-3}|
2065 % {\tt\frenchspacing%
2066 % |\Acolon| May my prayer come before you;
2067 % |\Bcolon| turn your ear to my cry.
2068 % |\strophe|
2069 % |\Acolon| For my soul is full of trouble
2070 % |\Bcolon| and my life draws near the grave.
2071 % } |\endscripture|
2072 % \end{codeblock}
2073 %
2074 % \noindent produces
2075 %
2076 % \begin{sample}
2077 % \beginscripture{Psalm 88:2-3}
2078 % \Acolon May my prayer come before you;\par
2079 % \Bcolon turn your ear to my cry.\par
2080 % \strophe
2081 % \Acolon For my soul is full of trouble\par
2082 % \Bcolon and my life draws near the grave.
2083 % \endscripture
2084 % \end{sample}
2085 %
2086 % \paragraph{Indented Blocks.}
2087 % \DescMacro{scripindent}
2088 % \DescMacro{scripoutdent}
2089 % Some bible passages, such as those that mix prose and poetry, contain
2090 % indented blocks of text.
2091 % You can increase the indentation level within a scripture quotation
2092 % by using |\scripindent| and decrease it by using |\scripoutdent|.
2093 % For example,
2094 %
2095 % \begin{codeblock}
2096 % |\beginscripture{Hebrews 10:17-18}|
2097 % {\tt\frenchspacing%
2098 % Then he adds:
2099 % |\scripindent|
2100 % |\Acolon ``|Their sins and lawless acts
2101 % |\Bcolon| I will remember no more.|''|
2102 % |\scripoutdent|
2103 % And where these have been forgiven, there is no longer any sacrifice for sin.
2104 % } |\endscripture|
2105 % \end{codeblock}
2106 %
2107 % \noindent produces
2108 %
2109 % \begin{sample}
2110 % \beginscripture{Hebrews 10:17-18}
2111 % Then he adds:\par
2112 % \scripindent
2113 % \Acolon ``Their sins and lawless acts\par
2114 % \Bcolon I will remember no more.''\par
2115 % \scripoutdent
2116 % And where these have been forgiven, there is no longer any sacrifice for sin.
2117 % \endscripture
2118 % \end{sample}
2119 %
2120 % \section{Chapters and Sections}\label{sec:sectioning}
2121 %
2122 % \DescMacro{songsection}
2123 % \DescMacro{songchapter}
2124 % Song books can be divided into chapters and sections using all the usual
2125 % macros provided by \LaTeX{} (e.g., |\chapter|, |\section|, etc.) and by
2126 % other macro packages.
2127 % In addition, the \Songs{} package provides two helpful built-in sectioning
2128 % macros:
2129 %
2130 % \begin{codeblock}
2131 % |\songchapter{|\Meta{title}|}|
2132 % |\songsection{|\Meta{title}|}|
2133 % \end{codeblock}
2134 %
2135 % \noindent
2136 % which act like \LaTeX's |\chapter| and |\section| commands except that they
2137 % center the \Meta{title} text in sans serif font and omit the chapter/section
2138 % number.
2139 % The |\songchapter| macro only works in document classes that support
2140 % |\chapter| (e.g., the |book| class).
2141 %
2142 % \section{Indexes}
2143 %
2144 % \subsection{Index Creation}\label{sec:indexes}
2145 %
2146 % \DescMacro{newindex}
2147 % \DescMacro{newauthorindex}
2148 % \DescMacro{newscripindex}
2149 % The \Songs{} package supports three kinds of indexes: indexes by title and/or
2150 % notable lyrics, indexes by author, and indexes by scripture reference.
2151 % To generate an index, first declare the index in the document preamble
2152 % (i.e., before the |\begin{document}| line) with one of the following:
2153 %
2154 % \begin{codeblock}
2155 % |\newindex{|\Meta{id}|}{|\Meta{filename}|}|
2156 % |\newauthorindex{|\Meta{id}|}{|\Meta{filename}|}|
2157 % |\newscripindex{|\Meta{id}|}{|\Meta{filename}|}|
2158 % \end{codeblock}
2159 %
2160 % \noindent
2161 % The \Meta{id} should be an alphabetic identifier that will be used to
2162 % identify the index in other macros that reference it.
2163 % The \Meta{filename} should be a string that, when appended with an
2164 % extension, constitutes a valid filename on the system.
2165 % Auxiliary files named \Meta{filename}|.sxd| and \Meta{filename}|.sbx|
2166 % are generated during the automatic index generation process.
2167 % For example:
2168 %
2169 % \begin{codeblock}
2170 % |\newindex{mainindex}{idxfile}|
2171 % \end{codeblock}
2172 %
2173 % \noindent
2174 % creates a title index named ``|mainindex|'' whose data is
2175 % stored in files named |idxfile.sxd| and |idxfile.sbx|.
2176 %
2177 % \DescMacro{showindex}
2178 % To display the index in the document, use:
2179 %
2180 % \begin{codeblock}
2181 % |\showindex[|\Meta{columns}|]{|\Meta{title}|}{|\Meta{id}|}|
2182 % \end{codeblock}
2183 %
2184 % \noindent
2185 % where \Meta{id} is the same identifier used in the \mac{newindex},
2186 % \mac{newauthorindex}, or \mac{newscripindex} command, and where
2187 % the \Meta{title} is the title of the index, which should consist only of
2188 % simple text (no font or formatting macros, since those cannot be used in
2189 % pdf bookmark indexes).
2190 % The |[|\Meta{columns}|]| part is optional; if specified it dictates the
2191 % number of columns if the index can't fit in a single column.
2192 % For example, for a 2-column title index, write:
2193 %
2194 % \begin{codeblock}
2195 % |\showindex[2]{Index of Song Titles}{mainindex}|
2196 % \end{codeblock}
2197 %
2198 % \subsection{Index Entries}\label{sec:ientry}
2199 %
2200 % Every song automatically gets entries in the current \env{songs}
2201 % environment's list of title index(es) (see \S\ref{sec:songs}).
2202 % However, you can also add extra index entries for a song to any index.
2203 %
2204 % \paragraph{Indexing Lyrics.}
2205 % \DescEnv{index=}
2206 % For example, title indexes often have entries for memorable lines
2207 % of lyrics in a song in addition to the song's title.
2208 % You can add an index entry for the current song to the section's
2209 % title index(es) by adding |index={|\Meta{lyrics}|}| to the song's
2210 % \mac{beginsong} line.
2211 % For example,
2212 %
2213 % \begin{codeblock}
2214 % \mac{beginsong}|{Doxology}|
2215 % | [index={Praise God from Whom all blessings flow}]|
2216 % \end{codeblock}
2217 %
2218 % \noindent
2219 % causes the song to be indexed both as ``\textit{Doxology}'' and as
2220 % ``Praise God from Whom all blessings flow'' in the section's title index(es).
2221 % You can use |index=| multiple times in a \mac{beginsong} line to produce
2222 % multiple additional index entries.
2223 % Index entries produced with |index={|\Meta{lyrics}|}| are
2224 % typeset in an upright font instead of in italics to distinguish
2225 % them from song titles.
2226 %
2227 % \paragraph{Indexing Extra Song Titles.}
2228 % \DescEnv{ititle=}
2229 % To add a regular index entry typeset in italics to the title
2230 % index(es), use:
2231 %
2232 % \begin{codeblock}
2233 % |ititle={|\Meta{title}|}|
2234 % \end{codeblock}
2235 %
2236 % \noindent
2237 % in the \mac{beginsong} line instead.
2238 % Like \env{index=} keyvals, |ititle=| can be used multiple times to produce
2239 % multiple additional index entries.
2240 %
2241 % \DescMacro{indexentry}
2242 % \DescMacro{indextitleentry}
2243 % You can also create index entries by saying
2244 % |\indexentry[|\Meta{indexes}|]{|\Meta{lyrics}|}| (which creates an
2245 % entry like \env{index=}) or
2246 % |\indextitleentry[|\Meta{indexes}|]{|\Meta{title}|}| (which
2247 % creates an entry like \env{ititle=}).
2248 % These two macros can be used anywhere between the song's \mac{beginsong}
2249 % and \mac{endsong} lines, and can be used multiple times to produce
2250 % multiple entries.
2251 % If specified, \Meta{indexes} is a comma-separated list of the identifiers
2252 % of indexes to which the entry should be added.
2253 % Otherwise the new entry is added to all of the title indexes for the current
2254 % \env{songs} environment.
2255 %
2256 % \subsection{Compiling}\label{sec:compiling}
2257 %
2258 % As with a typical \LaTeX{} document, compiling a song book document with
2259 % indexes requires three steps.
2260 % First, use \LaTeX{} (|pdflatex| is recommended) to generate auxiliary files
2261 % from the |.tex| file:
2262 %
2263 % \begin{codeblock}
2264 % |pdflatex mybook.tex|
2265 % \end{codeblock}
2266 %
2267 % Second, use the |songidx.lua| script to generate an index for each index that
2268 % you declared with \mac{newindex}, \mac{newauthorindex}, or
2269 % \mac{newscripindex}.
2270 % The script can be launched using Lua\TeX, using the following syntax:
2271 %
2272 % \begin{codeblock}
2273 % |texlua songidx.lua |\textcolor{black}{[}|-b| \Meta{canon}|.can|\textcolor{black}{]} \Meta{filename}|.sxd| \Meta{filename}|.sbx|
2274 % \end{codeblock}
2275 %
2276 % \noindent
2277 % where \Meta{filename} is the same \Meta{filename} that was used in the
2278 % \mac{newindex}, \mac{newauthorindex}, or \mac{newscripindex} macro.
2279 % If the index was declared with \mac{newscripindex}, then the |-b| option
2280 % is used to specify which version of the bible you wish to use as a basis
2281 % for sorting your scripture index.
2282 % The \Meta{canon} part can be any of the |.can| files provided with
2283 % the |songidx| distribution.
2284 % If you are using a Protestant, Catholic, or Greek Orthodox Christian bible
2285 % with book names in English, then the |bible.can| canon file should work
2286 % well.
2287 % For other bibles, you should create your own |.can| file by copying and
2288 % modifying one of the existing |.can| files.
2289 %
2290 % For example, if your song book |.tex| file contains the lines
2291 %
2292 % \begin{codeblock}
2293 % \mac{newindex}|{titleidx}{titlfile}|
2294 % \mac{newauthorindex}|{authidx}{authfile}|
2295 % \mac{newscripindex}|{scripidx}{scrpfile}|
2296 % \end{codeblock}
2297 %
2298 % \noindent
2299 % then to generate indexes sorted according to a Christian English bible,
2300 % execute:
2301 %
2302 % \begin{codeblock}
2303 % |texlua songidx.lua titlfile.sxd titlfile.sbx|
2304 % |texlua songidx.lua authfile.sxd authfile.sbx|
2305 % |texlua songidx.lua -b bible.can scrpfile.sxd scrpfile.sbx|
2306 % \end{codeblock}
2307 %
2308 % Once the indexes are generated, generate the final book by invoking
2309 % \LaTeX{} one more time:
2310 %
2311 % \begin{codeblock}
2312 % |pdflatex mybook.tex|
2313 % \end{codeblock}
2314 %
2315 % \section{Customizing the Book}
2316 %
2317 % \subsection{Song and Verse Numbering}\label{sec:numbering}
2318 %
2319 % \paragraph{Song Numbering.}
2320 % \DescEnv{songnum}
2321 % The |songnum| counter defines the next song's number.
2322 % It is set to 1 at the beginning of a \env{songs} environment and is
2323 % increased by 1 after each \mac{endsong}.
2324 % It can be redefined anywhere except within a song.
2325 % For example,
2326 %
2327 % \begin{codeblock}
2328 % |\setcounter{songnum}{3}|
2329 % \end{codeblock}
2330 %
2331 % \noindent sets the next song's number to be 3.
2332 %
2333 % \DescMacro{thesongnum}
2334 % You can change the song numbering style for a song section by redefining
2335 % |\thesongnum|.
2336 % For example, to cause songs to be numbered A1, A2, etc., in the current
2337 % song section, type
2338 %
2339 % \begin{codeblock}
2340 % |\renewcommand{\thesongnum}{A\arabic{songnum}}|
2341 % \end{codeblock}
2342 %
2343 % \noindent
2344 % The expansion of |\thesongnum| must always produce plain text with no
2345 % font formatting or unexpandable macro tokens, since its text is
2346 % exported to auxiliary index generation files where it is sorted.
2347 %
2348 % \DescMacro{printsongnum}
2349 % To change the formatting of song numbers as they appear at the beginning
2350 % of each song, redefine the |\printsongnum| macro,
2351 % which expects the text yielded by \mac{thesongnum} as its only argument.
2352 % For example, to typeset song numbers in italics atop each song, define
2353 %
2354 % \begin{codeblock}
2355 % |\renewcommand{\printsongnum}[1]{\it\LARGE#1}|
2356 % \end{codeblock}
2357 %
2358 % \DescMacro{songnumwidth}
2359 % The |\songnumwidth| length defines the width of the shaded boxes that contain
2360 % song numbers at the beginning of each song.
2361 % For example, to make each such box 2 centimeters wide, you could define
2362 %
2363 % \begin{codeblock}
2364 % |\setlength{\songnumwidth}{2cm}|
2365 % \end{codeblock}
2366 %
2367 % \noindent
2368 % If |\songnumwidth| is set to zero, song numbers are not shown at all.
2369 %
2370 % \DescMacro{nosongnumbers}
2371 % To turn off song numbering entirely, type |\nosongnumbers|.
2372 % This inhibits the display of the song number atop each song
2373 % (but song numbers are still be displayed elsewhere, such as in indexes).
2374 % The same effect can be achieved by setting \mac{songnumwidth} to zero.
2375 %
2376 % \paragraph{Verse Numbering.}
2377 % \DescEnv{versenum}
2378 % The |versenum| counter defines the next verse's number.
2379 % It is set to 1 after each \mac{beginsong} line and is increased by 1 after
2380 % each \mac{endverse} (except if the verse begins with \mac{beginverse}|*|).
2381 % The |versenum| counter can be redefined anywhere within a song.
2382 % For example,
2383 %
2384 % \begin{codeblock}
2385 % |\setcounter{versenum}{3}|
2386 % \end{codeblock}
2387 %
2388 % \noindent sets the next verse's number to be 3.
2389 %
2390 % \DescMacro{theversenum}
2391 % You can change the verse numbering style by redefining |\theversenum|.
2392 % For example, to cause verses to be numbered in uppercase roman numerals,
2393 % define
2394 %
2395 % \begin{codeblock}
2396 % |\renewcommand{\theversenum}{\Roman{versenum}}|
2397 % \end{codeblock}
2398 %
2399 % \DescMacro{printversenum}
2400 % To change the formatting of verse numbers as they appear at the beginning
2401 % of each verse, redefine the |\printversenum| macro,
2402 % which expects the text yielded by \mac{theversenum} as its only argument.
2403 % For example, to typeset verse numbers in italics, define
2404 %
2405 % \begin{codeblock}
2406 % |\renewcommand{\printversenum}[1]{\it\LARGE#1.\ }|
2407 % \end{codeblock}
2408 %
2409 % \DescMacro{versenumwidth}
2410 % The |\versenumwidth| length defines the horizontal space reserved for verse
2411 % numbers to the left of each verse text.
2412 % Verse text is shifted right by this amount.
2413 % For example, to reserve half a centimeter of space for verse numbers, define
2414 %
2415 % \begin{codeblock}
2416 % |\setlength{\versenumwidth}{0.5cm}|
2417 % \end{codeblock}
2418 %
2419 % Verse numbers whose widths exceed |\versenumwidth| indent the first
2420 % line of the verse an additional amount to make room, but subsequent lines
2421 % of the verse are only indented by |\versenumwidth|.
2422 %
2423 % \DescMacro{noversenumbers}
2424 % To turn off verse numbering entirely, use |\noversenumbers|.
2425 % This is equivalent to saying
2426 %
2427 % \begin{codeblock}
2428 % |\renewcommand{|\mac{printversenum}|}[1]{}|
2429 % |\setlength{\versenumwidth}{0pt}|
2430 % \end{codeblock}
2431 %
2432 % \DescMacro{placeversenum}
2433 % The horizontal placement of verse numbers within the first line of each
2434 % verse is controlled by the |\placeversenum| macro.
2435 % By default, each verse number is placed flush-left.
2436 % \ImplOrDesc
2437 % {Authors interested in changing the placement of verse numbers should
2438 % consult \S\ref{sec:impparams} of the implementation section for more
2439 % information on this macro.}
2440 % {For more information on this macro, recompile this documentation with
2441 % the implementation section included.}
2442 %
2443 % \subsection{Song Appearance}
2444 %
2445 % \paragraph{Font Selection.}
2446 % \DescMacro{lyricfont}
2447 % By default, lyrics are typeset using the document-default font
2448 % (|\normalfont|) and with the document-default point size (|\normalsize|).
2449 % You can change these defaults by redefining |\lyricfont|.
2450 % For example, to cause lyrics to be typeset in small sans serif font,
2451 % you could define
2452 %
2453 % \begin{codeblock}
2454 % |\renewcommand{\lyricfont}{\sffamily\small}|
2455 % \end{codeblock}
2456 %
2457 % \DescMacro{stitlefont}
2458 % Song titles are typeset in a sans-serif, slanted font by default
2459 % (sans-serif, upright if producing slides), with minimal line spacing.
2460 % You can change this default by redefining |\stitlefont|.
2461 % For example, to cause titles to be typeset in a roman font with lines
2462 % spaced 20 points apart, you could define
2463 %
2464 % \begin{codeblock}
2465 % |\renewcommand{\stitlefont}{|
2466 % | \rmfont\Large\baselineskip=20pt\lineskiplimit=0pt|
2467 % |}|
2468 % \end{codeblock}
2469 %
2470 % \DescMacro{versefont}
2471 % \DescMacro{chorusfont}
2472 % \DescMacro{meterfont}
2473 % \DescMacro{echofont}
2474 % \DescMacro{notefont}
2475 % You can apply additional font changes to verses, choruses, meter numbers,
2476 % echo parts produced with \mac{echo}, and textual notes produced with
2477 % \mac{textnote} and \mac{musicnote}, by redefining |\versefont|,
2478 % |\chorusfont|, |\meterfont|, |\echofont|, and |\notefont|, respectively.
2479 % For example, to typeset choruses in italics, you could define
2480 %
2481 % \begin{codeblock}
2482 % |\renewcommand{\chorusfont}{\it}|
2483 % \end{codeblock}
2484 %
2485 % \DescMacro{notebgcolor}
2486 % \DescMacro{snumbgcolor}
2487 % The colors of shaded boxes containing textual notes and song numbers
2488 % can be changed by redefining the |\notebgcolor| and |\snumbgcolor|
2489 % macros.
2490 % For example:
2491 %
2492 % \begin{codeblock}
2493 % |\renewcommand{\notebgcolor}{red}|
2494 % \end{codeblock}
2495 %
2496 % \DescMacro{printchord}
2497 % By default, chords are typeset in sans serif oblique (slanted) font.
2498 % You can customize chord appearance by redefining |\printchord|, which
2499 % accepts the chord text as its argument.
2500 % For example, to cause chords to be printed in roman boldface font,
2501 % you could define
2502 %
2503 % \begin{codeblock}
2504 % |\renewcommand{\printchord}[1]{\rmfamily\bf#1}|
2505 % \end{codeblock}
2506 %
2507 % \paragraph{Accidental Symbols.}
2508 % \DescMacro{sharpsymbol}
2509 % \DescMacro{flatsymbol}
2510 % By default, sharp and flat symbols are typeset using \LaTeX's
2511 % |\#| ($\#$) and |\flat| ($\flat$) macros.
2512 % Users can change this by redefining |\sharpsymbol| and |\flatsymbol|.
2513 % For example, to use |\sharp| ($\sharp$) instead of $\#$, one could
2514 % redefine |\sharpsymbol| as follows.
2515 %
2516 % \begin{codeblock}
2517 % |\renewcommand{\sharpsymbol}{\ensuremath{^\sharp}}|
2518 % \end{codeblock}
2519 %
2520 % \paragraph{Verse and Chorus Titles.}
2521 % \DescMacro{everyverse}
2522 % \DescMacro{everychorus}
2523 % The |\everyverse| macro is executed at the beginning of each verse, and
2524 % |\everychorus| is executed at the beginning of each chorus.
2525 % Thus, to begin each chorus with the word ``Chorus:'' one could type,
2526 %
2527 % \begin{codeblock}
2528 % |\renewcommand{\everychorus}{|\mac{textnote}|{Chorus:}}|
2529 % \end{codeblock}
2530 %
2531 % \paragraph{Spacing Options.}
2532 % \DescMacro{versesep}
2533 % The vertical distance between song verses and song choruses is defined by
2534 % the skip register |\versesep|.
2535 % For example, to put 12 points of space between each pair of verses and
2536 % choruses, with a flexibility of plus or minus 2 points, you could define
2537 %
2538 % \begin{codeblock}
2539 % |\versesep=12pt plus 2pt minus 2pt|
2540 % \end{codeblock}
2541 %
2542 % \DescMacro{afterpreludeskip}
2543 % \DescMacro{beforepostludeskip}
2544 % The vertical distance between the song's body and its prelude and postlude
2545 % material is controlled by skips |\afterpreludeskip| and
2546 % |\beforepostludeskip|.
2547 % This glue can be made stretchable for centering effects.
2548 % For example, to cause each song body to be centered on the page with one
2549 % song per page, you could write:
2550 %
2551 % \begin{codeblock}
2552 % \mac{songcolumns}|{1}|
2553 % \mac{spenalty}|=-10000|
2554 % |\afterpreludeskip=2pt plus 1fil|
2555 % |\beforepostludeskip=2pt plus 1fil|
2556 % \end{codeblock}
2557 %
2558 % \DescMacro{baselineadj}
2559 % The vertical distance between the baselines of consecutive lines of
2560 % lyrics is computed by the \Songs{} package based on several factors
2561 % including the lyric font size, the chord font size (if in \env{chorded}
2562 % mode), and whether \env{slides} mode is currently active.
2563 % You can adjust the results of this computation by redefining skip
2564 % register |\baselineadj|.
2565 % For example, to reduce the natural distance between baselines by 1 point
2566 % but allow an additional 1 point of stretching when attempting to balance
2567 % columns, you could define
2568 %
2569 % \begin{codeblock}
2570 % |\baselineadj=-1pt plus 1pt minus 0pt|
2571 % \end{codeblock}
2572 %
2573 % \DescMacro{clineparams}
2574 % To change the vertical distance between chords and the lyrics below them,
2575 % redefine the |\clineparams| macro with a definition that adjusts the
2576 % \LaTeX{} parameters |\baselineskip|, |\lineskiplimit|, and |\lineskip|.
2577 % For example, to cause the baselines of chords and their lyrics to be
2578 % 12 points apart with at least 1 point of space between the bottom of the
2579 % chord and the top of the lyric, you could write:
2580 %
2581 % \begin{codeblock}
2582 % |\renewcommand{\clineparams}{|
2583 % | \baselineskip=12pt|
2584 % | \lineskiplimit=1pt|
2585 % | \lineskip=1pt|
2586 % |}|
2587 % \end{codeblock}
2588 %
2589 % \DescMacro{cbarwidth}
2590 % The width of the vertical line that appears to the left of choruses is
2591 % controlled by the |\cbarwidth| length.
2592 % To eliminate the line entirely (and the spacing around it), you can set
2593 % |\cbarwidth| to |0pt|:
2594 %
2595 % \begin{codeblock}
2596 % |\setlength{\cbarwidth}{0pt}|
2597 % \end{codeblock}
2598 %
2599 % \DescMacro{sbarheight}
2600 % The height of the horizontal line that appears between each pair of songs
2601 % is controlled by the |\sbarheight| length.
2602 % To eliminate the line entirely (and the spacing around it), you can set
2603 % |\sbarheight| to |0pt|:
2604 %
2605 % \begin{codeblock}
2606 % |\setlength{\sbarheight}{0pt}|
2607 % \end{codeblock}
2608 %
2609 % \paragraph{Song Top and Bottom Material.}
2610 % You can adjust the header and footer material that precedes and concludes
2611 % each song by redefining |\extendprelude| and |\extendpostlude|.
2612 %
2613 % \DescMacro{extendprelude}
2614 % \DescMacro{showauthors}
2615 % \DescMacro{showrefs}
2616 % By default, |\extendprelude| displays the song's authors and scripture
2617 % references using the macros |\showauthors| and |\showrefs|.
2618 % The following definition changes it to also print copyright info:
2619 %
2620 % \begin{codeblock}
2621 % |\renewcommand{\extendprelude}{|
2622 % | |\mac{showrefs}\mac{showauthors}
2623 % | {\bfseries|\mac{songcopyright}|\par}|
2624 % |}|
2625 % \end{codeblock}
2626 %
2627 % \DescMacro{extendpostlude}
2628 % By default, |\extendpostlude| prints the song's copyright and licensing
2629 % information as a single paragraph using \mac{songcopyright} and
2630 % \mac{songlicense}.
2631 % The following definition changes it to also print the words
2632 % ``Used with permission'' at the end of every song's footer information:
2633 %
2634 % \begin{codeblock}
2635 % |\renewcommand{\extendpostlude}{|
2636 % | |\mac{songcopyright}|\ |\mac{songlicense}|\unskip|
2637 % | \ Used with permission.|
2638 % |}|
2639 % \end{codeblock}
2640 %
2641 % In general, any macro documented in \S\ref{sec:songinfo} can be used
2642 % in |\extendprelude| and |\extendpostlude| to print song information, such
2643 % as \mac{songauthors}, \mac{songrefs}, \mac{songcopyright}, and
2644 % \mac{songlicense}.
2645 % For convenience, the \mac{showauthors} and \mac{showrefs} macros display
2646 % author and scripture reference information as a pre-formatted paragraph
2647 % the way it appears in the default song header blocks.
2648 %
2649 % See \S\ref{sec:newkey} for how to define new \mac{beginsong} keyvals and
2650 % use them in |\extendprelude|.
2651 %
2652 % \DescMacro{makeprelude}
2653 % \DescMacro{makepostlude}
2654 % For complete control over the appearance of the header and footer material
2655 % that precedes and concludes each song, you can redefine the macros
2656 % |\makeprelude| and |\makepostlude|.
2657 % When typesetting a song, the \Songs{} package code invokes both of these
2658 % macros once (after processing all the material between the \mac{beginsong}
2659 % and \mac{endsong} lines), placing the results within vboxes.
2660 % The resulting vboxes are placed atop and below the song content.
2661 % By default, |\makeprelude| displays the song's titles, authors, and scripture
2662 % references to the right of a shaded box containing the song's number; and
2663 % |\makepostlude| displays the song's copyright and licensing information in
2664 % fine print.
2665 %
2666 % As a simple example, the following causes each song to start with its
2667 % number and title(s), centered, in a large, boldface font, and then centers
2668 % the rest of the prelude material (e.g., references and authors) below that
2669 % (using \mac{extendprelude}).
2670 %
2671 % \begin{codeblock}
2672 % |\renewcommand\makeprelude{%|
2673 % | |\mac{resettitles}
2674 % | \centering|
2675 % | {\Large\bfseries|\mac{thesongnum}|. |\mac{songtitle}|\par|
2676 % | |\mac{nexttitle}\mac{foreachtitle}|{(|\mac{songtitle}|)\par}}%|
2677 % | |\mac{extendprelude}
2678 % |}|
2679 % \end{codeblock}
2680 %
2681 % \paragraph{Page- and Column-breaking.}
2682 % \DescMacro{vvpenalty}
2683 % \DescMacro{ccpenalty}
2684 % \DescMacro{vcpenalty}
2685 % \DescMacro{cvpenalty}
2686 % \DescMacro{brkpenalty}
2687 % Page-breaking and column-breaking within songs that are too large to fit
2688 % in a single column/page is influenced by the values of several penalties.
2689 % Penalties of value |\interlinepenalty| are inserted between consecutive
2690 % lines of each verse and chorus;
2691 % penalties of value |\vvpenalty|, |\ccpenalty|, |\vcpenalty|, and |\cvpenalty|
2692 % are inserted into each song between consecutive verses, between consecutive
2693 % choruses, after a verse followed by a chorus, and after a chorus followed by
2694 % a verse, respectively;
2695 % and penalties of value |\brkpenalty| are inserted wherever \mac{brk} is
2696 % used on a line by itself.
2697 % The higher the penalty, the less likely \TeX{} is to place a
2698 % page- or column-break at that site.
2699 % If any are set to $-10000$ or lower, breaks are forced there.
2700 % By default, |\interlinepenalty| is set to 1000 and the rest are set to 200
2701 % so that breaks between verses and choruses are preferred over breaks within
2702 % choruses and verses, but are not forced.
2703 %
2704 % \DescMacro{sepverses}
2705 % Saying |\sepverses| sets all of the above penalties to $-10000$ except for
2706 % |\ccpenalty| which is set to 100.
2707 % This is useful in \env{slides} mode because it forces each verse and
2708 % chorus to be typeset on a separate slide, except for consecutive choruses,
2709 % which remain together when possible.
2710 % (This default reflects an expectation that consecutive choruses typically
2711 % consist of a pre-chorus and chorus that are always sung together.)
2712 %
2713 % These defaults can be changed by changing the relevant penalty register
2714 % directly.
2715 % For example, to force a page- or column-break between consecutive choruses,
2716 % type
2717 %
2718 % \begin{codeblock}
2719 % |\ccpenalty=-10000|
2720 % \end{codeblock}
2721 %
2722 % \paragraph{Text Justification.}
2723 % \DescMacro{versejustify}
2724 % \DescMacro{chorusjustify}
2725 % \DescMacro{justifyleft}
2726 % \DescMacro{justifycenter}
2727 % To left-justify or center the lines of verses or choruses, redefine
2728 % |\versejustify| or |\chorusjustify| to |\justifyleft| or |\justifycenter|,
2729 % respectively.
2730 % For example, to cause choruses to be centered, one could type:
2731 %
2732 % \begin{codeblock}
2733 % |\renewcommand{|\mac{chorusjustify}|}{\justifycenter}|
2734 % \end{codeblock}
2735 %
2736 % \DescMacro{notejustify}
2737 % Justification of textual notes too long to fit on a single line
2738 % is controlled by the |\notejustify| macro.
2739 % By default, it sets up an environment that fully justifies the note
2740 % (i.e., all but the last line of each paragraph extends all the way from
2741 % the left to the right margin).
2742 % \ImplOrDesc
2743 % {Authors interested in changing this behavior should consult
2744 % \S\ref{sec:impparams} of the implementation section for more
2745 % information about this macro.}
2746 % {For more information, recompile this documentation with the
2747 % implementation section included.}
2748 %
2749 % \DescMacro{placenote}
2750 % A textual note that is shorter than a single line is placed flush-left by
2751 % default, or is centered when in slides mode.
2752 % This placement of textual notes is controlled by |\placenote|.
2753 % \ImplOrDesc
2754 % {Authors interested in changing this behavior should consult
2755 % \S\ref{sec:impparams} of the implementation section for more
2756 % information about this macro.}
2757 % {For more information, recompile this documentation with the
2758 % implementation section included.}
2759 %
2760 % \subsection{Scripture Appearance}
2761 %
2762 % \DescMacro{scripturefont}
2763 % By default, scripture quotations are typeset in Zaph Chancery font
2764 % with the document-default point size (|\normalsize|).
2765 % You can change these defaults by redefining |\scripturefont|.
2766 % For example, to cause scripture quotations to be typeset in sans serif
2767 % italics, define:
2768 %
2769 % \begin{codeblock}
2770 % |\renewcommand{\scripturefont}{\sffamily\it}|
2771 % \end{codeblock}
2772 %
2773 % \DescMacro{printscrcite}
2774 % By default, the citation at the end of a scripture quotation is
2775 % typeset in sans serif font at the document-default point size
2776 % (|\normalsize|).
2777 % You can customize the appearance of the citation by redefining
2778 % |\printscrcite|, which accepts the citation text as its argument.
2779 % For example, to cause citations to be printed in roman italics font, define:
2780 %
2781 % \begin{codeblock}
2782 % |\renewcommand{\printscrcite}[1]{\rmfamily\it#1}|
2783 % \end{codeblock}
2784 %
2785 % \subsection{Conditional Blocks}\label{sec:conditionals}
2786 %
2787 % Conditional macros allow certain material to be included in some books but
2788 % not others.
2789 % For example, a musician's chord book might include extra verses with
2790 % alternate chordings.
2791 %
2792 % \DescMacroGroup{if}{if...}{ifchorded,iflyric,ifslides,ifpartiallist,ifsongindexes,ifmeasures,ifrawtext,iftranscapos,ifnolyrics,ifpagepreludes,ifvnumbered}
2793 % A conditional block begins with a macro named |\if|\Meta{type}, where
2794 % \Meta{type} is one of the types listed in the first column of
2795 % Table~\ref{tab:conditionals}.
2796 % \begin{table}
2797 % \newcommand\tablerule{\noalign{\hrule}}
2798 % \newlength\oldbaselineskip \oldbaselineskip\baselineskip
2799 % \newlength\oldlineskip \oldlineskip\lineskip
2800 % \newdimen\oldlineskiplimit \oldlineskiplimit\lineskiplimit
2801 % \newcommand\oninterlineskip{%
2802 % \baselineskip\oldbaselineskip
2803 % \lineskip\oldlineskip
2804 % \lineskiplimit\oldlineskiplimit}
2805 % \vbox{\offinterlineskip\hrule
2806 % \halign{&\vrule#&\strut\quad#\hfil\quad&\vrule#&\quad\vtop{\oninterlineskip\hsize3.5in\leftskip0.25in\parindent-0.25in\indent\vrule height\ht\strutbox width0pt depth0pt#\vrule height0pt width0pt depth\dp\strutbox\par}\quad\cr
2807 % height2pt&\omit&&\omit&\cr
2808 % &\hfil{\large\strut Type}&&\hfil{\large\strut Processed only if\kern1pt$\ldots$}&\cr\tablerule
2809 % height2pt&\omit&&\omit&\cr
2810 % &|chorded|&&the \env{chorded} option is active&\cr\tablerule
2811 % &|lyric|&&the \env{chorded} option is not active&\cr\tablerule
2812 % &|slides|&&the \env{slides} option is active&\cr\tablerule
2813 % &|partiallist|&&the \mac{includeonlysongs} macro is being used to extract
2814 % a partial list of songs&\cr\tablerule
2815 % &|songindexes|&&the \env{noindexes} option is not active&\cr\tablerule
2816 % &|measures|&&the \env{nomeasures} option is not active&\cr\tablerule
2817 % &|rawtext|&&the \env{rawtext} option is active&\cr\tablerule
2818 % &|transcapos|&&the \env{transposecapos} option is active&\cr\tablerule
2819 % &|nolyrics|&&the \mac{nolyrics} macro is in effect&\cr\tablerule
2820 % &|pagepreludes|&&the \mac{pagepreludes} macro is in effect&\cr\tablerule
2821 % &|vnumbered|&&the current verse is numbered (i.e., it was started
2822 % with \mac{beginverse} instead of \mac{beginverse}|*|)&\cr}
2823 % \hrule}
2824 % \caption{Conditional macros}\label{tab:conditionals}
2825 % \end{table}
2826 % The conditional block concludes with the macro |\fi|.
2827 % Between the |\if|\Meta{type} and the |\fi| may also appear an |\else|.
2828 % For example, in the construction
2829 %
2830 % \begin{codeblock}
2831 % |\ifchorded|
2832 % \quad\Meta{A}
2833 % |\else|
2834 % \quad\Meta{B}
2835 % |\fi|
2836 % \end{codeblock}
2837 %
2838 % \noindent
2839 % material \Meta{A} is only included if the \env{chorded} option is active,
2840 % and material \Meta{B} is only included if the \env{chorded} option is not
2841 % active.
2842 %
2843 % \subsection{Page Layout}\label{sec:layout}
2844 %
2845 % \DescMacro{songcolumns}
2846 % The number of columns per page can be set with |\songcolumns|.
2847 % For example, to create 3 columns per page, write
2848 %
2849 % \begin{codeblock}
2850 % |\songcolumns{3}|
2851 % \end{codeblock}
2852 %
2853 % \noindent
2854 % The number of columns should only be changed outside of \env{songs}
2855 % environments.
2856 %
2857 % Setting the number of columns to zero disables the page-building algorithm
2858 % entirely.
2859 % This can be useful if you want to use an external package, such as
2860 % |multicol| or \LaTeX's built-in |\twocolumn| macro, to build pages.
2861 % For example, the following sets up an environment that is suitable for
2862 % a lyric book that uses |\twocolumn|:
2863 %
2864 % \begin{codeblock}
2865 % |\songcolumns{0}|
2866 % |\flushbottom|
2867 % |\twocolumn[\LARGE\centering My Songs]|
2868 % |\begin{|\env{songs}|}{}|
2869 % $\vdots$
2870 % |\end{|\env{songs}|}|
2871 % \end{codeblock}
2872 %
2873 % \noindent
2874 % When disabling the page-builder, please note the following potential
2875 % issues:
2876 %
2877 % \begin{itemize}
2878 % \item The \mac{repchoruses} feature does not work when the page-builder
2879 % is disabled because the page-builder is responsible for inserting
2880 % repeated choruses as new columns are formed.
2881 % \item External page-building packages tend to allow column- and
2882 % page-breaks within songs because they have no mechanism for moving an
2883 % entire song to the next column or page to avoid such a break
2884 % (see \mac{songpos} below).
2885 % \item Indexes produced with \mac{showindex} are typeset to the width of
2886 % the enclosing environment.
2887 % Thus, you should be sure to reset \LaTeX{} back to one column (via
2888 % |\onecolumn|) before executing \mac{showindex}.
2889 % \end{itemize}
2890 %
2891 % \DescMacro{pagepreludes}
2892 % Song preludes (i.e., the material atop each song, including the title) are
2893 % typeset by default at column width.
2894 % Writing |\pagepreludes| typesets subsequent preludes at page width atop
2895 % fresh pages, with the rest of the song in multiple columns beneath its title.
2896 % (To prohibit separation of songs from their preludes, it also sets
2897 % \mac{songpos} to 0.)
2898 %
2899 % \DescMacro{columnsep}
2900 % The horizontal distance between consecutive columns is controlled by
2901 % the |\columnsep| dimension.
2902 % For example, to separate columns by 1 centimeter of space, write
2903 %
2904 % \begin{codeblock}
2905 % |\columnsep=1cm|
2906 % \end{codeblock}
2907 %
2908 % \DescMacro{colbotglue}
2909 % When \LaTeX{} ends each column it inserts glue equal to |\colbotglue|.
2910 % In lyric books this macro is set to |0pt| so that each column ends flush with
2911 % the bottom of the page.
2912 % In other books that have ragged bottoms, it is set to stretchable
2913 % glue so that columns end at whatever vertical position is convenient.
2914 % The recommended setting for typsetting columns with ragged bottoms is:
2915 %
2916 % \begin{codeblock}
2917 % |\renewcommand{\colbotglue}{0pt plus .5\textheight minus 0pt}|
2918 % \end{codeblock}
2919 %
2920 % \DescMacro{lastcolglue}
2921 % The last column in a \env{songs} environment gets |\lastcolglue| appended
2922 % to it instead.
2923 % By default it is infinitely stretchable so that the last column ends
2924 % at its natural height.
2925 % By setting it to |0pt|, you can force the last column to be flush with
2926 % the bottom of the page:
2927 %
2928 % \begin{codeblock}
2929 % |\renewcommand{\lastcolglue}{0pt}|
2930 % \end{codeblock}
2931 %
2932 % \DescMacro{songpos}
2933 % The \Songs{} package uses a song-positioning algorithm that
2934 % moves songs to the next column or page in order to avoid column- or
2935 % page-breaks within songs.
2936 % The algorithm has four levels of aggressiveness, numbered from 0 to 3.
2937 % You can change the aggressiveness level by typing
2938 %
2939 % \begin{codeblock}
2940 % |\songpos{|\Meta{level}|}|
2941 % \end{codeblock}
2942 %
2943 % \noindent
2944 % The default level is 3, which avoids column-breaks, page-breaks,
2945 % and page-turns within songs whenever possible.
2946 % (Page-turns are page-breaks after odd-numbered pages in two-sided documents,
2947 % or after all pages in one-sided documents.)
2948 % Level 2 avoids page-breaks and page-turns but allows column-breaks within
2949 % songs.
2950 % Level 1 avoids only page-turns within songs.
2951 % Level 0 turns off the song-positioning algorithm entirely.
2952 % This causes songs to be positioned wherever \TeX{} thinks is best
2953 % based on penalty settings (see \mac{vvpenalty} and \mac{spenalty}).
2954 %
2955 % \DescMacro{spenalty}
2956 % The value of |\spenalty| controls the undesirability of column breaks
2957 % at song boundaries.
2958 % Usually it should be set to a value between 0 and \mac{vvpenalty} so that
2959 % breaks between songs are preferable to breaks between verses within a song.
2960 % By default it is set to 100.
2961 % When it is $-10000$ or less, breaks between songs are required, so that
2962 % each song always begins a fresh column.
2963 %
2964 % \subsection{Indexes}\label{sec:idxcust}
2965 %
2966 % \subsubsection{Index Appearance}
2967 %
2968 % \paragraph{Index Titles.}
2969 % To customize the appearance of index titles, redefine the \mac{songsection}
2970 % and/or \mac{songchapter} macros from \S\ref{sec:sectioning}.
2971 % For example, to use \LaTeX's built-in |\section| and |\chapter| macros
2972 % instead, you could write:
2973 %
2974 % \begin{codeblock}
2975 % |\renewcommand{|\mac{songchapter}|}{\chapter}|
2976 % |\renewcommand{|\mac{songsection}|}{\section}|
2977 % \end{codeblock}
2978 %
2979 % \paragraph{Layout and page divisions.}
2980 % \DescMacro{sepindexestrue}
2981 % \DescMacro{sepindexesfalse}
2982 % Indexes are by default typeset on separate pages, and when an index is
2983 % sufficiently small, it is centered on the page in one column.
2984 % To disable these defaults, write |\sepindexesfalse|.
2985 % This causes indexes to avoid using unnecessary vertical space or
2986 % starting unnecessary new pages.
2987 % To re-enable the defaults, use |\sepindexestrue|.
2988 %
2989 % \DescMacro{idxheadwidth}
2990 % The |\idxheadwidth| length defines the width of the shaded boxes that
2991 % begin each alphabetic block of a large title index.
2992 % Setting it to 0pt suppresses the boxes entirely.
2993 % For example, to set the width of those boxes to 1 centimeter, you could
2994 % define
2995 %
2996 % \begin{codeblock}
2997 % |\setlength{\idxheadwidth}{1cm}|
2998 % \end{codeblock}
2999 %
3000 % \paragraph{Fonts and colors.}
3001 % \DescMacro{idxrefsfont}
3002 % To control the formatting of the list of references on the right-hand side
3003 % of index entries, redefine |\idxrefsfont|.
3004 % For example, to typeset each list in boldface, write
3005 %
3006 % \begin{codeblock}
3007 % |\renewcommand{\idxrefsfont}{\bfseries}|
3008 % \end{codeblock}
3009 %
3010 % \DescMacro{idxtitlefont}
3011 % \DescMacro{idxlyricfont}
3012 % Title indexes contain entries for song titles and also entries for notable
3013 % lines of lyrics.
3014 % The fonts for these entries are controlled by |\idxtitlefont| and
3015 % |\idxlyricfont|, respectively.
3016 % For example, to show title entries in boldface sans-serif and lyric entries
3017 % in regular roman font, one could define:
3018 %
3019 % \begin{codeblock}
3020 % |\renewcommand{\idxtitlefont}{\sffamily\bfseries}|
3021 % |\renewcommand{\idxlyricfont}{\rmfamily\mdseries}|
3022 % \end{codeblock}
3023 %
3024 % \DescMacro{idxheadfont}
3025 % To change the font used to typeset the capital letters that start each
3026 % alphabetic section of a large title index, redefine |\idxheadfont|.
3027 % For example, to typeset those letters in italics instead of boldface, type
3028 %
3029 % \begin{codeblock}
3030 % |\renewcommand{\idxheadfont}{\sffamily\it\LARGE}|
3031 % \end{codeblock}
3032 %
3033 % \DescMacro{idxbgcolor}
3034 % To change the background color of the shaded boxes that contain the
3035 % capital letters that start each alphabetic sectino of a large title
3036 % index, redefine |\idxbgcolor|.
3037 % For example:
3038 %
3039 % \begin{codeblock}
3040 % |\renewcommand{\idxbgcolor}{red}|
3041 % \end{codeblock}
3042 %
3043 % \DescMacro{idxauthfont}
3044 % The font used to typeset entries of an author index is controlled by
3045 % |\idxauthfont|.
3046 % For example, to typeset such entries in italics instead of boldface, type
3047 %
3048 % \begin{codeblock}
3049 % |\renewcommand{\idxauthfont}{\small\it}|
3050 % \end{codeblock}
3051 %
3052 % \DescMacro{idxscripfont}
3053 % The font used to typeset entries of a scripture index is controlled by
3054 % |\idxscripfont|.
3055 % For example, to typeset such entries in boldface instead of italics, type
3056 %
3057 % \begin{codeblock}
3058 % |\renewcommand{\idxscripfont}{\sffamily\small\bfseries}|
3059 % \end{codeblock}
3060 %
3061 % \DescMacro{idxbook}
3062 % To control the formatting of the lines that start each new book of the
3063 % bible in a scripture index, redefine |\idxbook|, which accepts the book
3064 % name as its single argument.
3065 % For example, to typeset each book name in a box, one could define
3066 %
3067 % \begin{codeblock}
3068 % |\renewcommand{\idxbook}[1]{\framebox{\small\bfseries#1}}|
3069 % \end{codeblock}
3070 %
3071 % \DescMacro{idxcont}
3072 % In a scripture index, when a column break separates a block of entries
3073 % devoted to a book of the bible, the new column is titled
3074 % ``\Meta{bookname} (continued)'' by default.
3075 % You can change this default by redefining the |\idxcont| macro, which
3076 % receives the \Meta{bookname} as its single argument.
3077 % For example, to typeset an index in German, one might define
3078 %
3079 % \begin{codeblock}
3080 % |\renewcommand{\idxcont}[1]{\small\textbf{#1} (fortgefahren)}|
3081 % \end{codeblock}
3082 %
3083 % \subsubsection{Entry References}
3084 %
3085 % \DescMacro{indexsongsas}
3086 % By default, the right-hand side of each index entry contains a list of
3087 % one or more song numbers.
3088 % To instead list page numbers, use the |\indexsongsas| macro:
3089 %
3090 % \begin{codeblock}
3091 % |\indexsongsas{|\Meta{id}|}{\thepage}|
3092 % \end{codeblock}
3093 %
3094 % \noindent
3095 % where \Meta{id} is the same identifier used in the \mac{newindex},
3096 % \mac{newauthorindex}, or \mac{newscripindex} macro that created the index.
3097 % The second argument must always be something that expands into raw text
3098 % without any formatting, since this text gets output to auxiliary files that
3099 % are lexographically sorted by the index-generation program.
3100 % To go back to indexing songs by song number, use \mac{thesongnum} in place
3101 % of |\thepage| in the above.
3102 %
3103 % \subsubsection{PDF Bookmarks and Links}
3104 %
3105 % \DescMacro{songtarget}
3106 % \DescMacro{songlink}
3107 % Each \mac{beginsong} environment adds a PDF bookmark (if generating a PDF)
3108 % and hyperlink target (if using the |hyperref| package) for the
3109 % song by invoking |\songtarget| with two arguments:
3110 % (1) a suggested PDF bookmark level, and (2) a link target name.
3111 % Links in indexes to these targets are created by |\songlink|, which
3112 % also gets two arguments:
3113 % (1) the link target name (same as the second argument to \mac{songtarget}),
3114 % and (2) the text to be linked.
3115 %
3116 % Redefine these macros to customize or suppress these bookmarks, targets,
3117 % and links.
3118 % For example, to enable both bookmarks and links (the default behavior) use:
3119 %
3120 % \begin{codeblock}
3121 % |\renewcommand{\songtarget}[2]|
3122 % | {\pdfbookmark[#1]{|\mac{thesongnum}|. |\mac{songtitle}|}{#2}}|
3123 % |\renewcommand{\songlink}[2]{\hyperlink{#1}{#2}}|
3124 % \end{codeblock}
3125 %
3126 % \noindent
3127 % To enable links but not bookmarks, use:
3128 %
3129 % \begin{codeblock}
3130 % |\renewcommand{\songtarget}[2]{\hypertarget{#2}{\relax}}|
3131 % |\renewcommand{\songlink}[2]{\hyperlink{#1}{#2}}|
3132 % \end{codeblock}
3133 %
3134 % \noindent
3135 % To disable both bookmarks and links, use:
3136 %
3137 % \begin{codeblock}
3138 % |\renewcommand{\songtarget}[2]{}|
3139 % |\renewcommand{\songlink}[2]{#2}|
3140 % \end{codeblock}
3141 %
3142 % \subsubsection{Sort Order}
3143 %
3144 % The alphabetic ordering of entries in title and author indexes is dictated
3145 % by the computer system on which the \Songs{} software is installed.
3146 % Different languages and regions have different sorting conventions, so the
3147 % |songidx| Lua script delegates decisions about order to your operating system.
3148 % If the default ordering proves inadequate, you can modify it by changing your
3149 % operating system's \emph{locale} (see your system's local help files).
3150 % Alternatively, you can explicitly tell the |songidx| program which locale to
3151 % use in one of three ways:
3152 %
3153 % \begin{itemize}
3154 % \item \emph{Windows:}
3155 % Edit the |generate.bat| file in the |Sample| folder (or your working folder)
3156 % with any plain text editor (e.g., Vim or Notepad).
3157 % Near the top, find the line that says |SET locale=|.
3158 % After the |=|, type any valid locale name.
3159 % For a list of valid locale names on Windows, please see the ``Language name
3160 % abbreviation'' column of Microsoft's online National Language Support (NLS)
3161 % API Reference:
3162 %
3163 % {\centering\url{http://msdn.microsoft.com/en-us/goglobal/bb896001.aspx}\par}
3164 %
3165 % \item \emph{Unix:}
3166 % Create an environment variable named |SONGIDX_LOCALE| and set it equal to
3167 % the desired locale name.
3168 % The command |locale -a| lists all valid locale names on most Unix systems.
3169 %
3170 % \item \emph{Command-line:}
3171 % If you are executing the |songidx| script manually, use the |-l| option to
3172 % specify the locale:
3173 %
3174 % \begin{codeblock}
3175 % |texlua songidx -l sv_SE myindex.sxd myindex.sbx|
3176 % \end{codeblock}
3177 %
3178 % \end{itemize}
3179 %
3180 % \subsubsection{Special Words In Song Info}
3181 %
3182 % The following macros control how certain keywords are treated when parsing
3183 % and sorting index entries.
3184 % They only affect indexes that have already been declared, so put them
3185 % strictly after all your index creation commands (see \S\ref{sec:indexes}).
3186 %
3187 % \DescMacro{titleprefixword}
3188 % In English, when a title begins with ``The'' or ``A'', it is traditional to
3189 % move these words to the end of the title and sort the entry by the following
3190 % word.
3191 % So for example, ``The Song Title'' is typically indexed as
3192 % ``Song Title, The''.
3193 % To change this default behavior, you can use |\titleprefixword| in the
3194 % document preamble to identify each word to be moved to the end whenever
3195 % it appears as the first word of a title index entry.
3196 % For example, to cause the word ``I'' to be moved to the end of title index
3197 % entries, one could say,
3198 %
3199 % \begin{codeblock}
3200 % |\titleprefixword{I}|
3201 % \end{codeblock}
3202 %
3203 % \noindent
3204 % The first use of |\titleprefixword| overrides the defaults, so if you also
3205 % want to continue to move ``The'' and ``A'' to the end of entries, you must
3206 % also say |\titleprefixword{The}| and |\titleprefixword{A}| explicitly.
3207 % This macro may only be used in the document preamble but may be used
3208 % multiple times to declare multiple prefix words.
3209 %
3210 % \DescMacro{authsepword}
3211 % When parsing author index entries, the word ``and'' is recognized by the
3212 % |songidx| script as a conjunctive that separates author names.
3213 % To override this default and specify a different conjunctive, use the
3214 % |\authsepword| macro one or more times in the document preamble.
3215 % For example, to instead treat ``und'' as a conjunctive, you could say,
3216 %
3217 % \begin{codeblock}
3218 % |\authsepword{und}|
3219 % \end{codeblock}
3220 %
3221 % \noindent
3222 % The first use of |\authsepword| and each of the following macros overrides
3223 % the default, so if you also want to continue to treat ``and'' as a
3224 % conjunctive, you must also say |\authsepword{and}| explicitly.
3225 %
3226 % \DescMacro{authbyword}
3227 % When parsing author index entries, the word ``by'' is recognized as a
3228 % keyword signaling that the index entry should only include material
3229 % in the current list item that follows the word ``by''.
3230 % So for example, ``Music by J.S. Bach'' is indexed as ``Bach, J.S.''
3231 % rather than ``Bach, Music by J.S.''
3232 % To recognize a different word instead of ``by'', you can use |\authbyword|
3233 % in the document preamble.
3234 % For example, to recognize ``durch'' instead, you could say
3235 %
3236 % \begin{codeblock}
3237 % |\authbyword{durch}|
3238 % \end{codeblock}
3239 %
3240 % \DescMacro{authignoreword}
3241 % When parsing author index entries, if a list item contains the word
3242 % ``unknown'', that item is ignored and is not indexed.
3243 % This prevents items like ``Composer unknown'' from being indexed as names.
3244 % To cause the indexer to recognize and ignore a different word, you can
3245 % use the |\authignoreword| macro in the document preamble.
3246 % For example, to ignore author index entries containing the word
3247 % ``unbekannt'', you could say,
3248 %
3249 % \begin{codeblock}
3250 % |\authignoreword{unbekannt}|
3251 % \end{codeblock}
3252 %
3253 % \subsection{Page Headers and Footers}
3254 %
3255 % In \LaTeX, page headers and footers are defined using a system of
3256 % invisible \emph{marks} that get inserted into the document at the
3257 % beginning of each logical unit of the document (e.g., each section, song,
3258 % verse, and chorus).
3259 % The headers and footers are then defined so as to refer to the first
3260 % and/or last invisible mark that ends up on each page once the document
3261 % is divided into pages.
3262 % This section describes the marks made available by the \Songs{} package.
3263 % For more detailed information about the marks already provided by
3264 % \LaTeX{} and how to use them, consult any \LaTeX{} user manual.
3265 %
3266 % \DescMacro{songmark}
3267 % \DescMacro{versemark}
3268 % \DescMacro{chorusmark}
3269 % To add song information to page headings and footers, redefine |\songmark|,
3270 % |\versemark|, or |\chorusmark| to add the necessary \TeX{} marks to the
3271 % current page whenever a new song, verse, or chorus begins.
3272 % These macros expect no arguments; to access the current song's
3273 % information including titles, use the macros documented in
3274 % \S\ref{sec:songinfo}.
3275 % To access the current song's number or the current verse's number, use
3276 % \mac{thesongnum} or \mac{theversenum} (see \S\ref{sec:numbering}).
3277 % For example, to include the song number in the page headings produced by
3278 % \LaTeX's |\pagestyle{myheadings}| feature, you could redefine |\songmark|
3279 % as follows:
3280 %
3281 % \begin{codeblock}
3282 % |\renewcommand{\songmark}{\markboth{|\mac{thesongnum}|}{|\mac{thesongnum}|}}|
3283 % \end{codeblock}
3284 %
3285 % \subsection{Defining New Beginsong Keyvals}\label{sec:newkey}
3286 %
3287 % \DescMacro{newsongkey}
3288 % The \mac{beginsong} macro supports several optional keyval parameters for
3289 % declaring song information, including \env{by=}, \env{sr=}, and \env{cr=}.
3290 % Users can define their own additional keyvals as well.
3291 % To do so, use the |\newsongkey| macro, which has the syntax
3292 %
3293 % \begin{codeblock}
3294 % |\newsongkey{|\Meta{keyname}|}{|\Meta{initcode}|}[|\Meta{default}|]{|\Meta{setcode}|}|
3295 % \end{codeblock}
3296 %
3297 % \noindent
3298 % Here, \Meta{keyname} is the name of the new key for the keyval,
3299 % \Meta{initcode} is \LaTeX{} code that is executed at the start of each
3300 % \mac{beginsong} line before the \mac{beginsong} arguments are processed,
3301 % \Meta{default} (if specified) is the default value used for the keyval when
3302 % \Meta{keyname} appears in \mac{beginsong} without a value,
3303 % and \Meta{setcode} is macro code that is executed whenever
3304 % \Meta{key} is parsed as part of the \mac{beginsong} keyval arguments.
3305 % In \Meta{setcode}, |#1| expands to the value given by the user for the
3306 % keyval (or to \Meta{default} if no value was given).
3307 %
3308 % For example, to define a new song key called |arr| which stores its
3309 % value in a macro called |\arranger|, one could write:
3310 %
3311 % \begin{codeblock}
3312 % |\newcommand{\arranger}{}|
3313 % |\newsongkey{arr}{\def\arranger{}}|
3314 % | {\def\arranger{Arranged by #1\par}}|
3315 % \end{codeblock}
3316 %
3317 % \noindent
3318 % Then one could redefine \mac{extendprelude} to print the arranger below the
3319 % other song header information:
3320 %
3321 % \begin{codeblock}
3322 % |\renewcommand{\extendprelude}{|
3323 % | |\mac{showrefs}\mac{showauthors}
3324 % | {\bfseries\arranger}|
3325 % |}|
3326 % \end{codeblock}
3327 %
3328 % \noindent
3329 % A \mac{beginsong} line could then specify the song's arranger as follows:
3330 %
3331 % \begin{codeblock}
3332 % \mac{beginsong}|{The Title}[arr={R. Ranger}]|
3333 % $\vdots$
3334 % \mac{endsong}
3335 % \end{codeblock}
3336 %
3337 % \noindent This produces
3338 %
3339 % \begin{sample}
3340 % \setcounter{songnum}{1}%
3341 % \vskip1pt%
3342 % \newcommand\arranger{}%
3343 % \newsongkey{arr}{\def\arranger{}}%
3344 % {\def\arranger{Arranged by #1\par}}%
3345 % \renewcommand{\extendprelude}{
3346 % \showrefs\showauthors
3347 % {\bfseries\arranger}
3348 % }%
3349 % \beginsong{The Title}[arr={R. Ranger}]
3350 % \endsong
3351 % \renewcommand{\extendprelude}{}%
3352 % \end{sample}
3353 %
3354 % For more detailed information about keyvals and how they work, consult the
3355 % documentation for David Carlisle's |keyval| package, which comes standard
3356 % with most \LaTeXe{} installations.
3357 %
3358 % \subsection{Font Kerning Corrections}
3359 %
3360 % \paragraph{Chord Overstriking.}
3361 % In order to conserve space and keep songs readable, the \Songs{} package
3362 % pushes chords down very close to the lyrics with which they are paired.
3363 % Unfortunately, this can sometimes cause low-hanging characters in chord
3364 % names to overstrike the lyrics they sit above.
3365 % For example,
3366 %
3367 % \example|\[(Gsus4/D)]Overstrike|\produces{\[(Gsus4/D)]Overstrike}
3368 % \eat\]
3369 %
3370 % \noindent
3371 % Note that the parentheses and slash symbols in the chord name have
3372 % invaded the lyric that sits beneath them.
3373 %
3374 % \DescMacro{chordlocals}
3375 % The best solution to this problem is to use a font for chord names that
3376 % minimizes low-hanging symbols; but if you lack such a font, then the
3377 % following trick works pretty well.
3378 % Somewhere in the preamble of your document, you can write the following
3379 % \LaTeX{} code:
3380 %
3381 % \begin{codeblock}
3382 % |\renewcommand{\chordlocals}{\catcode`(\active|
3383 % | \catcode`)\active|
3384 % | \catcode`/\active}|
3385 % |\newcommand{\smraise}[1]{\raise2pt\hbox{\small#1}}|
3386 % |\newcommand{\myslash}{\smraise/}|
3387 % |\newcommand{\myopenparen}{\smraise(|\eat)|}|
3388 % |\newcommand{\mycloseparen}{\smraise)}|
3389 % |{\chordlocals|
3390 % | \global\let(\myopenparen|
3391 % | \global\let)\mycloseparen|
3392 % | \global\let/\myslash}|
3393 % \end{codeblock}
3394 %
3395 % \noindent
3396 % This sets the |/|, |(|, and |)| symbols as active characters whenever they
3397 % appear within chord names.
3398 % \ImplOrDesc
3399 % {(See \S\ref{sec:chordlocals} for documentation of the
3400 % \texttt{\string\chordlocals} hook.)}
3401 % {(Recompile this documentation to include the implementation section
3402 % for more information about the \texttt{\string\chordlocals} macro.)}
3403 % Each active character is defined so that it produces a smaller, raised
3404 % version of the original symbol.
3405 % The result is as follows:
3406 %
3407 % \renewcommand{\chordlocals}{\catcode`(\active
3408 % \catcode`)\active
3409 % \catcode`/\active}
3410 % \newcommand{\smraise}[1]{\raise2pt\hbox{\small#1}}
3411 % \newcommand{\myslash}{\smraise/}
3412 % \newcommand{\myopenparen}{\smraise(}
3413 % \newcommand{\mycloseparen}{\smraise)}
3414 % {\chordlocals
3415 % \global\let(\myopenparen
3416 % \global\let)\mycloseparen
3417 % \global\let/\myslash}
3418 %
3419 % \example|\[(Gsus4/D)]Overstrike (fixed)|\produces{\[(Gsus4/D)]Overstrike (fixed)}
3420 % \eat\]
3421 %
3422 % \renewcommand\chordlocals{}
3423 %
3424 % \noindent
3425 % As you can see, the low-hanging symbols have been elevated so that they
3426 % sit above the baseline, correcting the overstrike problem.
3427 %
3428 % \paragraph{Scripture Font Quotation Marks.}
3429 % \DescMacro{shiftdblquotes}
3430 % The \Songs{} package compensates for a kerning problem in the Zaph Chancery
3431 % font (used to typeset scripture quotations) by redefining the |``| and |''|
3432 % token sequences to be active characters that yield double-quotes shifted
3433 % 1.1 points and 2 points left, respectively, of their normal positions.
3434 % If you use a different font size for scripture quotations, then you can use
3435 % the |\shiftdblquotes| macro when redefining \mac{scripturefont} to change
3436 % this kerning correction.
3437 % For example,
3438 %
3439 % \begin{codeblock}
3440 % |\renewcommand{|\mac{scripturefont}|}{|
3441 % | \usefont{OT1}{pzc}{mb}{it}|
3442 % | \shiftdblquotes{-1pt}{-2pt}{-3pt}{-4pt}|
3443 % |}|
3444 % \end{codeblock}
3445 %
3446 % \noindent
3447 % removes 1 point of space to the left and 2 points of space to the
3448 % right of left-double-quote characters, and 3 points to the left and 4 points
3449 % to the right of right-double-quotes, within scripture quotations.
3450 %
3451 % \section{Informational Macros}\label{sec:songinfo}
3452 %
3453 % The macros described in this section can be used to retrieve information
3454 % about the current song.
3455 % This can be used when redefining \mac{extendprelude}, \mac{extendpostlude},
3456 % \mac{makeprelude}, \mac{makepostlude}, \mac{songmark}, \mac{versemark}, or
3457 % \mac{chorusmark}, or any other macros that might typeset this information.
3458 %
3459 % \DescMacro{songauthors}
3460 % To get the current song's list of authors (if any) use |\songauthors|.
3461 % This yields the value of the \env{by=} key used in the \mac{beginsong}
3462 % line.
3463 %
3464 % \DescMacro{songrefs}
3465 % To get the current song's list of scripture references (if any) use
3466 % |\songrefs|.
3467 % This yields the value of the \env{sr=} key used in the \mac{beginsong}
3468 % line, but modified with hyphens changed to en-dashes and spaces falling
3469 % within a list of verse numbers changed to thin spaces for better
3470 % typesetting.
3471 % In addition, various penalties have been added to inhibit line breaks
3472 % in strange places and encourage line breaks in others.
3473 %
3474 % \DescMacro{songcopyright}
3475 % To get the current song's copyright info (if any), use |\songcopyright|.
3476 % This yields the value of the \env{cr=} key used in the \mac{beginsong} line.
3477 %
3478 % \DescMacro{songlicense}
3479 % To get the current song's licensing information (if any), use
3480 % |\songlicense|.
3481 % This yields the value of the \env{li=} key used in the \mac{beginsong}
3482 % line, or whatever text was declared with \mac{setlicense}.
3483 %
3484 % \DescMacro{songtitle}
3485 % The |\songtitle| macro yields the current song's title.
3486 % By default this is the first title provided in the \mac{beginsong} line.
3487 % The \mac{nexttitle} and \mac{foreachtitle} macros (see below) cause it
3488 % to be set to the current song's other titles, if any.
3489 %
3490 % \DescMacro{resettitles}
3491 % To get the current song's primary title (i.e., the first title specified
3492 % in the song's \mac{beginsong} line), execute |\resettitles|.
3493 % This sets the |\songtitle| macro to be the song's primary title.
3494 %
3495 % \DescMacro{nexttitle}
3496 % To get the song's next title, execute |\nexttitle|, which
3497 % sets |\songtitle| to be the next title in the song's list of titles
3498 % (or sets |\songtitle| to |\relax| if there are no more titles).
3499 %
3500 % \DescMacro{foreachtitle}
3501 % The |\foreachtitle| macro accepts \LaTeX{} code as its single
3502 % argument and executes it once for each (remaining) song title.
3503 % Within the provided code, use |\songtitle| to get the current title.
3504 % For example, the following code generates a comma-separated list of all
3505 % of the current song's titles:
3506 %
3507 % \begin{codeblock}
3508 % \mac{resettitles}
3509 % \mac{songtitle}
3510 % \mac{nexttitle}
3511 % |\foreachtitle{, |\mac{songtitle}|}|
3512 % \end{codeblock}
3513 %
3514 % \DescMacro{songlist}
3515 % When \mac{includeonlysongs} is used to extract a partial list of songs, the
3516 % |\songlist| macro expands to the comma-separated list of songs that is being
3517 % extracted.
3518 % Redefining |\songlist| within the document preamble alters the list of
3519 % songs to be extracted.
3520 % Redefining it after the preamble may have unpredictable results.
3521 %
3522 % \section{Other Resources}
3523 %
3524 % There are a number of other \LaTeX{} packages available for typesetting
3525 % songs, tablature diagrams, or song books.
3526 % Probably the best of these is the \Rath{} package by Christopher Rath
3527 % (\href{http://rath.ca/Misc/Songbook/}{{\tt http://rath.ca/Misc/Songbook/}}).
3528 % Most of the differences between other packages and this one are intentional;
3529 % the following is a summary of where I've adopted various differing design
3530 % decisions and why.
3531 %
3532 % \bigskip
3533 %
3534 % \paragraph{Ease of Song Entry.}
3535 % Much of the \Songs{} package programming is devoted to easing the burden of
3536 % typing chords.
3537 % With most \LaTeX{} song book packages the user types chords using a standard
3538 % \LaTeX{} macro syntax like |\chord{|\Meta{chord}|}{|\Meta{lyric}|}|.
3539 % The \Songs{} package uses a less conventional
3540 % |\[|\Meta{chord}|]|\Meta{lyric}\eat\] syntax for several
3541 % reasons detailed below.
3542 %
3543 % First, macros in the standard \LaTeX{} syntax require more key-presses
3544 % than macros in the \Songs{} package's syntax.
3545 % This can become become very taxing when typing up a large book.
3546 % Chords often appear as frequently as one per syllable, especially in hymns,
3547 % so keeping the syntax as brief as possible is desirable.
3548 %
3549 % Second, the standard \LaTeX{} macro syntax requires the user to estimate how
3550 % much of the \Meta{lyric} will lie below the chord (because the \Meta{lyric}
3551 % part must be enclosed in braces) whereas the \Songs{} package's syntax does
3552 % not.
3553 % Estimating this accurately can be quite difficult, since in many cases the
3554 % \Meta{lyric} part must include punctuation or multiple words to get proper
3555 % results.
3556 % The \Songs{} package automates this for the user, significantly easing the
3557 % task of chord-entry.
3558 %
3559 % Third, unlike the standard \LaTeX{} chord syntax, the \Songs{} package's
3560 % syntax handles all hyphenation of chorded lyrics fully automatically.
3561 % Extra hyphenation must be introduced in chord books wherever a chord
3562 % is wider than the syllable it sits above.
3563 % With the standard \LaTeX{} chord syntax such hyphenation must be
3564 % introduced manually by the user (usually via a special hyphenation macro),
3565 % but the \Songs{} package does this automatically.
3566 %
3567 % Fourth and finally, some other packages allow the user to use ``|b|''
3568 % in a \Meta{chord} to produce a flat symbol, whereas the \Songs{} package
3569 % requires an ``|&|'' instead.
3570 % Using ``|b|'' is more intuitive but prevents the
3571 % use of ``|b|'' for any other purpose within a \Meta{chord}, such as to
3572 % produce a literal ``b'' or to type another macro name like |\hbox| that
3573 % contains a ``b''.
3574 % Consequently, the \Songs{} package uses the less obvious ``|&|'' symbol to
3575 % produce flat symbols.
3576 %
3577 % \paragraph{Song Structure.}
3578 % The \Songs{} package provides a relatively small number of macros for
3579 % typesetting high-level song structure, including verses, choruses,
3580 % textual comments, and conditional macros that indicate that certain sections
3581 % should go in chord books but not lyric books.
3582 % These can be combined to typeset more sophisticated structures such as
3583 % intros, bridges, brackets, endings, and the like.
3584 % This is done in lieu of providing a specific macro for each of these
3585 % structures since it results in greater flexibility and fewer macros for
3586 % users to learn.
3587 %
3588 % \paragraph{Multiple columns.}
3589 % The \Songs{} package was designed from the ground up to produce song books
3590 % with many songs per page, arranged in multiple columns.
3591 % As a result, it includes elaborate support for many features not found in
3592 % most other packages, such as automatic column balancing, completely
3593 % customizable song header and song footer blocks, and facilities for adding
3594 % beautiful scripture quotations to fill in gaps between songs.
3595 %
3596 % \paragraph{Indexes.}
3597 % Another major feature of the \Songs{} package is its support for a variety
3598 % of different index types, most notably indexes arranged by scripture
3599 % reference.
3600 % Scripture indexes can be invaluable for planning services around particular
3601 % sermons or topics.
3602 % The \Songs{} package allows book authors to specify the names and preferred
3603 % ordering of books of the bible, and automatically handles complex issues
3604 % like overlapping verse ranges to produce an easy-to-read, compact, and
3605 % well-ordered index.
3606 % Other supported indexes include those sorted by author, by title, and by
3607 % notable lines of lyrics.
3608 %
3609 % \paragraph{Automatic Transposition.}
3610 % The \Songs{} package has a facility for automatically transposing songs, and
3611 % even generating chord books that print the chords in multiple keys (e.g., so
3612 % that a pianist and guitarist using a capo can play together from the same
3613 % book).
3614 %
3615 % \bigskip
3616 %
3617 % The \Songs{} package was developed entirely independently of all other
3618 % \LaTeX{} song book packages.
3619 % I originally developed the set of \LaTeX{} macros that eventually became
3620 % the \Songs{} package in order to typeset a song book for the Graduate
3621 % Christian Fellowship (GCF) at Cornell University, and the Cornell
3622 % International Christian Fellowship (CICF).
3623 % Once I had fine-tuned my package to be sufficiently versatile, I decided
3624 % to release it for public use.
3625 % At that time I noticed the \Rath{} package and others, and wrote this
3626 % summary of the most prominent differences.
3627 %
3628 % For information on more song-typesetting resources for \LaTeX, I recommend
3629 % consulting the documentation provided with the \Rath{} package.
3630 % It includes an excellent list of other resources that might be of interest
3631 % to creators of song books.
3632 %
3633 % \section{GNU General Public License}\label{sec:license}
3634 %
3635 % \begingroup\small
3636 %
3637 % \begin{center}
3638 % {\large\sc Terms and Conditions For \\ Copying, Distribution and Modification}
3639 % \end{center}
3640 %
3641 % \begin{enumerate}\addtocounter{enumi}{-1}
3642 %
3643 % \item
3644 %
3645 % This License applies to any program or other work which contains a notice
3646 % placed by the copyright holder saying it may be distributed under the
3647 % terms of this General Public License. The ``Program'', below, refers to
3648 % any such program or work, and a ``work based on the Program'' means either
3649 % the Program or any derivative work under copyright law: that is to say, a
3650 % work containing the Program or a portion of it, either verbatim or with
3651 % modifications and/or translated into another language. (Hereinafter,
3652 % translation is included without limitation in the term ``modification''.)
3653 % Each licensee is addressed as ``you''.
3654 %
3655 % Activities other than copying, distribution and modification are not
3656 % covered by this License; they are outside its scope. The act of
3657 % running the Program is not restricted, and the output from the Program
3658 % is covered only if its contents constitute a work based on the
3659 % Program (independent of having been made by running the Program).
3660 % Whether that is true depends on what the Program does.
3661 %
3662 % \item You may copy and distribute verbatim copies of the Program's source
3663 % code as you receive it, in any medium, provided that you conspicuously
3664 % and appropriately publish on each copy an appropriate copyright notice
3665 % and disclaimer of warranty; keep intact all the notices that refer to
3666 % this License and to the absence of any warranty; and give any other
3667 % recipients of the Program a copy of this License along with the Program.
3668 %
3669 % You may charge a fee for the physical act of transferring a copy, and you
3670 % may at your option offer warranty protection in exchange for a fee.
3671 %
3672 % \item
3673 %
3674 % You may modify your copy or copies of the Program or any portion
3675 % of it, thus forming a work based on the Program, and copy and
3676 % distribute such modifications or work under the terms of Section~1
3677 % above, provided that you also meet all of these conditions:
3678 %
3679 % \begin{enumerate}
3680 %
3681 % \item
3682 %
3683 % You must cause the modified files to carry prominent notices stating that
3684 % you changed the files and the date of any change.
3685 %
3686 % \item
3687 %
3688 % You must cause any work that you distribute or publish, that in
3689 % whole or in part contains or is derived from the Program or any
3690 % part thereof, to be licensed as a whole at no charge to all third
3691 % parties under the terms of this License.
3692 %
3693 % \item
3694 % If the modified program normally reads commands interactively
3695 % when run, you must cause it, when started running for such
3696 % interactive use in the most ordinary way, to print or display an
3697 % announcement including an appropriate copyright notice and a
3698 % notice that there is no warranty (or else, saying that you provide
3699 % a warranty) and that users may redistribute the program under
3700 % these conditions, and telling the user how to view a copy of this
3701 % License. (Exception: if the Program itself is interactive but
3702 % does not normally print such an announcement, your work based on
3703 % the Program is not required to print an announcement.)
3704 %
3705 % \end{enumerate}
3706 %
3707 % These requirements apply to the modified work as a whole. If
3708 % identifiable sections of that work are not derived from the Program,
3709 % and can be reasonably considered independent and separate works in
3710 % themselves, then this License, and its terms, do not apply to those
3711 % sections when you distribute them as separate works. But when you
3712 % distribute the same sections as part of a whole which is a work based
3713 % on the Program, the distribution of the whole must be on the terms of
3714 % this License, whose permissions for other licensees extend to the
3715 % entire whole, and thus to each and every part regardless of who wrote it.
3716 %
3717 % Thus, it is not the intent of this section to claim rights or contest
3718 % your rights to work written entirely by you; rather, the intent is to
3719 % exercise the right to control the distribution of derivative or
3720 % collective works based on the Program.
3721 %
3722 % In addition, mere aggregation of another work not based on the Program
3723 % with the Program (or with a work based on the Program) on a volume of
3724 % a storage or distribution medium does not bring the other work under
3725 % the scope of this License.
3726 %
3727 % \item
3728 % You may copy and distribute the Program (or a work based on it,
3729 % under Section~2) in object code or executable form under the terms of
3730 % Sections~1 and~2 above provided that you also do one of the following:
3731 %
3732 % \begin{enumerate}
3733 %
3734 % \item
3735 %
3736 % Accompany it with the complete corresponding machine-readable
3737 % source code, which must be distributed under the terms of Sections~1
3738 % and~2 above on a medium customarily used for software interchange; or,
3739 %
3740 % \item
3741 %
3742 % Accompany it with a written offer, valid for at least three
3743 % years, to give any third party, for a charge no more than your
3744 % cost of physically performing source distribution, a complete
3745 % machine-readable copy of the corresponding source code, to be
3746 % distributed under the terms of Sections~1 and~2 above on a medium
3747 % customarily used for software interchange; or,
3748 %
3749 % \item
3750 %
3751 % Accompany it with the information you received as to the offer
3752 % to distribute corresponding source code. (This alternative is
3753 % allowed only for noncommercial distribution and only if you
3754 % received the program in object code or executable form with such
3755 % an offer, in accord with Subsection~b above.)
3756 %
3757 % \end{enumerate}
3758 %
3759 % The source code for a work means the preferred form of the work for
3760 % making modifications to it. For an executable work, complete source
3761 % code means all the source code for all modules it contains, plus any
3762 % associated interface definition files, plus the scripts used to
3763 % control compilation and installation of the executable. However, as a
3764 % special exception, the source code distributed need not include
3765 % anything that is normally distributed (in either source or binary
3766 % form) with the major components (compiler, kernel, and so on) of the
3767 % operating system on which the executable runs, unless that component
3768 % itself accompanies the executable.
3769 %
3770 % If distribution of executable or object code is made by offering
3771 % access to copy from a designated place, then offering equivalent
3772 % access to copy the source code from the same place counts as
3773 % distribution of the source code, even though third parties are not
3774 % compelled to copy the source along with the object code.
3775 %
3776 % \item
3777 % You may not copy, modify, sublicense, or distribute the Program
3778 % except as expressly provided under this License. Any attempt
3779 % otherwise to copy, modify, sublicense or distribute the Program is
3780 % void, and will automatically terminate your rights under this License.
3781 % However, parties who have received copies, or rights, from you under
3782 % this License will not have their licenses terminated so long as such
3783 % parties remain in full compliance.
3784 %
3785 % \item
3786 % You are not required to accept this License, since you have not
3787 % signed it. However, nothing else grants you permission to modify or
3788 % distribute the Program or its derivative works. These actions are
3789 % prohibited by law if you do not accept this License. Therefore, by
3790 % modifying or distributing the Program (or any work based on the
3791 % Program), you indicate your acceptance of this License to do so, and
3792 % all its terms and conditions for copying, distributing or modifying
3793 % the Program or works based on it.
3794 %
3795 % \item
3796 % Each time you redistribute the Program (or any work based on the
3797 % Program), the recipient automatically receives a license from the
3798 % original licensor to copy, distribute or modify the Program subject to
3799 % these terms and conditions. You may not impose any further
3800 % restrictions on the recipients' exercise of the rights granted herein.
3801 % You are not responsible for enforcing compliance by third parties to
3802 % this License.
3803 %
3804 % \item
3805 % If, as a consequence of a court judgment or allegation of patent
3806 % infringement or for any other reason (not limited to patent issues),
3807 % conditions are imposed on you (whether by court order, agreement or
3808 % otherwise) that contradict the conditions of this License, they do not
3809 % excuse you from the conditions of this License. If you cannot
3810 % distribute so as to satisfy simultaneously your obligations under this
3811 % License and any other pertinent obligations, then as a consequence you
3812 % may not distribute the Program at all. For example, if a patent
3813 % license would not permit royalty-free redistribution of the Program by
3814 % all those who receive copies directly or indirectly through you, then
3815 % the only way you could satisfy both it and this License would be to
3816 % refrain entirely from distribution of the Program.
3817 %
3818 % If any portion of this section is held invalid or unenforceable under
3819 % any particular circumstance, the balance of the section is intended to
3820 % apply and the section as a whole is intended to apply in other
3821 % circumstances.
3822 %
3823 % It is not the purpose of this section to induce you to infringe any
3824 % patents or other property right claims or to contest validity of any
3825 % such claims; this section has the sole purpose of protecting the
3826 % integrity of the free software distribution system, which is
3827 % implemented by public license practices. Many people have made
3828 % generous contributions to the wide range of software distributed
3829 % through that system in reliance on consistent application of that
3830 % system; it is up to the author/donor to decide if he or she is willing
3831 % to distribute software through any other system and a licensee cannot
3832 % impose that choice.
3833 %
3834 % This section is intended to make thoroughly clear what is believed to
3835 % be a consequence of the rest of this License.
3836 %
3837 % \item
3838 % If the distribution and/or use of the Program is restricted in
3839 % certain countries either by patents or by copyrighted interfaces, the
3840 % original copyright holder who places the Program under this License
3841 % may add an explicit geographical distribution limitation excluding
3842 % those countries, so that distribution is permitted only in or among
3843 % countries not thus excluded. In such case, this License incorporates
3844 % the limitation as if written in the body of this License.
3845 %
3846 % \item
3847 % The Free Software Foundation may publish revised and/or new versions
3848 % of the General Public License from time to time. Such new versions will
3849 % be similar in spirit to the present version, but may differ in detail to
3850 % address new problems or concerns.
3851 %
3852 % Each version is given a distinguishing version number. If the Program
3853 % specifies a version number of this License which applies to it and ``any
3854 % later version'', you have the option of following the terms and conditions
3855 % either of that version or of any later version published by the Free
3856 % Software Foundation. If the Program does not specify a version number of
3857 % this License, you may choose any version ever published by the Free Software
3858 % Foundation.
3859 %
3860 % \item
3861 % If you wish to incorporate parts of the Program into other free
3862 % programs whose distribution conditions are different, write to the author
3863 % to ask for permission. For software which is copyrighted by the Free
3864 % Software Foundation, write to the Free Software Foundation; we sometimes
3865 % make exceptions for this. Our decision will be guided by the two goals
3866 % of preserving the free status of all derivatives of our free software and
3867 % of promoting the sharing and reuse of software generally.
3868 %
3869 % \begin{center}
3870 % {\large\sc No Warranty}
3871 % \end{center}
3872 %
3873 % \item
3874 % {\sc Because the program is licensed free of charge, there is no warranty
3875 % for the program, to the extent permitted by applicable law. Except when
3876 % otherwise stated in writing the copyright holders and/or other parties
3877 % provide the program ``as is'' without warranty of any kind, either expressed
3878 % or implied, including, but not limited to, the implied warranties of
3879 % merchantability and fitness for a particular purpose. The entire risk as
3880 % to the quality and performance of the program is with you. Should the
3881 % program prove defective, you assume the cost of all necessary servicing,
3882 % repair or correction.}
3883 %
3884 % \item
3885 % {\sc In no event unless required by applicable law or agreed to in writing
3886 % will any copyright holder, or any other party who may modify and/or
3887 % redistribute the program as permitted above, be liable to you for damages,
3888 % including any general, special, incidental or consequential damages arising
3889 % out of the use or inability to use the program (including but not limited
3890 % to loss of data or data being rendered inaccurate or losses sustained by
3891 % you or third parties or a failure of the program to operate with any other
3892 % programs), even if such holder or other party has been advised of the
3893 % possibility of such damages.}
3894 %
3895 % \end{enumerate}
3896 %
3897 % \endgroup
3898 %
3899 % \StopEventually{\PrintIndex}
3900 %
3901 % \clearpage
3902 % \section{Implementation}
3903 %
3904 % The following provides the verbatim implementation of the \Songs{} \LaTeX{}
3905 % package, along with commentary on how it works.
3906 % In general, macro names that contain a |@| symbol are not intended to be
3907 % directly accessible by the outside world; they are for purely internal use.
3908 % All other macros are intended to be used or redefined by document authors.
3909 %
3910 % Most of the macros likely to be of real interest to song book authors can
3911 % be found in \S\ref{sec:impparams}.
3912 % To find the implementation of any particular macro, the index at the end
3913 % of this document should prove helpful.
3914 %
3915 % The unwary \TeX er may wonder at the rather large size of the
3916 % implementation.
3917 % The volume and complexity of the code stems mainly from the following
3918 % challenging features:
3919 % \begin{itemize}
3920 % \item Putting chords above lyrics fully automatically requires building an
3921 % entire lyric-parser in \LaTeX{} (see \S\ref{sec:lyricscan}).
3922 % \item Avoiding page-turns within songs without prohibiting column-breaks
3923 % requires building a completely new page-breaking algorithm
3924 % (see \S\ref{sec:pagebuilder}).
3925 % \item The package must be able to generate a daunting number of document
3926 % variants from a common source: lyric-only books, chorded books, digital
3927 % slides, transparency slides, selected song subsets, transposed songs, and
3928 % combinations of the above.
3929 % This is like putting six or more packages into one.
3930 % \item Song book indexes are far more complex than those for a prose book.
3931 % See \S\ref{sec:indexgen} for some of the difficulties involved.
3932 % \end{itemize}
3933 %
3934 % \subsection{Initialization}
3935 %
3936 % The code in this section detects any \TeX{} versioning or configuration
3937 % settings that are relevant to the rest of the song book code.
3938 %
3939 % \begin{macro}{\ifSB@etex}
3940 % Numerous enhancements are possible when using an $\varepsilon$-\TeX{}
3941 % compatible version of \LaTeX.
3942 % We start by checking to see whether $\varepsilon$-\TeX{} primitives are
3943 % available.
3944 % \begin{macrocode}
3945 \newif\ifSB@etex
3946 \ifx\eTeXversion\undefined\else
3947 \ifx\eTeXversion\relax\else
3948 \SB@etextrue
3949 \ifx\e@alloc\@undefined
3950 \IfFileExists{etex.sty}{\RequirePackage{etex}}{}
3951 \fi
3952 \fi
3953 \fi
3954 % \end{macrocode}
3955 % \end{macro}
3956 %
3957 % \begin{macro}{\ifSB@pdf}
3958 % Detect whether we're generating a pdf file, since this affects the
3959 % treatment of hyperlinks and bookmark indexes.
3960 % \begin{macrocode}
3961 \newif\ifSB@pdf\SB@pdffalse
3962 \IfFileExists{ifpdf.sty}{\RequirePackage{ifpdf}\ifpdf\SB@pdftrue\fi}{
3963 \ifx\pdfoutput\undefined\else
3964 \ifx\pdfoutput\relax\else
3965 \ifnum\pdfoutput<\@ne\else
3966 \SB@pdftrue
3967 \fi
3968 \fi
3969 \fi
3970 }
3971 % \end{macrocode}
3972 % \end{macro}
3973 %
3974 % \begin{macro}{\ifSB@preamble}
3975 % Some macros have different effects depending on when they're used in the
3976 % preamble or in the document body, so we need a conditional that remembers
3977 % whether we're still in the preamble.
3978 % It gets initialized to true and later changed to false once the body begins.
3979 % \begin{macrocode}
3980 \newif\ifSB@preamble
3981 \SB@preambletrue
3982 % \end{macrocode}
3983 % \end{macro}
3984 %
3985 % \begin{macro}{\ifSB@test}
3986 % \begin{macro}{\ifSB@testii}
3987 % \begin{macro}{\SB@temp}
3988 % \begin{macro}{\SB@tempii}
3989 % \begin{macro}{\SB@tempiii}
3990 % \begin{macro}{\SB@tempiv}
3991 % \begin{macro}{\SB@tempv}
3992 % Reserve some control sequence names for scratch use.
3993 % \begin{macrocode}
3994 \newif\ifSB@test
3995 \newif\ifSB@testii
3996 \newcommand\SB@temp{}
3997 \newcommand\SB@tempii{}
3998 \newcommand\SB@tempiii{}
3999 \newcommand\SB@tempiv{}
4000 \newcommand\SB@tempv{}
4001 % \end{macrocode}
4002 % \end{macro}
4003 % \end{macro}
4004 % \end{macro}
4005 % \end{macro}
4006 % \end{macro}
4007 % \end{macro}
4008 % \end{macro}
4009 %
4010 % \begin{macro}{\SB@newcount}
4011 % \begin{macro}{\SB@newdimen}
4012 % \begin{macro}{\SB@newbox}
4013 % \begin{macro}{\SB@newtoks}
4014 % \begin{macro}{\SB@newwrite}
4015 % Create macros for safely allocating count, dimen, box, token, and write
4016 % registers with detection for name-clashes.
4017 % For some reason, the default allocation macros provided by the \LaTeX{}
4018 % kernel do not detect name-clashes(!), which means that packages that use them
4019 % might accidentally overwrite our registers, causing all sorts of problems.
4020 % But at least we can do our best to avoid overwriting their registers.
4021 % \begin{macrocode}
4022 \newcommand\SB@newcount[1]{\@ifdefinable#1{\newcount#1}}
4023 \newcommand\SB@newdimen[1]{\@ifdefinable#1{\newdimen#1}}
4024 \newcommand\SB@newbox[1]{\@ifdefinable#1{\newbox#1}}
4025 \newcommand\SB@newtoks[1]{\@ifdefinable#1{\newtoks#1}}
4026 \newcommand\SB@newwrite[1]{\@ifdefinable#1{\newwrite#1}}
4027 % \end{macrocode}
4028 % \end{macro}
4029 % \end{macro}
4030 % \end{macro}
4031 % \end{macro}
4032 % \end{macro}
4033 %
4034 % \begin{macro}{\SB@dimen}
4035 % \begin{macro}{\SB@dimenii}
4036 % \begin{macro}{\SB@dimeniii}
4037 % \begin{macro}{\SB@dimeniv}
4038 % \begin{macro}{\SB@box}
4039 % \begin{macro}{\SB@boxii}
4040 % \begin{macro}{\SB@boxiii}
4041 % \begin{macro}{\SB@toks}
4042 % \begin{macro}{\SB@cnt}
4043 % \begin{macro}{\SB@cntii}
4044 % \begin{macro}{\SB@skip}
4045 % Reserve some temp registers for various purposes.
4046 % \begin{macrocode}
4047 \SB@newdimen\SB@dimen
4048 \SB@newdimen\SB@dimenii
4049 \SB@newdimen\SB@dimeniii
4050 \SB@newdimen\SB@dimeniv
4051 \SB@newbox\SB@box
4052 \SB@newbox\SB@boxii
4053 \SB@newbox\SB@boxiii
4054 \SB@newtoks\SB@toks
4055 \SB@newcount\SB@cnt
4056 \SB@newcount\SB@cntii
4057 \newlength\SB@skip
4058 % \end{macrocode}
4059 % \end{macro}
4060 % \end{macro}
4061 % \end{macro}
4062 % \end{macro}
4063 % \end{macro}
4064 % \end{macro}
4065 % \end{macro}
4066 % \end{macro}
4067 % \end{macro}
4068 % \end{macro}
4069 % \end{macro}
4070 %
4071 % \begin{macro}{\SB@envbox}
4072 % Also reserve a slightly less volatile box register for per-environment use.
4073 % In scripture environments it holds the scripture citation.
4074 % In indexes it holds the index title text.
4075 % \begin{macrocode}
4076 \SB@newbox\SB@envbox
4077 % \end{macrocode}
4078 % \end{macro}
4079 %
4080 % Load David Carlisle's |keyval| package for processing
4081 % \Meta{key}=\Meta{value} style macro arguments.
4082 % \begin{macrocode}
4083 \RequirePackage{keyval}
4084 % \end{macrocode}
4085 %
4086 % \begin{macro}{\SB@app}
4087 % Utility macro: Append some text to the definition of another macro.
4088 % \begin{macrocode}
4089 \newcommand\SB@app[3]{%
4090 \expandafter#1\expandafter#2\expandafter{#2#3}%
4091 }
4092 % \end{macrocode}
4093 % \end{macro}
4094 %
4095 % \subsection{Default Parameters}\label{sec:impparams}
4096 %
4097 % This section defines macros and lengths that will typically be executed or
4098 % redefined by the user in the document preamble to initialize the document.
4099 % (Not all of these are restricted to preamble usage, however. Many can be used
4100 % throughout the document to switch styles for different sections or different
4101 % songs.)
4102 %
4103 % \begin{macro}{\lyricfont}\MainImpl{lyricfont}
4104 % Define the font style to use for formatting song lyrics.
4105 % \begin{macrocode}
4106 \newcommand\lyricfont{\normalfont\normalsize}
4107 % \end{macrocode}
4108 % \end{macro}
4109 %
4110 % \begin{macro}{\stitlefont}\MainImpl{stitlefont}
4111 % Define the font style to use for formatting song titles.
4112 % \begin{macrocode}
4113 \newcommand\stitlefont{%
4114 \sffamily\ifslides\Huge\else\slshape\Large\fi%
4115 }
4116 % \end{macrocode}
4117 % \end{macro}
4118 %
4119 % \begin{macro}{\versefont}\MainImpl{versefont}
4120 % \begin{macro}{\chorusfont}\MainImpl{chorusfont}
4121 % \begin{macro}{\notefont}\MainImpl{notefont}
4122 % \begin{macro}{\meterfont}\MainImpl{meterfont}
4123 % \changes{v2.1}{2007/08/02}{Added}
4124 % By default, verses, choruses, and textual notes just allow the |\lyricfont|
4125 % style to continue.
4126 % Meter numbers are in tiny, sans-serif, upright font.
4127 % Echo parts toggle slanted and upright fonts.
4128 % \begin{macrocode}
4129 \newcommand\versefont{}
4130 \newcommand\chorusfont{}
4131 \newcommand\notefont{}
4132 \newcommand\meterfont{\tiny\sffamily\upshape}
4133 % \end{macrocode}
4134 % \end{macro}
4135 % \end{macro}
4136 % \end{macro}
4137 % \end{macro}
4138 %
4139 % \begin{macro}{\echofont}\MainImpl{echofont}
4140 % \changes{v2.18}{2014/06/28}{Added}
4141 % Echo parts toggle between oblique and upright shapes like |\emph|, but we
4142 % use |\slshape| instead of |\itshape| because it tends to look nicer with the
4143 % larger fonts used in slides mode.
4144 % \begin{macrocode}
4145 \newcommand\echofont{%
4146 \ifdim\fontdimen\@ne\font>\z@\upshape\else\slshape\fi%
4147 }
4148 % \end{macrocode}
4149 % \end{macro}
4150 %
4151 % \begin{macro}{\scripturefont}\MainImpl{scripturefont}
4152 % \changes{v1.13}{2005/05/12}{Added kerning correction for double-quote ligatures}
4153 % Define the font style to use for formatting scripture quotations
4154 % (defaults to Zapf Chancery).
4155 % \begin{macrocode}
4156 \newcommand\scripturefont{%
4157 \usefont{OT1}{pzc}{mb}{it}%
4158 \shiftdblquotes{-1.1\p@}\z@{-2\p@}\z@%
4159 }
4160 % \end{macrocode}
4161 % \end{macro}
4162 %
4163 % \begin{macro}{\printscrcite}\MainImpl{printscrcite}
4164 % Define the printing style for the citation at the end of a scripture
4165 % quotation.
4166 % \begin{macrocode}
4167 \newcommand\printscrcite[1]{\sffamily\small#1}
4168 % \end{macrocode}
4169 % \end{macro}
4170 %
4171 % \begin{macro}{\snumbgcolor}\MainImpl{snumbgcolor}
4172 % \begin{macro}{\notebgcolor}\MainImpl{notebgcolor}
4173 % \begin{macro}{\idxbgcolor}\MainImpl{idxbgcolor}
4174 % Define the background color used for shaded boxes containing
4175 % song numbers, textual notes, and index section headers, respectively.
4176 % To turn off all shading for a box type, use |\def|\Meta{macroname}|{}|.
4177 % \begin{macrocode}
4178 \newcommand\snumbgcolor{SongbookShade}
4179 \newcommand\notebgcolor{SongbookShade}
4180 \newcommand\idxbgcolor{SongbookShade}
4181 % \end{macrocode}
4182 % \end{macro}
4183 % \end{macro}
4184 % \end{macro}
4185 %
4186 % \begin{macro}{\versejustify}\MainImpl{versejustify}
4187 % \begin{macro}{\chorusjustify}\MainImpl{chorusjustify}
4188 % \changes{v2.1}{2007/08/02}{Added}
4189 % Verses and choruses are both left-justified with hanging indentation equal
4190 % to |\parindent|.
4191 % \begin{macrocode}
4192 \newcommand\versejustify{\justifyleft}
4193 \newcommand\chorusjustify{\justifyleft}
4194 % \end{macrocode}
4195 % \end{macro}
4196 % \end{macro}
4197 %
4198 % \begin{macro}{\notejustify}\MainImpl{notejustify}
4199 % \changes{v2.1}{2007/08/02}{Added}
4200 % Textual notes are fully justified when they are too long to fit in
4201 % a single line.
4202 % \begin{macrocode}
4203 \newcommand\notejustify{%
4204 \advance\baselineskip\p@\relax%
4205 \leftskip\z@skip\rightskip\z@skip%
4206 \parfillskip\@flushglue\parindent\z@%
4207 }
4208 % \end{macrocode}
4209 % \end{macro}
4210 %
4211 % \begin{macro}{\placenote}\MainImpl{placenote}
4212 % \changes{v2.1}{2007/08/02}{Added}
4213 % Textual notes are placed flush-left.
4214 % The single argument to this macro is horizontal material that comprises the
4215 % note.
4216 % Usually it will consist of various hboxes and specials that were produced
4217 % by |\colorbox|.
4218 % \begin{macrocode}
4219 \newcommand\placenote[1]{%
4220 \leftskip\z@skip\rightskip\@flushglue\SB@cbarshift%
4221 \noindent#1\par%
4222 }
4223 % \end{macrocode}
4224 % \end{macro}
4225 %
4226 % These counters define the current song number and verse number.
4227 % They can be redefined by the user at any time.
4228 % \begin{macrocode}
4229 \newcounter{songnum}
4230 \newcounter{versenum}
4231 % \end{macrocode}
4232 %
4233 % \begin{macro}{\thesongnum}\MainImpl{thesongnum}
4234 % \begin{macro}{\songnumstyle}
4235 % By default, the song numbering style will simply be an arabic number.
4236 % Redefine |\thesongnum| to change it.
4237 % (The |\songnumstyle| macro is obsolete and exists only for backward
4238 % compatibility.)
4239 % \begin{macrocode}
4240 \renewcommand\thesongnum{\songnumstyle{songnum}}
4241 \newcommand\songnumstyle{}
4242 \let\songnumstyle\arabic
4243 % \end{macrocode}
4244 % \end{macro}
4245 % \end{macro}
4246 %
4247 % \begin{macro}{\theversenum}\MainImpl{theversenum}
4248 % \begin{macro}{\versenumstyle}
4249 % By default, the verse numbering style will simply be an arabic number.
4250 % Redefine |\theversenum| to change it.
4251 % (The |\versenumstyle| macro is obsolete and exists only for backward
4252 % compatibility.)
4253 % \begin{macrocode}
4254 \renewcommand\theversenum{\versenumstyle{versenum}}
4255 \newcommand\versenumstyle{}
4256 \let\versenumstyle\arabic
4257 % \end{macrocode}
4258 % \end{macro}
4259 % \end{macro}
4260 %
4261 % \begin{macro}{\printsongnum}\MainImpl{printsongnum}
4262 % Define the printing style for the large, boxed song numbers starting each
4263 % song.
4264 % \begin{macrocode}
4265 \newcommand\printsongnum[1]{\sffamily\bfseries\LARGE#1}
4266 % \end{macrocode}
4267 % \end{macro}
4268 %
4269 % \begin{macro}{\printversenum}\MainImpl{printversenum}
4270 % Define the printing style for the verse numbers to the left of each verse.
4271 % \begin{macrocode}
4272 \newcommand\printversenum[1]{\lyricfont#1.\ }
4273 % \end{macrocode}
4274 % \end{macro}
4275 %
4276 % \begin{macro}{\placeversenum}\MainImpl{placeversenum}
4277 % \changes{v2.1}{2007/08/02}{Added}
4278 % Verse numbers are placed flush-left.
4279 % This is achieved by inserting horizontal glue that reverses both the
4280 % |\leftskip| and the |\parindent|.
4281 % The single argument to this macro is an hbox containing the verse number.
4282 % \begin{macrocode}
4283 \newcommand\placeversenum[1]{%
4284 \hskip-\leftskip\hskip-\parindent\relax%
4285 \box#1%
4286 }
4287 % \end{macrocode}
4288 % \end{macro}
4289 %
4290 % \begin{macro}{\everyverse}\MainImpl{everyverse}
4291 % \begin{macro}{\everychorus}\MainImpl{everychorus}
4292 % \changes{v2.1}{2007/08/02}{Added}
4293 % The following hooks allow users to insert material at the head of each
4294 % verse or chorus.
4295 % \begin{macrocode}
4296 \newcommand\everyverse{}
4297 \newcommand\everychorus{}
4298 % \end{macrocode}
4299 % \end{macro}
4300 % \end{macro}
4301 %
4302 % \begin{macro}{\printchord}\MainImpl{printchord}
4303 % Define the printing style for chords.
4304 % \begin{macrocode}
4305 \newcommand\printchord[1]{\sffamily\slshape\large#1}
4306 % \end{macrocode}
4307 % \end{macro}
4308 %
4309 % \begin{macro}{\chordlocals}\MainImpl{chordlocals}
4310 % \label{sec:chordlocals}
4311 % This hook is expanded at the start of the scoping group that surrounds
4312 % every chord name.
4313 % Thus, it can be used to set any catcodes or definitions that should be
4314 % local to chord names.
4315 % \begin{macrocode}
4316 \newcommand\chordlocals{}
4317 % \end{macrocode}
4318 % \end{macro}
4319 %
4320 % \begin{macro}{\versesep}\MainImpl{versesep}
4321 % Specify the vertical distance between song verses.
4322 % This gets set to a sentinel value by default; if the user doesn't redefine
4323 % it by the end of the document preamble, it gets redefined to something
4324 % sensible based on other settings.
4325 % \begin{macrocode}
4326 \newlength\versesep
4327 \versesep123456789sp\relax
4328 % \end{macrocode}
4329 % \end{macro}
4330 %
4331 % \begin{macro}{\afterpreludeskip}\MainImpl{afterpreludeskip}
4332 % \begin{macro}{\beforepostludeskip}\MainImpl{beforepostludeskip}
4333 % Users can specify the amount of vertical space that separates song prelude
4334 % and postlude material from the body of the song by adjusting the following
4335 % two macros.
4336 % \begin{macrocode}
4337 \newlength\afterpreludeskip
4338 \afterpreludeskip=2\p@\@plus4\p@
4339 \newlength\beforepostludeskip
4340 \beforepostludeskip=2\p@\@plus4\p@
4341 % \end{macrocode}
4342 % \end{macro}
4343 % \end{macro}
4344 %
4345 % \begin{macro}{\baselineadj}\MainImpl{baselineadj}
4346 % Define an adjustment factor for the vertical distance between consecutive
4347 % lyric baselines.
4348 % Setting this to zero accepts the default baseline distance computed by the
4349 % songs package.
4350 % \begin{macrocode}
4351 \newlength\baselineadj
4352 \baselineadj\z@skip
4353 % \end{macrocode}
4354 % \end{macro}
4355 %
4356 % \begin{macro}{\clineparams}\MainImpl{clineparams}
4357 % The spacing between chords and the lyrics below them can be adjusted
4358 % by changing the values of |\baselineskip|, |\lineskiplimit|, and
4359 % |\lineskip| within the following macro.
4360 % By default, |\baselineskip| is set to 2 points smaller than the height
4361 % of the current (lyric) font, and |\lineskiplimit| and |\lineskip| are
4362 % set so that chords intrude at most 2 points into the lyric below them.
4363 % This helps to keep chords tight with lyrics.
4364 % \begin{macrocode}
4365 \newcommand\clineparams{%
4366 \baselineskip\f@size\p@%
4367 \advance\baselineskip-2\p@%
4368 \lineskiplimit-2\p@%
4369 \lineskip-2\p@%
4370 }
4371 % \end{macrocode}
4372 % \end{macro}
4373 %
4374 % \begin{macro}{\parindent}
4375 % The |\parindent| length controls how far broken lyric lines are
4376 % indented from the left margin.
4377 % \begin{macrocode}
4378 \parindent.25in
4379 % \end{macrocode}
4380 % \end{macro}
4381 %
4382 % \begin{macro}{\idxheadwidth}\MainImpl{idxheadwidth}
4383 % Specify the width of the head-boxes in a large index.
4384 % \begin{macrocode}
4385 \newlength\idxheadwidth
4386 \setlength\idxheadwidth{1.5cm}
4387 % \end{macrocode}
4388 % \end{macro}
4389 %
4390 % \begin{macro}{\songnumwidth}\MainImpl{songnumwidth}
4391 % Set the width of the song number boxes that begin each song.
4392 % We guess a suitable width by typesetting the text ``999.''
4393 % \begin{macrocode}
4394 \newlength\songnumwidth
4395 \settowidth\songnumwidth{\printsongnum{999.}}
4396 % \end{macrocode}
4397 % \end{macro}
4398 %
4399 % \begin{macro}{\versenumwidth}\MainImpl{versenumwidth}
4400 % Set the width that is reserved for normal-sized verse numbers.
4401 % (Verse numbers wider than this will indent the first line of lyrics.)
4402 % \begin{macrocode}
4403 \newlength\versenumwidth
4404 \settowidth\versenumwidth{\printversenum{9\kern1em}}
4405 % \end{macrocode}
4406 % \end{macro}
4407 %
4408 % \begin{macro}{\cbarwidth}
4409 % This dictates the width of the vertical line placed to the left of
4410 % choruses.
4411 % Setting it to |0pt| eliminates the line entirely.
4412 % \begin{macrocode}
4413 \newlength\cbarwidth
4414 \setlength\cbarwidth\p@
4415 % \end{macrocode}
4416 % \end{macro}
4417 %
4418 % \begin{macro}{\sbarheight}
4419 % This dictates the height of the horizontal line placed between each pair
4420 % of songs.
4421 % Setting it to |0pt| eliminates the line entirely.
4422 % \begin{macrocode}
4423 \newlength\sbarheight
4424 \setlength\sbarheight\p@
4425 % \end{macrocode}
4426 % \end{macro}
4427 %
4428 % Column- and page-breaks should typically not occur within a verse or chorus
4429 % unless they are unavoidable.
4430 % Thus, we set the |\interlinepenalty| to a high number (1000).
4431 % \begin{macrocode}
4432 \interlinepenalty\@m
4433 % \end{macrocode}
4434 %
4435 % \begin{macro}{\vvpenalty}\MainImpl{vvpenalty}
4436 % \begin{macro}{\ccpenalty}\MainImpl{ccpenalty}
4437 % \begin{macro}{\vcpenalty}\MainImpl{vcpenalty}
4438 % \begin{macro}{\cvpenalty}\MainImpl{cvpenalty}
4439 % \begin{macro}{\brkpenalty}\MainImpl{brkpenalty}
4440 % \changes{v2.1}{2007/08/02}{Added.}
4441 % The following count registers define the line-breaking penalties inserted
4442 % between verses, between choruses, after a verse followed by a chorus, after
4443 % a chorus followed by a verse, and at |\brk| macros, respectively.
4444 %
4445 % The default value of 200 was chosen based on the following logic:
4446 % Chord books should not yield underfull vbox warnings no matter how short
4447 % their columns are.
4448 % However, we still want to put as much material in each column as possible
4449 % while avoiding intra-song column-breaks when they can be avoided.
4450 % Chorded mode therefore sets |\colbotglue| with glue whose stretchability
4451 % is half of the |\textheight|.
4452 % Such glue will stretch at most twice its stretchability, yielding a
4453 % badness of 800 in the worst case.
4454 % The default |\vbadness| setting starts issuing warnings at badness 1000,
4455 % so we set the penalties below to $1000-800=200$.
4456 % \begin{macrocode}
4457 \SB@newcount\vvpenalty\vvpenalty200
4458 \SB@newcount\ccpenalty\ccpenalty200
4459 \SB@newcount\vcpenalty\vcpenalty200
4460 \SB@newcount\cvpenalty\cvpenalty200
4461 \SB@newcount\brkpenalty\brkpenalty200
4462 % \end{macrocode}
4463 % \end{macro}
4464 % \end{macro}
4465 % \end{macro}
4466 % \end{macro}
4467 % \end{macro}
4468 %
4469 % \begin{macro}{\spenalty}\MainImpl{spenalty}
4470 % \changes{v2.1}{2007/08/02}{Added.}
4471 % The following penalty gets inserted between songs.
4472 % Setting it to a proper value is a somewhat delicate balancing act.
4473 % It should typically be something between 0 and the default penalties above,
4474 % so for now it defaults to 100.
4475 % To start each song on a fresh column/page, set it to $-10000$ or below.
4476 % \begin{macrocode}
4477 \SB@newcount\spenalty\spenalty100
4478 % \end{macrocode}
4479 % \end{macro}
4480 %
4481 % \begin{macro}{\songmark}\MainImpl{songmark}
4482 % \changes{v1.17}{2005/09/24}{Added.}
4483 % \begin{macro}{\versemark}\MainImpl{versemark}
4484 % \begin{macro}{\chorusmark}\MainImpl{chorusmark}
4485 % \changes{v2.1}{2007/08/02}{Added.}
4486 % The user can redefine the following macros to add \TeX{} marks for each
4487 % song, each verse, or each chorus.
4488 % Such marks are used by \LaTeX{} to define page headers and footers.
4489 % \begin{macrocode}
4490 \newcommand\songmark{}
4491 \newcommand\versemark{}
4492 \newcommand\chorusmark{}
4493 % \end{macrocode}
4494 % \end{macro}
4495 % \end{macro}
4496 % \end{macro}
4497 %
4498 % \begin{macro}{\extendprelude}\MainImpl{extendprelude}
4499 % \begin{macro}{\extendpostlude}\MainImpl{extendpostlude}
4500 % \changes{v2.0}{2007/06/18}{Added.}
4501 % To just add some fields to the existing |\makeprelude| or |\makepostlude|
4502 % without having to redefine them entirely, users can redefine
4503 % |\extendprelude| or |\extendpostlude|.
4504 % By default, the prelude has the scripture references followed by the
4505 % authors, and the postlude has the copyright info followed by the licensing
4506 % info.
4507 % \begin{macrocode}
4508 \newcommand\extendprelude{\showrefs\showauthors}
4509 \newcommand\extendpostlude{\songcopyright\ \songlicense\unskip}
4510 % \end{macrocode}
4511 % \end{macro}
4512 % \end{macro}
4513 %
4514 % \begin{macro}{\idxheadfont}\MainImpl{idxheadfont}
4515 % \changes{v2.8}{2009/02/22}{Added.}
4516 % Users can redefine |\idxheadfont| to affect the font in which each capital
4517 % letter that heads a section of a title index is rendered.
4518 % \begin{macrocode}
4519 \newcommand\idxheadfont{\sffamily\bfseries\LARGE}
4520 % \end{macrocode}
4521 % \end{macro}
4522 %
4523 % \begin{macro}{\idxtitlefont}\MainImpl{idxtitlefont}
4524 % \changes{v2.8}{2009/02/22}{Added.}
4525 % Users can redefine |\idxtitlefont| to affect the font in which song title
4526 % index entries are rendered.
4527 % \begin{macrocode}
4528 \newcommand\idxtitlefont{\sffamily\slshape}
4529 % \end{macrocode}
4530 % \end{macro}
4531 %
4532 % \begin{macro}{\idxlyricfont}\MainImpl{idxlyricfont}
4533 % \changes{v2.8}{2009/02/22}{Added.}
4534 % Users can redefine |\idxlyricfont| to affect the font in which notable lines
4535 % of lyrics are rendered in a title index.
4536 % \begin{macrocode}
4537 \newcommand\idxlyricfont{\rmfamily}
4538 % \end{macrocode}
4539 % \end{macro}
4540 %
4541 % \begin{macro}{\idxscripfont}\MainImpl{idxscripfont}
4542 % \changes{v2.8}{2009/02/22}{Added.}
4543 % Users can redefine |\idxscripfont| to affect the font in which scripture
4544 % references are rendered in a scripture index.
4545 % \begin{macrocode}
4546 \newcommand\idxscripfont{\sffamily\small\slshape}
4547 % \end{macrocode}
4548 % \end{macro}
4549 %
4550 % \begin{macro}{\idxauthfont}\MainImpl{idxauthfont}
4551 % \changes{v2.8}{2009/02/22}{Added.}
4552 % Users can redefine |\idxauthfont| to affect the font in which contributor
4553 % names are rendered in an author index.
4554 % \begin{macrocode}
4555 \newcommand\idxauthfont{\small\bfseries}
4556 % \end{macrocode}
4557 % \end{macro}
4558 %
4559 % \begin{macro}{\idxrefsfont}\MainImpl{idxrefsfont}
4560 % \changes{v2.8}{2009/02/22}{Added.}
4561 % Users can redefine |\idxrefsfont| to affect the font in which the list of
4562 % song references on the right-hand-side of an index entry is typeset.
4563 % \begin{macrocode}
4564 \newcommand\idxrefsfont{\normalfont\normalsize}
4565 % \end{macrocode}
4566 % \end{macro}
4567 %
4568 % \begin{macro}{\idxbook}\MainImpl{idxbook}
4569 % \changes{v2.8}{2009/02/22}{Added.}
4570 % Users can redefine |\idxbook| to dictate the book name header in a
4571 % scripture index that begins each book of the bible.
4572 % \begin{macrocode}
4573 \newcommand\idxbook[1]{\small\bfseries#1}
4574 % \end{macrocode}
4575 % \end{macro}
4576 %
4577 % \begin{macro}{\idxcont}\MainImpl{idxcont}
4578 % \changes{v2.0}{2007/06/18}{Added.}
4579 % Users can redefine |\idxcont| to dictate the column header in a scripture
4580 % index after a column break falls within a book of the bible.
4581 % \begin{macrocode}
4582 \newcommand\idxcont[1]{\small\textbf{#1} (continued)}
4583 % \end{macrocode}
4584 % \end{macro}
4585 %
4586 % \begin{macro}{\colbotglue}
4587 % Glue of size |\colbotglue| is inserted at the bottom of each column.
4588 % We use a macro instead of a glue register so that this can be redefined
4589 % in terms of variable quantities such as |\textheight|.
4590 % \begin{macrocode}
4591 \newcommand\colbotglue{}
4592 \let\colbotglue\z@skip
4593 % \end{macrocode}
4594 % \end{macro}
4595 %
4596 % \begin{macro}{\lastcolglue}
4597 % Glue of size |\lastcolglue| is inserted at the bottom of the last column.
4598 % \begin{macrocode}
4599 \newcommand\lastcolglue{}
4600 \let\lastcolglue\@flushglue
4601 % \end{macrocode}
4602 % \end{macro}
4603 %
4604 % \begin{macro}{\minfrets}
4605 % Define the minimum number of fret rows that should appear in tablature
4606 % diagrams.
4607 % \begin{macrocode}
4608 \SB@newcount\minfrets\minfrets4
4609 % \end{macrocode}
4610 % \end{macro}
4611 %
4612 % \begin{macro}{\SB@colwidth}
4613 % Define a length to store the computed width of each column in a
4614 % multi-column song page.
4615 % The user shouldn't set this one directly, but some users might want to
4616 % refer to it in calculations.
4617 % \begin{macrocode}
4618 \SB@newdimen\SB@colwidth
4619 % \end{macrocode}
4620 % \end{macro}
4621 %
4622 % \subsection{Package Options}
4623 %
4624 % This section defines code associated with the various option
4625 % settings that can be specified on the |\usepackage| line.
4626 % Many of these options can also be turned on or off subsequent to the
4627 % |\usepackage| line, so macros for doing that are also located here.
4628 % The options are not actually processed until \S\ref{sec:optproc} because
4629 % some of the macros defined here refer to macros that have not yet been
4630 % defined.
4631 %
4632 % \begin{option}{slides}\MainEnvImpl{slides}
4633 % \begin{macro}{\slides}\MainImpl{slides}
4634 % \optdef{off}
4635 % Turning this option on generates a book of overhead slides---one for each
4636 % song.
4637 % It really just amounts to changing various parameter settings.
4638 % Elsewhere in the code we also consult |\ifslides| to determine a few default
4639 % parameter settings and to use a different song preamble structure.
4640 % All the parameter changes below are local to the current scope; so to
4641 % undo slides mode, just put |\slides| within a group and end the group
4642 % wherever you want the slides settings to end.
4643 % \begin{macrocode}
4644 \DeclareOption{slides}{\slides}
4645 \newcommand\slides{%
4646 \slidestrue%
4647 \def\lyricfont{\normalfont\huge}%
4648 \def\chorusfont{\slshape}%
4649 \def\versejustify{\justifycenter}%
4650 \let\chorusjustify\versejustify
4651 \def\placenote##1{\justifycenter\noindent##1\par}%
4652 \scriptureoff%
4653 \onesongcolumn%
4654 \ifSB@preamble\ifSB@chordedspec\else\SB@chordsoff\fi\fi%
4655 \spenalty-\@M%
4656 \let\colbotglue\@flushglue%
4657 \setlength\cbarwidth\z@%
4658 \setlength\sbarheight\z@%
4659 }
4660 % \end{macrocode}
4661 % \end{macro}
4662 % \end{option}
4663 %
4664 % \begin{macro}{\justifyleft}
4665 % \changes{v2.1}{2007/08/02}{Added}
4666 % The |\justifyleft| macro sets up an environment in which lyrics are
4667 % left-justified with hanging indentation equal to |\parindent|.
4668 % It reserves spaces for verse numbers if used in a verse, and reserves
4669 % space for the vertical bar left of choruses if used in a chorus.
4670 % \begin{macrocode}
4671 \newcommand\justifyleft{%
4672 \leftskip\parindent%
4673 \ifSB@inverse\advance\leftskip\versenumwidth\fi%
4674 \SB@cbarshift%
4675 \parindent-\parindent%
4676 }
4677 % \end{macrocode}
4678 % \end{macro}
4679 %
4680 % \begin{macro}{\justifycenter}
4681 % \changes{v2.1}{2007/08/02}{Added}
4682 % The |\justifycenter| macro sets up an environment in which lyrics are
4683 % centered on each line.
4684 % Verse numbers continue to be placed flush-left, but |\placeversenum|
4685 % is temporarily redefined to keep the rest of the line containing a
4686 % verse number centered.
4687 % \begin{macrocode}
4688 \newcommand\justifycenter{%
4689 \centering\SB@cbarshift\rightskip\leftskip%
4690 \def\placeversenum##1{%
4691 \hskip-\leftskip\hskip-\parindent\relax%
4692 \hangindent-\wd##1\hangafter\m@ne%
4693 \box##1\hfil%
4694 }%
4695 }
4696 % \end{macrocode}
4697 % \end{macro}
4698 %
4699 % \begin{option}{unouter}\MainEnvImpl{unouter}
4700 % \begin{macro}{\SB@outer}
4701 % \optdef{off}
4702 % Several macros provided by the \Songs{} package are, by default, declared
4703 % |\outer| to aid in debugging.
4704 % However, unusual documents may need to use these macros within larger
4705 % constructs.
4706 % To do so, use the |unouter| option to prevent any of the macros supplied
4707 % by this package from being declared |\outer|.
4708 % \begin{macrocode}
4709 \newcommand\SB@outer{\outer}
4710 \DeclareOption{unouter}{\let\SB@outer\relax}
4711 % \end{macrocode}
4712 % \end{macro}
4713 % \end{option}
4714 %
4715 % \begin{option}{rawtext}\MainEnvImpl{rawtext}
4716 % \optdef{off}
4717 % Instead of generating a document, this dumps a text version of the song book
4718 % to a file. This option can only be set in the |\usepackage| line because
4719 % it dictates many top-level macro definitions. Turning rawtext on turns off
4720 % the indexes by default, but this can be overridden by explicitly setting
4721 % index options. (Note: Using rawtext with indexes turned on doesn't actually
4722 % work yet, but might be added in a future revision.)
4723 % \begin{macrocode}
4724 \DeclareOption{rawtext}{\rawtexttrue\indexesoff}
4725 % \end{macrocode}
4726 % \end{option}
4727 %
4728 % \begin{option}{noshading}\MainEnvImpl{noshading}
4729 % \optdef{off}
4730 % Inhibit all shaded boxes (e.g., if the color package is unavailable).
4731 % This option can only be set in the |\usepackage| line because the color
4732 % package must be loaded in the preamble if at all. (Note: In a future release
4733 % this might be extended to be modifiable throughout the preamble.)
4734 % \begin{macrocode}
4735 \DeclareOption{noshading}{\SB@colorboxesfalse}
4736 % \end{macrocode}
4737 % \end{option}
4738 %
4739 % \begin{option}{noindexes}\MainEnvImpl{noindexes}
4740 % \begin{macro}{\indexeson}\MainImpl{indexeson}
4741 % \begin{macro}{\indexesoff}\MainImpl{indexesoff}
4742 % \optdef{off}
4743 % Suppress generation of index files and displaying of in-document indexes.
4744 % The |\indexeson| and |\indexesoff| macros can be used elsewhere to toggle
4745 % display of indexes.
4746 % Index-regeneration will occur if indexes are turned on by the end of the
4747 % document.
4748 % \begin{macrocode}
4749 \DeclareOption{noindexes}{\indexesoff}
4750 \newcommand\indexeson{\songindexestrue}
4751 \newcommand\indexesoff{\songindexesfalse}
4752 % \end{macrocode}
4753 % \end{macro}
4754 % \end{macro}
4755 % \end{option}
4756 %
4757 % \begin{option}{nopdfindex}\MainEnvImpl{nopdfindex}
4758 % \optdef{off}
4759 % Suppress creation of PDF bookmark entries and hyperlinks.
4760 % \begin{macrocode}
4761 \DeclareOption{nopdfindex}{%
4762 \let\songtarget\@gobbletwo%
4763 \let\songlink\@secondoftwo%
4764 }
4765 % \end{macrocode}
4766 % \end{option}
4767 %
4768 % \begin{macro}{\ifSB@measurespec}
4769 % \begin{macro}{\ifSB@chordedspec}
4770 % The |showmeasures| and |chorded| options interact in the sense that by
4771 % default, switching one of them on or off switches the other on or off as
4772 % well.
4773 % However, if the user explicitly says that one should be on or off, then
4774 % switching the other shouldn't affect it.
4775 % To produce this behavior, we need two extra conditionals to remember whether
4776 % each of these options has been explicitly specified by the user or whether
4777 % it is still in a default state.
4778 % \begin{macrocode}
4779 \newif\ifSB@measurespec
4780 \newif\ifSB@chordedspec
4781 % \end{macrocode}
4782 % \end{macro}
4783 % \end{macro}
4784 %
4785 % \begin{option}{chorded}\MainEnvImpl{chorded}
4786 % \begin{option}{lyric}\MainEnvImpl{lyric}
4787 % \begin{macro}{\chordson}\MainImpl{chordson}
4788 % \begin{macro}{\chordsoff}\MainImpl{chordsoff}
4789 % \begin{macro}{\SB@chordson}
4790 % \begin{macro}{\SB@chordsoff}
4791 % \changes{v1.22}{2007/05/15}{Update \cs{baselineskip} when in songs.}
4792 % \optdef{chorded}
4793 % Determines whether chords should be shown.
4794 % This option can be set in the |\usepackage| line or toggled elsewhere
4795 % with the |\chordson| and |\chordsoff| macros.
4796 % Chords cannot be turned on in conjunction with the |rawtext| option.
4797 % If chords are turned on by the end of the preamble, no attempt will be made
4798 % to balance columns on each page.
4799 % \begin{macrocode}
4800 \DeclareOption{chorded}{\chordson}
4801 \DeclareOption{lyric}{\chordsoff}
4802 \newcommand\chordson{\SB@chordedspectrue\SB@chordson}
4803 \newcommand\chordsoff{\SB@chordedspectrue\SB@chordsoff}
4804 \newcommand\SB@chordson{%
4805 \ifrawtext%
4806 \SB@errrtopt%
4807 \else%
4808 \chordedtrue\lyricfalse%
4809 \let\SB@bracket\SB@chord%
4810 \let\SB@rechord\SB@@rechord%
4811 \let\SB@ch\SB@ch@on%
4812 \ifSB@measurespec%
4813 \ifmeasures\SB@measureson\else\SB@measuresoff\fi%
4814 \else%
4815 \SB@measureson%
4816 \fi%
4817 \ifSB@preamble\def\colbotglue{\z@\@plus.5\textheight}\fi%
4818 \SB@setbaselineskip%
4819 \fi%
4820 }
4821 \newcommand\SB@chordsoff{%
4822 \chordedfalse\lyrictrue%
4823 \def\SB@bracket##1]{\ignorespaces}%
4824 \let\SB@rechord\relax%
4825 \let\SB@ch\SB@ch@off%
4826 \ifSB@measurespec%
4827 \ifmeasures\SB@measureson\else\SB@measuresoff\fi%
4828 \else%
4829 \SB@measuresoff%
4830 \fi%
4831 \ifSB@preamble\let\colbotglue\z@skip\fi%
4832 \SB@setbaselineskip%
4833 }
4834 % \end{macrocode}
4835 % \eat\]
4836 % \end{macro}
4837 % \end{macro}
4838 % \end{macro}
4839 % \end{macro}
4840 % \end{option}
4841 % \end{option}
4842 %
4843 % \begin{option}{showmeasures}\MainEnvImpl{showmeasures}
4844 % \begin{option}{nomeasures}\MainEnvImpl{nomeasures}
4845 % \begin{macro}{\measureson}\MainImpl{measureson}
4846 % \begin{macro}{\measuresoff}\MainImpl{measuresoff}
4847 % \begin{macro}{\SB@measureson}
4848 % \begin{macro}{\SB@measuresoff}
4849 % \optdef{showmeasures if chorded, nomeasures otherwise}
4850 % Determines whether measure bars and meter notes should be shown.
4851 % Option can be set in the |\usepackage| line or toggled elsewhere with the
4852 % |\measureson| and |\measuresoff| macros.
4853 % \begin{macrocode}
4854 \DeclareOption{showmeasures}{\measureson}
4855 \DeclareOption{nomeasures}{\measuresoff}
4856 \newcommand\measureson{\SB@measurespectrue\SB@measureson}
4857 \newcommand\measuresoff{\SB@measurespectrue\SB@measuresoff}
4858 \newcommand\SB@measureson{%
4859 \measurestrue%
4860 \let\SB@mbar\SB@makembar%
4861 \ifchorded%
4862 \let\SB@mch\SB@mch@on%
4863 \else%
4864 \let\SB@mch\SB@mch@m%
4865 \fi%
4866 \ifSB@inverse\SB@loadactives\fi%
4867 \ifSB@inchorus\SB@loadactives\fi%
4868 }
4869 \newcommand\SB@measuresoff{%
4870 \measuresfalse%
4871 \let\SB@mbar\@gobbletwo%
4872 \ifchorded%
4873 \let\SB@mch\SB@ch@on%
4874 \else%
4875 \let\SB@mch\SB@ch@off%
4876 \fi%
4877 \ifSB@inverse\SB@loadactives\fi%
4878 \ifSB@inchorus\SB@loadactives\fi%
4879 }
4880 % \end{macrocode}
4881 % \end{macro}
4882 % \end{macro}
4883 % \end{macro}
4884 % \end{macro}
4885 % \end{option}
4886 % \end{option}
4887 %
4888 % \begin{option}{transposecapos}\MainEnvImpl{transposecapos}
4889 % \optdef{off}
4890 % If set, the |\capo| macro transposes the song instead of printing a note
4891 % to use a capo. Use this option to generate a chord book for pianists who
4892 % have trouble transposing or guitarists who don't have capos.
4893 % \begin{macrocode}
4894 \DeclareOption{transposecapos}{\transcapostrue}
4895 % \end{macrocode}
4896 % \end{option}
4897 %
4898 % \begin{option}{noscripture}\MainEnvImpl{noscripture}
4899 % \begin{macro}{\scriptureon}\MainImpl{scriptureon}
4900 % \begin{macro}{\scriptureoff}\MainImpl{scriptureoff}
4901 % \optdef{off}
4902 % Inhibits the display of scripture quotes.
4903 % This option can also be toggled on and off anywhere with the |\sciptureon|
4904 % and |\scriptureoff| macros.
4905 % \begin{macrocode}
4906 \DeclareOption{noscripture}{\SB@omitscriptrue}
4907 \newcommand\scriptureon{\SB@omitscripfalse}
4908 \newcommand\scriptureoff{\SB@omitscriptrue}
4909 % \end{macrocode}
4910 % \end{macro}
4911 % \end{macro}
4912 % \end{option}
4913 %
4914 % \begin{option}{onesongcolumn}\MainEnvImpl{onesongcolumn}
4915 % \begin{option}{twosongcolumns}\MainEnvImpl{twosongcolumns}
4916 % \begin{macro}{\onesongcolumn}\MainImpl{onesongcolumn}
4917 % \begin{macro}{\twosongcolumns}\MainImpl{twosongcolumns}
4918 % \begin{macro}{\songcolumns}\MainImpl{songcolumns}
4919 % \optdef{onesongcolumn is the default if generating slides or rawtext, twosongcolumns otherwise}
4920 % The number of columns per page is specified using the following package
4921 % options and macros.
4922 % In \env{rawtext} mode it must remain set to one column per page.
4923 % The entire page-making system can be turned off by setting the number of
4924 % columns to zero.
4925 % This will cause each song to be contributed to the current vertical list
4926 % without any attempt to form columns; the enclosing environment must handle
4927 % the page layout.
4928 % Probably this means that |\repchoruses| will not work, since an external
4929 % package won't know to insert repeated choruses when building pages.
4930 % \begin{macrocode}
4931 \DeclareOption{twosongcolumns}{\SB@numcols\tw@}
4932 \DeclareOption{onesongcolumn}{\SB@numcols\@ne}
4933 \newcommand\songcolumns[1]{%
4934 \SB@cnt#1\relax%
4935 \ifnum\SB@cnt=\SB@numcols\else%
4936 \ifSB@preamble\else{\SB@clearpage}\fi%
4937 \fi%
4938 \SB@numcols\SB@cnt%
4939 \ifnum\SB@numcols>\z@%
4940 \SB@colwidth-\columnsep%
4941 \multiply\SB@colwidth\SB@numcols%
4942 \advance\SB@colwidth\columnsep%
4943 \advance\SB@colwidth\textwidth%
4944 \divide\SB@colwidth\SB@numcols%
4945 \else%
4946 \ifrepchorus\SB@warnrc\fi%
4947 \fi%
4948 }
4949 \newcommand\onesongcolumn{\songcolumns\@ne}
4950 \newcommand\twosongcolumns{\songcolumns\tw@}
4951 % \end{macrocode}
4952 % \end{macro}
4953 % \end{macro}
4954 % \end{macro}
4955 % \end{option}
4956 % \end{option}
4957 %
4958 % \begin{macro}{\includeonlysongs}\MainImpl{includeonlysongs}
4959 % \begin{macro}{\songlist}
4960 % Display only a select list of songs and ignore the rest.
4961 % \begin{macrocode}
4962 \newcommand\songlist{}
4963 \newcommand\includeonlysongs[1]{%
4964 \ifSB@songsenv\SB@errpl\else%
4965 \partiallisttrue%
4966 \renewcommand\songlist{#1}%
4967 \fi%
4968 }
4969 % \end{macrocode}
4970 % \end{macro}
4971 % \end{macro}
4972 %
4973 % \begin{macro}{\nosongnumbers}\MainImpl{nosongnumbers}
4974 % \changes{v2.9}{2009/04/01}{Added.}
4975 % The user can turn off song numbering with the following macro.
4976 % \begin{macrocode}
4977 \newcommand\nosongnumbers{\setlength\songnumwidth\z@}
4978 % \end{macrocode}
4979 % \end{macro}
4980 %
4981 % \begin{macro}{\noversenumbers}\MainImpl{noversenumbers}
4982 % \changes{v1.20}{2006/03/12}{Added.}
4983 % The user can turn off verse numbering with the following macro.
4984 % \begin{macrocode}
4985 \newcommand\noversenumbers{%
4986 \renewcommand\printversenum[1]{}%
4987 \setlength\versenumwidth\z@%
4988 }
4989 % \end{macrocode}
4990 % \end{macro}
4991 %
4992 % \begin{macro}{\repchoruses}\MainImpl{repchoruses}
4993 % \begin{macro}{\norepchoruses}\MainImpl{norepchoruses}
4994 % \changes{v2.1}{2007/08/02}{Added.}
4995 % Using |\repchoruses| causes choruses to be automatically repeated on
4996 % subsequent pages of the song.
4997 % The feature requires $\varepsilon$-\TeX{} because the supporting code needs
4998 % an extended mark register class.
4999 % \begin{macrocode}
5000 \ifSB@etex
5001 \newcommand\repchoruses{%
5002 \ifnum\SB@numcols<\@ne\SB@warnrc\fi%
5003 \repchorustrue%
5004 }
5005 \else
5006 \newcommand\repchoruses{\SB@erretex}
5007 \fi
5008 \newcommand\norepchoruses{\repchorusfalse}
5009 % \end{macrocode}
5010 % \end{macro}
5011 % \end{macro}
5012 %
5013 % \begin{macro}{\sepverses}
5014 % The following penalty settings cause verses and choruses to be separated
5015 % onto different slides when in slides mode, except that consecutive choruses
5016 % remain together when they fit.
5017 % \begin{macrocode}
5018 \newcommand\sepverses{%
5019 \vvpenalty-\@M%
5020 \ccpenalty100 %
5021 \vcpenalty\vvpenalty%
5022 \cvpenalty\vvpenalty%
5023 \let\colbotglue\@flushglue%
5024 }
5025 % \end{macrocode}
5026 % \end{macro}
5027 %
5028 % Some option settings, margins, and other lengths are finalized at the end of
5029 % the preamble.
5030 % That code is below.
5031 %
5032 % \begin{macrocode}
5033 \AtBeginDocument{
5034 % \end{macrocode}
5035 %
5036 % If the user hasn't set the |\versesep|, set it to the default.
5037 % \begin{macrocode}
5038 \SB@setversesep
5039 % \end{macrocode}
5040 %
5041 % Initialize page layout algorithm.
5042 % \begin{macrocode}
5043 \songcolumns\SB@numcols
5044 % \end{macrocode}
5045 %
5046 % Macros used after this point occur outside the preamble.
5047 % \begin{macrocode}
5048 \SB@preamblefalse
5049 }
5050 % \end{macrocode}
5051 %
5052 % \subsection{Page-builder}
5053 % \label{sec:pagebuilder}
5054 %
5055 % The following macros handle the building of pages that contain songs.
5056 % They compute where best to place each song (e.g., whether to place it in the
5057 % current column or move to the next column or page).
5058 % The output routines for generating a partial list of songs in a specified
5059 % order also can be found here.
5060 %
5061 % \begin{macro}{\SB@songbox}
5062 % The most recently processed song (or scripture quotation) is stored in this
5063 % box.
5064 % \begin{macrocode}
5065 \SB@newbox\SB@songbox
5066 % \end{macrocode}
5067 % \end{macro}
5068 %
5069 % \begin{macro}{\SB@numcols}
5070 % \begin{macro}{\SB@colnum}
5071 % Reserve two count registers to hold the total number of columns and the
5072 % current column number, respectively.
5073 % \begin{macrocode}
5074 \SB@newcount\SB@numcols\SB@numcols\tw@
5075 \SB@newcount\SB@colnum
5076 % \end{macrocode}
5077 % \end{macro}
5078 % \end{macro}
5079 %
5080 % \begin{macro}{\SB@colbox}
5081 % Reserve a box register to hold the current column in progress.
5082 % \begin{macrocode}
5083 \SB@newbox\SB@colbox
5084 % \end{macrocode}
5085 % \end{macro}
5086 %
5087 % \begin{macro}{\SB@pgbox}
5088 % Reserve a box register to hold the current page in progress.
5089 % \begin{macrocode}
5090 \SB@newbox\SB@pgbox
5091 % \end{macrocode}
5092 % \end{macro}
5093 %
5094 % \begin{macro}{\SB@mrkbox}
5095 % Reserve a box register to hold marks that migrate out of songs as they
5096 % get split into columns and pages.
5097 % \begin{macrocode}
5098 \SB@newbox\SB@mrkbox
5099 % \end{macrocode}
5100 % \end{macro}
5101 %
5102 % \begin{macro}{\SB@maxmin}
5103 % The following helper macro takes the max or min of two dimensions.
5104 % If \argp{2}=``|<|'', it sets \argp{1} to the maximum of \argp{1} and
5105 % \argp{3}.
5106 % If \argp{2}=``|>|'', it sets \argp{1} to the minimum of \argp{1} and
5107 % \argp{3}.
5108 % \begin{macrocode}
5109 \newcommand\SB@maxmin[3]{\ifdim#1#2#3#1#3\fi}
5110 % \end{macrocode}
5111 % \end{macro}
5112 %
5113 % \begin{macro}{\SB@mkpage}
5114 % The following macro is the heart of the page-building engine.
5115 % It splits the contents of a box into a page of columns.
5116 % If |\repchoruses| is active, the contents of |\SB@chorusbox|
5117 % are additionally inserted into fresh columns created during the spitting
5118 % process.
5119 % The macro arguments are:
5120 % \begin{enumerate}
5121 % \item an integer (positive or zero) indicating whether box $b$ should be
5122 % fully emptied and committed as columns (if positive), or whether its
5123 % final less-than-column-height remainder should be reserved as an in-progress
5124 % column (if zero);
5125 % \item the box $b$ to split;
5126 % \item a count register $i$ equaling the column index (zero or greater)
5127 % where the content of $b$ is to begin; and
5128 % \item the desired column height.
5129 % \end{enumerate}
5130 % Box $b$ is split and $i$ is incremented until $i$ reaches
5131 % |\SB@numcols| or $b$ is emptied.
5132 % If $b$ is emptied and the first argument is 0, the final column is \emph{not}
5133 % contributed; instead it is left in $b$ and $i$ is left equal to the index
5134 % of the column that would have been added if $b$ had been emptied.
5135 % This allows the next call to reconsider whether to end the
5136 % current column here or add some or all of the next contribution to it.
5137 % Otherwise, if $b$ is emptied and the first argument is positive, the final
5138 % column is contributed and $i$ is set to one greater than the index of that
5139 % column.
5140 % (If $i$ reaches |\SB@numcols| before $b$ is emptied, the first argument is
5141 % ignored.)
5142 %
5143 % Box $b$ and count register $i$ are globally modified.
5144 % If |\SB@updatepage| is not redefined, boxes |\SB@pgbox| and |\SB@mrkbox|
5145 % are also globally modified based on the results of the split.
5146 %
5147 % The implementation takes two special steps to avoid pre-committing
5148 % in-progress columns (when the first macro argument is zero):
5149 % First, the final split that empties box $b$ is ``undone'' by reverting to a
5150 % backup copy made before each split.
5151 % Second, any underfull box warnings for this final split are suppressed by
5152 % temporarily adding infinite-stretch |\vfil| glue to the bottom of the box.
5153 % This strategy preserves underfull and overfull box warnings for the columns
5154 % that are actually committed, but suppresses faux warnings for the last split
5155 % that is undone.
5156 % \begin{macrocode}
5157 \newcommand\SB@mkpage[4]{%
5158 \ifvoid#2\else\begingroup%
5159 \edef\SB@temp{\ifnum#2=\SB@box\SB@boxii\else\SB@box\fi}%
5160 \edef\SB@tempii{\ifnum#2=\SB@boxiii\SB@boxii\else\SB@boxiii\fi}%
5161 \splitmaxdepth\maxdepth\splittopskip\z@skip%
5162 \ifnum#1=\z@\global\setbox#2\vbox{\unvbox#2\vfil}\fi%
5163 \loop\ifnum#3<\SB@numcols%
5164 \ifnum#1=\z@\setbox\SB@tempii\copy#2\fi%
5165 \setbox\SB@temp\vsplit#2to#4\relax%
5166 \ifvoid#2%
5167 \ifnum#1=\z@%
5168 \global\setbox#2\box\SB@tempii%
5169 \else%
5170 \SB@updatepage%
5171 \global\advance#3\@ne%
5172 \fi%
5173 #3\SB@numcols%
5174 \else%
5175 \SB@updatepage%
5176 \global\advance#3\@ne%
5177 \ifrepchorus\ifvoid\SB@chorusbox\else%
5178 \SB@insertchorus#2%
5179 \fi\fi%
5180 \fi%
5181 \repeat%
5182 \ifnum#1=\z@\global\setbox#2\vbox{\unvbox#2\unskip}\fi%
5183 \endgroup\fi%
5184 }
5185 % \end{macrocode}
5186 % \end{macro}
5187 %
5188 % \begin{macro}{\SB@migrate}
5189 % Migrate a mark out of a recently split vertical list, but do not insert
5190 % superfluous empty marks that may override previous marks.
5191 % \begin{macrocode}
5192 \newcommand\SB@migrate[1]{%
5193 \SB@toks\expandafter{#1}%
5194 \edef\SB@temp{\the\SB@toks}%
5195 \ifx\SB@temp\@empty\else\mark{\the\SB@toks}\fi%
5196 }
5197 % \end{macrocode}
5198 % \end{macro}
5199 %
5200 % \begin{macro}{\SB@updatepage}
5201 % Update boxes |\SB@pgbox| and |\SB@mrkbox| immediately after splitting
5202 % the contents of |\SB@colbox|.
5203 % \begin{macrocode}
5204 \newcommand\SB@updatepage{%
5205 \global\setbox\SB@mrkbox\vbox{%
5206 \unvbox\SB@mrkbox%
5207 \SB@migrate\splitfirstmark%
5208 \SB@migrate\splitbotmark%
5209 }%
5210 \global\setbox\SB@pgbox\hbox{%
5211 \SB@dimen\SB@colwidth%
5212 \advance\SB@dimen\columnsep%
5213 \multiply\SB@dimen\SB@colnum%
5214 \advance\SB@dimen-\wd\SB@pgbox%
5215 \unhbox\SB@pgbox%
5216 \ifdim\SB@dimen=\z@\else\hskip\SB@dimen\relax\fi%
5217 \box\SB@temp%
5218 }%
5219 }
5220 % \end{macrocode}
5221 % \end{macro}
5222 %
5223 % \begin{macro}{\SB@droppage}
5224 % This alternate definition of |\SB@updatepage| drops the just-created
5225 % page instead of contributing it.
5226 % This allows |\SB@mkpage| to be called by the song-positioning algorithm
5227 % as a trial run without outputting anything.
5228 % \begin{macrocode}
5229 \newcommand\SB@droppage{\setbox\SB@temp\box\voidb@x}
5230 % \end{macrocode}
5231 % \end{macro}
5232 %
5233 % \begin{macro}{\SB@output}
5234 % This is the main output routine for the page-builder.
5235 % It repeatedly calls |\SB@mkpage|, emitting pages as they are completed,
5236 % until the remaining content of box |\SB@colbox| is not enough to fill a
5237 % column.
5238 % If the macro argument is 0, this final, in-progress column is left
5239 % unfinished, pending future contributions.
5240 % If the argument is positive, the final material is committed as a column.
5241 % If the argument is two or greater, the entire in-progress page is also
5242 % committed and the column number reset.
5243 % \begin{macrocode}
5244 \newcommand\SB@output[1]{%
5245 \ifnum\SB@numcols>\z@\begingroup%
5246 \loop%
5247 \SB@dimen\textheight%
5248 \ifinner\else\advance\SB@dimen-\pagetotal\fi%
5249 \SB@mkpage#1\SB@colbox\SB@colnum\SB@dimen%
5250 \SB@testfalse\SB@testiitrue%
5251 \ifnum#1>\@ne\ifvoid\SB@colbox\ifnum\SB@colnum>\z@%
5252 \SB@testtrue\SB@testiifalse%
5253 \fi\fi\fi%
5254 \ifnum\SB@colnum<\SB@numcols\SB@testiifalse\else\SB@testtrue\fi%
5255 \ifSB@test%
5256 \unvbox\SB@mrkbox%
5257 \ifinner\else\kern\z@\fi%
5258 \box\SB@pgbox%
5259 \ifinner\else\vfil\break\vskip\vsize\relax\fi%
5260 \global\SB@colnum\z@%
5261 \fi%
5262 \ifSB@testii\repeat%
5263 \endgroup\else%
5264 \unvbox\SB@colbox\unskip%
5265 \fi%
5266 }
5267 % \end{macrocode}
5268 % \end{macro}
5269 %
5270 % \begin{macro}{\SB@putboxes}
5271 % Create a vertical list consisting of the already committed contents of the
5272 % current column plus the most recently submitted song box.
5273 % The \LaTeX{} primitive that should be used to contribute each box is
5274 % specified in the first argument.
5275 % \begin{macrocode}
5276 \newcommand\SB@putboxes[1]{%
5277 \SB@dimen\ifnum\SB@numcols>\z@\ht\SB@colbox\else\p@\fi%
5278 #1\SB@colbox%
5279 \ifdim\SB@dimen>\z@%
5280 \SB@breakpoint\spenalty%
5281 \ifdim\sbarheight>\z@%
5282 \vskip-\sbarheight\relax%
5283 \fi%
5284 \fi%
5285 #1\SB@songbox%
5286 }
5287 % \end{macrocode}
5288 % \end{macro}
5289 %
5290 % \begin{macro}{\SB@nextcol}
5291 % Force $n$ column breaks, where $n$ is given by the first argument.
5292 % The first created column is finished with the glue specified in the
5293 % second argument.
5294 % When the second argument is |\@flushglue|, this forces a break that leaves
5295 % whitespace at the bottom of the column.
5296 % When it's |\colbotglue|, it acts like a natural column break chosen by
5297 % the page-breaker.
5298 % However, if the current column is empty, |\@flushglue| is always used so
5299 % that an empty column will result.
5300 % \begin{macrocode}
5301 \newcommand\SB@nextcol[2]{%
5302 \ifnum#1>\z@%
5303 \ifnum\SB@numcols>\z@%
5304 \global\setbox\SB@colbox\vbox{%
5305 \SB@cnt#1\relax%
5306 \SB@dimen\ht\SB@colbox%
5307 \unvbox\SB@colbox%
5308 \unskip%
5309 \ifdim\SB@dimen>\z@%
5310 \vskip#2\relax%
5311 \break%
5312 \advance\SB@cnt\m@ne%
5313 \fi%
5314 \loop\ifnum\SB@cnt>\z@%
5315 \nointerlineskip%
5316 \null%
5317 \vfil%
5318 \break%
5319 \advance\SB@cnt\m@ne%
5320 \repeat%
5321 }%
5322 \SB@output1%
5323 \else%
5324 \ifnum\lastpenalty=-\@M\null\fi%
5325 \break%
5326 \fi%
5327 \fi%
5328 }
5329 % \end{macrocode}
5330 % \end{macro}
5331 %
5332 % \begin{macro}{\SB@selectcol}
5333 % This is the entrypoint to the song-positioning algorithm.
5334 % It gets defined by |\songpos| to either |\SB@@selectcol| (below) or
5335 % |\relax| (when song-positioning is turned off).
5336 % \begin{macrocode}
5337 \newcommand\SB@selectcol{}
5338 % \end{macrocode}
5339 % \end{macro}
5340 %
5341 % \begin{macro}{\SB@@selectcol}
5342 % \changes{v2.1}{2007/08/02}{Rewritten to better handle glue}
5343 % \changes{v2.9}{2009/07/30}{Rewritten to handle repeated choruses}
5344 % Songs should be squeezed in wherever they fit, but breaking a column or page
5345 % within a song should be avoided.
5346 % The following macro outputs zero or more column breaks to select a good
5347 % place for |\SB@songbox| to be contributed to the current (or the next) page.
5348 % The number of column breaks is determined by temporarily setting
5349 % |\SB@updatepage| to |\SB@droppage| and then calling the |\SB@mkpage|
5350 % algorithm under various conditions to see how many columns it would
5351 % contribute if we start the current song at various positions.
5352 % \begin{macrocode}
5353 \newcommand\SB@@selectcol{%
5354 \begingroup%
5355 \SB@cnt\z@%
5356 \vbadness\@M\vfuzz\maxdimen%
5357 \let\SB@updatepage\SB@droppage%
5358 \SB@dimen\textheight%
5359 \ifinner\else\advance\SB@dimen-\pagetotal\fi%
5360 \setbox\SB@boxii\vbox{\SB@putboxes\unvcopy}%
5361 \SB@cntii\SB@colnum%
5362 \SB@mkpage0\SB@boxii\SB@cntii\SB@dimen%
5363 \SB@spos%
5364 \global\SB@cnt\SB@cnt%
5365 \endgroup%
5366 \SB@nextcol\SB@cnt\colbotglue%
5367 }
5368 % \end{macrocode}
5369 % \end{macro}
5370 %
5371 % \begin{macro}{\SB@spbegnew}
5372 % Begin a trial typesetting of the current song on a fresh page to see if
5373 % it fits within a page.
5374 % \begin{macrocode}
5375 \newcommand\SB@spbegnew{%
5376 \setbox\SB@boxiii\copy\SB@songbox%
5377 \SB@cntii\z@%
5378 \SB@mkpage0\SB@boxiii\SB@cntii\textheight%
5379 }
5380 % \end{macrocode}
5381 % \end{macro}
5382 %
5383 % \begin{macro}{\SB@spextold}
5384 % Tentatively extend the song previously typeset on the current even page to
5385 % the next odd page to see whether it fits on a double-page.
5386 % If the current page is odd-numbered, do nothing since extending the song
5387 % to the next page would introduce a page-turn.
5388 % \begin{macrocode}
5389 \newcommand\SB@spextold{%
5390 \ifodd\c@page\else%
5391 \SB@cntii\z@%
5392 \SB@mkpage0\SB@boxii\SB@cntii\textheight%
5393 \fi%
5394 }
5395 % \end{macrocode}
5396 % \end{macro}
5397 %
5398 % \begin{macro}{\SB@spextnew}
5399 % Extend the trial typesetting started with |\SB@spbegnew| to a second
5400 % page to see whether the song fits on a fresh double-page.
5401 % \begin{macrocode}
5402 \newcommand\SB@spextnew{%
5403 \SB@cntii\z@%
5404 \SB@mkpage0\SB@boxiii\SB@cntii\textheight%
5405 }
5406 % \end{macrocode}
5407 % \end{macro}
5408 %
5409 % \begin{macro}{\SB@spdblpg}
5410 % Compute the number of column breaks required to shift the current song
5411 % to the next double-page if the result of the last test run fits within
5412 % its page (as indicated by counter |\SB@cntii|).
5413 % Otherwise leave the requested number of column breaks set to zero.
5414 % \begin{macrocode}
5415 \newcommand\SB@spdblpg{%
5416 \ifnum\SB@cntii<\SB@numcols%
5417 \SB@cnt\SB@numcols%
5418 \advance\SB@cnt-\SB@colnum%
5419 \if@twoside\ifodd\c@page\else%
5420 \advance\SB@cnt\SB@numcols%
5421 \fi\fi%
5422 \fi%
5423 }
5424 % \end{macrocode}
5425 % \end{macro}
5426 %
5427 % \begin{macro}{\SB@sposi}
5428 % This is the level-1 song positioning algorithm.
5429 % It moves songs to the next double-page only if doing so would avoid a
5430 % page-turn that would otherwise appear within the song.
5431 % \begin{macrocode}
5432 \newcommand\SB@sposi{%
5433 \ifnum\SB@cntii<\SB@numcols\else\if@twoside%
5434 \SB@spextold%
5435 \fi\fi%
5436 \ifnum\SB@cntii<\SB@numcols\else%
5437 \SB@spbegnew%
5438 \ifnum\SB@cntii<\SB@numcols\else\if@twoside%
5439 \SB@spextnew%
5440 \fi\fi%
5441 \SB@spdblpg%
5442 \fi%
5443 }
5444 % \end{macrocode}
5445 % \end{macro}
5446 %
5447 % \begin{macro}{\SB@sposii}
5448 % This is the level-2 song-positioning algorithm.
5449 % It moves songs to the next page or double-page if doing so avoids a
5450 % page-break or page-turn that would otherwise appear within the song.
5451 % \begin{macrocode}
5452 \newcommand\SB@sposii{%
5453 \ifnum\SB@cntii<\SB@numcols\else%
5454 \SB@spbegnew%
5455 \ifnum\SB@cntii<\SB@numcols%
5456 \SB@cnt\SB@numcols%
5457 \advance\SB@cnt-\SB@colnum%
5458 \else%
5459 \if@twoside%
5460 \SB@spextold%
5461 \ifnum\SB@cntii<\SB@numcols\else%
5462 \SB@spextnew%
5463 \SB@spdblpg%
5464 \fi%
5465 \fi%
5466 \fi%
5467 \fi%
5468 }
5469 % \end{macrocode}
5470 % \end{macro}
5471 %
5472 % \begin{macro}{\SB@sposiii}
5473 % This is the level-3 song-positioning algorithm.
5474 % It moves songs to the next column, the next page, or the next double-page
5475 % if doing so avoids a column-break, page-break, or page-turn that would
5476 % otherwise appear within the song.
5477 % \begin{macrocode}
5478 \newcommand\SB@sposiii{%
5479 \ifnum\SB@cntii>\SB@colnum%
5480 \SB@cnt\SB@colnum%
5481 \advance\SB@cnt\@ne%
5482 \ifnum\SB@cnt<\SB@numcols%
5483 \setbox\SB@boxiii\copy\SB@songbox%
5484 \SB@mkpage0\SB@boxiii\SB@cnt\SB@dimen%
5485 \advance\SB@cnt\m@ne%
5486 \fi%
5487 \ifnum\SB@cnt>\SB@colnum%
5488 \SB@cnt\z@%
5489 \SB@sposii%
5490 \else%
5491 \SB@cnt\@ne%
5492 \fi%
5493 \fi%
5494 }
5495 % \end{macrocode}
5496 % \end{macro}
5497 %
5498 % \begin{macro}{\songpos}
5499 % This is the macro by which the user adjusts the aggressiveness level of the
5500 % song-positioning algorithm.
5501 % See the macros above for what each level does.
5502 % \begin{macrocode}
5503 \newcommand\songpos[1]{%
5504 \ifcase#1%
5505 \let\SB@selectcol\relax%
5506 \let\SB@spos\relax%
5507 \or%
5508 \let\SB@selectcol\SB@@selectcol%
5509 \let\SB@spos\SB@sposi%
5510 \or%
5511 \let\SB@selectcol\SB@@selectcol%
5512 \let\SB@spos\SB@sposii%
5513 \or%
5514 \let\SB@selectcol\SB@@selectcol%
5515 \let\SB@spos\SB@sposiii%
5516 \else%
5517 \SB@errspos%
5518 \fi%
5519 }
5520 % \end{macrocode}
5521 % \end{macro}
5522 %
5523 % \begin{macro}{\SB@spos}
5524 % The |\SB@spos| macro gets redefined by |\songpos| above depending on the
5525 % current song-positioning aggressiveness level.
5526 % By default it is set to level 3.
5527 % \begin{macrocode}
5528 \newcommand\SB@spos{}
5529 \songpos\thr@@
5530 % \end{macrocode}
5531 % \end{macro}
5532 %
5533 % \begin{macro}{\SB@clearpage}
5534 % Output all contributed material as a new page unless there is no contributed
5535 % material. In that case do nothing (i.e., don't produce a blank page).
5536 % The |\SB@colbox| is tested for zero height and depth rather than voidness,
5537 % since sometimes it contains zero-length |\splittopskip| glue.
5538 % \begin{macrocode}
5539 \newcommand\SB@clearpage{%
5540 \SB@testtrue%
5541 \ifvoid\SB@pgbox%
5542 \ifdim\ht\SB@colbox=\z@\ifdim\dp\SB@colbox=\z@%
5543 \SB@testfalse%
5544 \fi\fi%
5545 \fi%
5546 \ifSB@test%
5547 \SB@cnt\SB@numcols%
5548 \advance\SB@cnt-\SB@colnum%
5549 \SB@nextcol\SB@cnt\lastcolglue%
5550 \SB@output2%
5551 \fi%
5552 }
5553 % \end{macrocode}
5554 % \end{macro}
5555 %
5556 % \begin{macro}{\SB@cleardpage}
5557 % Like |\SB@clearpage| but shift to a fresh \emph{even-numbered} page in
5558 % two-sided documents.
5559 % Note that this differs from \LaTeX's |\cleardoublepage|, which shifts to
5560 % odd-numbered pages.
5561 % Song books prefer starting things on even-numbered pages because this
5562 % maximizes the distance until the next page-turn.
5563 % \begin{macrocode}
5564 \newcommand\SB@cleardpage{%
5565 \SB@clearpage%
5566 \if@twoside\ifodd\c@page%
5567 \SB@nextcol\SB@numcols\@flushglue%
5568 \SB@output2%
5569 \fi\fi%
5570 }
5571 % \end{macrocode}
5572 % \end{macro}
5573 %
5574 % \begin{macro}{\SB@stype}
5575 % There are two song content submission types: column- and page-submissions.
5576 % Page-submissions are page-width and go atop fresh pages unless the current
5577 % page has only page-width material so far.
5578 % Column-submissions are column-width and start a new page only when the
5579 % current page is full.
5580 % This macro gets set to the desired type for the current submission.
5581 % Mostly it stays set to the default column-submission type.
5582 % \begin{macrocode}
5583 \newcommand\SB@stype{\SB@stypcol}
5584 % \end{macrocode}
5585 % \end{macro}
5586 %
5587 % \begin{macro}{\SB@stypcol}
5588 % \changes{v2.1}{2007/08/02}{Rewritten to better handle glue}
5589 % Column-submissions contribute the contents of |\SB@songbox| to either the
5590 % current column or the next column or page, depending on where it best fits.
5591 % \begin{macrocode}
5592 \newcommand\SB@stypcol{%
5593 \ifnum\SB@numcols>\z@%
5594 \SB@selectcol%
5595 \global\setbox\SB@colbox\vbox{\SB@putboxes\unvbox}%
5596 \SB@output0%
5597 \else%
5598 \unvbox\voidb@x%
5599 \SB@breakpoint\spenalty%
5600 \ifdim\sbarheight>\z@%
5601 \vskip-\sbarheight\relax%
5602 \fi%
5603 \unvbox\SB@songbox%
5604 \fi%
5605 }
5606 % \end{macrocode}
5607 % \end{macro}
5608 %
5609 % \begin{macro}{\SB@styppage}
5610 % Page-submissions go directly to the top of the nearest fresh page unless
5611 % the current page has all page-width material so far.
5612 %
5613 % Implementation notes:
5614 % The |\null| is needed because the page builder consults |\pagetotal|,
5615 % which isn't updated by \TeX{} until a box is contributed (|\unvbox| doesn't
5616 % count).
5617 % Both |\nointerlineskip|s are needed because |\unvbox| fails to update
5618 % |\prevdepth|, and it doesn't make sense to inherit its value from whatever
5619 % preceeded this contribution.
5620 % Authors who want interline glue must therefore insert it explicitly at the
5621 % bottom of their contributed text.
5622 % \begin{macrocode}
5623 \newcommand\SB@styppage{%
5624 \ifnum\SB@numcols>\z@%
5625 \SB@clearpage%
5626 \unvbox\SB@songbox%
5627 \nointerlineskip\null%
5628 \else%
5629 \unvbox\SB@songbox%
5630 \fi%
5631 \nointerlineskip%
5632 }
5633 % \end{macrocode}
5634 % \end{macro}
5635 %
5636 % \begin{macro}{\SB@sgroup}
5637 % This macro controls whether songs submitted to the
5638 % page-builder are actually contributed to the final document when
5639 % using |\includeonlysongs| to generate a partial list.
5640 % If |\SB@sgroup| is empty, then the song is silently dropped.
5641 % Otherwise it is contributed only if |\SB@sgroup| is a member of
5642 % |\songlist|.
5643 % \begin{macrocode}
5644 \newcommand\SB@sgroup{}
5645 \let\SB@sgroup\@empty
5646 % \end{macrocode}
5647 % \end{macro}
5648 %
5649 % \begin{macro}{\SB@groupcnt}
5650 % This counter assigns a unique integer to each item of a group.
5651 % Environments that come before the group's song are numbered decreasingly
5652 % from $-1$.
5653 % The song itself has number 0.
5654 % Environments that come after the song are numbered increasingly from 1.
5655 % \begin{macrocode}
5656 \SB@newcount\SB@groupcnt
5657 % \end{macrocode}
5658 % \end{macro}
5659 %
5660 % \begin{macro}{\SB@clearpboxes}
5661 % This dynamically constructed macro clears the content of all boxes created
5662 % by the workings of |\includeonlysongs|.
5663 % \begin{macrocode}
5664 \newcommand\SB@clearpboxes{}
5665 % \end{macrocode}
5666 % \end{macro}
5667 %
5668 % \begin{macro}{\SB@partbox}
5669 % Save a box of full-song or chorus material for later output when producing
5670 % a partial list using |\includeonlysongs|.
5671 % \begin{macrocode}
5672 \newcommand\SB@partbox[1]{%
5673 \SB@newbox#1%
5674 \SB@app\gdef\SB@clearpboxes{\setbox#1\box\voidb@x}%
5675 \global\setbox#1\box%
5676 }
5677 % \end{macrocode}
5678 % \end{macro}
5679 %
5680 % \begin{macro}{\SB@submitpart}
5681 % When a song completes and we're generating a partial list, save the song
5682 % in a box so that it can be submitted at the end of the section in the
5683 % order specified by |\includeonlysongs|.
5684 % \begin{macrocode}
5685 \newcommand\SB@submitpart{%
5686 \ifx\SB@sgroup\@empty\else%
5687 \SB@testfalse
5688 \@for\SB@temp:=\songlist\do{\ifx\SB@temp\SB@sgroup\SB@testtrue\fi}%
5689 \ifSB@test%
5690 \edef\SB@tempii{\SB@sgroup @\the\SB@groupcnt}%
5691 \expandafter\SB@partbox
5692 \csname songbox@\SB@tempii\endcsname\SB@songbox%
5693 \global\expandafter\let%
5694 \csname stype@\SB@tempii\endcsname\SB@stype%
5695 \ifrepchorus\ifvoid\SB@chorusbox\else%
5696 \expandafter\SB@partbox
5697 \csname chbox@\SB@tempii\endcsname\SB@chorusbox%
5698 \fi\fi%
5699 \fi%
5700 \global\advance\SB@groupcnt%
5701 \ifnum\SB@groupcnt<\z@\m@ne\else\@ne\fi%
5702 \fi%
5703 \setbox\SB@songbox\box\voidb@x%
5704 \setbox\SB@chorusbox\box\voidb@x%
5705 }
5706 % \end{macrocode}
5707 % \end{macro}
5708 %
5709 % \begin{macro}{\SB@submitsong}
5710 % Submit the most recently finished song (or block of other vertical material)
5711 % for output.
5712 % If we're generating a partial list of songs, save it in a box instead of
5713 % submitting it here.
5714 % (The saved boxes will be submitted in the requested order at the end of
5715 % the songs section.)
5716 % \begin{macrocode}
5717 \newcommand\SB@submitsong{%
5718 \ifpartiallist\SB@submitpart\else\SB@stype\fi%
5719 }
5720 % \end{macrocode}
5721 % \end{macro}
5722 %
5723 % \begin{macro}{\SB@submitenv}
5724 % Submit the |\SB@envbox| box as a page-width contribution.
5725 % \begin{macrocode}
5726 \newcommand\SB@submitenv{%
5727 \begingroup%
5728 \let\SB@songbox\SB@envbox%
5729 \SB@styppage%
5730 \endgroup%
5731 }
5732 % \end{macrocode}
5733 % \end{macro}
5734 %
5735 % \begin{macro}{\SB@songlistbrk}
5736 % \begin{macro}{\SB@songlistnc}
5737 % \begin{macro}{\SB@songlistcp}
5738 % \begin{macro}{\SB@songlistcdp}
5739 % These macros define the words that, when placed in a |\songlist|,
5740 % force a column break at that point.
5741 % Using |brk| produces a soft break (like |\brk|) that won't leave
5742 % whitespace at the bottom of the broken column in lyric books.
5743 % Using |nextcol| produces a hard break (like |\nextcol|) that may
5744 % insert whitespace to finish the column.
5745 % Using |sclearpage| moves to the next page if the current page is
5746 % nonempty.
5747 % Using |scleardpage| moves to the next double-page if the current
5748 % double-page is nonempty.
5749 % \begin{macrocode}
5750 \newcommand*\SB@songlistbrk{brk}
5751 \newcommand*\SB@songlistnc{nextcol}
5752 \newcommand*\SB@songlistcp{sclearpage}
5753 \newcommand*\SB@songlistcdp{scleardpage}
5754 % \end{macrocode}
5755 % \end{macro}
5756 % \end{macro}
5757 % \end{macro}
5758 % \end{macro}
5759 %
5760 % \begin{macro}{\commitsongs}\MainImpl{commitsongs}
5761 % If we're generating only a partial list, then wait until the end of the
5762 % section and then output all the songs we saved in boxes in the order
5763 % specified.
5764 % \begin{macrocode}
5765 \newcommand\commitsongs{%
5766 \ifpartiallist%
5767 \ifnum\SB@numcols>\z@%
5768 \@for\SB@temp:=\songlist\do{%
5769 \ifx\SB@temp\SB@songlistnc\SB@nextcol\@ne\@flushglue\else%
5770 \ifx\SB@temp\SB@songlistbrk\SB@nextcol\@ne\colbotglue\else%
5771 \ifx\SB@temp\SB@songlistcp\SB@clearpage\else%
5772 \ifx\SB@temp\SB@songlistcdp\SB@cleardpage\else%
5773 \SB@groupcnt\m@ne\SB@finloop%
5774 \SB@groupcnt\z@\SB@finloop%
5775 \fi\fi\fi\fi%
5776 }%
5777 \else%
5778 \@for\SB@temp:=\songlist\do{%
5779 \ifx\SB@temp\SB@songlistnc\vfil\break\else%
5780 \ifx\SB@temp\SB@songlistbrk\break\else%
5781 \ifx\SB@temp\SB@songlistcp\clearpage\else%
5782 \ifx\SB@temp\SB@songlistcdp%
5783 \clearpage%
5784 \ifodd\c@page\null\newpage\fi%
5785 \else%
5786 \SB@groupcnt\m@ne\SB@finloop%
5787 \SB@groupcnt\z@\SB@finloop%
5788 \fi\fi\fi\fi%
5789 }%
5790 \fi%
5791 \SB@clearpboxes%
5792 \fi%
5793 \SB@clearpage%
5794 }
5795 % \end{macrocode}
5796 % \end{macro}
5797 %
5798 % \begin{macro}{\SB@finloop}
5799 % While contributing saved material included by |\includeonlysongs|,
5800 % this macro contributes each series of boxes grouped together as part of a
5801 % |songgroup| environment.
5802 % \begin{macrocode}
5803 \newcommand\SB@finloop{%
5804 \loop\edef\SB@tempii{\SB@temp @\the\SB@groupcnt}%
5805 \expandafter\ifx%
5806 \csname songbox@\SB@tempii\endcsname\relax\else%
5807 \setbox\SB@songbox\expandafter\copy%
5808 \csname songbox@\SB@tempii\endcsname%
5809 \expandafter\ifx\csname chbox@\SB@tempii\endcsname\relax%
5810 \repchorusfalse%
5811 \else%
5812 \repchorustrue%
5813 \setbox\SB@chorusbox\expandafter\copy%
5814 \csname chbox@\SB@tempii\endcsname%
5815 \fi%
5816 \csname stype@\SB@tempii\endcsname%
5817 \advance\SB@groupcnt\ifnum\SB@groupcnt<\z@\m@ne\else\@ne\fi%
5818 \repeat%
5819 }
5820 % \end{macrocode}
5821 % \end{macro}
5822 %
5823 % \begin{macro}{\SB@insertchorus}
5824 % Insert a chorus into the first marked spot in the box given
5825 % in the first argument.
5826 % This is usually achieved by splitting the box at the first valid
5827 % breakpoint after the first |\SB@cmark| in the box.
5828 % The box is globally modified.
5829 % \begin{macrocode}
5830 \newcommand\SB@insertchorus[1]{{%
5831 \vbadness\@M\vfuzz\maxdimen%
5832 \setbox\SB@box\copy#1%
5833 \setbox\SB@box\vsplit\SB@box to\maxdimen%
5834 \edef\SB@temp{\splitfirstmarks\SB@nocmarkclass}%
5835 \ifx\SB@temp\SB@nocmark\else%
5836 \edef\SB@temp{\splitfirstmarks\SB@cmarkclass}%
5837 \ifx\SB@temp\SB@cmark%
5838 \SB@dimen4096\p@%
5839 \SB@dimenii\maxdimen%
5840 \SB@dimeniii\SB@dimen%
5841 \loop%
5842 \[email protected]\SB@dimeniii%
5843 \setbox\SB@box\copy#1%
5844 \setbox\SB@box\vsplit\SB@box to\SB@dimen%
5845 \edef\SB@temp{\splitfirstmarks\SB@cmarkclass}%
5846 \ifx\SB@temp\SB@cmark%
5847 \SB@dimenii\SB@dimen%
5848 \advance\SB@dimen-\SB@dimeniii%
5849 \else%
5850 \advance\SB@dimen\SB@dimeniii%
5851 \fi%
5852 \ifdim\SB@dimeniii>2\p@\repeat%
5853 \setbox\SB@box\vsplit#1to\SB@dimenii%
5854 \global\setbox#1\vbox{%
5855 \unvbox\SB@box\unskip%
5856 \SB@inversefalse\SB@prevversetrue\SB@stanzabreak%
5857 \SB@putbox\unvcopy\SB@chorusbox%
5858 \SB@inversetrue\SB@prevversefalse\SB@stanzabreak%
5859 \unvbox#1%
5860 }%
5861 % \end{macrocode}
5862 % However, if the first mark is a |\SB@lastcmark|, it means that this chorus
5863 % should go after the last verse in the song.
5864 % There is no valid breakpoint there, so to get a chorus into that spot, we
5865 % have to do a rather ugly hack:
5866 % We pull the bottom material off the box with |\unskip|, |\unpenalty|, and
5867 % |\lastbox|, then insert the chorus, then put the bottom material back on.
5868 % This works because the high-level structure of the bottom material should
5869 % be static.
5870 % Even if the user redefines |\makepostlude|, the new definition gets put
5871 % in a single box that can be manipulated with |\lastbox|.
5872 % However, if we ever change the high-level structure, we need to remember to
5873 % change this code accordingly.
5874 % \begin{macrocode}
5875 \else\ifx\SB@temp\SB@lastcmark%
5876 \global\setbox#1\vbox{%
5877 \unvbox#1%
5878 \unskip%
5879 \ifdim\sbarheight>\z@%
5880 \setbox\SB@box\lastbox%
5881 \unskip\unpenalty%
5882 \fi%
5883 \setbox\SB@box\lastbox%
5884 \unskip\unskip%
5885 \SB@inversefalse\SB@prevversetrue\SB@stanzabreak%
5886 \marks\SB@nocmarkclass{\SB@nocmark}%
5887 \unvcopy\SB@chorusbox%
5888 \vskip\versesep\vskip\beforepostludeskip\relax%
5889 \nointerlineskip\box\SB@box%
5890 \ifdim\sbarheight>\z@%
5891 \nobreak\vskip2\p@\@plus\p@%
5892 \hrule\@height\sbarheight\@width\SB@colwidth%
5893 \fi%
5894 }%
5895 \fi\fi%
5896 \fi%
5897 }}
5898 % \end{macrocode}
5899 % \end{macro}
5900 %
5901 % \begin{macro}{\nextcol}\MainImpl{nextcol}
5902 % End the current column (inserting vertical space as needed).
5903 % This differs from column breaks produced with |\brk|, which does not
5904 % introduce any empty vertical space.
5905 % \begin{macrocode}
5906 \newcommand\nextcol{%
5907 \@ifstar{\SB@nextcol\@ne\@flushglue}%
5908 {\ifpartiallist\else\SB@nextcol\@ne\@flushglue\fi}%
5909 }
5910 % \end{macrocode}
5911 % \end{macro}
5912 %
5913 % \begin{macro}{\sclearpage}\MainImpl{sclearpage}
5914 % Move to the next page if the current page is nonempty.
5915 % \begin{macrocode}
5916 \newcommand\sclearpage{%
5917 \@ifstar\SB@clearpage{\ifpartiallist\else\SB@clearpage\fi}%
5918 }
5919 % \end{macrocode}
5920 % \end{macro}
5921 %
5922 % \begin{macro}{\scleardpage}\MainImpl{scleardpage}
5923 % Move to the next even-numbered page if the current page is odd or nonempty.
5924 % \begin{macrocode}
5925 \newcommand\scleardpage{%
5926 \@ifstar\SB@cleardpage{\ifpartiallist\else\SB@cleardpage\fi}%
5927 }
5928 % \end{macrocode}
5929 % \end{macro}
5930 %
5931 % \subsection{Songs}
5932 %
5933 % The following macros handle the parsing and formatting of the material that
5934 % begins and ends each song.
5935 %
5936 % \begin{macro}{\SB@lop}
5937 % \begin{macro}{\SB@@lop}
5938 % \begin{macro}{\SB@emptylist}
5939 % \begin{macro}{\SB@ifempty}
5940 % The following macros were adapted from Donald Knuth's \emph{The \TeX book},
5941 % for manipulating lists of the form
5942 % {\it |\\|item1|\\|item2|\\|...|\\|itemN|\\|}.
5943 % \begin{macrocode}
5944 \newcommand\SB@lop[1]{\expandafter\SB@@lop\the#1\SB@@lop#1}
5945 \newcommand\SB@@lop{}
5946 \def\SB@@lop\\#1\\#2\SB@@lop#3#4{\global#3{\\#2}\global#4{#1}}
5947 \newcommand*\SB@emptylist{\\}
5948 \newcommand\SB@ifempty[3]{%
5949 \edef\SB@temp{\the#1}%
5950 \ifx\SB@temp\SB@emptylist#2\else#3\fi%
5951 }
5952 % \end{macrocode}
5953 % \end{macro}
5954 % \end{macro}
5955 % \end{macro}
5956 % \end{macro}
5957 %
5958 % \begin{macro}{\SB@titlelist}
5959 % \begin{macro}{\SB@titletail}
5960 % These registers hold the full list of titles for the current song and
5961 % the tail list of titles that has not yet been iterated over.
5962 % \begin{macrocode}
5963 \SB@newtoks\SB@titlelist
5964 \SB@newtoks\SB@titletail
5965 % \end{macrocode}
5966 % \end{macro}
5967 % \end{macro}
5968 %
5969 % \begin{macro}{\songtitle}
5970 % \changes{v1.15}{2005/05/26}{Added song title iterators}
5971 % The |\songtitle| macro will initially hold the primary title of the
5972 % current song.
5973 % The user can iterate over titles using |\nexttitle| or |\foreachtitle|.
5974 % \begin{macrocode}
5975 \newcommand\songtitle{}
5976 % \end{macrocode}
5977 % \end{macro}
5978 %
5979 % \begin{macro}{\resettitles}\MainImpl{resettitles}
5980 % \changes{v1.15}{2005/05/26}{Added.}
5981 % Initialize the title list iterator.
5982 % \begin{macrocode}
5983 \newcommand\resettitles{%
5984 \global\SB@titletail\SB@titlelist%
5985 \nexttitle%
5986 }
5987 % \end{macrocode}
5988 % \end{macro}
5989 %
5990 % \begin{macro}{\nexttitle}\MainImpl{nexttitle}
5991 % \changes{v1.15}{2005/05/26}{Added.}
5992 % Advance the title list iterator to the next title.
5993 % \begin{macrocode}
5994 \newcommand\nexttitle{%
5995 \SB@ifempty\SB@titletail{%
5996 \global\let\songtitle\relax%
5997 }{%
5998 \SB@lop\SB@titletail\SB@toks%
5999 \edef\songtitle{\the\SB@toks}%
6000 }%
6001 }
6002 % \end{macrocode}
6003 % \end{macro}
6004 %
6005 % \begin{macro}{\foreachtitle}\MainImpl{foreachtitle}
6006 % \changes{v1.15}{2005/05/26}{Added.}
6007 % Execute a block of code for each remaining title in the title list.
6008 % \begin{macrocode}
6009 \newcommand\foreachtitle[1]{%
6010 \ifx\songtitle\relax\else%
6011 \loop#1\nexttitle\ifx\songtitle\relax\else\repeat%
6012 \fi%
6013 }
6014 % \end{macrocode}
6015 % \end{macro}
6016 %
6017 % \begin{macro}{\ifSB@insong}
6018 % \begin{macro}{\ifSB@intersong}
6019 % \begin{macro}{\ifSB@inverse}
6020 % \begin{macro}{\ifSB@inchorus}
6021 % To help the user locate errors, keep track of which environments we're inside
6022 % and immediately signal an error if someone tries to use a song command inside
6023 % a scripture quotation, etc.
6024 % \begin{macrocode}
6025 \newif\ifSB@songsenv\SB@songsenvfalse
6026 \newif\ifSB@insong\SB@insongfalse
6027 \newif\ifSB@intersong\SB@intersongfalse
6028 \newif\ifSB@inverse\SB@inversefalse
6029 \newif\ifSB@inchorus\SB@inchorusfalse
6030 % \end{macrocode}
6031 % \end{macro}
6032 % \end{macro}
6033 % \end{macro}
6034 % \end{macro}
6035 %
6036 % \begin{macro}{\SB@closeall}
6037 % If an error is detected using one of the above, the following macro will
6038 % contain a macro sequence sufficient to end the unclosed environment,
6039 % hopefully allowing processing to continue.
6040 % \begin{macrocode}
6041 \newcommand\SB@closeall{}
6042 % \end{macrocode}
6043 % \end{macro}
6044 %
6045 % \begin{macro}{\SB@rawrefs}
6046 % \begin{macro}{\songauthors}\MainImpl{songauthors}
6047 % \begin{macro}{\songcopyright}\MainImpl{songcopyright}
6048 % \begin{macro}{\songlicense}\MainImpl{songlicense}
6049 % The current song's scripture references, authors, copyright info, and
6050 % copyright license information are stored in these macros.
6051 % \begin{macrocode}
6052 \newcommand\SB@rawrefs{}
6053 \newcommand\songauthors{}
6054 \newcommand\songcopyright{}
6055 \newcommand\songlicense{}
6056 % \end{macrocode}
6057 % \end{macro}
6058 % \end{macro}
6059 % \end{macro}
6060 % \end{macro}
6061 %
6062 % \begin{macro}{\songrefs}\MainImpl{songrefs}
6063 % When the user asks for the song's scripture references, rather than give
6064 % them the raw token list that the author entered, we return a prettier
6065 % version in which spaces, dashes, and penalties have been adjusted.
6066 % The prettier version is stored in the following control sequence.
6067 % \begin{macrocode}
6068 \newcommand\songrefs{}
6069 % \end{macrocode}
6070 % \end{macro}
6071 %
6072 % \begin{macro}{\setlicense}\MainImpl{setlicense}
6073 % The user sets the licensing info for the current song with this command.
6074 % \begin{macrocode}
6075 \newcommand\setlicense{\gdef\songlicense}
6076 % \end{macrocode}
6077 % \end{macro}
6078 %
6079 % \begin{macro}{\newsongkey}\MainImpl{newsongkey}
6080 % \begin{macro}{\SB@clearbskeys}
6081 % \changes{v2.0}{2007/06/18}{Added.}
6082 % Defining a new key for |\beginsong| is just like the |keyval| package's
6083 % |\define@key| macro except that we must also define some initializer code
6084 % for each key.
6085 % This provides an opportunity to clear registers before each song.
6086 % (Otherwise when a key wasn't specified, we'd inherit the old values from
6087 % the previous song.)
6088 % \begin{macrocode}
6089 \newcommand\SB@clearbskeys{}
6090 \newcommand\newsongkey[2]{%
6091 \SB@app\gdef\SB@clearbskeys{#2}%
6092 \define@key{beginsong}{#1}%
6093 }
6094 % \end{macrocode}
6095 % \end{macro}
6096 % \end{macro}
6097 %
6098 % Define keys |sr|, |by|, |cr|, |li|, |index|, and |ititle| for scripture
6099 % references, authors, copyright info, licensing info, lyric index entries,
6100 % and alternate title index entries, respectively.
6101 % \begin{macrocode}
6102 \newsongkey{sr}{\def\SB@rawrefs{}\gdef\songrefs{}}
6103 {\def\SB@rawrefs{#1}\SB@parsesrefs{#1}}
6104 \newsongkey{by}{\def\songauthors{}}{\def\songauthors{#1}}
6105 \newsongkey{cr}{\def\songcopyright{}}{\def\songcopyright{#1}}
6106 \newsongkey{li}{\setlicense{}}{\setlicense{#1}}
6107 \newsongkey{index}{}{\indexentry{#1}}
6108 \newsongkey{ititle}{}{\indextitleentry{#1}}
6109 % \end{macrocode}
6110 %
6111 % \begin{environment}{song}\MainEnvImpl{song}
6112 % \begin{macro}{\beginsong}
6113 % \begin{macro}{\SB@@beginsong}
6114 % \begin{macro}{\SB@bsoldfmt}
6115 % \begin{macro}{\SB@@bskvfmt}
6116 % Parse the arguments of a |\beginsong| macro.
6117 % The |\beginsong| macro supports two syntaxes.
6118 % The preferred syntax takes the song title(s) as its first argument and
6119 % an optional keyval list in brackets as its second argument.
6120 % A legacy syntax supports four arguments, all enclosed in braces,
6121 % which are: the title(s), scripture references, authors, and copyright info.
6122 % \begin{macrocode}
6123 \newenvironment{song}{\beginsong}{\SB@endsong}
6124 \newcommand\beginsong[1]{%
6125 \ifSB@insong\SB@errboo\SB@closeall\fi%
6126 \ifSB@intersong\SB@errbor\SB@closeall\fi%
6127 \SB@insongtrue%
6128 \def\SB@closeall{\endsong}%
6129 \SB@parsetitles{#1}%
6130 \global\setbox\SB@songwrites\box\voidb@x%
6131 \SB@clearbskeys%
6132 \@ifnextchar[\SB@bskvfmt\SB@@beginsong%
6133 }
6134 \newcommand\SB@@beginsong{%
6135 \@ifnextchar\bgroup\SB@bsoldfmt\SB@@@beginsong%
6136 }
6137 \newcommand\SB@bsoldfmt[3]{%
6138 \SB@bskvfmt[sr={#1},by={#2},cr={#3}]%
6139 }
6140 \newcommand\SB@bskvfmt{}
6141 \def\SB@bskvfmt[#1]{%
6142 \setkeys{beginsong}{#1}%
6143 \SB@@@beginsong%
6144 }
6145 % \end{macrocode}
6146 % \end{macro}
6147 % \end{macro}
6148 % \end{macro}
6149 % \end{macro}
6150 %
6151 % \begin{macro}{\SB@@@beginsong}
6152 % \changes{v1.12}{2005/05/10}{Redid spacing and page-breaking}
6153 % \changes{v1.14}{2005/05/15}{Improved scripture reference line-breaking}
6154 % \changes{v2.0}{2007/06/18}{Added keyval syntax.}
6155 % Begin typesetting a song.
6156 % Beginning a song involves typesetting the title and other info, adding
6157 % entries to the indexes, and setting up the environment in which verses and
6158 % choruses reside.
6159 % \begin{macrocode}
6160 \newcommand\SB@@@beginsong{%
6161 \global\SB@stanzafalse%
6162 \setbox\SB@chorusbox\box\voidb@x%
6163 \SB@gotchorusfalse%
6164 \setbox\SB@songbox\vbox\bgroup\begingroup%
6165 \ifnum\SB@numcols>\z@\hsize\SB@colwidth\fi%
6166 \leftskip\z@skip\rightskip\z@skip%
6167 \parfillskip\@flushglue\parskip\z@skip%
6168 \SB@raggedright%
6169 \global\SB@transposefactor\z@%
6170 \global\SB@cr@{\\}%
6171 \protected@edef\@currentlabel{\p@songnum\thesongnum}%
6172 \setcounter{versenum}{1}%
6173 \SB@prevversetrue%
6174 \meter44%
6175 \resettitles%
6176 \SB@addtoindexes\songtitle\SB@rawrefs\songauthors%
6177 \nexttitle%
6178 \foreachtitle{\expandafter\SB@addtotitles\expandafter{\songtitle}}%
6179 \resettitles%
6180 \lyricfont\relax%
6181 \SB@setbaselineskip%
6182 }
6183 % \end{macrocode}
6184 % \end{macro}
6185 %
6186 % \begin{macro}{\SB@endsong}
6187 % \changes{v1.12}{2005/05/10}{Redid spacing and page-breaking}
6188 % \changes{v2.0}{2007/06/18}{Removed hyperref dependency}
6189 % Ending a song involves creating the song header (with |\makeprelude|),
6190 % creating the song footer (with |\makepostlude|), and then assembling
6191 % everything together into the |\SB@songbox|.
6192 % The box is then submitted to the page-builder via |\SB@submitsong|.
6193 % We do things this way instead of just contributing material directly
6194 % to the main vertical list because submitting material song by song allows
6195 % for a more sophisticated page-breaking algorithm than is possible with
6196 % \TeX's built-in algorithm.
6197 % \begin{macrocode}
6198 \newcommand\SB@endsong{%
6199 \ifSB@insong%
6200 \ifSB@inverse\SB@erreov\endverse\fi%
6201 \ifSB@inchorus\SB@erreoc\endchorus\fi%
6202 \global\SB@skip\versesep%
6203 \unskip%
6204 \ifrepchorus\ifvoid\SB@chorusbox\else%
6205 \ifSB@prevverse\ifvnumbered%
6206 \marks\SB@cmarkclass{\SB@lastcmark}%
6207 \fi\fi%
6208 \fi\fi%
6209 \endgroup\egroup%
6210 \begingroup%
6211 \ifnum\SB@numcols>\z@%
6212 \hsize\ifpagepreludes\textwidth\else\SB@colwidth\fi%
6213 \fi%
6214 \leftskip\z@skip\rightskip\z@skip%
6215 \parfillskip\@flushglue\parskip\z@skip\parindent\z@%
6216 \global\setbox\SB@envbox\vbox{%
6217 \songmark%
6218 \unvbox\SB@songwrites%
6219 \ifpagepreludes\else\ifdim\sbarheight>\z@%
6220 \hrule\@height\sbarheight\@width\hsize%
6221 \nobreak\vskip5\p@\relax%
6222 \fi\fi%
6223 \resettitles%
6224 \begingroup%
6225 \songtarget{\ifnum\c@section=\z@1\else2\fi}%
6226 {song\theSB@songsnum-\thesongnum}%
6227 \endgroup%
6228 \vbox{\makeprelude}%
6229 \nobreak\vskip\SB@skip%
6230 \vskip\afterpreludeskip\relax%
6231 }%
6232 \ifnum\SB@numcols>\z@\hsize\SB@colwidth\fi%
6233 \global\setbox\SB@songbox\vbox{%
6234 \ifpagepreludes\else\unvbox\SB@envbox\fi%
6235 \unvbox\SB@songbox%
6236 \nobreak\vskip\SB@skip%
6237 \vskip\beforepostludeskip\relax%
6238 \nointerlineskip%
6239 \vbox{\makepostlude}%
6240 \ifdim\sbarheight>\z@%
6241 \nobreak\vskip2\p@\@plus\p@%
6242 \nointerlineskip%
6243 \hbox{\vrule\@height\sbarheight\@width\hsize}%
6244 \fi%
6245 }%
6246 \endgroup%
6247 \SB@insongfalse%
6248 \edef\SB@sgroup{\thesongnum}%
6249 \global\SB@groupcnt\z@%
6250 \ifpagepreludes\SB@submitenv\fi%
6251 \SB@submitsong%
6252 \ifnum\SB@grouplvl=\z@\let\SB@sgroup\@empty\fi%
6253 \stepcounter{songnum}%
6254 \else%
6255 \ifSB@intersong\SB@erreor\SB@closeall%
6256 \else\SB@erreot\fi%
6257 \fi%
6258 }
6259 % \end{macrocode}
6260 % \end{macro}
6261 % \end{environment}
6262 %
6263 % \begin{macro}{\SB@setbaselineskip}
6264 % \changes{v1.22}{2007/05/15}{Added.}
6265 % \changes{v2.1}{2007/08/02}{Fixed to scale better with large font sizes.}
6266 % Set the |\baselineskip| to an appropriate line height.
6267 % \begin{macrocode}
6268 \newcommand\SB@setbaselineskip{%
6269 \SB@dimen\f@size\p@%
6270 \baselineskip\SB@dimen\relax%
6271 \ifchorded%
6272 \setbox\SB@box\hbox{{\printchord{ABCDEFG\shrp\flt/j7}}}%
6273 \advance\baselineskip\ht\SB@box%
6274 \advance\baselineskip2\p@%
6275 \fi%
6276 \ifslides%
6277 \advance\baselineskip.2\SB@dimen\@plus.5\SB@dimen%
6278 \@minus.2\SB@dimen%
6279 \else%
6280 \advance\baselineskip\z@\@plus.1\SB@dimen\relax%
6281 \fi%
6282 \advance\baselineskip\baselineadj%
6283 }
6284 % \end{macrocode}
6285 % \end{macro}
6286 %
6287 % \begin{macro}{\SB@setversesep}
6288 % Set the |\versesep| to an appropriate amount if has not already been
6289 % explicitly set by the user.
6290 % \begin{macrocode}
6291 \newcommand\SB@setversesep{%
6292 \SB@dimen123456789sp%
6293 \edef\SB@temp{\the\SB@dimen}%
6294 \edef\SB@tempii{\the\versesep}%
6295 \ifx\SB@temp\SB@tempii%
6296 \begingroup%
6297 \lyricfont\relax%
6298 \SB@dimen\f@size\p@%
6299 \ifchorded%
6300 \setbox\SB@box\hbox{{\printchord{ABCDEFG\shrp\flt/j7}}}%
6301 \advance\SB@dimen\ht\SB@box%
6302 \fi%
6303 \ifslides%
6304 \global\versesep1.2\SB@dimen\@plus.3\SB@dimen%
6305 \@minus.3\SB@dimen%
6306 \else%
6307 \global\versesep.75\SB@dimen\@plus.25\SB@dimen%
6308 \@minus.13\SB@dimen%
6309 \fi%
6310 \endgroup%
6311 \fi%
6312 }
6313 % \end{macrocode}
6314 % \end{macro}
6315 %
6316 % \begin{macro}{\makeprelude}\MainImpl{makeprelude}
6317 % \changes{v1.15}{2005/05/26}{Added to make song header format customizable.}
6318 % \changes{v2.0}{2007/06/18}{Arguments removed to support keyval syntax.}
6319 % Generate the material that begins each song.
6320 % This macro is invoked at |\endsong| so that its code can access song info
6321 % defined throughout the song.
6322 %
6323 % Note that if you are redefining |\makeprelude|, you can probably replace
6324 % everything below with something much simpler.
6325 % The code below is lengthy because it accommodates all of the many different
6326 % options that various authors may adjust to customize their books.
6327 % If you redefine it, you can replace all of this with smaller, more
6328 % specialized programming that just outputs the prelude format you desire.
6329 % \begin{macrocode}
6330 \newcommand\makeprelude{%
6331 \resettitles%
6332 % \end{macrocode}
6333 % In slides mode, the title, references, and authors are simply centered on
6334 % the page with no song number.
6335 % Only the first of the song titles is included.
6336 % The references and authors only span the middle 50\% of the page, since
6337 % letting them span the whole page width stretches them out too much and makes
6338 % their fine print too hard to read.
6339 % \begin{macrocode}
6340 \ifslides%
6341 \hbox to\hsize{{\hfil\stitlefont\relax\songtitle\hfil}}%
6342 \vskip5\p@%
6343 \hbox to\hsize{%
6344 \hfil%
6345 \vbox{%
6346 \divide\hsize\tw@\parskip\p@\relax%
6347 \centering\small\extendprelude%
6348 }%
6349 \hfil%
6350 }%
6351 \else%
6352 % \end{macrocode}
6353 % In non-slides mode, we write the song number in a shaded box to the left
6354 % (if |\songnumwidth| is positive) and everything else in left-justified
6355 % paragraphs to the right of it (or centered if |\pagepreludes| is on).
6356 % The height of the shaded box that contains the song number depends on
6357 % which is higher: the natural height of the song number, or everything else
6358 % that goes to the right of it.
6359 % To find out which is higher, we start by putting the song number in its
6360 % own box (|\SB@boxii|).
6361 % \begin{macrocode}
6362 \ifdim\songnumwidth>\z@%
6363 \setbox\SB@boxii\hbox{{\SB@colorbox\snumbgcolor{%
6364 \hbox to\songnumwidth{%
6365 \printsongnum{\thesongnum}\hfil%
6366 }%
6367 }}}%
6368 \fi%
6369 % \end{macrocode}
6370 % Now we know the width $w$ of the song number box, so we typeset everything
6371 % else in a box (|\SB@box|) of width $c-w$, where $c$ is the column width.
6372 % (If |\pagepreludes| is on, we instead use width $c-2w$ so that the material
6373 % stays centered on the page.)
6374 % \begin{macrocode}
6375 \setbox\SB@box\vbox{%
6376 \ifdim\songnumwidth>\z@%
6377 \SB@dimen\wd\SB@boxii%
6378 \advance\SB@dimen3\p@%
6379 \ifpagepreludes\multiply\SB@dimen\tw@\fi%
6380 \advance\hsize-\SB@dimen%
6381 \fi%
6382 \ifpagepreludes\centering\else\SB@raggedright\fi%
6383 \offinterlineskip\lineskip\p@%
6384 {\stitlefont\relax%
6385 \songtitle\par%
6386 \nexttitle%
6387 \foreachtitle{(\songtitle)\par}}%
6388 \ifdim\prevdepth=\z@\kern\p@\fi%
6389 \parskip\p@\relax\tiny%
6390 \extendprelude%
6391 \kern\z@%
6392 }%
6393 % \end{macrocode}
6394 % If the song number is being printed (i.e., |\songnumwidth| is positive),
6395 % and its height is greater than the height of the other material, then we
6396 % just put |\SB@boxii| and |\SB@box| side-by-side.
6397 % If the song number is being printed but its height is less, then we
6398 % re-typeset it at height equal to the other material, and place the boxes
6399 % side-by-side.
6400 % Finally, if the song number is not being printed at all, we just unbox
6401 % |\SB@box| onto the vertical list.
6402 % \begin{macrocode}
6403 \ifdim\songnumwidth>\z@%
6404 \hbox{%
6405 \ifdim\ht\SB@boxii>\ht\SB@box%
6406 \box\SB@boxii%
6407 \kern3\p@%
6408 \vtop{\box\SB@box}%
6409 \else%
6410 \SB@colorbox\snumbgcolor{\vbox to\ht\SB@box{{%
6411 \hbox to\songnumwidth{%
6412 \printsongnum{\thesongnum}\hfil%
6413 }\vfil%
6414 }}}%
6415 \kern3\p@%
6416 \box\SB@box%
6417 \fi%
6418 }%
6419 \else%
6420 \unvbox\SB@box%
6421 \fi%
6422 \fi%
6423 }
6424 % \end{macrocode}
6425 % \end{macro}
6426 %
6427 % \begin{macro}{\makepostlude}\MainImpl{makepostlude}
6428 % \changes{v1.15}{2005/05/26}{Added to make song trailer format customizable.}
6429 % \changes{v2.0}{2007/06/18}{Arguments removed to support keyval syntax.}
6430 % Generate the material that ends each song.
6431 % The default implementation just prints the copyright and licensing
6432 % information (if any) as a single, left-justified, non-indentended paragraph
6433 % in fine print.
6434 % \begin{macrocode}
6435 \newcommand\makepostlude{%
6436 \SB@raggedright\baselineskip\z@skip\parskip\z@skip\parindent\z@%
6437 \tiny\extendpostlude%
6438 }
6439 % \end{macrocode}
6440 % \end{macro}
6441 %
6442 % \begin{macro}{\showauthors}\MainImpl{showauthors}
6443 % Display the author information in the prelude.
6444 % This macro is only called by |\extendprelude|, which is only called by
6445 % |\makeprelude|; so if you redefine either of those, you don't need this.
6446 % The default implementation prints the authors in boldface and shortens the
6447 % spacing after periods so that they don't look like ends of sentences.
6448 % \begin{macrocode}
6449 \newcommand\showauthors{%
6450 \setbox\SB@box\hbox{\bfseries\sfcode`.\@m\songauthors}%
6451 \ifdim\wd\SB@box>\z@\unhbox\SB@box\par\fi%
6452 }
6453 % \end{macrocode}
6454 % \end{macro}
6455 %
6456 % \begin{macro}{\showrefs}\MainImpl{showrefs}
6457 % Display the scripture references in the prelude.
6458 % This macro is only called by |\extendprelude|, which is only called by
6459 % |\makeprelude|; so if you redefine either of those, you don't need this.
6460 % The default implementation prints the scripture references in slanted
6461 % (oblique) font.
6462 % \begin{macrocode}
6463 \newcommand\showrefs{%
6464 \setbox\SB@box\hbox{\slshape\songrefs\vphantom,}%
6465 \ifdim\wd\SB@box>\z@\unhbox\SB@box\par\fi%
6466 }
6467 % \end{macrocode}
6468 % \end{macro}
6469 %
6470 % \begin{macro}{\SB@next}
6471 % \begin{macro}{\SB@donext}
6472 % \begin{macro}{\SB@dothis}
6473 % Several macros use |\futurelet| to look ahead in the input stream, and then
6474 % take various actions depending on what is seen.
6475 % In these macros, |\SB@next| is assigned the token seen, |\SB@dothis| is
6476 % assigned the action to be taken on this loop iteration, and |\SB@donext| is
6477 % assigned the action to be taken to continue (or terminate) the loop.
6478 % \begin{macrocode}
6479 \newcommand\SB@next{}
6480 \newcommand\SB@donext{}
6481 \newcommand\SB@dothis{}
6482 % \end{macrocode}
6483 % \end{macro}
6484 % \end{macro}
6485 % \end{macro}
6486 %
6487 % \begin{macro}{\SB@nextname}
6488 % Sometimes when scanning ahead we |\string|ify the name of the next token.
6489 % When that happens, the name is stored in this macro for safekeeping.
6490 % \begin{macrocode}
6491 \newcommand\SB@nextname{}
6492 % \end{macrocode}
6493 % \end{macro}
6494 %
6495 % \begin{macro}{\SB@appendsp}
6496 % Append an explicit space token (catcode 10) to a token register.
6497 % This is a useful macro to have around because inlining this code directly
6498 % into a larger macro is harder than it seems:
6499 % If you write the following code but with an explicit control sequence
6500 % instead of |#1|, then the space immediately following the name will get
6501 % stripped by the \TeX{} parser.
6502 % But invoking the following macro with a control sequence as an argument
6503 % works fine, because in that case the explicit space has already been
6504 % tokenized when this macro was first defined and won't be stripped as it
6505 % is expanded.
6506 % \begin{macrocode*}
6507 \newcommand\SB@appendsp[1]{#1\expandafter{\the#1 }}
6508 % \end{macrocode*}
6509 % \end{macro}
6510 %
6511 % \begin{macro}{\SB@parsetitles}
6512 % \changes{v2.1}{2007/08/02}{Added}
6513 % Parse a list of song titles.
6514 % This just involves removing leading and trailing spaces from around each
6515 % title in the |\\|-separated list.
6516 % \begin{macrocode}
6517 \newcommand\SB@parsetitles[1]{%
6518 \begingroup%
6519 \global\SB@titlelist{\\}%
6520 \SB@toks{}%
6521 \let\\\SB@titlesep%
6522 \SB@pthead#1\SB@endparse%
6523 \endgroup%
6524 }
6525 % \end{macrocode}
6526 % \end{macro}
6527 %
6528 % \begin{macro}{\SB@pthead}
6529 % \begin{macro}{\SB@@pthead}
6530 % \begin{macro}{\SB@@@pthead}
6531 % While processing tokens at the head of a title, we skip over all spaces
6532 % until we reach a non-space token.
6533 % \begin{macrocode}
6534 \newcommand\SB@pthead{\futurelet\SB@next\SB@@pthead}
6535 \newcommand\SB@@pthead{%
6536 \ifcat\noexpand\SB@next\@sptoken%
6537 \expandafter\SB@@@pthead%
6538 \else%
6539 \expandafter\SB@ptmain%
6540 \fi%
6541 }
6542 \newcommand\SB@@@pthead{%
6543 \afterassignment\SB@pthead%
6544 \let\SB@next= }
6545 % \end{macrocode}
6546 % \end{macro}
6547 % \end{macro}
6548 % \end{macro}
6549 %
6550 % \begin{macro}{\SB@ptloop}
6551 % The iterator of the title parser loop just scans the next token.
6552 % \begin{macrocode}
6553 \newcommand\SB@ptloop{\futurelet\SB@next\SB@ptmain}
6554 % \end{macrocode}
6555 % \end{macro}
6556 %
6557 % \begin{macro}{\SB@ptmain}
6558 % Once we've reached a non-space token in the title, we consume the remainder
6559 % of the title as-is, except that space tokens should be trimmed from the end
6560 % of each title.
6561 % \begin{macrocode}
6562 \newcommand\SB@ptmain{%
6563 \ifcat\noexpand\SB@next\@sptoken%
6564 \let\SB@donext\SB@ptsp%
6565 \else\ifcat\noexpand\SB@next\bgroup%
6566 \let\SB@donext\SB@ptbg%
6567 \else\ifx\SB@next\SB@endparse%
6568 \global\SB@titlelist\expandafter{\the\SB@titlelist\\}%
6569 \let\SB@donext\@gobble%
6570 \else\ifx\SB@next\\%
6571 \SB@toks{}%
6572 \def\SB@donext{\SB@ptstep\SB@pthead}%
6573 \else%
6574 \def\SB@donext{\SB@ptstep\SB@ptloop}%
6575 \fi\fi\fi\fi%
6576 \SB@donext}
6577 % \end{macrocode}
6578 % \end{macro}
6579 %
6580 % \begin{macro}{\SB@ptstep}
6581 % Consume a non-space, non-left-brace token and add it to the current song
6582 % title.
6583 % If any spaces preceded it, add those too.
6584 % \begin{macrocode}
6585 \newcommand\SB@ptstep[2]{%
6586 \global\SB@titlelist\expandafter\expandafter\expandafter{%
6587 \expandafter\the\expandafter\SB@titlelist\the\SB@toks#2}%
6588 \SB@toks{}%
6589 #1}
6590 % \end{macrocode}
6591 % \end{macro}
6592 %
6593 % \begin{macro}{\SB@ptbg}
6594 % The next title token is a left-brace.
6595 % It should be balanced, so consume the entire group and add it (along with
6596 % its surrounding braces) as-is to the current title.
6597 % \begin{macrocode}
6598 \newcommand\SB@ptbg[1]{\SB@ptstep\SB@ptloop{{#1}}}
6599 % \end{macrocode}
6600 % \end{macro}
6601 %
6602 % \begin{macro}{\SB@ptsp}
6603 % The next title token is a space.
6604 % We won't know whether to include it in the title until we see what
6605 % follows it.
6606 % Strings of spaces followed by the |\\| title-delimiter token, or that
6607 % conclude a title argument, should be stripped.
6608 % So rather than add the space token to the title, we remember it in a
6609 % token register for possible later inclusion.
6610 % \begin{macrocode}
6611 \newcommand\SB@ptsp{
6612 \SB@appendsp\SB@toks%
6613 \afterassignment\SB@ptloop%
6614 \let\SB@next= }
6615 % \end{macrocode}
6616 % \end{macro}
6617 %
6618 % \begin{macro}{\SB@titlesep}
6619 % While parsing song titles, we temporarily assign |\\| a non-trivial
6620 % top-level expansion (|\SB@titlesep|) in order to distinguish it from
6621 % other macros.
6622 % \begin{macrocode}
6623 \newcommand\SB@titlesep{SB@titlesep}
6624 % \end{macrocode}
6625 % \end{macro}
6626 %
6627 % \begin{macro}{\SB@endparse}
6628 % The |\SB@endparse| token marks the end of a token sequence being parsed.
6629 % If parsing works as intended, the macro should never be expanded, so
6630 % produce an error if it is.
6631 % \begin{macrocode}
6632 \newcommand\SB@endparse{%
6633 \SB@Error{Title parsing failed}{This error should not occur.}%
6634 }
6635 % \end{macrocode}
6636 % \end{macro}
6637 %
6638 % \begin{macro}{\SB@parsesrefs}
6639 % \changes{v1.14}{2005/05/15}{Added}
6640 % Assign the |\songrefs| macro a processed version of a scripture reference in
6641 % which the following adjustments have been made:
6642 % (1)~Spaces not preceded by a comma or semicolon are made non-breaking.
6643 % For example, |2 John 1:1| and |Song of Solomon 1:1| become |2~John~1:1| and
6644 % |Song~of~Solomon~1:1|, respectively.
6645 % (2)~Spaces between a semicolon and a book name are lengthened to en-spaces.
6646 % (3)~Single hyphens are lengthened to en-dashes (|--|).
6647 % (4)~Non-breaking, thin spaces are appended to commas not followed by a
6648 % space. For example |John 3:16,17| becomes |John~3:16,\nobreak\thinspace17|.
6649 % (5)~Everything within an explicit group is left unchanged, allowing the
6650 % user to suppress all of the above as desired.
6651 %
6652 % To achieve this, we must change all commas, hyphens, and spaces
6653 % in the scripture reference into active characters.
6654 % Unfortunately, the catcodes of everything in the text were set back when
6655 % the full keyval list was digested as an argument to |\beginsong|, so we
6656 % must unset and reset the catcodes.
6657 % One obvious solution is to use |\scantokens| from $\varepsilon$-\TeX{} to
6658 % do this, but that doesn't allow us to suppress the re-catcoding process
6659 % within groups, and we'd like to avoid intoducing features that require
6660 % $\varepsilon$-\TeX{} anyway for compatibility reasons.
6661 % Therefore, we build the following small scanner instead.
6662 %
6663 % The scanner walks through the text token by token, replacing each important
6664 % token by its active equivalent.
6665 % No character codes are modified during this process and no tokens are
6666 % inserted because some of these tokens might end up being arguments to
6667 % multi-byte unicode character macros rather than being expanded directly.
6668 % The |inputenc| package only cares about the character codes, not the
6669 % category codes, so modifying only the category codes should be safe.
6670 % \begin{macrocode}
6671 \newcommand\SB@parsesrefs[1]{%
6672 \begingroup%
6673 \SB@toks{\begingroup\SB@sractives}%
6674 \SB@prloop#1\SB@endparse%
6675 \xdef\songrefs{\the\SB@toks\endgroup}%
6676 \endgroup%
6677 }
6678 % \end{macrocode}
6679 % \end{macro}
6680 %
6681 % \begin{macro}{\SB@prloop}
6682 % \begin{macro}{\SB@prstep}
6683 % \begin{macro}{\SB@@prstep}
6684 % The main loop of the scripture reference scanner identifies each space,
6685 % hyphen, and comma for special treatment.
6686 % \begin{macrocode}
6687 \newcommand\SB@prloop{\futurelet\SB@next\SB@prstep}
6688 \newcommand\SB@prstep{%
6689 \ifcat\noexpand\SB@next A%
6690 \expandafter\SB@prcpy%
6691 \else%
6692 \expandafter\SB@@prstep%
6693 \fi%
6694 }
6695 \newcommand\SB@@prstep{%
6696 \ifcat\noexpand\SB@next\@sptoken%
6697 \let\SB@donext\SB@prspace%
6698 \else\ifx\SB@next-%
6699 \let\SB@donext\SB@prhyphen%
6700 \else\ifx\SB@next,%
6701 \let\SB@donext\SB@prcomma%
6702 \else\ifx\SB@next\SB@endparse%
6703 \let\SB@donext\@gobble%
6704 \else\ifcat\noexpand\SB@next\bgroup%
6705 \let\SB@donext\SB@prgr%
6706 \else%
6707 \let\SB@donext\SB@prcpy%
6708 \fi\fi\fi\fi\fi%
6709 \SB@donext%
6710 }
6711 % \end{macrocode}
6712 % \end{macro}
6713 % \end{macro}
6714 % \end{macro}
6715 %
6716 % \begin{macro}{\SB@prcpy}
6717 % \begin{macro}{\SB@prgr}
6718 % Anything that isn't one of the special tokens above, and anything in a
6719 % group, is copied without modification.
6720 % \begin{macrocode}
6721 \newcommand\SB@prcpy[1]{\SB@toks\expandafter{\the\SB@toks#1}\SB@prloop}
6722 \newcommand\SB@prgr[1]{\SB@toks\expandafter{\the\SB@toks{#1}}\SB@prloop}
6723 % \end{macrocode}
6724 % \end{macro}
6725 % \end{macro}
6726
6727 % \begin{macro}{\SB@prcomma}
6728 % \begin{macro}{\SB@prhyphen}
6729 % Commas and hyphens are replaced with active equivalents.
6730 % \begin{macrocode}
6731 \newcommand\SB@prcomma[1]{}
6732 {\catcode`,\active
6733 \gdef\SB@prcomma#1{\SB@toks\expandafter{\the\SB@toks,}\SB@prloop}}
6734 \newcommand\SB@prhyphen[1]{}
6735 {\catcode`-\active
6736 \gdef\SB@prhyphen#1{\SB@toks\expandafter{\the\SB@toks-}\SB@prloop}}
6737 % \end{macrocode}
6738 % \end{macro}
6739 % \end{macro}
6740 %
6741 % \begin{macro}{\SB@prspace}
6742 % \begin{macro}{\SB@@prspace}
6743 % Spaces are made active as well, but doing so requires some
6744 % specialized code since they cannot be consumed as implicit macro arguments.
6745 % \begin{macrocode*}
6746 \newcommand\SB@prspace[1]{}
6747 {\obeyspaces
6748 \gdef\SB@prspace{\SB@toks\expandafter{\the\SB@toks }\SB@@prspace}}
6749 % \end{macrocode*}
6750 % \begin{macrocode}
6751 \newcommand\SB@@prspace{\afterassignment\SB@prloop\let\SB@temp= }
6752 % \end{macrocode}
6753 % \end{macro}
6754 % \end{macro}
6755
6756 % \begin{macro}{\SB@sractives}
6757 % Assign macro definitions to active commas, hyphens, spaces, and returns
6758 % when the token list generated by |\SB@parsesrefs| is used to typeset a
6759 % scripture reference list.
6760 % \begin{macrocode*}
6761 \newcommand\SB@sractives{}
6762 {\catcode`,\active\catcode`-\active\obeyspaces%
6763 \gdef\SB@sractives{%
6764 \let,\SB@srcomma\let-\SB@srhyphen\let \SB@srspace%
6765 \SB@srspacing}%
6766 }
6767 % \end{macrocode*}
6768 % \end{macro}
6769 %
6770 % \begin{macro}{\SB@srspacing}
6771 % The space factors of semicolons and commas are what the active spaces
6772 % within a scripture reference text use to decide what came before.
6773 % The following sets them to their default values in case they have been
6774 % changed, but sets all other space factors to 1000.
6775 % \begin{macrocode}
6776 \newcommand\SB@srspacing{%
6777 \nonfrenchspacing\sfcode`\;=1500\sfcode`\,=1250\relax%
6778 }
6779 % \end{macrocode}
6780 % \end{macro}
6781 %
6782 % \begin{macro}{\SB@srcomma}
6783 % \begin{macro}{\SB@@srcomma}
6784 % Commas not already followed by whitespace are appended with a thin,
6785 % non-breaking space.
6786 % \begin{macrocode}
6787 \newcommand\SB@srcomma{,\futurelet\SB@next\SB@@srcomma}
6788 \newcommand\SB@@srcomma{%
6789 \ifx\SB@next\SB@srspace\else%
6790 \nobreak\thinspace%
6791 \fi%
6792 }
6793 % \end{macrocode}
6794 % \end{macro}
6795 % \end{macro}
6796 %
6797 % \begin{macro}{\SB@srhyphen}
6798 % \begin{macro}{\SB@@srhyphen}
6799 % \begin{macro}{\SB@srdash}
6800 % \begin{macro}{\SB@@srdash}
6801 % Hyphens that are not already part of a ligature (an en- or em-dash)
6802 % become en-dashes.
6803 % \begin{macrocode}
6804 \newcommand\SB@srhyphen{\futurelet\SB@next\SB@@srhyphen}
6805 \newcommand\SB@@srhyphen{%
6806 \ifx\SB@next\SB@srhyphen\expandafter\SB@srdash\else--\fi%
6807 }
6808 \newcommand\SB@srdash[1]{\futurelet\SB@next\SB@@srdash}
6809 \newcommand\SB@@srdash{%
6810 \ifx\SB@next\SB@srhyphen---\expandafter\@gobble\else--\fi%
6811 }
6812 % \end{macrocode}
6813 % \end{macro}
6814 % \end{macro}
6815 % \end{macro}
6816 % \end{macro}
6817 %
6818 % \begin{macro}{\SB@srspace}
6819 % \begin{macro}{\SB@@srspace}
6820 % To compress consecutive whitespace, we ignore spaces
6821 % immediately followed by more whitespace.
6822 % Spaces not preceded by a semicolon or comma become non-breaking.
6823 % Most spaces following a semicolon become en-spaces with favorable
6824 % breakpoints, but a special case arises for spaces between a semicolon
6825 % and a digit (see |\SB@srcso| below).
6826 % \begin{macrocode}
6827 \newcommand\SB@srspace{\futurelet\SB@next\SB@@srspace}
6828 \newcommand\SB@@srspace{%
6829 \let\SB@donext\relax%
6830 \ifx\SB@next\SB@srspace\else%
6831 \ifnum\spacefactor>\@m%
6832 \ifnum\spacefactor>1499 %
6833 \ifcat\noexpand\SB@next0%
6834 \let\SB@donext\SB@srcso%
6835 \else%
6836 \penalty-5\enskip%
6837 \fi%
6838 \else%
6839 \space%
6840 \fi%
6841 \else%
6842 \nobreak\space%
6843 \fi%
6844 \fi%
6845 \SB@donext%
6846 }
6847 % \end{macrocode}
6848 % \end{macro}
6849 % \end{macro}
6850 %
6851 % \begin{macro}{\SB@srcso}
6852 % \begin{macro}{\SB@@srcso}
6853 % A space between a semicolon and a digit could be within a list of
6854 % verse references for a common book (e.g., |Job 1:1; 2:2|);
6855 % or it could separate the previous book from a new book whose name
6856 % starts with a number (e.g., |Job 1:1; 1 John 1:1|).
6857 % In the former case, we should just use a regular space;
6858 % but in the latter case we should be using an en-space with a
6859 % favorable breakpoint.
6860 % To distinguish between the two, we peek ahead at the next two tokens.
6861 % If the second one is a space, assume the latter; otherwise assume the
6862 % former.
6863 % \begin{macrocode}
6864 \newcommand\SB@srcso[1]{\futurelet\SB@temp\SB@@srcso}
6865 \newcommand\SB@@srcso{%
6866 \ifx\SB@temp\SB@srspace%
6867 \penalty-5\enskip%
6868 \else%
6869 \space%
6870 \fi%
6871 \SB@next%
6872 }
6873 % \end{macrocode}
6874 % \end{macro}
6875 % \end{macro}
6876 %
6877 % \subsection{Verses and Choruses}
6878 %
6879 % The following programming typesets song contents, including verses, choruses,
6880 % and textual notes.
6881 %
6882 % \begin{macro}{\ifSB@stanza}
6883 % The following conditional remembers if we've seen any stanzas yet in the
6884 % current song.
6885 % \begin{macrocode}
6886 \newif\ifSB@stanza
6887 % \end{macrocode}
6888 % \end{macro}
6889 %
6890 % \begin{macro}{\SB@stanzabreak}
6891 % \changes{v1.12}{2005/05/10}{Fixed stanza counting code and improved spacing}
6892 % End this song stanza and start a new one.
6893 % \begin{macrocode}
6894 \newcommand\SB@stanzabreak{%
6895 \ifhmode\par\fi%
6896 \ifSB@stanza%
6897 \SB@breakpoint{%
6898 \ifSB@inverse%
6899 \ifSB@prevverse\vvpenalty\else\cvpenalty\fi%
6900 \else%
6901 \ifSB@prevverse\vcpenalty\else\ccpenalty\fi%
6902 \fi%
6903 }%
6904 \vskip\versesep%
6905 \fi%
6906 }
6907 % \end{macrocode}
6908 % \end{macro}
6909 %
6910 % \begin{macro}{\SB@breakpoint}
6911 % Insert a valid breakpoint into the vertical list comprising a song.
6912 % \begin{macrocode}
6913 \newcommand\SB@breakpoint[1]{%
6914 \begingroup%
6915 \ifnum#1<\@M%
6916 \SB@skip\colbotglue\relax%
6917 \SB@skip-\SB@skip%
6918 \else%
6919 \SB@skip\z@skip%
6920 \fi%
6921 \advance\SB@skip\lastskip%
6922 \unskip%
6923 \nobreak%
6924 \ifnum#1<\@M%
6925 \vskip\colbotglue\relax%
6926 \penalty#1%
6927 \fi%
6928 \vskip\SB@skip%
6929 \endgroup%
6930 }
6931 % \end{macrocode}
6932 % \end{macro}
6933 %
6934 % \begin{macro}{\SB@putbox}
6935 % Unbox a vbox and follow it by vertical glue if its depth is unusually
6936 % shallow.
6937 % This ensures that verses and choruses will look equally spaced even if
6938 % one of them has a final line with no descenders.
6939 % \begin{macrocode}
6940 \newcommand\SB@putbox[2]{%
6941 \begingroup%
6942 \SB@dimen\dp#2%
6943 #1#2%
6944 \setbox\SB@box\hbox{{\lyricfont\relax p}}%
6945 \ifdim\SB@dimen<\dp\SB@box%
6946 \advance\SB@dimen-\dp\SB@box%
6947 \vskip-\SB@dimen%
6948 \fi%
6949 \setbox\SB@box\box\voidb@x%
6950 \endgroup%
6951 }
6952 % \end{macrocode}
6953 % \end{macro}
6954 %
6955 % \begin{macro}{\SB@obeylines}
6956 % Within verses and choruses we would like to use |\obeylines| so that each
6957 % \Meta{return} in the source file ends a paragraph without having to say
6958 % |\par| explicitly.
6959 % The \LaTeX{} base code establishes the convention that short-term changes to
6960 % |\par| will restore |\par| by setting it equal to |\@par|.
6961 % Long-term (i.e., environment-long) changes to |\par| should therefore
6962 % redefine |\@par| to restore the desired long-term definition.
6963 % The following code starts a long-term redefinition of |\par| adhering to
6964 % these conventions, and extends that definition to \Meta{return} as well.
6965 % \begin{macrocode}
6966 \newcommand\SB@obeylines{%
6967 \let\par\SB@par%
6968 \obeylines%
6969 \let\@par\SB@@par%
6970 }
6971 % \end{macrocode}
6972 % \end{macro}
6973 %
6974 % \begin{macro}{\SB@par}
6975 % The following replacement definition of |\par| constructs paragraphs in
6976 % which page-breaks are disallowed, since no wrapped line in a song should
6977 % span a page- or column-break.
6978 % It then inserts an interlinepenalty after the paragraph so that such
6979 % penalties will appear between consecutive lines in each verse.
6980 % (Note: The |\endgraf| macro must not be uttered within a local group
6981 % since this prevents parameters like |\hangindent| from being
6982 % reset at the conclusion of each paragraph.)
6983 % \begin{macrocode}
6984 \newcommand\SB@par{%
6985 \ifhmode%
6986 \SB@cnt\interlinepenalty%
6987 \interlinepenalty\@M%
6988 \endgraf%
6989 \interlinepenalty\SB@cnt%
6990 \ifSB@inchorus%
6991 \ifdim\cbarwidth>\z@\nobreak\else\SB@ilpenalty\fi%
6992 \else%
6993 \SB@ilpenalty%
6994 \fi%
6995 \fi%
6996 }
6997 % \end{macrocode}
6998 % \end{macro}
6999 %
7000 % \begin{macro}{\SB@ilpenalty}
7001 % By default, breaking a vertical list between paragraphs incurs a penalty
7002 % of zero.
7003 % Thus, we only insert an explicit penalty between lines if
7004 % |\interlinepenalty| is non-zero.
7005 % This avoids cluttering the vertical list with superfluous zero penalties.
7006 % \begin{macrocode}
7007 \newcommand\SB@ilpenalty{%
7008 \ifnum\interlinepenalty=\z@\else%
7009 \penalty\interlinepenalty%
7010 \fi%
7011 }
7012 % \end{macrocode}
7013 % \end{macro}
7014 %
7015 % \begin{macro}{\SB@@par}
7016 % This replacement definition of |\@par| restores the |\SB@par| definition of
7017 % |\par| and then ends the paragraph.
7018 % \begin{macrocode}
7019 \newcommand\SB@@par{\let\par\SB@par\par}
7020 % \end{macrocode}
7021 % \end{macro}
7022 %
7023 % \begin{macro}{\SB@parindent}
7024 % \changes{v1.12}{2005/05/10}{Added}
7025 % Reserve a length to remember the current |\parindent|.
7026 % \begin{macrocode}
7027 \SB@newdimen\SB@parindent
7028 % \end{macrocode}
7029 % \end{macro}
7030 %
7031 % \begin{macro}{\SB@everypar}
7032 % Reserve a control sequence to hold short-term changes to |\everypar|.
7033 % \begin{macrocode}
7034 \newcommand\SB@everypar{}
7035 % \end{macrocode}
7036 % \end{macro}
7037 %
7038 % \begin{macro}{\SB@raggedright}
7039 % \changes{v1.12}{2005/05/10}{Added}
7040 % Perform |\raggedright| except don't nuke the |\parindent|.
7041 % \begin{macrocode}
7042 \newcommand\SB@raggedright{%
7043 \SB@parindent\parindent%
7044 \raggedright%
7045 \parindent\SB@parindent%
7046 }
7047 % \end{macrocode}
7048 % \end{macro}
7049 %
7050 % \begin{macro}{\vnumbered}
7051 % \changes{v2.1}{2007/08/02}{Renamed.}
7052 % The following conditional remembers whether this verse is being numbered
7053 % or not (i.e., it distinguishes between |\beginverse| and |\beginverse*|).
7054 % \begin{macrocode}
7055 \newif\ifvnumbered
7056 % \end{macrocode}
7057 % \end{macro}
7058 %
7059 % \begin{macro}{\ifSB@prevverse}
7060 % Reserve a conditional to remember if the previous block in this song was
7061 % a verse.
7062 % \begin{macrocode}
7063 \newif\ifSB@prevverse
7064 % \end{macrocode}
7065 % \end{macro}
7066 %
7067 % Before replacing the little-used |verse| environment with a new one,
7068 % issue a warning if the current definition of |\verse| is not the
7069 % \LaTeX-default one.
7070 % This may indicate a package clash.
7071 % \begin{macrocode}
7072 \CheckCommand\verse{%
7073 \let\\\@centercr%
7074 \list{}{%
7075 \itemsep\z@%
7076 \itemindent-1.5em%
7077 \listparindent\itemindent%
7078 \rightmargin\leftmargin%
7079 \advance\leftmargin1.5em%
7080 }%
7081 \item\relax%
7082 }
7083 % \end{macrocode}
7084 %
7085 % \begin{environment}{verse}\MainEnvImpl{verse}
7086 % \begin{environment}{verse*}
7087 % \begin{macro}{\beginverse}
7088 % Begin a new verse.
7089 % This can be done by beginning a |verse| environment or by using the
7090 % |\beginverse| macro.
7091 % The latter must check for a trailing star to determine whether this
7092 % verse should be numbered.
7093 % We use |\@ifstar| to scan ahead for the star, but this needs to be done
7094 % carefully because while scanning we might encounter tokens that
7095 % should be assigned different catcodes once the verse really begins.
7096 % Thus, we temporarily invoke |\SB@loadactives| for the duration of
7097 % |\@ifstar| so that everything gets the right catcode.
7098 % \begin{macrocode}
7099 \renewenvironment{verse}
7100 {\vnumberedtrue\SB@beginverse}
7101 {\SB@endverse}
7102 \newenvironment{verse*}
7103 {\vnumberedfalse\SB@beginverse}
7104 {\SB@endverse}
7105 \newcommand\beginverse{%
7106 \begingroup%
7107 \SB@loadactives%
7108 \@ifstar{\endgroup\vnumberedfalse\SB@beginverse}%
7109 {\endgroup\vnumberedtrue\SB@beginverse}%
7110 }
7111 % \end{macrocode}
7112 % \end{macro}
7113 % \end{environment}
7114 % \end{environment}
7115 %
7116 % \begin{macro}{\SB@beginverse}
7117 % \changes{v1.12}{2005/05/10}{Shifted to using \cs{parindent} instead of \cs{everypar} to do indentation}
7118 % Start the body of a verse.
7119 % We begin by inserting a mark if |\repchoruses| is active and this verse
7120 % was preceded by a numbered verse (making this an eligible place to insert
7121 % a chorus later).
7122 %
7123 % Verse numbering is implemented using |\everypar| so that if there is any
7124 % vertical material between the |\beginverse| and the first line of the
7125 % verse, that material will come before the verse number.
7126 % Intervening horizontal material (e.g., |\textnote|) can temporarily
7127 % clear |\everypar| to defer the verse number until later.
7128 % \begin{macrocode}
7129 \newcommand\SB@beginverse{%
7130 \ifSB@insong%
7131 \ifSB@inverse\SB@errbvv\endverse\fi%
7132 \ifSB@inchorus\SB@errbvc\endchorus\fi%
7133 \else%
7134 \SB@errbvt\beginsong{Unknown Song}%
7135 \fi%
7136 \ifrepchorus\ifvoid\SB@chorusbox\else%
7137 \SB@gotchorustrue%
7138 \ifSB@prevverse\ifvnumbered%
7139 \marks\SB@cmarkclass{\SB@cmark}%
7140 \fi\fi%
7141 \fi\fi%
7142 \SB@inversetrue%
7143 \def\SB@closeall{\endverse\endsong}%
7144 \SB@stanzabreak%
7145 \versemark\nobreak%
7146 \global\SB@stanzatrue%
7147 \SB@ifempty\SB@cr@\memorize{\replay[]}%
7148 \setbox\SB@box\vbox\bgroup\begingroup%
7149 \ifvnumbered%
7150 \protected@edef\@currentlabel{\p@versenum\theversenum}%
7151 \def\SB@everypar{%
7152 \setbox\SB@box\hbox{{\printversenum{\theversenum}}}%
7153 \ifdim\wd\SB@box<\versenumwidth%
7154 \setbox\SB@box%
7155 \hbox to\versenumwidth{\unhbox\SB@box\hfil}%
7156 \fi%
7157 \ifchorded\vrule\@height\baselineskip\@width\z@\@depth\z@\fi%
7158 \placeversenum\SB@box%
7159 \gdef\SB@everypar{}%
7160 }%
7161 \else%
7162 \def\SB@everypar{%
7163 \ifchorded\vrule\@height\baselineskip\@width\z@\@depth\z@\fi%
7164 \gdef\SB@everypar{}%
7165 }%
7166 \fi%
7167 \everypar{\SB@everypar\everypar{}}%
7168 \versefont\relax\SB@setbaselineskip\versejustify%
7169 \SB@loadactives%
7170 \SB@obeylines%
7171 \penalty12345 %
7172 \everyverse\relax%
7173 }
7174 % \end{macrocode}
7175 % \end{macro}
7176 %
7177 % \begin{macro}{\SB@endverse}
7178 % End a verse.
7179 % This involves unboxing the verse material with |\SB@putbox|, which
7180 % corrects for last lines that are unusually shallow.
7181 % \begin{macrocode}
7182 \newcommand\SB@endverse{%
7183 \ifSB@insong%
7184 \ifSB@inverse%
7185 \unpenalty%
7186 \endgroup\egroup%
7187 \SB@putbox\unvbox\SB@box%
7188 \SB@inversefalse%
7189 \def\SB@closeall{\endsong}%
7190 \ifvnumbered\stepcounter{versenum}\fi%
7191 \SB@prevversetrue%
7192 \else\ifSB@inchorus\SB@errevc\endchorus%
7193 \else\SB@errevo\fi\fi%
7194 \else%
7195 \SB@errevt%
7196 \fi%
7197 }
7198 % \end{macrocode}
7199 % \end{macro}
7200 %
7201 % \begin{macro}{\ifSB@chorustop}
7202 % When a chorus is broken in to several pieces by column-breaks (via |\brk|),
7203 % the following conditional remembers whether the current piece is the
7204 % topmost one for this chorus.
7205 % \begin{macrocode}
7206 \newif\ifSB@chorustop
7207 % \end{macrocode}
7208 % \end{macro}
7209 %
7210 % \begin{macro}{\SB@chorusbox}
7211 % When |\repchoruses| is used, the first sequence of consecutive choruses
7212 % is remembered in the following box register.
7213 % \begin{macrocode}
7214 \SB@newbox\SB@chorusbox
7215 % \end{macrocode}
7216 % \end{macro}
7217 %
7218 % \begin{macro}{\ifSB@gotchorus}
7219 % The following conditional remembers whether we've completed storing the
7220 % first block of consecutive choruses.
7221 % \begin{macrocode}
7222 \newif\ifSB@gotchorus
7223 % \end{macrocode}
7224 % \end{macro}
7225 %
7226 % \begin{macro}{\SB@cmarkclass}
7227 % \begin{macro}{\SB@nocmarkclass}
7228 % \changes{v2.6}{2008/02/14}{Added safe allocation of extended mark registers}
7229 % The |\repeatchoruses| feature requires the use of two extended mark
7230 % classes provided by $\varepsilon$-\TeX.
7231 % We use the |\newmarks| macro to allocate these classes, if it's
7232 % available.
7233 % If |\newmarks| doesn't exist, then that means the user has an
7234 % $\varepsilon$-\TeX{} compatible version of \LaTeX, but no |etex| style
7235 % file to go with it;
7236 % we just have to pick two mark classes and hope that nobody else is
7237 % using them.
7238 % \begin{macrocode}
7239 \ifSB@etex
7240 \@ifundefined{newmarks}{
7241 \@ifundefined{newmark}{
7242 \mathchardef\SB@cmarkclass83
7243 \mathchardef\SB@nocmarkclass84
7244 }{
7245 \newmark\SB@cmarkclass
7246 \newmark\SB@nocmarkclass
7247 }
7248 }{
7249 \newmarks\SB@cmarkclass
7250 \newmarks\SB@nocmarkclass
7251 }
7252 \fi
7253 % \end{macrocode}
7254 % \end{macro}
7255 % \end{macro}
7256 %
7257 % \begin{macro}{\SB@cmark}
7258 % \begin{macro}{\SB@lastcmark}
7259 % \begin{macro}{\SB@nocmark}
7260 % To determine where choruses should be inserted when |\repchoruses| is
7261 % active, three kinds of marks are inserted into song boxes:
7262 % |\SB@cmark| is used to mark places where a chorus might be inserted between
7263 % verses, and |\SB@lastcmark| marks a place where a chorus might be inserted
7264 % after the last verse of the song.
7265 % Both marks are $\varepsilon$-\TeX{} marks of class |\SB@cmarkclass|,
7266 % to avoid disrupting the use of standard \TeX{} marks.
7267 % Each time a chorus is automatically inserted, |\SB@nocmark| is inserted
7268 % with mark class |\SB@nocmarkclass| just above it (and at the top of each
7269 % additional page it spans).
7270 % This inhibits future chorus inserts until the already-inserted chorus has
7271 % been fully committed to the output file.
7272 % Otherwise some choruses could get auto-inserted multiple times at the same
7273 % spot, possibly even leading to an infinite loop!
7274 % \begin{macrocode}
7275 \newcommand*\SB@cmark{SB@cmark}
7276 \newcommand*\SB@lastcmark{SB@lastcmark}
7277 \newcommand*\SB@nocmark{SB@nocmark}
7278 % \end{macrocode}
7279 % \end{macro}
7280 % \end{macro}
7281 % \end{macro}
7282 %
7283 % \begin{environment}{chorus}\MainEnvImpl{chorus}
7284 % \begin{macro}{\beginchorus}
7285 % \changes{v1.12}{2005/05/10}{Shifted to using \cs{parindent} instead of \cs{everypar} to do indentation}
7286 % \changes{v1.14}{2005/05/15}{Choruses now stretch like the verses}
7287 % Start a new chorus.
7288 % If |\repchoruses| is active and this is part of the first set of consecutive
7289 % choruses in the song, then include it and its preceding vertical material
7290 % in the |\SB@chorusbox| for possible later duplication elsewhere.
7291 % \begin{macrocode}
7292 \newenvironment{chorus}{\beginchorus}{\SB@endchorus}
7293 \newcommand\beginchorus{%
7294 \ifSB@insong
7295 \ifSB@inverse\SB@errbcv\endverse\fi%
7296 \ifSB@inchorus\SB@errbcc\endchorus\fi%
7297 \else%
7298 \SB@errbct\beginsong{Unknown Song}%
7299 \fi%
7300 \SB@inchorustrue%
7301 \def\SB@closeall{\endchorus\endsong}%
7302 \SB@chorustoptrue%
7303 \vnumberedfalse%
7304 \SB@stanzabreak%
7305 \chorusmark%
7306 \ifrepchorus%
7307 \ifSB@gotchorus\else\ifSB@prevverse\else%
7308 \global\setbox\SB@chorusbox\vbox{%
7309 \unvbox\SB@chorusbox%
7310 \SB@stanzabreak%
7311 \chorusmark%
7312 }%
7313 \fi\fi%
7314 \fi%
7315 \global\SB@stanzatrue%
7316 \replay[]%
7317 \SB@@beginchorus%
7318 \everychorus\relax%
7319 }
7320 % \end{macrocode}
7321 % \end{macro}
7322 % \end{environment}
7323 %
7324 % \begin{macro}{\SB@@beginchorus}
7325 % Begin the body of a chorus, or continue the body of a chorus after |\brk|
7326 % has paused it to insert a valid breakpoint.
7327 % We insert an empty class-|\SB@cmarkclass| mark here so that this chorus
7328 % will not be duplicated elsewhere on the same page(s) where it initially
7329 % appears.
7330 % \begin{macrocode}
7331 \newcommand\SB@@beginchorus{%
7332 \ifrepchorus\marks\SB@cmarkclass{}\fi%
7333 \setbox\SB@box\vbox\bgroup\begingroup%
7334 \ifchorded%
7335 \def\SB@everypar{%
7336 \vrule\@height\baselineskip\@width\z@\@depth\z@%
7337 \gdef\SB@everypar{}%
7338 }%
7339 \everypar{\SB@everypar\everypar{}}%
7340 \fi%
7341 \chorusfont\relax\SB@setbaselineskip\chorusjustify%
7342 \SB@loadactives%
7343 \SB@obeylines%
7344 \penalty12345 %
7345 }
7346 % \end{macrocode}
7347 % \end{macro}
7348 %
7349 % \begin{macro}{\SB@endchorus}
7350 % End a chorus.
7351 % This involves creating the vertical line to the left of the chorus and then
7352 % unboxing the chorus material that was previously accumulated.
7353 % \begin{macrocode}
7354 \newcommand\SB@endchorus{%
7355 \ifSB@insong%
7356 \ifSB@inchorus%
7357 \unpenalty%
7358 \endgroup\egroup%
7359 \SB@inchorusfalse%
7360 \def\SB@closeall{\endsong}%
7361 \setbox\SB@box\vbox{%
7362 \SB@chorusbar\SB@box%
7363 \SB@putbox\unvbox\SB@box%
7364 }
7365 \ifrepchorus\ifSB@gotchorus\else%
7366 \global\setbox\SB@chorusbox\vbox{%
7367 \unvbox\SB@chorusbox%
7368 \unvcopy\SB@box%
7369 }%
7370 \fi\fi%
7371 \unvbox\SB@box%
7372 \SB@prevversefalse%
7373 \else\ifSB@inverse\SB@errecv\endverse%
7374 \else\SB@erreco\fi\fi%
7375 \else%
7376 \SB@errect%
7377 \fi%
7378 }
7379 % \end{macrocode}
7380 % \end{macro}
7381 %
7382 % \begin{macro}{\SB@cbarshift}
7383 % Increase |\leftskip| to accommodate the chorus bar, if any.
7384 % \begin{macrocode}
7385 \newcommand\SB@cbarshift{%
7386 \ifSB@inchorus\ifdim\cbarwidth>\z@%
7387 \advance\leftskip\cbarwidth%
7388 \advance\leftskip5\p@\relax%
7389 \fi\fi%
7390 }
7391 % \end{macrocode}
7392 % \end{macro}
7393 %
7394 % \begin{macro}{\SB@chorusbar}
7395 % Create the vertical bar that goes to the left of a chorus.
7396 % Rather than boxing up the chorus in order to put the bar to the left,
7397 % the bar is introduced as leaders directly into the vertical list of the
7398 % main song box.
7399 % This allows it to stretch and shrink when a column is typeset by the
7400 % page-builder.
7401 % \begin{macrocode}
7402 \newcommand\SB@chorusbar[1]{%
7403 \ifdim\cbarwidth>\z@%
7404 \SB@dimen\ht#1%
7405 \SB@dimenii\dp#1%
7406 \advance\SB@dimen%
7407 \ifSB@chorustop\ifchorded\else2\fi\fi\SB@dimenii%
7408 \SB@skip\SB@dimen\relax%
7409 \SB@computess\SB@skip1\@plus#1%
7410 \SB@computess\SB@skip{-1}\@minus#1%
7411 \nointerlineskip\null\nobreak%
7412 \leaders\vrule\@width\cbarwidth\vskip\SB@skip%
7413 \ifSB@chorustop\ifchorded\else%
7414 \advance\SB@skip-\SB@dimenii%
7415 \fi\fi%
7416 \nobreak\vskip-\SB@skip%
7417 \fi%
7418 }
7419 % \end{macrocode}
7420 % \end{macro}
7421 %
7422 % \begin{macro}{\SB@computess}
7423 % \changes{v1.14}{2005/05/15}{Added}
7424 % This computes the stretchability or shrinkability of a vbox and stores
7425 % the result in the skip register given by \argp{1}.
7426 % If $\argp{2}=1$ and \argp{3} is ``\texttt{plus}'', then the stretchability
7427 % of box \argp{4} is added to the plus component of \argp{1}.
7428 % If $\argp{2}=-1$ and \argp{3} is ``\texttt{minus}'', then the shrinkability
7429 % of the box is added to the minus component of \argp{1}.
7430 % If the stretchability or shrinkability is infinite, then we guess 1fil
7431 % for that component.
7432 % \begin{macrocode}
7433 \newcommand\SB@computess[4]{%
7434 \begingroup%
7435 \vbadness\@M\vfuzz\maxdimen%
7436 \SB@dimen4096\p@%
7437 \setbox\SB@box\vbox spread#2\SB@dimen{\unvcopy#4}%
7438 \ifnum\badness=\z@%
7439 \global\advance#1\z@#31fil\relax%
7440 \else%
7441 \SB@dimenii\SB@dimen%
7442 \loop%
7443 \[email protected]\SB@dimenii%
7444 \ifnum\badness<100 %
7445 \advance\SB@dimen\SB@dimenii%
7446 \else
7447 \advance\SB@dimen-\SB@dimenii%
7448 \fi%
7449 \setbox\SB@box\vbox spread#2\SB@dimen{\unvcopy#4}%
7450 \ifnum\badness=100 \SB@dimenii\z@\fi%
7451 \ifdim\SB@dimenii>.1\p@\repeat%
7452 \ifdim\SB@dimen<.1\p@\SB@dimen\z@\fi%
7453 \global\advance#1\z@#3\SB@dimen\relax%
7454 \fi%
7455 \endgroup%
7456 }
7457 % \end{macrocode}
7458 % \end{macro}
7459 %
7460 % \begin{macro}{\brk}\MainImpl{brk}
7461 % Placing |\brk| within a line in a verse or chorus tells \TeX{} to break the
7462 % line at that point (if it needs to be broken at all).
7463 %
7464 % Placing |\brk| on a line by itself within a chorus stops the chorus (and its
7465 % vertical bar), inserts a valid breakpoint, and then restarts the chorus
7466 % with no intervening space so that if the breakpoint isn't used, there will
7467 % be no visible effect.
7468 % Placing it on a line by itself within a verse just inserts a breakpoint.
7469 %
7470 % Placing |\brk| between songs forces a column- or page-break, but only if
7471 % generating a non-partial list of songs.
7472 % When generating a partial list, |\brk| between songs is ignored.
7473 % \begin{macrocode}
7474 \newcommand\brk{%
7475 \ifSB@insong%
7476 \ifhmode\penalty-5 \else%
7477 \unpenalty%
7478 \ifSB@inchorus%
7479 \ifdim\cbarwidth=\z@%
7480 \ifrepchorus\marks\SB@cmarkclass{}\fi%
7481 \SB@breakpoint\brkpenalty%
7482 \else%
7483 \endgroup\egroup%
7484 \ifrepchorus\ifSB@gotchorus\else%
7485 \global\setbox\SB@chorusbox\vbox{%
7486 \unvbox\SB@chorusbox%
7487 \SB@chorusbar\SB@box%
7488 \unvcopy\SB@box%
7489 \SB@breakpoint\brkpenalty%
7490 }%
7491 \fi\fi%
7492 \SB@chorusbar\SB@box%
7493 \unvbox\SB@box%
7494 \SB@breakpoint\brkpenalty%
7495 \SB@chorustopfalse%
7496 \SB@@beginchorus%
7497 \fi%
7498 \else%
7499 \SB@breakpoint\brkpenalty%
7500 \fi%
7501 \fi%
7502 \else%
7503 \ifpartiallist\else\SB@nextcol\@ne\colbotglue\fi%
7504 \fi%
7505 }
7506 % \end{macrocode}
7507 % \end{macro}
7508 %
7509 % \begin{macro}{\SB@boxup}
7510 % Typeset a shaded box containing a textual note to singers or musicians.
7511 % We first try typesetting the note on a single line.
7512 % If it's too big, then we try again in paragraph mode with full
7513 % justification.
7514 % \begin{macrocode}
7515 \newcommand\SB@boxup[1]{%
7516 \setbox\SB@box\hbox{{\notefont\relax#1}}%
7517 \SB@dimen\wd\SB@box%
7518 \advance\SB@dimen6\p@%
7519 \advance\SB@dimen\leftskip%
7520 \advance\SB@dimen\rightskip%
7521 \ifdim\SB@dimen>\hsize%
7522 \vbox{{%
7523 \advance\hsize-6\p@%
7524 \advance\hsize-\leftskip%
7525 \advance\hsize-\rightskip%
7526 \notejustify%
7527 \unhbox\SB@box\par%
7528 \kern\z@%
7529 }}%
7530 \else%
7531 \vbox{\box\SB@box\kern\z@}%
7532 \fi%
7533 }
7534 % \end{macrocode}
7535 % \end{macro}
7536 %
7537 % \begin{macro}{\textnote}\MainImpl{textnote}
7538 % \changes{v1.12}{2005/05/10}{Defined unset paragraph parameters}
7539 % Create a textual note for singers and musicians.
7540 % If the note begins a verse or chorus, it should not be preceded by any
7541 % spacing.
7542 % Verses and choruses begin with the sentinel penalty 12345, so we check
7543 % |\lastpenalty| to identify this case.
7544 % When typesetting the note, we must be sure to temporarily clear |\everypar|
7545 % to inhibit any verse numbering that might be pending.
7546 % We also readjust the |\baselineskip| as if we weren't doing chords, since
7547 % no chords go above a textual note.
7548 % \begin{macrocode}
7549 \newcommand\textnote[1]{%
7550 \ifhmode\par\fi%
7551 \ifnum\lastpenalty=12345\else%
7552 \ifSB@inverse%
7553 \vskip2\p@\relax%
7554 \else\ifSB@inchorus%
7555 \vskip2\p@\relax%
7556 \else\ifSB@stanza%
7557 \nobreak\vskip\versesep%
7558 \fi\fi\fi%
7559 \fi%
7560 \begingroup%
7561 \everypar{}%
7562 \ifchorded\chordedfalse\SB@setbaselineskip\chordedtrue\fi%
7563 \placenote{\SB@colorbox\notebgcolor{\SB@boxup{#1}}}%
7564 \endgroup%
7565 \nobreak%
7566 \ifSB@inverse%
7567 \vskip2\p@\relax%
7568 \else\ifSB@inchorus%
7569 \vskip2\p@\relax%
7570 \else\ifSB@stanza\else%
7571 \nobreak\vskip\versesep%
7572 \fi\fi\fi%
7573 }
7574 % \end{macrocode}
7575 % \end{macro}
7576 %
7577 % \begin{macro}{\musicnote}\MainImpl{musicnote}
7578 % \changes{v1.12}{2005/05/10}{Now just (conditionally) calls \cs{textnote} for consistency}
7579 % Create a textual note for musicians.
7580 % \begin{macrocode}
7581 \newcommand\musicnote[1]{\ifchorded\textnote{#1}\fi}
7582 % \end{macrocode}
7583 % \end{macro}
7584 %
7585 % \begin{macro}{\echo}\MainImpl{echo}
7586 % \begin{macro}{\SB@echo}
7587 % \begin{macro}{\SB@@echo}
7588 % \changes{v1.21}{2006/09/17}{Customized fonts now preserved.}
7589 % \changes{v2.1}{2007/08/02}{Toggles instead of forces slanted font.}
7590 % Typeset an echo part in the lyrics.
7591 % Echo parts are in a user-customizable font and parenthesized.
7592 %
7593 % The |\echo| macro must be able to accept chords in its argument.
7594 % This complicates the implementation because chord macros should change
7595 % catcodes, but if we grab |\echo|'s argument in the usual way then all the
7596 % catcodes will be set before the chord macros have a chance to change them.
7597 % This would disallow chord name abbreviations like |#| and |&| within
7598 % |\echo| parts.
7599 %
7600 % If we're using $\varepsilon$-\TeX{} then the solution is easy: we use
7601 % |\scantokens| to re-scan the argument and thereby re-assign the catcodes.
7602 % (One subtlety: Whenever \LaTeX{} consumes an argument to a macro, it changes
7603 % |#| to |##| so that when the argument text is substituted into the body of
7604 % the macro, the replacement text will not contain unsubstituted parameters
7605 % (such as |#1|).
7606 % If |\scantokens| is used on the replacement text and the scanned tokens
7607 % assign a new catcode to |#|, that causes |#|'s to be doubled in the
7608 % \emph{output}, which was not the intent.
7609 % To avoid this problem, we use |\@sanitize| before consuming the argument to
7610 % |\echo|, which sets the catcodes of most special tokens (including |#|) to
7611 % 12, so that \LaTeX{} will not recognize any of them as parameters and will
7612 % therefore not double any of them.)
7613 % \begin{macrocode}
7614 \ifSB@etex
7615 \newcommand\echo{\begingroup\@sanitize\SB@echo}
7616 \newcommand\SB@echo[1]{%
7617 \endgroup%
7618 \begingroup%
7619 \echofont\relax%
7620 \endlinechar\m@ne%
7621 \scantokens{(#1)}%
7622 \endgroup%
7623 }
7624 \else
7625 % \end{macrocode}
7626 % If we're not using $\varepsilon$-\TeX, we must do something more complicated.
7627 % We set up the appropriate font within a local group and finish with
7628 % |\hbox| so that the argument to |\echo| is treated as the body of the box.
7629 % Control is reacquired after the box using |\aftergroup|, whereupon we
7630 % unbox the box and insert the closing parenthesis.
7631 % This almost works except that if the last thing in an echo part is a long
7632 % chord name atop a short lyric, the closing parenthesis will float out away
7633 % from the lyric instead of being sucked under the chord.
7634 % I can find no solution to this problem, so to avoid it users must find a
7635 % version of \LaTeX{} that is $\varepsilon$-\TeX{} compatible.
7636 % \begin{macrocode}
7637 \newcommand\echo{%
7638 \begingroup%
7639 \echofont\relax%
7640 \afterassignment\SB@echo%
7641 \setbox\SB@box\hbox%
7642 }
7643 \newcommand\SB@echo{\aftergroup\SB@@echo(}
7644 \newcommand\SB@@echo{\unhbox\SB@box)\endgroup}
7645 \fi
7646 % \end{macrocode}
7647 % \end{macro}
7648 % \end{macro}
7649 % \end{macro}
7650 %
7651 % \begin{macro}{\rep}\MainImpl{rep}
7652 % \changes{v1.21}{2006/09/17}{Changed to avoid math mode.}
7653 % Place |\rep{|\Meta{n}|}| at the end of a line to indicate that it should be
7654 % sung \Meta{n} times.
7655 % \begin{macrocode}
7656 \newcommand\rep[1]{%
7657 (\raise.25ex\hbox{%
7658 \fontencoding{OMS}\fontfamily{cmsy}\selectfont\char\tw@%
7659 }#1)%
7660 }
7661 % \end{macrocode}
7662 % \end{macro}
7663 %
7664 % \subsection{Scripture Quotations}
7665 %
7666 % The macros in this section typeset scripture quotations and other
7667 % between-songs environments.
7668 %
7669 % \begin{environment}{songgroup}\MainEnvImpl{songgroup}
7670 % A |songgroup| environment associates all enclosed environments
7671 % with the enclosed song.
7672 % When generating a partial list, all the enclosed environments are
7673 % contributed if and only if the enclosed song is contributed.
7674 % \begin{macrocode}
7675 \newenvironment{songgroup}{%
7676 \ifnum\SB@grouplvl=\z@%
7677 \edef\SB@sgroup{\thesongnum}%
7678 \global\SB@groupcnt\m@ne%
7679 \fi%
7680 \advance\SB@grouplvl\@ne%
7681 }{%
7682 \advance\SB@grouplvl\m@ne%
7683 \ifnum\SB@grouplvl=\z@\let\SB@sgroup\@empty\fi%
7684 }
7685 % \end{macrocode}
7686 % \end{environment}
7687 %
7688 % \begin{macro}{\SB@grouplvl}
7689 % Count the |songgroup| environment nesting depth.
7690 % \begin{macrocode}
7691 \SB@newcount\SB@grouplvl
7692 % \end{macrocode}
7693 % \end{macro}
7694 %
7695 % \begin{environment}{intersong}\MainEnvImpl{intersong}
7696 % An intersong block contributes vertical material to a column between the
7697 % songs of a songs section.
7698 % It is subject to the same column-breaking algorithm as real songs, but
7699 % receives none of the other formatting applied to songs.
7700 % \begin{macrocode}
7701 \newenvironment{intersong}{%
7702 \ifSB@insong\SB@errbro\SB@closeall\fi%
7703 \ifSB@intersong\SB@errbrr\SB@closeall\fi%
7704 \setbox\SB@chorusbox\box\voidb@x%
7705 \SB@intersongtrue%
7706 \def\SB@closeall{\end{intersong}}%
7707 \setbox\SB@songbox\vbox\bgroup\begingroup%
7708 \ifnum\SB@numcols>\z@\hsize\SB@colwidth\fi%
7709 \ifdim\sbarheight>\z@%
7710 \hrule\@height\sbarheight\@width\hsize%
7711 \nobreak%
7712 \fi%
7713 }{%
7714 \ifSB@intersong
7715 \ifdim\sbarheight>\z@%
7716 \ifhmode\par\fi%
7717 \SB@skip\lastskip%
7718 \unskip\nobreak\vskip\SB@skip%
7719 \hbox{\vrule\@height\sbarheight\@width\hsize}%
7720 \fi%
7721 \endgroup\egroup%
7722 \ifSB@omitscrip%
7723 \setbox\SB@songbox\box\voidb@x%
7724 \else%
7725 \SB@submitsong%
7726 \fi%
7727 \SB@intersongfalse%
7728 \else%
7729 \ifSB@insong\SB@errero\SB@closeall\else\SB@errert\fi%
7730 \fi%
7731 }
7732 % \end{macrocode}
7733 % The starred form contributes page-spanning vertical material directly to
7734 % the top of the nearest fresh page.
7735 % \begin{macrocode}
7736 \newenvironment{intersong*}{%
7737 \ifSB@insong\SB@errbro\SB@closeall\fi%
7738 \ifSB@intersong\SB@errbrr\SB@closeall\fi%
7739 \setbox\SB@chorusbox\box\voidb@x%
7740 \SB@intersongtrue%
7741 \def\SB@closeall{\end{intersong*}}%
7742 \setbox\SB@songbox\vbox\bgroup\begingroup%
7743 }{%
7744 \ifSB@intersong%
7745 \endgroup\egroup%
7746 \ifSB@omitscrip%
7747 \setbox\SB@songbox\box\voidb@x%
7748 \else%
7749 \def\SB@stype{\SB@styppage}%
7750 \SB@submitsong%
7751 \def\SB@stype{\SB@stypcol}%
7752 \fi%
7753 \SB@intersongfalse%
7754 \else%
7755 \ifSB@insong\SB@errero\SB@closeall\else\SB@errert\fi%
7756 \fi%
7757 }
7758 % \end{macrocode}
7759 % \end{environment}
7760 %
7761 % \begin{environment}{scripture}\MainEnvImpl{scripture}
7762 % \begin{macro}{\beginscripture}
7763 % Begin a scripture quotation.
7764 % We first store the reference in a box for later use, and then set up
7765 % a suitable environment for the quotation.
7766 % Quotations cannot typically be reworded if line-breaking fails,
7767 % so we set |\emergencystretch| to a relatively high value at the outset.
7768 % \begin{macrocode}
7769 \newenvironment{scripture}{\beginscripture}{\SB@endscripture}
7770 \newcommand\beginscripture[1]{%
7771 \begin{intersong}%
7772 \SB@parsesrefs{#1}%
7773 \setbox\SB@envbox\hbox{{\printscrcite\songrefs}}%
7774 \def\SB@closeall{\endscripture}%
7775 \nobreak\vskip5\p@%
7776 \SB@parindent\parindent\parindent\z@%
7777 \parskip\z@skip\parfillskip\@flushglue%
7778 \leftskip\SB@parindent\rightskip\SB@parindent\relax%
7779 \scripturefont\relax%
7780 \baselineskip\f@size\p@\@plus\p@\relax%
7781 \advance\baselineskip\p@\relax%
7782 \emergencystretch.3em%
7783 }
7784 % \end{macrocode}
7785 % \end{macro}
7786 %
7787 % \begin{macro}{\SB@endscripture}
7788 % End a scripture quotation.
7789 % \begin{macrocode}
7790 \newcommand\SB@endscripture{%
7791 \ifSB@intersong
7792 \scitehere%
7793 \ifhmode\par\fi%
7794 \vskip-3\p@%
7795 \end{intersong}%
7796 \fi%
7797 }
7798 % \end{macrocode}
7799 % \end{macro}
7800 % \end{environment}
7801 %
7802 % \begin{macro}{\scitehere}\MainImpl{scitehere}
7803 % \changes{v2.1}{2007/08/02}{Added}
7804 % Usually the scripture citation should just come at the |\endscripture|
7805 % line, but at times the user might want to invoke this macro explicitly
7806 % at a more suitable point.
7807 % A good example is when something near the end of the scripture quotation
7808 % drops \TeX{} into vertical mode.
7809 % In such cases, it is often better to issue the citation before leaving
7810 % horizontal mode.
7811 %
7812 % In any case, this macro should work decently whether in horizontal or
7813 % vertical mode.
7814 % In horizontal mode life is easy: we just append the reference to the
7815 % current horizontal list using the classic code from p.~106 of The \TeX book.
7816 % However, if we're now in vertical mode, the problem is a little harder.
7817 % We do the best we can by using |\lastbox| to remove the last line, then
7818 % adding the reference and re-typesetting it.
7819 % This isn't as good as the horizontal mode solution because \TeX{} only
7820 % gets to reevaluate the last line instead of the whole paragraph, but
7821 % usually the results are passable.
7822 % \begin{macrocode}
7823 \newcommand\scitehere{%
7824 \ifSB@intersong%
7825 \ifvoid\SB@envbox\else%
7826 \ifvmode%
7827 \setbox\SB@box\lastbox%
7828 \nointerlineskip\noindent\hskip-\leftskip%
7829 \unhbox\SB@box\unskip%
7830 \fi%
7831 \unskip\nobreak\hfil\penalty50\hskip.8em\null\nobreak\hfil%
7832 \box\SB@envbox\kern-\SB@parindent%
7833 {\parfillskip\z@\finalhyphendemerits2000\par}%
7834 \fi%
7835 \else%
7836 \SB@errscrip\scitehere%
7837 \fi%
7838 }
7839 % \end{macrocode}
7840 % \end{macro}
7841 %
7842 % \begin{macro}{\Acolon}\MainImpl{Acolon}
7843 % \begin{macro}{\Bcolon}\MainImpl{Bcolon}
7844 % \changes{v1.13}{2005/05/12}{Added}
7845 % Typeset a line of poetry in a scripture quotation.
7846 % \begin{macrocode}
7847 \newcommand\Acolon{\SB@colon2\Acolon}
7848 \newcommand\Bcolon{\SB@colon1\Bcolon}
7849 % \end{macrocode}
7850 % \end{macro}
7851 % \end{macro}
7852 %
7853 % \begin{macro}{\SB@colon}
7854 % Begin a group of temporary definitions that will end at the next
7855 % \Meta{return}.
7856 % The \Meta{return} will end the paragraph and close the local scope.
7857 % \begin{macrocode}
7858 \newcommand\SB@colon[2]{%
7859 \ifSB@intersong\else%
7860 \SB@errscrip#2%
7861 \beginscripture{Unknown}%
7862 \fi%
7863 \ifhmode\par\fi%
7864 \begingroup%
7865 \rightskip\SB@parindent\@plus4em%
7866 \advance\leftskip2\SB@parindent%
7867 \advance\parindent-#1\SB@parindent%
7868 \def\par{\endgraf\endgroup}%
7869 \obeylines%
7870 }
7871 % \end{macrocode}
7872 % \end{macro}
7873 %
7874 % \begin{macro}{\strophe}\MainImpl{strophe}
7875 % \changes{v1.13}{2005/05/12}{Added}
7876 % Insert blank space indicative of a strophe division in a scripture quotation.
7877 % \begin{macrocode}
7878 \newcommand\strophe{%
7879 \ifSB@intersong\else%
7880 \SB@errscrip\strophe\beginscripture{Unknown}%
7881 \fi%
7882 \vskip.9ex\@plus.45ex\@minus.68ex\relax%
7883 }
7884 % \end{macrocode}
7885 % \end{macro}
7886 %
7887 % \begin{macro}{\scripindent}\MainImpl{scripindent}
7888 % \begin{macro}{\scripoutdent}\MainImpl{scripoutdent}
7889 % \begin{macro}{\SB@scripdent}
7890 % \changes{v1.13}{2005/05/12}{Added}
7891 % Create an indented sub-block within a scripture quotation.
7892 % \begin{macrocode}
7893 \newcommand\SB@scripdent[2]{%
7894 \ifSB@intersong\else%
7895 \SB@errscrip#2\beginscripture{Unknown}%
7896 \fi%
7897 \ifhmode\par\fi%
7898 \advance\leftskip#1\SB@parindent\relax%
7899 }
7900 \newcommand\scripindent{\SB@scripdent1\scripindent}
7901 \newcommand\scripoutdent{\SB@scripdent-\scripoutdent}
7902 % \end{macrocode}
7903 % \end{macro}
7904 % \end{macro}
7905 % \end{macro}
7906 %
7907 % \begin{macro}{\shiftdblquotes}\MainImpl{shiftdblquotes}
7908 % \changes{v1.13}{2005/05/12}{Added}
7909 % \begin{macro}{\SB@ldqleft}
7910 % \begin{macro}{\SB@ldqright}
7911 % \begin{macro}{\SB@rdqleft}
7912 % \begin{macro}{\SB@rdqright}
7913 % \begin{macro}{\SB@scanlq}
7914 % \begin{macro}{\SB@scanrq}
7915 % \begin{macro}{\SB@dolq}
7916 % \begin{macro}{\SB@dorq}
7917 % The Zaph Chancery font used by default to typeset scripture quotations
7918 % seems to have some kerning problems with double-quote ligatures. The
7919 % |\shiftdblquotes| macro allows one to modify the spacing around all
7920 % double-quotes until the current group ends.
7921 % \begin{macrocode}
7922 \newcommand\SB@quotesactive{%
7923 \catcode`'\active%
7924 \catcode``\active%
7925 }
7926 \newcommand\shiftdblquotes[4]{}
7927 \newcommand\SB@ldqleft{}
7928 \newcommand\SB@ldqright{}
7929 \newcommand\SB@rdqleft{}
7930 \newcommand\SB@rdqright{}
7931 \newcommand\SB@scanlq{}
7932 \newcommand\SB@scanrq{}
7933 \newcommand\SB@dolq{}
7934 \newcommand\SB@dorq{}
7935 {
7936 \SB@quotesactive
7937 \gdef\shiftdblquotes#1#2#3#4{%
7938 \def\SB@ldqleft{\kern#1}%
7939 \def\SB@ldqright{\kern#2}%
7940 \def\SB@rdqleft{\kern#3}%
7941 \def\SB@rdqright{\kern#4}%
7942 \SB@quotesactive%
7943 \def`{\futurelet\SB@next\SB@scanlq}%
7944 \def'{\futurelet\SB@next\SB@scanrq}%
7945 }
7946 \gdef\SB@scanlq{%
7947 \ifx\SB@next`%
7948 \expandafter\SB@dolq%
7949 \else%
7950 \expandafter\lq%
7951 \fi%
7952 }
7953 \gdef\SB@scanrq{%
7954 \ifx\SB@next'%
7955 \expandafter\SB@dorq%
7956 \else%
7957 \expandafter\rq%
7958 \fi%
7959 }
7960 \gdef\SB@dolq`{%
7961 \ifvmode\leavevmode\else\/\fi%
7962 \vadjust{}%
7963 \SB@ldqleft\lq\lq\SB@ldqright%
7964 \vadjust{}%
7965 }
7966 \gdef\SB@dorq'{%
7967 \ifvmode\leavevmode\else\/\fi%
7968 \vadjust{}%
7969 \SB@rdqleft\rq\rq\SB@rdqright%
7970 \vadjust{}%
7971 }
7972 }
7973 % \end{macrocode}
7974 % \end{macro}
7975 % \end{macro}
7976 % \end{macro}
7977 % \end{macro}
7978 % \end{macro}
7979 % \end{macro}
7980 % \end{macro}
7981 % \end{macro}
7982 % \end{macro}
7983 %
7984 % \subsection{Transposition}
7985 %
7986 % The macros that transpose chords are contained in this section.
7987 %
7988 % \begin{macro}{\SB@transposefactor}
7989 % This counter identifies the requested number of halfsteps by which chords are
7990 % to be transposed (from $-11$ to $+11$).
7991 % \begin{macrocode}
7992 \SB@newcount\SB@transposefactor
7993 % \end{macrocode}
7994 % \end{macro}
7995 %
7996 % \begin{macro}{\ifSB@convertnotes}
7997 % Even when transposition is not requested, the transposition logic can be
7998 % used to automatically convert note names to another form.
7999 % The following conditional turns that feature on or off.
8000 % \begin{macrocode}
8001 \newif\ifSB@convertnotes
8002 % \end{macrocode}
8003 % \end{macro}
8004 %
8005 % \begin{macro}{\notenameA}
8006 % \begin{macro}{\notenameB}
8007 % \begin{macro}{\notenameC}
8008 % \begin{macro}{\notenameD}
8009 % \begin{macro}{\notenameE}
8010 % \begin{macro}{\notenameF}
8011 % \begin{macro}{\notenameG}
8012 % Reserve a control sequence for each note of the diatonic scale.
8013 % These will be used to identify which token sequences the input file uses
8014 % to denote the seven scale degrees.
8015 % Their eventual definitions \emph{must} consist entirely of uppercase
8016 % letters, and they must be assigned using |\def|, but that comes later.
8017 % \begin{macrocode}
8018 \newcommand\notenameA{}
8019 \newcommand\notenameB{}
8020 \newcommand\notenameC{}
8021 \newcommand\notenameD{}
8022 \newcommand\notenameE{}
8023 \newcommand\notenameF{}
8024 \newcommand\notenameG{}
8025 % \end{macrocode}
8026 % \end{macro}
8027 % \end{macro}
8028 % \end{macro}
8029 % \end{macro}
8030 % \end{macro}
8031 % \end{macro}
8032 % \end{macro}
8033 %
8034 % \begin{macro}{\printnoteA}
8035 % \begin{macro}{\printnoteB}
8036 % \begin{macro}{\printnoteC}
8037 % \begin{macro}{\printnoteD}
8038 % \begin{macro}{\printnoteE}
8039 % \begin{macro}{\printnoteF}
8040 % \begin{macro}{\printnoteG}
8041 % These control sequences are what the transposition logic actually
8042 % outputs to denote each scale degree.
8043 % They can include any \LaTeX{} code that is legal in horizontal mode.
8044 % \begin{macrocode}
8045 \newcommand\printnoteA{}
8046 \newcommand\printnoteB{}
8047 \newcommand\printnoteC{}
8048 \newcommand\printnoteD{}
8049 \newcommand\printnoteE{}
8050 \newcommand\printnoteF{}
8051 \newcommand\printnoteG{}
8052 % \end{macrocode}
8053 % \end{macro}
8054 % \end{macro}
8055 % \end{macro}
8056 % \end{macro}
8057 % \end{macro}
8058 % \end{macro}
8059 % \end{macro}
8060 %
8061 % \begin{macro}{\notenamesin}\MainImpl{notenamesin}
8062 % Set the note names used by the input file.
8063 % \begin{macrocode}
8064 \newcommand\notenamesin[7]{%
8065 \def\notenameA{#1}%
8066 \def\notenameB{#2}%
8067 \def\notenameC{#3}%
8068 \def\notenameD{#4}%
8069 \def\notenameE{#5}%
8070 \def\notenameF{#6}%
8071 \def\notenameG{#7}%
8072 \SB@convertnotestrue%
8073 }
8074 % \end{macrocode}
8075 % \end{macro}
8076 %
8077 % \begin{macro}{\notenamesout}\MainImpl{notenamesout}
8078 % Set the note names that are output by the transposition logic.
8079 % \begin{macrocode}
8080 \newcommand\notenamesout[7]{%
8081 \def\printnoteA{#1}%
8082 \def\printnoteB{#2}%
8083 \def\printnoteC{#3}%
8084 \def\printnoteD{#4}%
8085 \def\printnoteE{#5}%
8086 \def\printnoteF{#6}%
8087 \def\printnoteG{#7}%
8088 \SB@convertnotestrue%
8089 }
8090 % \end{macrocode}
8091 % \end{macro}
8092 %
8093 % \begin{macro}{\notenames}\MainImpl{notenames}
8094 % Set an identical input name and output name for each scale degree.
8095 % \begin{macrocode}
8096 \newcommand\notenames[7]{%
8097 \notenamesin{#1}{#2}{#3}{#4}{#5}{#6}{#7}%
8098 \notenamesout{#1}{#2}{#3}{#4}{#5}{#6}{#7}%
8099 \SB@convertnotesfalse%
8100 }
8101 % \end{macrocode}
8102 % \end{macro}
8103 %
8104 % \begin{macro}{\alphascale}\MainImpl{alphascale}
8105 % \begin{macro}{\solfedge}\MainImpl{solfedge}
8106 % Predefine scales for alphabetic names and solfedge names, and
8107 % set alphabetic scales to be the default.
8108 % \begin{macrocode}
8109 \newcommand\alphascale{\notenames ABCDEFG}
8110 \newcommand\solfedge{\notenames{LA}{SI}{DO}{RE}{MI}{FA}{SOL}}
8111 \alphascale
8112 % \end{macrocode}
8113 % \end{macro}
8114 % \end{macro}
8115 %
8116 % \begin{macro}{\ifSB@prefshrps}
8117 % When a transposed chord falls on a black key, the code must choose which
8118 % enharmonically equivalent name to give the new chord.
8119 % (For example, should C transposed by +1 be named C$\#$ or D$\flat$?)
8120 % A heuristic is used to guess which name is most appropriate.
8121 % The following conditional records whether the current key signature is
8122 % sharped or flatted according to this heuristic guess.
8123 % \begin{macrocode}
8124 \newif\ifSB@prefshrps
8125 % \end{macrocode}
8126 % \end{macro}
8127 %
8128 % \begin{macro}{\ifSB@needkey}
8129 % The first chord seen is usually the best indicator of the key of the song.
8130 % (Even when the first chord isn't the tonic, it will often be the dominant
8131 % or subdominant, which usually has the same kind of accidental in its key
8132 % signatures as the actual key.) This conditional remembers whether the current
8133 % chord is the first one seen in the song, and should therefore be used to
8134 % guess the key of the song.
8135 % \begin{macrocode}
8136 \newif\ifSB@needkey
8137 % \end{macrocode}
8138 % \end{macro}
8139 %
8140 % \begin{macro}{\transpose}\MainImpl{transpose}
8141 % The |\transpose| macro sets the transposition adjustment factor and
8142 % informs the transposition logic that the next chord seen will be the first
8143 % one in the new key.
8144 % \begin{macrocode}
8145 \newcommand\transpose[1]{%
8146 \advance\SB@transposefactor by#1\relax%
8147 \SB@cnt\SB@transposefactor%
8148 \divide\SB@cnt12 %
8149 \multiply\SB@cnt12 %
8150 \advance\SB@transposefactor-\SB@cnt%
8151 \SB@needkeytrue%
8152 }
8153 % \end{macrocode}
8154 % \end{macro}
8155 %
8156 % \begin{macro}{\capo}\MainImpl{capo}
8157 % Specifying a |\capo| normally just causes a textual note to musicians to be
8158 % typeset, but if the |transposecapos| option is active, it activates
8159 % transposition of the chords.
8160 % \begin{macrocode}
8161 \newcommand\capo[1]{%
8162 \iftranscapos\transpose{#1}\else\musicnote{capo #1}\fi%
8163 }
8164 % \end{macrocode}
8165 % \end{macro}
8166 %
8167 % \begin{macro}{\prefersharps}\MainImpl{prefersharps}
8168 % \begin{macro}{\preferflats}\MainImpl{preferflats}
8169 % One of these macros is called after the first chord has been seen to
8170 % register that we're transposing to a key with a sharped or flatted key
8171 % signature.
8172 % \begin{macrocode}
8173 \newcommand\prefersharps{\SB@prefshrpstrue\SB@needkeyfalse}
8174 \newcommand\preferflats{\SB@prefshrpsfalse\SB@needkeyfalse}
8175 % \end{macrocode}
8176 % \end{macro}
8177 % \end{macro}
8178 %
8179 % \begin{macro}{\transposehere}\MainImpl{transposehere}
8180 % If automatic transposition has been requested, yield the given chord
8181 % transposed by the requested amount.
8182 % Otherwise return the given chord verbatim.
8183 % \begin{macrocode}
8184 \newcommand\transposehere[1]{%
8185 \ifnum\SB@transposefactor=\z@%
8186 \ifSB@convertnotes%
8187 \SB@dotranspose{#1}%
8188 \the\SB@toks%
8189 \else%
8190 #1%
8191 \fi%
8192 \else%
8193 \ifSB@convertnotes%
8194 {\SB@transposefactor\z@%
8195 \SB@dotranspose{#1}%
8196 \xdef\SB@tempv{\the\SB@toks}}%
8197 \else%
8198 \def\SB@tempv{#1}%
8199 \fi%
8200 \SB@dotranspose{#1}%
8201 \expandafter\trchordformat\expandafter{\SB@tempv}{\the\SB@toks}%
8202 \fi%
8203 }
8204 % \end{macrocode}
8205 % \end{macro}
8206 %
8207 % \begin{macro}{\notrans}\MainImpl{notrans}
8208 % Suppress chord transposition without suppressing note name conversion.
8209 % When a |\notrans{|\Meta{text}|}| macro appears within text undergoing
8210 % transposition, the |\notrans| macro and the group will be preserved
8211 % verbatim by the transposition parser.
8212 % When it is then expanded after parsing, we must therefore re-invoke
8213 % the transposition logic on the argument, but in an environment where
8214 % the transposition factor has been temporarily set to zero.
8215 % This causes note name conversion to occur without actually transposing.
8216 % \begin{macrocode}
8217 \newcommand\notrans[1]{%
8218 \begingroup%
8219 \SB@transposefactor\z@%
8220 \transposehere{#1}%
8221 \endgroup%
8222 }
8223 % \end{macrocode}
8224 % \end{macro}
8225 %
8226 % \begin{macro}{\SB@dotranspose}
8227 % Parse the argument to a chord macro, yielding the transposed equivalent in
8228 % the |\SB@toks| token register.
8229 % \begin{macrocode}
8230 \newcommand\SB@dotranspose[1]{%
8231 \SB@toks{}%
8232 \let\SB@dothis\SB@trmain%
8233 \SB@trscan#1\SB@trend%
8234 }
8235 % \end{macrocode}
8236 % \end{macro}
8237 %
8238 % \begin{macro}{\trchordformat}\MainImpl{trchordformat}
8239 % By default, transposing means replacing old chords with new chords in the
8240 % new key. However, sometimes the user may want to typeset something more
8241 % sophisticated, like old chords followed by new chords in parentheses so
8242 % that musicians who use capos and those who don't can play from the same
8243 % piece of music. Such typesetting is possible by redefining the following
8244 % macro to something like |#1 (#2)| instead of |#2|.
8245 % \begin{macrocode}
8246 \newcommand\trchordformat[2]{#2}
8247 % \end{macrocode}
8248 % \end{macro}
8249 %
8250 % \begin{macro}{\SB@trscan}
8251 % This is the entrypoint to the code that scans over the list of tokens
8252 % comprising a chord and transposes note names as it goes.
8253 % Start by peeking ahead at the next symbol without consuming it.
8254 % \begin{macrocode}
8255 \newcommand\SB@trscan{\futurelet\SB@next\SB@dothis}
8256 % \end{macrocode}
8257 % \end{macro}
8258 %
8259 % \begin{macro}{\SB@trmain}
8260 % Test to see whether the token was a begin-brace, end-brace, or space.
8261 % These tokens require special treatment because they cannot be
8262 % accepted as implicit arguments to macros.
8263 % \begin{macrocode}
8264 \newcommand\SB@trmain{%
8265 \ifx\SB@next\bgroup%
8266 \let\SB@donext\SB@trgroup%
8267 \else\ifx\SB@next\egroup%
8268 \SB@toks\expandafter{\the\SB@toks\egroup}%
8269 \let\SB@donext\SB@trskip%
8270 \else\ifcat\noexpand\SB@next\@sptoken%
8271 \SB@appendsp\SB@toks%
8272 \let\SB@donext\SB@trskip%
8273 \else%
8274 \let\SB@donext\SB@trstep%
8275 \fi\fi\fi%
8276 \SB@donext%
8277 }
8278 % \end{macrocode}
8279 % \end{macro}
8280 %
8281 % \begin{macro}{\SB@trgroup}
8282 % A begin-group brace lies next in the input stream.
8283 % Consume the entire group as an argument to this macro, and append it,
8284 % including the begin- and end-group tokens, to the list of tokens processed
8285 % so far.
8286 % No transposition takes place within a group; they are copied verbatim
8287 % because they probably contain macro code.
8288 % \begin{macrocode}
8289 \newcommand\SB@trgroup[1]{%
8290 \SB@toks\expandafter{\the\SB@toks{#1}}%
8291 \SB@trscan%
8292 }
8293 % \end{macrocode}
8294 % \end{macro}
8295 %
8296 % \begin{macro}{\SB@trskip}
8297 % A space or end-brace lies next in the input stream.
8298 % It has already been added to the token list, so skip over it.
8299 % \begin{macrocode}
8300 \newcommand\SB@trskip{%
8301 \afterassignment\SB@trscan%
8302 \let\SB@next= }
8303 % \end{macrocode}
8304 % \end{macro}
8305 %
8306 % \begin{macro}{\SB@trstep}
8307 % A non-grouping token lies next in the input stream.
8308 % Consume it as an argument to this macro, and then test it to see whether
8309 % it's a note letter or some other recognized item.
8310 % If so, process it; otherwise just append it to the token list and continue
8311 % scanning.
8312 % \begin{macrocode}
8313 \newcommand\SB@trstep[1]{%
8314 \let\SB@donext\SB@trscan%
8315 \ifcat\noexpand\SB@next A%
8316 \ifnum\uccode`#1=`#1%
8317 \def\SB@temp{#1}%
8318 \let\SB@dothis\SB@trnote%
8319 \else%
8320 \SB@toks\expandafter{\the\SB@toks#1}%
8321 \fi%
8322 \else\ifx\SB@next\SB@trend
8323 \let\SB@donext\relax%
8324 \else%
8325 \SB@toks\expandafter{\the\SB@toks#1}%
8326 \fi\fi%
8327 \SB@donext%
8328 }
8329 % \end{macrocode}
8330 % \end{macro}
8331 %
8332 % \begin{macro}{\SB@trnote}
8333 % We're in the midst of processing a sequence of uppercase letters that
8334 % might comprise a note name.
8335 % Check to see whether the next token is an accidental (sharp or flat),
8336 % or yet another letter.
8337 % \begin{macrocode}
8338 \newcommand\SB@trnote{%
8339 \ifcat\noexpand\SB@next A%
8340 \let\SB@donext\SB@trnotestep%
8341 \else\ifnum\SB@transposefactor=\z@%
8342 \SB@cnt\z@%
8343 \let\SB@donext\SB@trtrans%
8344 \else\ifx\SB@next\flt%
8345 \SB@cnt\m@ne%
8346 \let\SB@donext\SB@tracc%
8347 \else\ifx\SB@next\shrp%
8348 \SB@cnt\@ne%
8349 \let\SB@donext\SB@tracc%
8350 \else%
8351 \SB@cnt\z@%
8352 \let\SB@donext\SB@trtrans%
8353 \fi\fi\fi\fi%
8354 \SB@donext%
8355 }
8356 % \end{macrocode}
8357 % \end{macro}
8358 %
8359 % \begin{macro}{\SB@trnotestep}
8360 % The next token is a letter.
8361 % Consume it and test to see whether it is an uppercase letter.
8362 % If so, add it to the note name being assembled; otherwise reinsert it into
8363 % the input stream and jump directly to the transposition logic.
8364 % \begin{macrocode}
8365 \newcommand\SB@trnotestep[1]{%
8366 \ifnum\uccode`#1=`#1%
8367 \SB@app\def\SB@temp{#1}%
8368 \expandafter\SB@trscan%
8369 \else%
8370 \SB@cnt\z@%
8371 \expandafter\SB@trtrans\expandafter#1%
8372 \fi%
8373 }
8374 % \end{macrocode}
8375 % \end{macro}
8376 %
8377 % \begin{macro}{\SB@tracc}
8378 % We've encountered an accidental (sharp or flat) immediately following a
8379 % note name.
8380 % Peek ahead at the next token without consuming it, and then jump to the
8381 % transposition logic.
8382 % This is done because the transposition logic might need to infer the key
8383 % signature of the song, and if the next token is an m (for minor), then
8384 % that information can help.
8385 % \begin{macrocode}
8386 \newcommand\SB@tracc[1]{\futurelet\SB@next\SB@trtrans}
8387 % \end{macrocode}
8388 % \end{macro}
8389 %
8390 % \begin{macro}{\SB@trtrans}
8391 % We've assembled a sequence of capital letters (in |\SB@temp|) that might
8392 % comprise a note name to be transposed.
8393 % If the letters were followed by a |\shrp| then |\SB@cnt| is 1; if they were
8394 % followed by a |\flt| then it is $-1$; otherwise it is 0.
8395 % If the assembled letters turn out to not match any valid note name, then
8396 % do nothing and return to scanning.
8397 % Otherwise compute a new transposed name.
8398 % \begin{macrocode}
8399 \newcommand\SB@trtrans{%
8400 \advance\SB@cnt%
8401 \ifx\SB@temp\notenameA\z@%
8402 \else\ifx\SB@temp\notenameB\tw@%
8403 \else\ifx\SB@temp\notenameC\thr@@%
8404 \else\ifx\SB@temp\notenameD5 %
8405 \else\ifx\SB@temp\notenameE7 %
8406 \else\ifx\SB@temp\notenameF8 %
8407 \else\ifx\SB@temp\notenameG10 %
8408 \else-99 \fi\fi\fi\fi\fi\fi\fi%
8409 \ifnum\SB@cnt<\m@ne%
8410 \SB@toks\expandafter\expandafter\expandafter{%
8411 \expandafter\the\expandafter\SB@toks\SB@temp}%
8412 \else%
8413 \advance\SB@cnt\SB@transposefactor%
8414 \ifnum\SB@cnt<\z@\advance\SB@cnt12 \fi%
8415 \ifnum\SB@cnt>11 \advance\SB@cnt-12 \fi%
8416 \ifSB@needkey\ifnum\SB@transposefactor=\z@\else\SB@setkeysig\fi\fi%
8417 \edef\SB@temp{%
8418 \the\SB@toks%
8419 \ifSB@prefshrps%
8420 \ifcase\SB@cnt\printnoteA\or\printnoteA\noexpand\shrp\or%
8421 \printnoteB\or\printnoteC\or\printnoteC\noexpand\shrp\or%
8422 \printnoteD\or\printnoteD\noexpand\shrp\or\printnoteE\or%
8423 \printnoteF\or\printnoteF\noexpand\shrp\or\printnoteG\or%
8424 \printnoteG\noexpand\shrp\fi%
8425 \else%
8426 \ifcase\SB@cnt\printnoteA\or\printnoteB\noexpand\flt\or%
8427 \printnoteB\or\printnoteC\or\printnoteD\noexpand\flt\or%
8428 \printnoteD\or\printnoteE\noexpand\flt\or\printnoteE\or%
8429 \printnoteF\or\printnoteG\noexpand\flt\or\printnoteG\or%
8430 \printnoteA\noexpand\flt\fi%
8431 \fi}%
8432 \SB@toks\expandafter{\SB@temp}%
8433 \fi%
8434 \let\SB@dothis\SB@trmain%
8435 \SB@trscan%
8436 }
8437 % \end{macrocode}
8438 % \end{macro}
8439 %
8440 % \begin{macro}{\SB@setkeysig}
8441 % If this is the first chord of the song, assume that this is the tonic of the
8442 % key, and select whether to use a sharped or flatted key signature for the
8443 % rest of the song based on that.
8444 % Even if this isn't the tonic, it's probably the dominant or sub-dominant,
8445 % which almost always has a number of sharps or flats similar to the tonic.
8446 % If the bottom note of the chord turns out to be a black key, we choose the
8447 % enharmonic equivalent that is closest to C on the circle of fifths
8448 % (i.e., the one that has fewest sharps or flats).
8449 % \begin{macrocode}
8450 \newcommand\SB@setkeysig{%
8451 \global\SB@needkeyfalse%
8452 \ifcase\SB@cnt%
8453 \global\SB@prefshrpstrue\or% A
8454 \global\SB@prefshrpsfalse\or% Bb
8455 \global\SB@prefshrpstrue\or% B
8456 \ifx\SB@next m% C
8457 \global\SB@prefshrpsfalse%
8458 \else%
8459 \global\SB@prefshrpstrue%
8460 \fi\or%
8461 \global\SB@prefshrpstrue\or% C#
8462 \ifx\SB@next m% D
8463 \global\SB@prefshrpsfalse%
8464 \else%
8465 \global\SB@prefshrpstrue%
8466 \fi\or%
8467 \global\SB@prefshrpsfalse\or% Eb
8468 \global\SB@prefshrpstrue\or% E
8469 \global\SB@prefshrpsfalse\or% F
8470 \global\SB@prefshrpstrue\or% F#
8471 \ifx\SB@next m% G
8472 \global\SB@prefshrpsfalse%
8473 \else%
8474 \global\SB@prefshrpstrue%
8475 \fi\or%
8476 \global\SB@prefshrpsfalse\else% Ab
8477 \global\SB@needkeytrue% non-chord
8478 \fi%
8479 }
8480 % \end{macrocode}
8481 % \end{macro}
8482 %
8483 % \begin{macro}{\SB@trend}
8484 % The following macro marks the end of chord text to be processed.
8485 % It should always be consumed and discarded by the chord-scanning
8486 % logic above, so generate an error if it is ever expanded.
8487 % \begin{macrocode}
8488 \newcommand\SB@trend{%
8489 \SB@Error{Internal Error: Transposition failed}%
8490 {This error should not occur.}%
8491 }
8492 % \end{macrocode}
8493 % \end{macro}
8494 %
8495 % \subsection{Measure Bars}
8496 %
8497 % The following code handles the typesetting of measure bars.
8498 %
8499 % \begin{macro}{\SB@metertop}
8500 % \begin{macro}{\SB@meterbot}
8501 % These macros remember the current numerator and denominator of the meter.
8502 % \begin{macrocode}
8503 \newcommand\SB@metertop{}
8504 \newcommand\SB@meterbot{}
8505 % \end{macrocode}
8506 % \end{macro}
8507 % \end{macro}
8508 %
8509 % \begin{macro}{\meter}\MainImpl{meter}
8510 % Set the current meter without producing an actual measure bar yet.
8511 % \begin{macrocode}
8512 \newcommand\meter[2]{\gdef\SB@metertop{#1}\gdef\SB@meterbot{#2}}
8513 % \end{macrocode}
8514 % \end{macro}
8515 %
8516 % \begin{macro}{\SB@measuremark}
8517 % Normally measure bar boxes should be as thin as possible so that they can be
8518 % slipped into lyrics without making them hard to read. But when two measure
8519 % bars appear consecutively, they need to be spaced apart more so that they
8520 % look like two separate lines instead of one thick line. To achieve this,
8521 % there needs to be a way to pull a vbox off the current list and determine
8522 % whether or not it is a box that contains a measure bar. The solution is to
8523 % insert a mark (|\SB@measuremark|) at the top of each measure bar vbox.
8524 % We can then see whether this measure bar immediately follows another measure
8525 % bar by using |\vsplit| on |\lastbox|.
8526 % \begin{macrocode}
8527 \newcommand\SB@measuremark{SB@IsMeasure}
8528 % \end{macrocode}
8529 % \end{macro}
8530 %
8531 % \begin{macro}{\SB@makembar}\MainImpl{mbar}
8532 % Typeset a measure bar. If provided, \argp{1} is the numerator and \argp{2} is
8533 % the denominator of the meter to be rendered above the bar. If those arguments
8534 % are left blank, render a measure bar without a meter marking.
8535 % \begin{macrocode}
8536 \newcommand\SB@makembar[2]{%
8537 \ifSB@inverse\else%
8538 \ifSB@inchorus\else\SB@errmbar\fi%
8539 \fi%
8540 \ifhmode%
8541 \SB@skip\lastskip\unskip%
8542 \setbox\SB@box\lastbox%
8543 \copy\SB@box%
8544 \ifvbox\SB@box%
8545 \begingroup%
8546 \setbox\SB@boxii\copy\SB@box%
8547 \vbadness\@M\vfuzz\maxdimen%
8548 \setbox\SB@boxii%
8549 \vsplit\SB@boxii to\maxdimen%
8550 \endgroup%
8551 \long\edef\SB@temp{\splitfirstmark}%
8552 \ifx\SB@temp\SB@measuremark%
8553 \penalty100\hskip1em%
8554 \else%
8555 \penalty100\hskip\SB@skip%
8556 \fi%
8557 \else%
8558 \penalty100\hskip\SB@skip%
8559 \fi%
8560 \fi%
8561 \ifvmode\leavevmode\fi%
8562 \setbox\SB@box\hbox{{\meterfont\relax#1}}%
8563 \setbox\SB@boxii\hbox{{\meterfont\relax#2}}%
8564 \SB@dimen\wd\ifdim\wd\SB@box>\wd\SB@boxii\SB@box\else\SB@boxii\fi%
8565 \SB@dimenii\baselineskip%
8566 \advance\SB@dimenii-2\p@%
8567 \advance\SB@dimenii-\ht\SB@box%
8568 \advance\SB@dimenii-\dp\SB@box%
8569 \advance\SB@dimenii-\ht\SB@boxii%
8570 \advance\SB@dimenii-\dp\SB@boxii%
8571 \let\SB@temp\relax%
8572 \ifdim\SB@dimen>\z@%
8573 \advance\[email protected]\p@%
8574 \def\SB@temp{\kern.75\p@}%
8575 \fi%
8576 \SB@maxmin\SB@dimen<{.5\p@}%
8577 \SB@maxmin\SB@dimenii<\z@%
8578 \vbox{%
8579 \mark{\SB@measuremark}%
8580 \hbox to\SB@dimen{%
8581 \hfil%
8582 \box\SB@box%
8583 \hfil%
8584 }%
8585 \nointerlineskip%
8586 \hbox to\SB@dimen{%
8587 \hfil%
8588 \box\SB@boxii%
8589 \hfil%
8590 }%
8591 \SB@temp%
8592 \nointerlineskip%
8593 \hbox to\SB@dimen{%
8594 \hfil%
8595 \vrule\@width.5\p@\@height\SB@dimenii%
8596 \hfil%
8597 }%
8598 }%
8599 \meter{}{}%
8600 }
8601 % \end{macrocode}
8602 % \end{macro}
8603 %
8604 % \begin{macro}{\mbar}
8605 % The |\mbar| macro invokes |\SB@mbar|, which gets redefined by macros and
8606 % options that turn measure bars on and off.
8607 % \begin{macrocode}
8608 \newcommand\mbar{\SB@mbar}
8609 % \end{macrocode}
8610 % \end{macro}
8611 %
8612 % \begin{macro}{\measurebar}\MainImpl{measurebar}
8613 % Make a measure bar using the most recently defined meter.
8614 % Then set the meter to nothing so that the next measure bar will not
8615 % display any meter unless the meter changes.
8616 % \begin{macrocode}
8617 \newcommand\measurebar{%
8618 \mbar\SB@metertop\SB@meterbot%
8619 }
8620 % \end{macrocode}
8621 % \end{macro}
8622 %
8623 % \begin{macro}{\SB@repcolon}
8624 % Create the colon that preceeds or follows a repeat sign.
8625 % \begin{macrocode}
8626 \newcommand\SB@repcolon{{%
8627 \usefont{OT1}{cmss}{m}{n}\selectfont%
8628 \ifchorded%
8629 \baselineskip.5\SB@dimen%
8630 \vbox{\hbox{:}\hbox{:}\kern.5\p@}%
8631 \else%
8632 \raise.5\p@\hbox{:}%
8633 \fi%
8634 }}
8635 % \end{macrocode}
8636 % \end{macro}
8637 %
8638 % \begin{macro}{\lrep}\MainImpl{lrep}
8639 % Create a begin-repeat sign.
8640 % \begin{macrocode}
8641 \newcommand\lrep{%
8642 \SB@dimen\baselineskip%
8643 \advance\SB@dimen-2\p@%
8644 \vrule\@width1.5\p@\@height\SB@dimen\@depth\p@%
8645 \kern1.5\p@%
8646 \vrule\@width.5\p@\@height\SB@dimen\@depth\p@%
8647 \SB@repcolon%
8648 }
8649 % \end{macrocode}
8650 % \end{macro}
8651 %
8652 % \begin{macro}{\rrep}\MainImpl{rrep}
8653 % Create an end-repeat sign.
8654 % \begin{macrocode}
8655 \newcommand\rrep{%
8656 \SB@dimen\baselineskip%
8657 \advance\SB@dimen-2\p@%
8658 \SB@repcolon%
8659 \vrule\@width.5\p@\@height\SB@dimen\@depth\p@%
8660 \kern1.5\p@%
8661 \vrule\@width1.5\p@\@height\SB@dimen\@depth\p@%
8662 }
8663 % \end{macrocode}
8664 % \end{macro}
8665 %
8666 % \subsection{Lyric Scanning}\label{sec:lyricscan}
8667 %
8668 % The obvious way to create a chord macro is as a normal macro with
8669 % two arguments, one for the chord name and one for the lyrics to go
8670 % under the chord---e.g.~|\chord{|\Meta{chordname}|}{|\Meta{lyric}|}|.
8671 % However, in practice such a macro is extremely cumbersome and
8672 % difficult to use.
8673 % The problem is that in order to use such a macro properly, the user
8674 % must remember a bunch of complex style rules that govern what
8675 % part of the lyric text needs to go in the \Meta{lyric} parameter and
8676 % what part should be typed after the closing brace.
8677 % To avoid separating a word from its trailing punctuation, the
8678 % \Meta{lyric} parameter must often include punctuation but not certain
8679 % special punctuation like hyphens, should include the rest of the
8680 % word but not if there's another chord in the word, should omit
8681 % measure bars but only if measure bars are being shown, etc.
8682 % This is way too difficult for the average user.
8683 %
8684 % To avoid this problem, we define chords using a one-argument macro
8685 % (the argument is the chord name), but with no explicit argument for
8686 % the lyric part.
8687 % Instead, the macro scans ahead in the input stream, automatically
8688 % determining what portion of the lyric text that follows should be
8689 % sucked in as an implicit second argument.
8690 % The following code does this look-ahead scanning.
8691 %
8692 % \begin{macro}{\ifSB@wordends}
8693 % \begin{macro}{\ifSB@brokenword}
8694 % Chord macros must look ahead in the input stream to see whether this chord
8695 % is immediately followed by whitespace or the remainder of a word.
8696 % If the latter, hyphenation might need to be introduced.
8697 % These macros keep track of the need for hyphenation, if any.
8698 % \begin{macrocode}
8699 \newif\ifSB@wordends
8700 \newif\ifSB@brokenword
8701 % \end{macrocode}
8702 % \end{macro}
8703 % \end{macro}
8704 %
8705 % \begin{macro}{\SB@lyric}
8706 % Lyrics appearing after a chord are scanned into the following token list
8707 % register.
8708 % \begin{macrocode}
8709 \SB@newtoks\SB@lyric
8710 % \end{macrocode}
8711 % \end{macro}
8712 %
8713 % \begin{macro}{\SB@numhyps}
8714 % Hyphens appearing in lyrics require special treatment.
8715 % The following counter counts the number of explicit hyphens ending
8716 % the lyric syllable that follows the current chord.
8717 % \begin{macrocode}
8718 \SB@newcount\SB@numhyps
8719 % \end{macrocode}
8720 % \end{macro}
8721 %
8722 % \begin{macro}{\SB@lyricnohyp}
8723 % When a lyric syllable under a chord ends in exactly one hyphen, the
8724 % following token register is set to be the syllable without the hyphen.
8725 % \begin{macrocode}
8726 \SB@newtoks\SB@lyricnohyp
8727 % \end{macrocode}
8728 % \end{macro}
8729 %
8730 % \begin{macro}{\SB@lyricbox}
8731 % \begin{macro}{\SB@chordbox}
8732 % The following two boxes hold the part of the lyric text that is to be
8733 % typeset under the chord, and the chord text that is to be typeset above.
8734 % \begin{macrocode}
8735 \SB@newbox\SB@lyricbox
8736 \SB@newbox\SB@chordbox
8737 % \end{macrocode}
8738 % \end{macro}
8739 % \end{macro}
8740 %
8741 % \begin{macro}{\SB@chbstok}
8742 % \changes{v1.22}{2007/05/15}{Added.}
8743 % When |\MultiwordChords| is active, the following reserved control
8744 % sequence remembers the first (space) token not yet included into the
8745 % |\SB@lyricbox| box.
8746 % \begin{macrocode}
8747 \newcommand\SB@chbstok{}
8748 % \end{macrocode}
8749 % \end{macro}
8750 %
8751 % \begin{macro}{\SB@setchord}
8752 % \changes{v2.3}{2007/09/23}{Support replayed chords over ligatures}
8753 % \changes{v2.7}{2009/01/08}{Extend rather than replace chordbox}
8754 % \changes{v3.0}{2017/04/19}{Fix transposition of replayed chord over ligature}
8755 % The following macro typesets its argument as a chord and stores the
8756 % result in box |\SB@chordbox| for later placement into the document.
8757 % The hat token (|^|) is redefined so that outside of math mode it
8758 % suppresses chord memorization, but inside of math mode it retains
8759 % its usual superscript meaning.
8760 % If memorization is active, the chord's token sequence is stored in
8761 % the current replay register.
8762 % If |\SB@chordbox| is non-empty, the new chord is appended to it
8763 % rather than replacing it.
8764 % This allows consecutive chords not separated by whitespace to be
8765 % typeset as a single chord sequence atop a common lyric.
8766 % \begin{macrocode}
8767 \newcommand\SB@setchord{}
8768 {
8769 \catcode`^\active
8770 \gdef\SB@setchord#1{%
8771 \SB@gettabindtrue\SB@nohattrue%
8772 \setbox\SB@chordbox\hbox{%
8773 \unhbox\SB@chordbox%
8774 \begingroup%
8775 \ifSB@trackch%
8776 \let\SB@activehat\SB@hat@tr%
8777 \else%
8778 \let\SB@activehat\SB@hat@notr%
8779 \fi%
8780 \let^\SB@activehat%
8781 \printchord{%
8782 \ifSB@firstchord\else\kern.15em\fi%
8783 \vphantom/%
8784 \transposehere{#1}%
8785 \kern.2em%
8786 }%
8787 \endgroup%
8788 }%
8789 \SB@gettabindfalse%
8790 \ifSB@trackch\ifSB@nohat%
8791 \global\SB@creg\expandafter{\the\SB@creg#1\\}%
8792 \fi\fi%
8793 \let\SB@noreplay\@firstofone%
8794 }
8795 }
8796 % \end{macrocode}
8797 % \end{macro}
8798 %
8799 % \begin{macro}{\SB@outertest}
8800 % \begin{macro}{\SB@otesta}
8801 % \begin{macro}{\SB@otestb}
8802 % The lyric-scanning code must preemptively determine whether the next token
8803 % is a macro declared |\outer| before it tries to accept that token as an
8804 % argument.
8805 % Otherwise \TeX{} will abort with a parsing error.
8806 % Macros declared |\outer| are not allowed in arguments, so determining
8807 % whether a token is |\outer| is a delicate process.
8808 % The following does so by consulting |\meaning|.
8809 % A macro can be identified as |\outer| if its meaning has the
8810 % word ``|\outer|'' before the first colon.
8811 % \begin{macrocode}
8812 \newcommand\SB@outertest{%
8813 \expandafter\SB@otesta\meaning\SB@next:\SB@otesta%
8814 }
8815 \newcommand\SB@otesta{}
8816 \edef\SB@otesta#1:#2\SB@otesta{%
8817 \noexpand\SB@otestb%
8818 #1\string\outer%
8819 \noexpand\SB@otestb%
8820 }
8821 \newcommand\SB@otestb{}
8822 \expandafter\def\expandafter\SB@otestb%
8823 \expandafter#\expandafter1\string\outer#2\SB@otestb{%
8824 \def\SB@temp{#2}%
8825 \ifx\SB@temp\@empty\SB@testfalse\else\SB@testtrue\fi%
8826 }
8827 % \end{macrocode}
8828 % \end{macro}
8829 % \end{macro}
8830 % \end{macro}
8831 %
8832 % \begin{macro}{\SB@UTFtest}
8833 % \begin{macro}{\SB@U@two}
8834 % \begin{macro}{\SB@U@three}
8835 % \begin{macro}{\SB@U@four}
8836 % \begin{macro}{\SB@@UTFtest}
8837 % \changes{v1.22}{2007/05/15}{Added.}
8838 % To support UTF-8 encoded \LaTeX{} source files, we need to be able to
8839 % identify multibyte characters during the lyric scanning process.
8840 % Alas, the |utf8.def| file provides no clean way of identifying the
8841 % macros it defines for this purpose.
8842 % The best solution seems to be to look for any token named
8843 % |\UTFviii@|$\ldots$|@octets| in the top-level expansion of the macro.
8844 % \begin{macrocode}
8845 \newcommand\SB@UTFtest{}
8846 \edef\SB@UTFtest#1{%
8847 \noexpand\expandafter%
8848 \noexpand\SB@@UTFtest%
8849 \noexpand\meaning#1%
8850 \string\UTFviii@zero@octets%
8851 \noexpand\SB@@UTFtest%
8852 }
8853 \newcommand\SB@U@two{\global\SB@cnt\tw@}
8854 \newcommand\SB@U@three{\global\SB@cnt\thr@@}
8855 \newcommand\SB@U@four{\global\SB@cnt4\relax}
8856 \newcommand\SB@@UTFtest{}
8857 {\escapechar\m@ne
8858 \xdef\SB@temp{\string\@octets}}
8859 \edef\SB@temp{##1\string\UTFviii@##2\SB@temp}
8860 \expandafter\def\expandafter\SB@@UTFtest\SB@temp#3\SB@@UTFtest{%
8861 \SB@cnt\z@%
8862 {\csname SB@U@#2\endcsname}%
8863 }
8864 % \end{macrocode}
8865 % \end{macro}
8866 % \end{macro}
8867 % \end{macro}
8868 % \end{macro}
8869 % \end{macro}
8870 %
8871 % \begin{macro}{\DeclareLyricChar}\MainImpl{DeclareLyricChar}
8872 % \begin{macro}{\DeclareNonLyric}\MainImpl{DeclareNonLyric}
8873 % \begin{macro}{\DeclareNoHyphen}\MainImpl{DeclareNoHyphen}
8874 % \begin{macro}{\SB@declare}
8875 % \changes{v1.22}{2007/05/15}{Added \cs{DeclareLyricChar}.}
8876 % \changes{v2.1}{2007/08/02}{Added \cs{DeclareNonLyric} and \cs{DeclareNoHyphen}.}
8877 % \changes{v2.6}{2008/03/27}{Macro tests made name-based instead of def-based}
8878 % When scanning the lyric text that follows a chord, it is necessary to
8879 % distinguish accents and other intra-word macros (which should be included
8880 % in the under-chord lyric text) from other macros (which should be pushed
8881 % out away from the text).
8882 % The following macros allow users to declare a token to be lyric-continuing
8883 % or lyric-ending.
8884 % \begin{macrocode}
8885 \newcommand\SB@declare[3]{%
8886 \afterassignment\iffalse\let\SB@next= #3\relax\fi%
8887 \SB@UTFtest\SB@next%
8888 \ifcase\SB@cnt%
8889 \ifcat\noexpand#3\relax%
8890 \SB@addNtest\SB@macrotests#1#2#3%
8891 \else\ifcat\noexpand#3.%
8892 \SB@addDtest\SB@othertests#1#2%
8893 \else\ifcat\noexpand#3A%
8894 \SB@addDtest\SB@lettertests#1#2%
8895 \else%
8896 \SB@addDtest\relax0#2%
8897 \fi\fi\fi%
8898 \or%
8899 \SB@addNtest\SB@macrotests#1#2#3%
8900 \else%
8901 \SB@addMtest\SB@multitests#1#2#3\relax\relax\relax%
8902 \fi%
8903 }
8904 \newcommand\DeclareLyricChar{\SB@declare\SB@testtrue0}
8905 \newcommand\DeclareNonLyric{\SB@declare\SB@testfalse\SB@testfalse}
8906 \newcommand\DeclareNoHyphen{\SB@declare\SB@testfalse\SB@testtrue}
8907 % \end{macrocode}
8908 % \end{macro}
8909 % \end{macro}
8910 % \end{macro}
8911 % \end{macro}
8912 %
8913 % \begin{macro}{\SB@lettertests}
8914 % \begin{macro}{\SB@macrotests}
8915 % \begin{macro}{\SB@multitests}
8916 % \begin{macro}{\SB@othertests}
8917 % For speed, token tests introduced by |\DeclareLyricChar| and friends
8918 % are broken out into separate macros based on category codes.
8919 % \begin{macrocode}
8920 \newcommand\SB@lettertests{}
8921 \newcommand\SB@macrotests{}
8922 \newcommand\SB@multitests{}
8923 \newcommand\SB@othertests{}
8924 % \end{macrocode}
8925 % \end{macro}
8926 % \end{macro}
8927 % \end{macro}
8928 % \end{macro}
8929 %
8930 % The following macros add tests to the test macros defined above.
8931 % In each, \argp{1} is the test macro to which the test should be added,
8932 % \argp{2} and \argp{3} is the code to be executed at scanning-time and
8933 % at hyphenation-time if the test succeeds (or ``0'' if no action is to
8934 % be performed), and \argp{4} is the token to which the currently scanned
8935 % token should be compared to determine whether it matches.
8936 %
8937 % \begin{macro}{\SB@addDtest}
8938 % A definition-test: The test succeeds if the next lyric token has the same
8939 % meaning (at test-time) of the non-macro, non-active character token that
8940 % was given to the |\Declare| macro.
8941 % \begin{macrocode}
8942 \newcommand\SB@addDtest[3]{%
8943 \ifx0#2\else%
8944 \def#1{{\csname SB@!\meaning\SB@next\endcsname}}%
8945 \expandafter\def\csname SB@!\meaning\SB@next\endcsname{\global#2}%
8946 \fi%
8947 \ifx0#3\else%
8948 \expandafter\def\csname SB@HT@\meaning\SB@next\endcsname{\global#3}%
8949 \fi%
8950 }
8951 % \end{macrocode}
8952 % \end{macro}
8953 %
8954 % \begin{macro}{\SB@addNtest}
8955 % A name-test: The test succeeds if the next token is a non-|\outer|
8956 % macro or active character and its |\string|ified name matches the
8957 % |\string|ified name of the control sequence that was given to the
8958 % |\Declare| macro.
8959 % \begin{macrocode}
8960 \newcommand\SB@addNtest[4]{%
8961 \ifx0#2\else%
8962 \def#1{{\csname SB@!\SB@nextname\endcsname}}%
8963 \expandafter\def\csname SB@!\string#4\endcsname{\global#2}%
8964 \fi%
8965 \ifx0#3\else%
8966 \expandafter\def\csname SB@HT@\string#4\endcsname{\global#3}%
8967 \fi%
8968 }
8969 % \end{macrocode}
8970 % \end{macro}
8971 %
8972 % \begin{macro}{\SB@addMtest}
8973 % A multibyte-test: The test succeeds if the next lyric token is the
8974 % beginning of a UTF-8 encoded multibyte character sequence that matches
8975 % the multibyte sequence given to the |\Declare| macro.
8976 % \begin{macrocode}
8977 \newcommand\SB@addMtest[7]{%
8978 \edef\SB@temp{%
8979 \string#4%
8980 \ifx\relax#5\else\string#5\fi%
8981 \ifx\relax#6\else\string#6\fi%
8982 \ifx\relax#7\else\string#7\fi%
8983 }%
8984 \ifx0#2\else%
8985 \def#1{{\csname SB@!\SB@nextname\endcsname}}%
8986 \expandafter\def\csname SB@!\SB@temp\endcsname{\global#2}%
8987 \fi%
8988 \ifx0#3\else%
8989 \expandafter\def\csname SB@HT@\SB@temp\endcsname{\global#3}%
8990 \fi%
8991 }
8992 % \end{macrocode}
8993 % \end{macro}
8994 %
8995 % The following code declares the common intra-word macros provided by
8996 % \TeX{} (as listed on p.~52 of The \TeX book) to be lyric-continuing.
8997 % \begin{macrocode}
8998 \DeclareLyricChar\`
8999 \DeclareLyricChar\'
9000 \DeclareLyricChar\^
9001 \DeclareLyricChar\"
9002 \DeclareLyricChar\~
9003 \DeclareLyricChar\=
9004 \DeclareLyricChar\.
9005 \DeclareLyricChar\u
9006 \DeclareLyricChar\v
9007 \DeclareLyricChar\H
9008 \DeclareLyricChar\t
9009 \DeclareLyricChar\c
9010 \DeclareLyricChar\d
9011 \DeclareLyricChar\b
9012 \DeclareLyricChar\oe
9013 \DeclareLyricChar\OE
9014 \DeclareLyricChar\ae
9015 \DeclareLyricChar\AE
9016 \DeclareLyricChar\aa
9017 \DeclareLyricChar\AA
9018 \DeclareLyricChar\o
9019 \DeclareLyricChar\O
9020 \DeclareLyricChar\l
9021 \DeclareLyricChar\L
9022 \DeclareLyricChar\ss
9023 \DeclareLyricChar\i
9024 \DeclareLyricChar\j
9025 \DeclareLyricChar\/
9026 \DeclareLyricChar\-
9027 \DeclareLyricChar\discretionary
9028 % \end{macrocode}
9029 %
9030 % We declare |\par| to be lyric-ending without introducing hyphenation.
9031 % The |\par| macro doesn't actually appear in most verses because we use
9032 % |\obeylines|, but we include a check for it in case the user says |\par|
9033 % explicitly somewhere.
9034 % \begin{macrocode}
9035 \DeclareNoHyphen\par
9036 % \end{macrocode}
9037 %
9038 % \begin{macro}{\SB@bracket}
9039 % This macro gets invoked by the |\[|\eat\] macro whenever a chord begins.
9040 % It gets redefined by code that turns chords on and off, so its initial
9041 % definition doesn't matter.
9042 % \begin{macrocode}
9043 \newcommand\SB@bracket{}
9044 % \end{macrocode}
9045 % \end{macro}
9046 %
9047 % \begin{macro}{\SB@chord}
9048 % Begin parsing a chord macro.
9049 % While parsing the chord name argument, we set some special catcodes so
9050 % that chord names can use |#| and |&| for sharps and flats.
9051 % \begin{macrocode}
9052 \newcommand\SB@chord{\SB@begincname\SB@@chord}
9053 % \end{macrocode}
9054 % \end{macro}
9055 %
9056 % \begin{macro}{\SB@begincname}
9057 % \begin{macro}{\SB@endcname}
9058 % While parsing a chord name, certain characters such as |#| and |&| are
9059 % temporarily set active so that they can be used as abbreviations for
9060 % sharps and flats.
9061 % To accomplish this, |\SB@begincname| must always be invoked before any
9062 % macro whose argument is a chord name, and |\SB@endcname| must be invoked
9063 % at the start of the body of any macro whose argument is a chord name.
9064 % To aid in debugging, we also temporarily set \Meta{return} characters and
9065 % chord macros |\outer|.
9066 % This will cause \TeX{} to halt with a runaway argument error on the correct
9067 % source line if the user forgets to type a closing end-brace (a common typo).
9068 % Colon characters are also set non-active to avoid a conflict between the
9069 % \textsf{Babel} French package and the |\gtab| macro.
9070 % \begin{macrocode}
9071 \newcommand\SB@begincname{}
9072 {\catcode`\^^M\active
9073 \gdef\SB@begincname{%
9074 \begingroup%
9075 \catcode`##\active\catcode`&\active%
9076 \catcode`:12\relax%
9077 \catcode`\^^M\active\SB@outer\def^^M{}%
9078 \SB@outer\def\[{}%
9079 \chordlocals\relax%
9080 }
9081 }
9082 \newcommand\SB@endcname{}
9083 \let\SB@endcname\endgroup
9084 % \end{macrocode}
9085 % \end{macro}
9086 % \end{macro}
9087 %
9088 % \begin{macro}{\SB@nbsp}
9089 % Non-breaking spaces (|~|) should be treated as spaces by the lyric-scanner
9090 % code that follows.
9091 % Although |~| is usually an active character that creates a non-breaking
9092 % space, some packages (e.g., the \textsf{Babel} package) redefine it to
9093 % produce accents, which are typically not lyric-ending.
9094 % To distinguish the real |~| from redefined |~|, we need to create a macro
9095 % whose definition is the non-breaking space definition normally assigned to
9096 % |~|.
9097 % \begin{macrocode}
9098 \newcommand*\SB@nbsp{\nobreakspace{}}
9099 % \end{macrocode}
9100 % \end{macro}
9101 %
9102 % \begin{macro}{\SB@firstchord}
9103 % The following conditional is true when the current chord is the first
9104 % chord in a sequence of one or more chord macros.
9105 % \begin{macrocode}
9106 \newif\ifSB@firstchord\SB@firstchordtrue
9107 % \end{macrocode}
9108 % \end{macro}
9109 %
9110 % \begin{macro}{\SB@@chord}
9111 % Finish processing the chord name and then begin scanning the implicit
9112 % lyric argument that follows it.
9113 % This is the main entrypoint to the lyric-scanner code.
9114 % \begin{macrocode}
9115 \newcommand*\SB@@chord{}
9116 \def\SB@@chord#1]{%
9117 \SB@endcname%
9118 \ifSB@firstchord%
9119 \setbox\SB@lyricbox\hbox{\kern\SB@tabindent}%
9120 \global\SB@tabindent\z@%
9121 \SB@lyric{}%
9122 \SB@numhyps\z@%
9123 \SB@spcinit%
9124 \setbox\SB@chordbox\box\voidb@x%
9125 \fi%
9126 \SB@setchord{#1}%
9127 \SB@firstchordfalse%
9128 \let\SB@dothis\SB@chstart%
9129 \SB@chscan%
9130 }
9131 % \end{macrocode}
9132 % \end{macro}
9133 %
9134 % \begin{macro}{\MultiwordChords}\MainImpl{MultiwordChords}
9135 % \begin{macro}{\SB@spcinit}
9136 % \changes{v1.22}{2007/05/15}{Added.}
9137 % The |\SB@spcinit| macro is invoked at the beginning of the lyric
9138 % scanning process.
9139 % By default it does nothing, but if |\MultiwordChords| is invoked,
9140 % it initializes the lyric-scanner state to process spaces as part of
9141 % lyrics.
9142 % \begin{macrocode}
9143 \newcommand\SB@spcinit{}
9144 \newcommand\MultiwordChords{%
9145 \def\SB@spcinit{%
9146 \let\SB@chdone\SB@chlyrdone%
9147 \let\SB@chimpspace\SB@chnxtdone%
9148 \let\SB@chexpspace\SB@chnxtdone%
9149 \let\SB@chespace\SB@chendspace%
9150 }%
9151 }
9152 % \end{macrocode}
9153 % \end{macro}
9154 % \end{macro}
9155 %
9156 % \begin{macro}{\SB@chscan}
9157 % \begin{macro}{\SB@chmain}
9158 % This is the main loop of the lyric-scanner.
9159 % Peek ahead at the next token without consuming it, then execute
9160 % a loop body based on the current state (|\SB@dothis|), and finally
9161 % go to the next iteration (|\SB@donext|).
9162 % \begin{macrocode}
9163 \newcommand\SB@chscan{%
9164 \let\SB@nextname\relax%
9165 \futurelet\SB@next\SB@chmain%
9166 }
9167 \newcommand\SB@chmain{\SB@dothis\SB@donext}
9168 % \end{macrocode}
9169 % \end{macro}
9170 % \end{macro}
9171 %
9172 % \begin{macro}{\SB@chnxtrelax}
9173 % \begin{macro}{\SB@chnxtstep}
9174 % \begin{macro}{\SB@chnxtdone}
9175 % To shorten the lyric parser macros that follow and thereby improve their
9176 % speed, we here define some abbreviations for common logic in untaken
9177 % branches.
9178 % \begin{macrocode}
9179 \newcommand\SB@chnxtrelax{\let\SB@donext\relax}
9180 \newcommand\SB@chnxtstep{\let\SB@donext\SB@chstep}
9181 \newcommand\SB@chnxtdone{\let\SB@donext\SB@chdone}
9182 % \end{macrocode}
9183 % \end{macro}
9184 % \end{macro}
9185 % \end{macro}
9186 %
9187 % Warning: In the lyric-scanner macros that follow, |\SB@next|
9188 % might be a macro declared |\outer|.
9189 % This means that it must \emph{never} be passed as an argument to
9190 % a macro and it must never explicitly appear in any untaken branch
9191 % of a conditional.
9192 % If it does, the \TeX{} parser will complain of a runaway argument
9193 % when it tries to skip over an |\outer| macro while consuming tokens
9194 % at high speed.
9195 %
9196 % \begin{macro}{\SB@chstart}
9197 % We begin lyric-scanning with two special cases:
9198 % (1) If the chord macro is immediately followed by another chord macro with
9199 % no intervening whitespace, drop out of the lyric scanner and reenter it when
9200 % the second macro is parsed.
9201 % The chord texts will get concatenated together above the lyric that follows.
9202 % (2) If the chord macro is immediately followed by one or more quote
9203 % tokens, then consume them all and output them \emph{before} the chord.
9204 % This causes the chord to sit above the actual word instead of the
9205 % left-quote or left-double-quote symbol, which looks better.
9206 % \begin{macrocode}
9207 \newcommand\SB@chstart{%
9208 \ifx\SB@next\[\SB@chnxtrelax%
9209 \else\ifx\SB@next\SB@activehat\SB@chnxtrelax%
9210 \else\ifx\SB@next\ch\SB@chnxtrelax%
9211 \else\ifx\SB@next\mch\SB@chnxtrelax%
9212 \else\ifx\SB@next`\SB@chnxtstep%
9213 \else\ifx\SB@next'\SB@chnxtstep%
9214 \else\ifx\SB@next"\SB@chnxtstep%
9215 \else%
9216 \the\SB@lyric%
9217 \SB@lyric{}%
9218 \SB@firstchordtrue%
9219 \let\SB@dothis\SB@chnorm%
9220 \SB@chnorm%
9221 \fi\fi\fi\fi\fi\fi\fi%
9222 }
9223 % \end{macrocode}
9224 % \end{macro}
9225 % \eat\]
9226 %
9227 % \begin{macro}{\SB@chnorm}
9228 % \changes{v2.0}{2007/06/18}{Rewritten for speed}
9229 % First, check to see whether the lyric token is a letter.
9230 % Since that's the most common case, we do this check first for speed.
9231 % \begin{macrocode}
9232 \newcommand\SB@chnorm{%
9233 \ifcat\noexpand\SB@next A%
9234 \SB@testtrue\SB@lettertests%
9235 \ifSB@test%
9236 \SB@chespace\SB@chnxtstep%
9237 \else%
9238 \SB@chnxtdone%
9239 \fi%
9240 \else%
9241 \SB@chtrymacro%
9242 \fi%
9243 }
9244 % \end{macrocode}
9245 % \end{macro}
9246 %
9247 % \begin{macro}{\SB@chtrymacro}
9248 % Next, check to see whether it's a macro or active character.
9249 % We do these checks next because these are the only cases when the
9250 % token might be |\outer|.
9251 % Once we eliminate that ugly possibility, we can write the rest of
9252 % the code without having to worry about putting |\SB@next| in
9253 % places where |\outer| tokens are illegal.
9254 % \begin{macrocode}
9255 \newcommand\SB@chtrymacro{%
9256 \ifcat\noexpand\SB@next\relax%
9257 \SB@chmacro%
9258 \else%
9259 \SB@chother%
9260 \fi%
9261 }
9262 % \end{macrocode}
9263 % \end{macro}
9264 %
9265 % \begin{macro}{\SB@chother}
9266 % The token is not a letter, macro, or active character.
9267 % The only other cases of interest are spaces, braces, and hyphens.
9268 % If it's one of those, take the appropriate action; otherwise end the
9269 % lyric here.
9270 % Since we've eliminated the possibility of macros and active characters,
9271 % we can be sure that the token isn't |\outer| at this point.
9272 % \begin{macrocode}
9273 \newcommand\SB@chother{%
9274 \ifcat\noexpand\SB@next\@sptoken%
9275 \SB@chexpspace%
9276 \else\ifcat\noexpand\SB@next\bgroup%
9277 \SB@chespace\let\SB@donext\SB@chbgroup%
9278 \else\ifcat\noexpand\SB@next\egroup%
9279 \SB@chespace\let\SB@donext\SB@chegroup%
9280 \else\ifx\SB@next-%
9281 \SB@numhyps\@ne\relax%
9282 \SB@lyricnohyp\expandafter{\the\SB@lyric}%
9283 \let\SB@dothis\SB@chhyph%
9284 \SB@chespace\SB@chnxtstep%
9285 \else\ifcat\noexpand\SB@next.%
9286 \SB@testtrue\SB@othertests%
9287 \ifSB@test%
9288 \SB@chespace\SB@chnxtstep%
9289 \else%
9290 \SB@chnxtdone%
9291 \fi%
9292 \else%
9293 \SB@chespace\SB@chnxtstep%
9294 \fi\fi\fi\fi\fi%
9295 }
9296 % \end{macrocode}
9297 % \end{macro}
9298 %
9299 % \begin{macro}{\SB@chmacro}
9300 % \changes{v1.22}{2007/05/15}{Added support for UTF-8.}
9301 % The lyric-scanner has encountered a macro or active character.
9302 % If it's |\outer|, it should never be used in an argument, so stop here.
9303 % \begin{macrocode}
9304 \newcommand\SB@chmacro{%
9305 \SB@outertest%
9306 \ifSB@test%
9307 \SB@chnxtdone%
9308 \else%
9309 \let\SB@donext\SB@chgetname%
9310 \fi%
9311 }
9312 % \end{macrocode}
9313 % \end{macro}
9314 %
9315 % \begin{macro}{\SB@chgetname}
9316 % We've encountered a non-|\outer| macro or active character.
9317 % Use |\string| to get its name, but insert the token back into the
9318 % input stream since we haven't decided whether to consume it yet.
9319 % \begin{macrocode}
9320 \newcommand\SB@chgetname[1]{%
9321 \edef\SB@nextname{\string#1}%
9322 \SB@@chmacro\SB@donext#1%
9323 }
9324 % \end{macrocode}
9325 % \end{macro}
9326 %
9327 % \begin{macro}{\SB@@chmacro}
9328 % The lyric-scanner has encountered a non-|\outer| macro or active character.
9329 % Its |\string|ified name has been stored in |\SB@nextname|.
9330 % Test to see whether it's a known macro or the beginning of a
9331 % multibyte-encoded international character.
9332 % If the former, dispatch some macro-specific code to handle it.
9333 % If the latter, grab the full multibyte sequence and include it in the lyric.
9334 % \begin{macrocode}
9335 \newcommand\SB@@chmacro{%
9336 \ifx\SB@next\SB@activehat%
9337 \SB@chnxtdone%
9338 \else\ifx\SB@next\SB@par%
9339 \SB@chnxtdone%
9340 \else\ifx\SB@next\measurebar%
9341 \SB@chmbar%
9342 \else\ifx\SB@next\mbar%
9343 \SB@chmbar%
9344 \else\ifx\SB@next\ch%
9345 \SB@chespace\let\SB@donext\SB@chlig%
9346 \else\ifx\SB@next\mch%
9347 \SB@chespace\let\SB@donext\SB@mchlig%
9348 \else\ifx\SB@next\ %
9349 \SB@chimpspace%
9350 \else\ifx\SB@next\SB@nbsp%
9351 \SB@chimpspace%
9352 \else%
9353 \SB@UTFtest\SB@next%
9354 \ifcase\SB@cnt\SB@chothermac%
9355 \or\or\SB@chespace\let\SB@donext\SB@chsteptwo%
9356 \or\SB@chespace\let\SB@donext\SB@chstepthree%
9357 \or\SB@chespace\let\SB@donext\SB@chstepfour\fi%
9358 \fi\fi\fi\fi\fi\fi\fi\fi%
9359 }
9360 % \end{macrocode}
9361 % \end{macro}
9362 %
9363 % \begin{macro}{\SB@chothermac}
9364 % \changes{v2.6}{2008/03/26}{All active chars now included in lyrics by default.}
9365 % The lyric-scanner has encountered a macro or active character that is
9366 % not |\outer|, not a known macro that requires special treatment,
9367 % and not a multibyte international character.
9368 % First, check the macro's name (stored in |\SB@nextname|) to see whether it
9369 % begins with a non-escape character.
9370 % If so, it's probably an accenting or punctuation character made active
9371 % by the |inputenc| or |babel| packages.
9372 % Most such characters should be included in the lyric, so include it by
9373 % default; otherwise exclude it by default.
9374 % The user can override the defaults using |\DeclareLyricChar| and friends.
9375 % \begin{macrocode}
9376 \newcommand\SB@chothermac{%
9377 \SB@testfalse%
9378 \afterassignment\iffalse%
9379 \SB@cnt\expandafter`\SB@nextname x\fi%
9380 \ifnum\the\catcode\SB@cnt=\z@\else\SB@testtrue\fi%
9381 \SB@macrotests%
9382 \ifSB@test%
9383 \SB@chespace\SB@chnxtstep%
9384 \else%
9385 \SB@chnxtdone%
9386 \fi%
9387 }
9388 % \end{macrocode}
9389 % \end{macro}
9390 %
9391 % \begin{macro}{\SB@chstep}
9392 % \begin{macro}{\SB@chsteptwo}
9393 % \begin{macro}{\SB@chstepthree}
9394 % \begin{macro}{\SB@chstepfour}
9395 % \begin{macro}{\SB@chmulti}
9396 % \begin{macro}{\SB@chmstop}
9397 % We've encountered one or more tokens that should be included in the
9398 % lyric text.
9399 % (More than one means we've encountered a multibyte encoding of an
9400 % international character.)
9401 % Consume them (as arguments to this macro) and add them to the list
9402 % of tokens we've already consumed.
9403 % \begin{macrocode}
9404 \newcommand\SB@chstep[1]{%
9405 \SB@lyric\expandafter{\the\SB@lyric#1}%
9406 \SB@chscan%
9407 }
9408 \newcommand\SB@chsteptwo[2]{\SB@chmulti{#1#2}{\string#1\string#2}}
9409 \newcommand\SB@chstepthree[3]{%
9410 \SB@chmulti{#1#2#3}{\string#1\string#2\string#3}%
9411 }
9412 \newcommand\SB@chstepfour[4]{%
9413 \SB@chmulti{#1#2#3#4}{\string#1\string#2\string#3\string#4}%
9414 }
9415 \newcommand\SB@chmulti[2]{%
9416 \def\SB@next{#1}%
9417 \edef\SB@nextname{#2}%
9418 \SB@testtrue\SB@multitests%
9419 \ifSB@test%
9420 \SB@lyric\expandafter{\the\SB@lyric#1}%
9421 \expandafter\SB@chscan%
9422 \else%
9423 \expandafter\SB@chmstop%
9424 \fi%
9425 }
9426 \newcommand\SB@chmstop{\expandafter\SB@chdone\SB@next}
9427 % \end{macrocode}
9428 % \end{macro}
9429 % \end{macro}
9430 % \end{macro}
9431 % \end{macro}
9432 % \end{macro}
9433 % \end{macro}
9434 %
9435 % \begin{macro}{\SB@chhyph}
9436 % We've encountered a hyphen.
9437 % Continue to digest hyphens, but terminate as soon as we see anything
9438 % else.
9439 % \begin{macrocode}
9440 \newcommand\SB@chhyph{%
9441 \ifx\SB@next-%
9442 \advance\SB@numhyps\@ne\relax%
9443 \SB@chnxtstep%
9444 \else%
9445 \SB@chnxtdone%
9446 \fi%
9447 }
9448 % \end{macrocode}
9449 % \end{macro}
9450 %
9451 % \begin{macro}{\SB@chimpspace}
9452 % \begin{macro}{\SB@chexpspace}
9453 % We've encountered an implicit or explicit space.
9454 % Normally this just ends the lyric, but if |\MultiwordChords| is
9455 % active, these macros both get redefined to process the space.
9456 % \begin{macrocode}
9457 \newcommand\SB@chimpspace{}
9458 \let\SB@chimpspace\SB@chnxtdone
9459 \newcommand\SB@chexpspace{}
9460 \let\SB@chexpspace\SB@chnxtdone
9461 % \end{macrocode}
9462 % \end{macro}
9463 % \end{macro}
9464 %
9465 % \begin{macro}{\SB@chespace}
9466 % \begin{macro}{\SB@chendspace}
9467 % \changes{v1.22}{2007/05/15}{Added.}
9468 % The |\SB@chespace| macro gets invoked by the lyric-scanner just before a
9469 % non-space token is about to be accepted as part of an under-chord lyric.
9470 % Normally it does nothing; however, if |\MultiwordChords| is active, it
9471 % gets redefined to do one of three things:
9472 % (1) Initially it is set equal to |\SB@chendspace| so that if the very
9473 % first token following the chord macro is not a space, the lyric-scanner
9474 % macros are redefined to process any future spaces encountered.
9475 % Otherwise the very first token is a space, and the lyric ends immediately.
9476 % (2) While scanning non-space lyric tokens, it is set to nothing, since no
9477 % special action needs to be taken until we encounter a sequence of one or
9478 % more spaces.
9479 % (3) When a space token is encountered (but not the very first token after
9480 % the chord macro), it is set equal to |\SB@chendspace| again so that
9481 % |\SB@chendspace| is invoked once the sequence of one or more space tokens
9482 % is finished.
9483 % \begin{macrocode}
9484 \newcommand\SB@chespace{}
9485 \newcommand\SB@chendspace{%
9486 \let\SB@chdone\SB@chlyrdone%
9487 \def\SB@chexpspace{\SB@chbspace\SB@chexpspace}%
9488 \def\SB@chimpspace{\SB@chbspace\SB@chimpspace}%
9489 \def\SB@chespace{}%
9490 }
9491 % \end{macrocode}
9492 % \end{macro}
9493 % \end{macro}
9494 %
9495 % \begin{macro}{\SB@chbspace}
9496 % \begin{macro}{\SB@chgetspace}
9497 % \changes{v1.22}{2007/05/15}{Added.}
9498 % The |\SB@chbspace| macro gets invoked when |\MultiwordChords| is active
9499 % and the lyric-scanner has encountered a space token that was immediately
9500 % preceded by a non-space token.
9501 % Before processing the space, we add all lyrics seen so far to the
9502 % |\SB@lyricbox| and check its width.
9503 % If we've seen enough lyrics to match or exceed the width of the chord,
9504 % a space stops the lyric-scanning process.
9505 % (This is important because it minimizes the size of the chord box,
9506 % providing as many line breakpoints as possible to the paragraph-formatter.)
9507 %
9508 % Otherwise we begin scanning space tokens without adding them to the
9509 % lyric until we see what the next non-space token is.
9510 % If the next non-space token would have ended the lyric anyway, roll back
9511 % and end the lyric here, reinserting the space tokens back into the token
9512 % stream.
9513 % If the next non-space token would have been included in the lyric,
9514 % the lyric-scanner proceeds as normal.
9515 % \begin{macrocode}
9516 \newcommand\SB@chbspace{%
9517 \setbox\SB@lyricbox\hbox{%
9518 \unhbox\SB@lyricbox%
9519 \the\SB@lyric%
9520 }%
9521 \SB@lyric{}%
9522 \ifdim\wd\SB@lyricbox<\wd\SB@chordbox%
9523 \let\SB@chbstok= \SB@next%
9524 \def\SB@chexpspace{\let\SB@donext\SB@chgetspace}%
9525 \let\SB@chimpspace\SB@chnxtstep%
9526 \let\SB@chespace\SB@chendspace%
9527 \let\SB@chdone\SB@chspcdone%
9528 \else%
9529 \let\SB@chimpspace\SB@chnxtdone%
9530 \let\SB@chexpspace\SB@chnxtdone%
9531 \fi%
9532 }
9533 \newcommand\SB@chgetspace{%
9534 \SB@appendsp\SB@lyric%
9535 \let\SB@nextname\relax%
9536 \afterassignment\SB@chscan%
9537 \let\SB@next= }
9538 % \end{macrocode}
9539 % \end{macro}
9540 % \end{macro}
9541 %
9542 % \begin{macro}{\SB@chmbar}
9543 % We've encountered a measure bar.
9544 % Either ignore it or end the lyric text, depending on whether
9545 % measure bars are being displayed.
9546 % \begin{macrocode}
9547 \newcommand\SB@chmbar{%
9548 \ifmeasures%
9549 \SB@chnxtdone%
9550 \else%
9551 \SB@chespace\SB@chnxtstep%
9552 \fi%
9553 }
9554 % \end{macrocode}
9555 % \end{macro}
9556 %
9557 % \begin{macro}{\SB@chbgroup}
9558 % We've encountered a begin-group brace.
9559 % Consume the entire group that it begins, and add it to the list
9560 % of tokens including the begin and end group tokens.
9561 % \begin{macrocode}
9562 \newcommand\SB@chbgroup[1]{%
9563 \SB@lyric\expandafter{\the\SB@lyric{#1}}%
9564 \SB@chscan%
9565 }
9566 % \end{macrocode}
9567 % \end{macro}
9568 %
9569 % \begin{macro}{\SB@chegroup}
9570 % \begin{macro}{\SB@chegrpscan}
9571 % \begin{macro}{\SB@chegrpmacro}
9572 % \begin{macro}{\SB@chegrpouter}
9573 % \begin{macro}{\SB@chegrpname}
9574 % \begin{macro}{\SB@chegrpdone}
9575 % We've encountered an end-group brace whose matching begin-group brace
9576 % must have come before the chord macro itself.
9577 % This forcibly ends the lyric text.
9578 % Before stopping, we must set |\SB@next| to the token following the brace
9579 % and |\SB@nextname| to its |\string|ified name so that |\SB@emitchord| will
9580 % know whether to add hyphenation.
9581 % Therefore, we temporarily consume the end-group brace, then scan the
9582 % next token without consuming it, and finally reinsert the end-group brace
9583 % and stop.
9584 % \begin{macrocode}
9585 \newcommand\SB@chegroup{%
9586 \let\SB@nextname\relax%
9587 \afterassignment\SB@chegrpscan%
9588 \let\SB@next= }
9589 \newcommand\SB@chegrpscan{%
9590 \futurelet\SB@next\SB@chegrpmacro%
9591 }
9592 \newcommand\SB@chegrpmacro{%
9593 \ifcat\noexpand\SB@next\relax%
9594 \expandafter\SB@chegrpouter%
9595 \else%
9596 \expandafter\SB@chegrpdone%
9597 \fi%
9598 }
9599 \newcommand\SB@chegrpouter{%
9600 \SB@outertest%
9601 \ifSB@test%
9602 \expandafter\SB@chegrpdone%
9603 \else%
9604 \expandafter\SB@chegrpname%
9605 \fi%
9606 }
9607 \newcommand\SB@chegrpname[1]{%
9608 \edef\SB@nextname{\string#1}%
9609 \SB@chegrpdone#1%
9610 }
9611 \newcommand\SB@chegrpdone{\SB@chdone\egroup}
9612 % \end{macrocode}
9613 % \end{macro}
9614 % \end{macro}
9615 % \end{macro}
9616 % \end{macro}
9617 % \end{macro}
9618 % \end{macro}
9619 %
9620 % \begin{macro}{\SB@chlig}
9621 % \begin{macro}{\SB@mchlig}
9622 % We've encountered a |\ch| chord-over-ligature macro, or an
9623 % |\mch| measurebar-and-chord-over-ligature macro.
9624 % Consume it and all of its arguments, and load them into some
9625 % registers for future processing.
9626 % (Part of the ligature might fall into this lyric text or might
9627 % not, depending on whether we decide to add hyphenation.)
9628 % Then end the lyric text here.
9629 % \begin{macrocode}
9630 \newcommand\SB@chlig[5]{%
9631 \gdef\SB@ligpre{{#3}}%
9632 \gdef\SB@ligpost{\[#2]{#4}}%
9633 \gdef\SB@ligfull{%
9634 \[\SB@noreplay{\hphantom{{\lyricfont\relax#3}}}#2]{#5}%
9635 }%
9636 \SB@chdone%
9637 }
9638 \newcommand\SB@mchlig[5]{%
9639 \SB@lyric\expandafter{\the\SB@lyric#3}%
9640 \let\SB@next\measurebar%
9641 \edef\SB@nextname{\string\measurebar}%
9642 \gdef\SB@ligpost{\measurebar\[#2]{#4}}%
9643 \gdef\SB@ligfull{\measurebar\[#2]{#4}}%
9644 \SB@chdone%
9645 }
9646 % \end{macrocode}
9647 % \eat\]
9648 % \end{macro}
9649 % \end{macro}
9650 %
9651 % \begin{macro}{\SB@chdone}
9652 % \begin{macro}{\SB@chlyrdone}
9653 % \begin{macro}{\SB@chspcdone}
9654 % The |\SB@chdone| macro is invoked when we've decided to end the lyric
9655 % text (usually because we've encountered a non-lyric token).
9656 % Normally this expands to |\SB@chlyrdone|, which adds any uncontributed
9657 % lyric material to the |\SB@lyricbox| and jumps to the main chord
9658 % formatting macro.
9659 % However, if |\MultiwordChords| is active and if the lyric ended with
9660 % a sequence of one or more space tokens, then we instead reinsert the
9661 % space tokens into the token stream without contributing them to the
9662 % |\SB@lyricbox|.
9663 % \begin{macrocode}
9664 \newcommand\SB@chlyrdone{%
9665 \setbox\SB@lyricbox\hbox{%
9666 \unhbox\SB@lyricbox%
9667 \ifnum\SB@numhyps=\@ne%
9668 \the\SB@lyricnohyp%
9669 \else%
9670 \the\SB@lyric%
9671 \fi%
9672 }%
9673 \SB@emitchord%
9674 }
9675 \newcommand\SB@chspcdone{%
9676 \let\SB@nextname\relax%
9677 \let\SB@next= \SB@chbstok%
9678 \expandafter\SB@emitchord\the\SB@lyric%
9679 }
9680 \newcommand\SB@chdone{}
9681 \let\SB@chdone\SB@chlyrdone
9682 % \end{macrocode}
9683 % \end{macro}
9684 % \end{macro}
9685 % \end{macro}
9686 %
9687 % \begin{macro}{\SB@ligpre}
9688 % \begin{macro}{\SB@ligpost}
9689 % \begin{macro}{\SB@ligfull}
9690 % The following three macros record arguments passed to a |\ch| macro that
9691 % concludes the lyric text of the |\[]|\eat\] macro currently being processed.
9692 % \begin{macrocode}
9693 \newcommand\SB@ligpre{}
9694 \newcommand\SB@ligpost{}
9695 \newcommand\SB@ligfull{}
9696 % \end{macrocode}
9697 % \end{macro}
9698 % \end{macro}
9699 % \end{macro}
9700 %
9701 % \begin{macro}{\SB@clearlig}
9702 % Clear all ligature-chord registers.
9703 % \begin{macrocode}
9704 \newcommand\SB@clearlig{%
9705 \gdef\SB@ligpre{}%
9706 \gdef\SB@ligpost{}%
9707 \gdef\SB@ligfull{}%
9708 }
9709 % \end{macrocode}
9710 % \end{macro}
9711 %
9712 % \subsection{Chords}
9713 %
9714 % \begin{macro}{\SB@emitchord}\MainImpl{[}
9715 % \changes{v1.12}{2005/05/10}{Inhibited hyphenation of trailing punctuation}
9716 % \changes{v1.13}{2005/05/12}{Added code to preserve the spacefactor}
9717 % \changes{v1.16}{2005/07/23}{Chord macros massively reorganized to take lyrics as implicit rather than explicit arguments}
9718 % The |\SB@emitchord| macro does the actual work of typesetting chord text
9719 % over lyric text, introducing appropriate hyphenation when necessary.
9720 % We begin by consulting |\SB@next|, which should have been set by the
9721 % lyric-scanning code in \S\ref{sec:lyricscan} to the token that immediately
9722 % follows the lyric under this chord, to determine whether the lyric text
9723 % ends on a word boundary.
9724 % \begin{macrocode}
9725 \newcommand\SB@emitchord{%
9726 \ifSB@inverse\else\ifSB@inchorus\else\SB@errchord\fi\fi%
9727 \SB@testfalse%
9728 \ifcat\noexpand\SB@next\@sptoken\SB@testtrue\fi%
9729 \ifcat\noexpand\SB@next.\SB@testtrue\fi%
9730 \ifx\SB@next\SB@par\SB@testtrue\fi%
9731 \ifx\SB@next\egroup\SB@testtrue\fi%
9732 \ifx\SB@next\endgroup\SB@testtrue\fi%
9733 {\csname%
9734 SB@HT@\ifx\SB@nextname\relax\meaning\SB@next\else\SB@nextname\fi%
9735 \endcsname}%
9736 \ifSB@test\SB@wordendstrue\else\SB@wordendsfalse\fi%
9737 % \end{macrocode}
9738 % Next, compare the width of the lyric to the width of the chord to
9739 % determine whether hyphenation might be necessary.
9740 % The original lyric text might have ended in a string of one or more
9741 % explicit hyphens, enumerated by |\SB@numhyps|.
9742 % If it ended in exactly one, the lyric-scanning code suppresses that hyphen
9743 % so that we can here add a new hyphen that floats out away from the word
9744 % when the chord above it is long.
9745 % If it ended in more than one (e.g., the encoding of an en- or em-dash) then
9746 % the lyric-scanner leaves it alone; we must not add any hyphenation or float
9747 % the dash away from the word.
9748 %
9749 % There is also code here to insert a penalty that discourages linebreaking
9750 % immediately before lyricless chords.
9751 % Beginning a wrapped line with a lyricless chord is undesirable because it
9752 % makes it look as though the wrapped line is extra-indented (due to the
9753 % empty lyric space below the chord).
9754 % It should therefore happen only as a last resort.
9755 % \begin{macrocode}
9756 \SB@dimen\wd\SB@chordbox%
9757 \ifvmode\leavevmode\fi%
9758 \SB@brokenwordfalse%
9759 \ifdim\wd\SB@lyricbox>\z@%
9760 \ifdim\SB@dimen>\wd\SB@lyricbox%
9761 \ifSB@wordends\else\SB@brokenwordtrue\fi%
9762 \fi%
9763 \else%
9764 \SB@skip\lastskip%
9765 \unskip\penalty200\hskip\SB@skip%
9766 \fi%
9767 \ifnum\SB@numhyps>\z@%
9768 \ifnum\SB@numhyps>\@ne%
9769 \SB@brokenwordfalse%
9770 \else%
9771 \SB@brokenwordtrue%
9772 \fi%
9773 \fi%
9774 % \end{macrocode}
9775 % If lyrics are suppressed on this line (e.g., by using |\nolyrics|), then just
9776 % typeset the chord text on the natural baseline.
9777 % \begin{macrocode}
9778 \SB@testfalse%
9779 \ifnolyrics\ifdim\wd\SB@lyricbox=\z@\SB@testtrue\fi\fi%
9780 \ifSB@test%
9781 \unhbox\SB@chordbox%
9782 \gdef\SB@temp{\expandafter\SB@clearlig\SB@ligfull}%
9783 \else%
9784 % \end{macrocode}
9785 % Otherwise, typeset the chord above the lyric on a double-height line.
9786 % \begin{macrocode}
9787 \vbox{\clineparams\relax%
9788 \ifSB@brokenword%
9789 \global\setbox\SB@lyricbox\hbox{%
9790 \unhbox\SB@lyricbox%
9791 \SB@ligpre%
9792 }%
9793 \SB@maxmin\SB@dimen<{\wd\SB@lyricbox}%
9794 \advance\[email protected]%
9795 \hbox to\SB@dimen{\unhbox\SB@chordbox\hfil}%
9796 \hbox to\SB@dimen{%
9797 \unhcopy\SB@lyricbox\hfil
9798 \ifnum\hyphenchar\font>\m@ne\char\hyphenchar\font\hfil\fi%
9799 }%
9800 \global\SB@cnt\@m%
9801 \gdef\SB@temp{\expandafter\SB@clearlig\SB@ligpost}%
9802 \else%
9803 \box\SB@chordbox%
9804 \hbox{%
9805 \unhcopy\SB@lyricbox%
9806 \global\SB@cnt\spacefactor%
9807 \hfil%
9808 }%
9809 \gdef\SB@temp{\expandafter\SB@clearlig\SB@ligfull}%
9810 \fi%
9811 }%
9812 % \end{macrocode}
9813 % If the chord is lyricless, inhibit a linebreak immediately following it.
9814 % This prevents sequences of lyricless chords (which often end lines) from
9815 % being wrapped in the middle, which looks very unsightly and makes them
9816 % difficult to read.
9817 % If the chord has a lyric but it doesn't end on a word boundary, insert
9818 % an appropriate penalty to prevent linebreaking without hyphenation.
9819 % Also preserve the spacefactor in this case, which allows \LaTeX{} to
9820 % fine-tune the spacing between consecutive characters in the word that
9821 % contains the chord.
9822 % \begin{macrocode}
9823 \ifSB@wordends%
9824 \ifdim\wd\SB@lyricbox>\z@\else\nobreak\fi%
9825 \else%
9826 \penalty%
9827 \ifnum\SB@numhyps>\z@\exhyphenpenalty%
9828 \else\ifSB@brokenword\hyphenpenalty%
9829 \else\@M\fi\fi%
9830 \spacefactor\SB@cnt%
9831 \fi%
9832 \fi%
9833 % \end{macrocode}
9834 % Finally, end the macro with some code that handles the special case that
9835 % this chord is immediately followed by a chord-over-ligature macro.
9836 % The code above sets |\SB@temp| to the portion of the ligature that should
9837 % come after this chord but before the chord that tops the ligature.
9838 % This text must be inserted here.
9839 % \begin{macrocode}
9840 \SB@temp%
9841 }
9842 % \end{macrocode}
9843 % \end{macro}
9844 %
9845 % \begin{macro}{\SB@accidental}
9846 % Typeset an accidental symbol as a superscript within a chord.
9847 % Since chord names are often in italics but math symbols like sharp and
9848 % flat are not, we need to do some kerning adjustments before and after the
9849 % accidental to position it as if it were italicized.
9850 % The pre-adjustment is just a simple italic correction using |\/|.
9851 % The post-adjustment is based on the current font's slant-per-point metric.
9852 % \begin{macrocode}
9853 \newcommand\SB@accidental[1]{{%
9854 \/%
9855 \m@th#1%
9856 \SB@dimen-\fontdimen\@ne\font%
9857 \advance\[email protected]\p@%
9858 \ifdim\SB@dimen<\z@%
9859 \kern\f@size\SB@dimen%
9860 \fi%
9861 }}
9862 % \end{macrocode}
9863 % \end{macro}
9864 %
9865 % \begin{macro}{\sharpsymbol}\MainImpl{sharpsymbol}
9866 % \begin{macro}{\flatsymbol}\MainImpl{flatsymbol}
9867 % When changing the sharp or flat symbol, change these macros rather than
9868 % changing |\shrp| or |\flt|.
9869 % This will ensure that other shortcuts like |#| and |&| will reflect your
9870 % change.
9871 % \begin{macrocode}
9872 \newcommand\sharpsymbol{\ensuremath{^\#}}
9873 \newcommand\flatsymbol{\raise.5ex\hbox{{\SB@flatsize$\flat$}}}
9874 % \end{macrocode}
9875 % \end{macro}
9876 % \end{macro}
9877 %
9878 % \begin{macro}{\shrp}\MainImpl{shrp}
9879 % \begin{macro}{\flt}\MainImpl{flt}
9880 % \changes{v2.10}{2009/08/18}{Font size made relative}
9881 % These macros typeset sharp and flat symbols.
9882 % \begin{macrocode}
9883 \newcommand\shrp{\SB@accidental\sharpsymbol}
9884 \newcommand\flt{\SB@accidental\flatsymbol}
9885 % \end{macrocode}
9886 % \end{macro}
9887 % \end{macro}
9888 %
9889 % \begin{macro}{\DeclareFlatSize}
9890 % The |\flat| math symbol is too small for properly typesetting
9891 % chord names.
9892 % (Its size was designed for staff notation not textual chord names.)
9893 % The correct size for the symbol should be approximately 30\% larger
9894 % than the current superscript size, or 90\% of the base font size $b$.
9895 % However, simply computing $0.9b$ does not work well because most fonts
9896 % do not render well in arbitrary sizes.
9897 % To solve the problem, we must therefore choose an appropriate size
9898 % individually for each possible base font size $b$.
9899 % This is the solution adopted by the rest of \LaTeX{} for such things.
9900 % For example, \LaTeX's |\DeclareMathSizes| macro defines an appropriate
9901 % superscript size for each possible base font size.
9902 % The macro below creates a similar macro that that defines an appropriate
9903 % flat-symbol size for each possible base font size.
9904 % \begin{macrocode}
9905 \newcommand\DeclareFlatSize[2]{%
9906 \expandafter\xdef\csname SB@flatsize@#1\endcsname{#2}%
9907 }
9908 \DeclareFlatSize\@vpt\@vpt
9909 \DeclareFlatSize\@vipt\@vipt
9910 \DeclareFlatSize\@viipt\@vipt
9911 \DeclareFlatSize\@viiipt\@viipt
9912 \DeclareFlatSize\@ixpt\@viiipt
9913 \DeclareFlatSize\@xpt\@ixpt
9914 \DeclareFlatSize\@xipt\@xpt
9915 \DeclareFlatSize\@xiipt\@xipt
9916 \DeclareFlatSize\@xivpt\@xiipt
9917 \DeclareFlatSize\@xviipt\@xivpt
9918 \DeclareFlatSize\@xxpt\@xviipt
9919 \DeclareFlatSize\@xxvpt\@xxpt
9920 % \end{macrocode}
9921 % \end{macro}
9922 %
9923 % \begin{macro}{\SB@flatsize}
9924 % Select the correct flat symbol size based on the current font size.
9925 % \begin{macrocode}
9926 \newcommand\SB@flatsize{%
9927 \@ifundefined{SB@flatsize@\f@size}{}{%
9928 \expandafter\fontsize%
9929 \csname SB@flatsize@\f@size\endcsname\f@baselineskip%
9930 \selectfont%
9931 }%
9932 }
9933 % \end{macrocode}
9934 % \end{macro}
9935 %
9936 % In the following code, the |\ch|, |\mch|, |\[|\eat\], and |^| macros are
9937 % each defined to be a single macro that then expands to the real definition.
9938 % This is necessary because the top-level definitions of each must stay the
9939 % same in order to allow the lyric-scanning code to uniquely identify them,
9940 % yet their internal definitions must be redefined by code that turns
9941 % chords and/or measure bars on and off.
9942 % Such code redefines |\SB@ch|, |\SB@mch|, |\SB@bracket|, and |\SB@rechord|
9943 % to effect a change of mode without touching the top-level definitions.
9944 %
9945 % \begin{macro}{\ch}\MainImpl{ch}
9946 % \begin{macro}{\SB@ch}
9947 % \begin{macro}{\SB@ch@on}
9948 % \begin{macro}{\SB@@ch}
9949 % \begin{macro}{\SB@@@ch}
9950 % \begin{macro}{\SB@ch@off}
9951 % The |\ch| macro puts a chord atop a ligature without breaking the ligature.
9952 % Normally this just means placing the chord midway over the unbroken
9953 % ligature (ignoring the third argument completely).
9954 % However, when a previous chord macro encounters it while scanning ahead in
9955 % the input stream to parse its lyric, the |\ch| macro itself is not actually
9956 % expanded at all.
9957 % Instead, the chord macro scans ahead, spots the |\ch| macro, gobbles it,
9958 % and then steals its arguments, breaking the ligature with hyphenation.
9959 % Thus, the |\ch| macro is only actually expanded when the ligature
9960 % shouldn't be broken.
9961 % \begin{macrocode}
9962 \newcommand\ch{\SB@ch}
9963 \newcommand\SB@ch{}
9964 \newcommand\SB@ch@on{\SB@begincname\SB@@ch}
9965 \newcommand*\SB@@ch[1]{\SB@endcname\SB@@@ch{#1}}
9966 \newcommand*\SB@@@ch[4]{\[\SB@noreplay{\hphantom{#2}}#1]#4}
9967 \newcommand*\SB@ch@off[4]{#4}
9968 % \end{macrocode}
9969 % \end{macro}
9970 % \end{macro}
9971 % \end{macro}
9972 % \end{macro}
9973 % \end{macro}
9974 % \end{macro}
9975 % \eat\]
9976 %
9977 % \begin{macro}{\mch}\MainImpl{mch}
9978 % \begin{macro}{\SB@mch}
9979 % \begin{macro}{\SB@mch@m}
9980 % \begin{macro}{\SB@mch@on}
9981 % \begin{macro}{\SB@@mch}
9982 % \begin{macro}{\SB@@@mch}
9983 % The |\mch| macro is like |\ch| except that it also introduces a measure
9984 % bar.
9985 % \begin{macrocode}
9986 \newcommand\mch{\SB@mch}
9987 \newcommand\SB@mch{}
9988 \newcommand*\SB@mch@m[4]{#2\measurebar#3}
9989 \newcommand\SB@mch@on{\SB@begincname\SB@@mch}
9990 \newcommand*\SB@@mch[1]{\SB@endcname\SB@@@mch{#1}}
9991 \newcommand*\SB@@@mch[4]{#2\measurebar\[#1]#3}
9992 % \end{macrocode}
9993 % \end{macro}
9994 % \end{macro}
9995 % \end{macro}
9996 % \end{macro}
9997 % \end{macro}
9998 % \end{macro}
9999 % \eat\]
10000 %
10001 % \begin{macro}{\SB@activehat}
10002 % This macro must always contain the current definition of the |^|
10003 % chord-replay active character, in order for the lyric scanner to properly
10004 % identify it and insert proper hyphenation when necessary.
10005 % \begin{macrocode}
10006 \newcommand\SB@activehat{%
10007 \ifmmode^\else\expandafter\SB@rechord\fi%
10008 }
10009 % \end{macrocode}
10010 % \end{macro}
10011 %
10012 % \begin{macro}{\SB@hat@tr}
10013 % In verses/choruses where chords are being memorized, |\SB@activehat|
10014 % gets set to this definition, which marks the current chord as immune to
10015 % memorization.
10016 % \begin{macrocode}
10017 \newcommand\SB@hat@tr{%
10018 \ifmmode^\else\global\SB@nohatfalse\fi%
10019 }
10020 % \end{macrocode}
10021 % \end{macro}
10022 %
10023 % \begin{macro}{\SB@hat@notr}
10024 % In verses/choruses where chords are being replayed, |\SB@activehat|
10025 % get set to the following, which replays the next memorized chord and
10026 % subjects it to any required transposition and/or note conversion.
10027 % \begin{macrocode}
10028 \newcommand\SB@hat@notr{%
10029 \ifmmode^\else%
10030 \SB@lop\SB@ctail\SB@toks%
10031 \expandafter\transposehere\expandafter{\the\SB@toks}%
10032 \fi%
10033 }
10034 % \end{macrocode}
10035 % \end{macro}
10036 %
10037 % \begin{macro}{\SB@loadactives}
10038 % It's cumbersome to have to type |\shrp|, |\flt|, and |\mbar| every time you
10039 % want a sharp, flat, or measure bar, so within verses and choruses we allow
10040 % the hash, ampersand, and pipe symbols to perform the those functions too.
10041 % It's also cumbersome to have to type something like |\chord{Am}{lyric}| to
10042 % produce each chord.
10043 % As an easier alternative, we here define |\[Am]|\eat\]
10044 % to typeset chords.
10045 % \begin{macrocode}
10046 \newcommand\SB@loadactives{}
10047 {
10048 \catcode`&\active
10049 \catcode`#\active
10050 \catcode`|\active
10051 \catcode`^\active
10052 \global\let&\flt
10053 \global\let#\shrp
10054 \global\let|\measurebar
10055 \global\let^\SB@activehat
10056 \gdef\SB@loadactives{%
10057 \catcode`^\ifchorded\active\else9 \fi%
10058 \catcode`|\ifmeasures\active\else9 \fi%
10059 \def\[{\SB@bracket}%
10060 }
10061 }
10062 % \end{macrocode}
10063 % \end{macro}
10064 %
10065 % \subsection{Chord Replaying}
10066 %
10067 % \begin{macro}{\SB@trackch}
10068 % While inside a verse where the chord history is being remembered for future
10069 % verses, |\SB@trackch| is true.
10070 % \begin{macrocode}
10071 \newif\ifSB@trackch
10072 % \end{macrocode}
10073 % \end{macro}
10074 %
10075 % \begin{macro}{\SB@cr@}
10076 % Reserve token registers to record a history of the chords seen in a verse.
10077 % \begin{macrocode}
10078 \SB@newtoks\SB@cr@
10079 \SB@newtoks\SB@ctail
10080 % \end{macrocode}
10081 % \end{macro}
10082 %
10083 % \begin{macro}{\SB@creg}
10084 % The following control sequence equals the token register being memorized
10085 % into or replayed from.
10086 % \begin{macrocode}
10087 \newcommand\SB@creg{}
10088 % \end{macrocode}
10089 % \end{macro}
10090 %
10091 % \begin{macro}{\newchords}\MainImpl{newchords}
10092 % \changes{v2.6}{2008/02/23}{Added}
10093 % Allocate a new chord-replay register to hold memorized chords.
10094 % \begin{macrocode}
10095 \newcommand\newchords[1]{%
10096 \@ifundefined{SB@cr@#1}{%
10097 \expandafter\SB@newtoks\csname SB@cr@#1\endcsname%
10098 \global\csname SB@cr@#1\endcsname{\\}%
10099 }{\SB@errdup{#1}}%
10100 }
10101 % \end{macrocode}
10102 % \end{macro}
10103 %
10104 % \begin{macro}{\memorize}\MainImpl{memorize}
10105 % \begin{macro}{\SB@memorize}
10106 % \changes{v2.6}{2008/02/23}{Optional argument added}
10107 % Saying |\memorize| throws out any previously memorized list of chords and
10108 % starts memorizing chords until the end of the current verse or chorus.
10109 % \begin{macrocode}
10110 \newcommand\memorize{%
10111 \@ifnextchar[\SB@memorize{\SB@memorize[]}%
10112 }
10113 \newcommand\SB@memorize{}
10114 \def\SB@memorize[#1]{%
10115 \@ifundefined{SB@cr@#1}{\SB@errreg{#1}}{%
10116 \SB@trackchtrue%
10117 \global\expandafter\let\expandafter\SB@creg%
10118 \csname SB@cr@#1\endcsname%
10119 \global\SB@creg{\\}%
10120 }%
10121 }
10122 % \end{macrocode}
10123 % \end{macro}
10124 % \end{macro}
10125 %
10126 % \begin{macro}{\replay}\MainImpl{replay}
10127 % \begin{macro}{\SB@replay}
10128 % \begin{macro}{\SB@@replay}
10129 % \changes{v2.6}{2008/02/23}{Added}
10130 % Saying |\replay| stops any memorization and begins replaying memorized
10131 % chords.
10132 % \begin{macrocode}
10133 \newcommand\replay{\@ifnextchar[\SB@replay\SB@@replay}
10134 \newcommand\SB@replay{}
10135 \def\SB@replay[#1]{%
10136 \@ifundefined{SB@cr@#1}{\SB@errreg{#1}}{%
10137 \SB@trackchfalse%
10138 \global\expandafter\let\expandafter\SB@creg%
10139 \csname SB@cr@#1\endcsname%
10140 \global\SB@ctail\SB@creg%
10141 }%
10142 }
10143 \newcommand\SB@@replay{%
10144 \SB@trackchfalse%
10145 \global\SB@ctail\SB@creg%
10146 }
10147 % \end{macrocode}
10148 % \end{macro}
10149 % \end{macro}
10150 % \end{macro}
10151 %
10152 % \begin{macro}{\SB@rechord}
10153 % \begin{macro}{\SB@@rechord}
10154 % Replay the same chord that was in a previous verse.
10155 % \begin{macrocode}
10156 \newcommand\SB@rechord{}
10157 \newcommand\SB@@rechord{%
10158 \SB@ifempty\SB@ctail{%
10159 \SB@errreplay%
10160 \SB@toks{}%
10161 \let\SB@donext\@gobble%
10162 }{%
10163 \SB@lop\SB@ctail\SB@toks%
10164 \let\SB@donext\SB@chord%
10165 \let\SB@noreplay\@gobble%
10166 }%
10167 \expandafter\SB@donext\the\SB@toks]%
10168 }
10169 % \end{macrocode}
10170 % \end{macro}
10171 % \end{macro}
10172 %
10173 % \begin{macro}{\ifSB@nohat}
10174 % The |\ifSB@nohat| conditional is set to false when a chord macro contains
10175 % a |^| in its argument.
10176 % This suppresses the recording mechanism momentarily so that replays will
10177 % skip this chord.
10178 % \begin{macrocode}
10179 \newif\ifSB@nohat
10180 % \end{macrocode}
10181 % \end{macro}
10182 %
10183 % \begin{macro}{\SB@noreplay}
10184 % Sometimes material must be added to a chord but omitted when the chord is
10185 % replayed.
10186 % We accomplish this by enclosing such material in |\SB@noreplay| macros,
10187 % which are set to |\@gobble| just before a replay and reset to
10188 % |\@firstofone| at other times.
10189 % \begin{macrocode}
10190 \newcommand\SB@noreplay{}
10191 \let\SB@noreplay\@firstofone
10192 % \end{macrocode}
10193 % \end{macro}
10194 %
10195 % \subsection{Guitar Tablatures}
10196 %
10197 % The song book software not only supports chord names alone, but can also
10198 % typeset guitar tablature diagrams. The macros for producing these diagrams
10199 % are found here.
10200 %
10201 % \begin{macro}{\SB@fretwidth}
10202 % Set the width of each vertical string in the tablature diagram.
10203 % \begin{macrocode}
10204 \newlength\SB@fretwidth
10205 \setlength\SB@fretwidth{6\p@}
10206 % \end{macrocode}
10207 % \end{macro}
10208 %
10209 % \begin{macro}{\SB@fretnum}
10210 % Typeset a fret number to appear to the left of the diagram.
10211 % \begin{macrocode}
10212 \newcommand\SB@fretnum[1]{{%
10213 \sffamily\fontsize\@xpt\@xpt\selectfont#1%
10214 }}
10215 % \end{macrocode}
10216 % \end{macro}
10217 %
10218 % \begin{macro}{\SB@onfret}
10219 % Typeset one string of one fret with \argp{1} typeset overtop of it (usually
10220 % a dot or nothing at all).
10221 % \begin{macrocode}
10222 \newcommand\SB@onfret[1]{%
10223 \kern.5\SB@fretwidth\kern-.2\p@%
10224 \vrule\@height6\p@%
10225 \kern-.2\p@\kern-.5\SB@fretwidth%
10226 \hbox to\SB@fretwidth{\hfil#1\hfil}%
10227 }
10228 % \end{macrocode}
10229 % \end{macro}
10230 %
10231 % \begin{macro}{\SB@atopfret}
10232 % Typeset material (given by \argp{1}) to be placed above a string in the
10233 % tablature diagram.
10234 % \begin{macrocode}
10235 \newcommand\SB@atopfret[1]{%
10236 \hbox to\SB@fretwidth{\hfil#1\hfil}%
10237 }
10238 % \end{macrocode}
10239 % \end{macro}
10240 %
10241 % \begin{macro}{\SB@fretbar}
10242 % Typeset a horizontal fret bar of width |\SB@dimen|.
10243 % \begin{macrocode}
10244 \newcommand\SB@fretbar{%
10245 \nointerlineskip%
10246 \hbox to\SB@dimen{%
10247 \advance\SB@dimen-\SB@fretwidth%
10248 \advance\[email protected]\p@%
10249 \hfil%
10250 \vrule\@width\SB@dimen\@height.4\p@\@depth\z@%
10251 \hfil%
10252 }%
10253 \nointerlineskip%
10254 }
10255 % \end{macrocode}
10256 % \end{macro}
10257 %
10258 % \begin{macro}{\SB@topempty}
10259 % \begin{macro}{\SB@topX}
10260 % \begin{macro}{\SB@topO}
10261 % Above a string in a tablature diagram there can be nothing,
10262 % an $\times$, or an $\circ$.
10263 % \begin{macrocode}
10264 \newcommand\SB@topempty{\SB@atopfret\relax}
10265 \newcommand\SB@topX{\SB@atopfret{%
10266 \hbox{%
10267 \kern-.2\p@%
10268 \fontencoding{OMS}\fontfamily{cmsy}%
10269 \fontseries{m}\fontshape{n}%
10270 \fontsize\@viipt\@viipt\selectfont\char\tw@%
10271 \kern-.2\p@%
10272 }%
10273 }}
10274 \newcommand\SB@topO{\SB@atopfret{%
10275 \vrule\@width\z@\@height4.3333\p@\@depth.8333\p@%
10276 \lower.74\p@\hbox{%
10277 \fontencoding{OMS}\fontfamily{cmsy}%
10278 \fontseries{m}\fontshape{n}%
10279 \fontsize\@xpt\@xpt\selectfont\char14%
10280 }%
10281 }}
10282 % \end{macrocode}
10283 % \end{macro}
10284 % \end{macro}
10285 % \end{macro}
10286 %
10287 % \begin{macro}{\SB@doify}
10288 % \begin{macro}{\SB@@doify}
10289 % \begin{macro}{\SB@do}
10290 % Define the macro given in the first argument to equal the fully expanded
10291 % content of the second argument, but with |\SB@do| inserted before each token
10292 % or group.
10293 % \begin{macrocode}
10294 \newcommand\SB@do[1]{}
10295 \newcommand\SB@doify[2]{%
10296 \SB@toks{}%
10297 \edef#1{#2}%
10298 \expandafter\SB@@doify#1\SB@@doify%
10299 \edef#1{\the\SB@toks}%
10300 }
10301 \newcommand\SB@@doify[1]{%
10302 \ifx#1\SB@@doify\else%
10303 \SB@toks\expandafter{\the\SB@toks\SB@do{#1}}%
10304 \expandafter\SB@@doify%
10305 \fi%
10306 }
10307 % \end{macrocode}
10308 % \end{macro}
10309 % \end{macro}
10310 % \end{macro}
10311 %
10312 % \begin{macro}{\SB@allbarres}
10313 % \begin{macro}{\SB@dobarre}
10314 % Reserve a control sequence to remember all the stacks, start control
10315 % sequences, and end control sequences associated with barre delimiter pairs;
10316 % and a control sequence to perform an arbitrary action on them.
10317 % \begin{macrocode}
10318 \newcommand\SB@allbarres{}
10319 \newcommand\SB@dobarre{}
10320 % \end{macrocode}
10321 % \end{macro}
10322 % \end{macro}
10323 %
10324 % \begin{macro}{\SB@barreI}
10325 % \begin{macro}{\SB@barreN}
10326 % \begin{macro}{\SB@barreY}
10327 % As we process strings in order, barres in progress can be in one of three
10328 % states: initial (|\SB@barreI|), deactivated (|\SB@barreN|), or
10329 % tentatively activated (|\SB@barreY|).
10330 % \begin{macrocode}
10331 \newcommand\SB@barreI{\noexpand\SB@barreI}
10332 \newcommand\SB@barreN{\noexpand\SB@barreN}
10333 \newcommand\SB@barreY{\noexpand\SB@barreY}
10334 % \end{macrocode}
10335 % \end{macro}
10336 % \end{macro}
10337 % \end{macro}
10338 %
10339 % \begin{macro}{\SB@lowfret}
10340 % \begin{macro}{\SB@@lowfret}
10341 % If we see a lower numbered fret than the current fret within a barre,
10342 % deactivate the barre.
10343 % (It has already been shown on an earlier fret.)
10344 % \begin{macrocode}
10345 \newcommand\SB@lowfret{%
10346 \let\SB@dobarre\SB@@lowfret\SB@allbarres%
10347 \SB@fretempty%
10348 }
10349 \newcommand\SB@@lowfret[3]{{%
10350 \let\SB@barreI\SB@barreN%
10351 \let\SB@barreY\SB@barreN%
10352 \xdef#1{#1}%
10353 }}
10354 % \end{macrocode}
10355 % \end{macro}
10356 % \end{macro}
10357 %
10358 % \begin{macro}{\SB@bactivate}
10359 % If we see the current fret within a barre, tentatively activate the barre
10360 % (unless it is already deactivated).
10361 % \begin{macrocode}
10362 \newcommand\SB@bactivate[3]{{%
10363 \let\SB@barreI\SB@barreY%
10364 \xdef#1{#1}%
10365 }}
10366 % \end{macrocode}
10367 % \end{macro}
10368 %
10369 % \begin{macro}{\SB@bbarre}
10370 % Starting a barre group pushes it onto its stack in the initial state.
10371 % \begin{macrocode}
10372 \newcommand\SB@bbarre[1]{%
10373 \xdef#1{\SB@barreI{\the\SB@cntii}#1}%
10374 }
10375 % \end{macrocode}
10376 % \end{macro}
10377 %
10378 % \begin{macro}{\SB@ebarre}
10379 % \begin{macro}{\SB@@ebarre}
10380 % \begin{macro}{\SB@@@ebarre}
10381 % Ending a barre group pops it and draws it if it's active.
10382 % \begin{macrocode}
10383 \newcommand\SB@ebarre[3]{%
10384 \ifx#1\@empty%
10385 \ifnum\SB@cnt=\@ne\SB@errebar#2#3\fi%
10386 \else%
10387 \expandafter\SB@@ebarre#1\SB@@ebarre#1%
10388 \fi%
10389 }
10390 \newcommand\SB@@ebarre{}
10391 \def\SB@@ebarre#1#2#3\SB@@ebarre#4{{%
10392 \gdef#4{#3}%
10393 \let\SB@barreI\@gobble%
10394 \let\SB@barreN\@gobble%
10395 \let\SB@barreY\SB@barre%
10396 #1{#2}%
10397 }}
10398 % \end{macrocode}
10399 % \end{macro}
10400 % \end{macro}
10401 % \end{macro}
10402 %
10403 % \begin{macro}{\SB@barreson}
10404 % \begin{macro}{\SB@barresoff}
10405 % Turn barre delimiters on or off, depending on whether we're typesetting
10406 % the interior or upper part of the tablature diagram.
10407 % \begin{macrocode}
10408 \newcommand\SB@barreson[3]{%
10409 \def#2{\SB@bbarre#1}%
10410 \def#3{\SB@ebarre#1#2#3}%
10411 }
10412 \newcommand\SB@barresoff[3]{\let#2\relax\let#3\relax}
10413 % \end{macrocode}
10414 % \end{macro}
10415 % \end{macro}
10416 %
10417 % \begin{macro}{\SB@fretempty}
10418 % \begin{macro}{\SB@fretdot}
10419 % \begin{macro}{\SB@@fretdot}
10420 % On a string in a fret diagram there can be nothing or a filled circle.
10421 % \begin{macrocode}
10422 \newcommand\SB@fretempty{%
10423 \advance\SB@cntii\@ne%
10424 \SB@onfret\relax%
10425 }
10426 \newcommand\SB@fretdot{%
10427 \advance\SB@cntii\@ne%
10428 \let\SB@dobarre\SB@bactivate\SB@allbarres%
10429 \SB@@fretdot%
10430 }
10431 \newcommand\SB@@fretdot{%
10432 \SB@onfret{%
10433 \fontencoding{OMS}\fontfamily{cmsy}%
10434 \fontseries{m}\fontshape{n}%
10435 \fontsize\@xiipt\@xiipt\selectfont\char15%
10436 }%
10437 }
10438 % \end{macrocode}
10439 % \end{macro}
10440 % \end{macro}
10441 % \end{macro}
10442 %
10443 % \begin{macro}{\SB@barre}
10444 % Draw a barre.
10445 % \begin{macrocode}
10446 \newcommand\SB@barre[1]{{%
10447 \SB@dimen\SB@fretwidth%
10448 \multiply\SB@dimen\SB@cntii%
10449 \advance\SB@dimen-#1\SB@fretwidth%
10450 \kern-\SB@dimen%
10451 \SB@@fretdot%
10452 \kern-.5\SB@fretwidth%
10453 \advance\SB@dimen-\SB@fretwidth%
10454 \raise.7pt\hbox{\vrule\@height4.6\p@\@width\SB@dimen}%
10455 \kern-.5\SB@fretwidth%
10456 \SB@@fretdot%
10457 }}
10458 % \end{macrocode}
10459 % \end{macro}
10460 %
10461 % \begin{macro}{\SB@fretend}
10462 % At the end of a barred row in a tablature diagram, we auto-finish any
10463 % activated barres that weren't explicitly closed by the user.
10464 % \begin{macrocode}
10465 \newcommand\SB@fretend{{%
10466 \let\SB@barreI\@gobble%
10467 \let\SB@barreN\@gobble%
10468 \let\SB@barreY\SB@barre%
10469 \def\SB@dobarre##1##2##3{##1\gdef##1{}}\SB@allbarres%
10470 }}
10471 % \end{macrocode}
10472 % \end{macro}
10473 %
10474 % \begin{macro}{\SB@finger}
10475 % \begin{macro}{\SB@X}
10476 % \begin{macro}{\SB@Z}
10477 % \begin{macro}{\SB@O}
10478 % If we're including fingering info in the tablature diagram, then below
10479 % each string there might be a number.
10480 % \begin{macrocode}
10481 \newcommand*\SB@X{X}
10482 \newcommand*\SB@Z{0}
10483 \newcommand*\SB@O{O}
10484 \newcommand\SB@finger[1]{%
10485 \def\SB@temp{#1}%
10486 \ifx\SB@temp\SB@X\SB@topempty\else%
10487 \ifx\SB@temp\SB@Z\SB@topempty\else%
10488 \ifx\SB@temp\SB@O\SB@topempty\else%
10489 \SB@atopfret{\sffamily\fontsize\@vipt\@vipt\selectfont#1}%
10490 \fi\fi\fi%
10491 }
10492 % \end{macrocode}
10493 % \end{macro}
10494 % \end{macro}
10495 % \end{macro}
10496 % \end{macro}
10497 %
10498 % \begin{macro}{\ifSB@gettabind}
10499 % \begin{macro}{\SB@tabindent}
10500 % Lyrics under tablature diagrams look odd if they aren't aligned with the
10501 % leftmost string of the diagram.
10502 % To accomplish this, the following two macros record the amount by which
10503 % a lyric under this tablature diagram must be indented to position it
10504 % properly.
10505 % \begin{macrocode}
10506 \newif\ifSB@gettabind\SB@gettabindfalse
10507 \SB@newdimen\SB@tabindent
10508 % \end{macrocode}
10509 % \end{macro}
10510 % \end{macro}
10511 %
10512 % \begin{macro}{\SB@targfret}
10513 % \begin{macro}{\SB@targstr}
10514 % \begin{macro}{\SB@targfing}
10515 % Reserve some macro names in which to store the three pieces of the
10516 % second argument to the |\gtab| macro.
10517 % The first is for the fret number, the second is for the \Meta{strings}
10518 % info, and the last is for the \Meta{fingering} info.
10519 % \begin{macrocode}
10520 \newcommand\SB@targfret{}
10521 \newcommand\SB@targstr{}
10522 \newcommand\SB@targfing{}
10523 % \end{macrocode}
10524 % \end{macro}
10525 % \end{macro}
10526 % \end{macro}
10527 %
10528 % In general |\gtab| macros often appear inside chord macros, which means
10529 % that their arguments have already been scanned by the time the
10530 % |\gtab| macro itself is expanded.
10531 % This means that catcodes cannot be reassigned (without resorting to
10532 % $\varepsilon$-\TeX).
10533 %
10534 % We therefore adopt the alternative strategy of converting each token
10535 % in the \Meta{strings} and \Meta{fingering} arguments of a |\gtab| macro
10536 % into a control sequence (using |\csname|).
10537 % We can then temporarily assign meanings to those control sequences and
10538 % replay the arguments to achieve various effects.
10539 %
10540 % \begin{macro}{\SB@gtinit}
10541 % \begin{macro}{\SB@gtinc}
10542 % Different meanings are assigned to digits, |X|'s, and |O|'s
10543 % as we typeset each row of the interior of the diagram.
10544 % These meanings are set by |\SB@gtinit| and |\SB@gtinc|.
10545 % \begin{macrocode}
10546 \newcommand\SB@gtinit{%
10547 \def\SB@do##1{\csname##1\endcsname}%
10548 \let\O\0%
10549 \let\3\2\let\4\2\let\5\2\let\6\2%
10550 \let\7\2\let\8\2\let\9\2%
10551 }
10552 \newcommand\SB@gtinc{%
10553 \advance\SB@cnt\@ne%
10554 \let\9\8\let\8\7\let\7\6\let\6\5\let\5\4%
10555 \let\4\3\let\3\2\let\2\1\let\1\SB@lowfret%
10556 }
10557 % \end{macrocode}
10558 % \end{macro}
10559 % \end{macro}
10560 %
10561 % \begin{macro}{\BarreDelims}
10562 % \begin{macro}{\SB@bdelims}
10563 % Each pair of barre delimiters reserves a stack and augments the
10564 % initialization state to recognize those delimiters.
10565 % \begin{macrocode}
10566 \newcommand\BarreDelims[2]{%
10567 \expandafter\SB@bdelims\csname SB@bs@#1#2\expandafter\endcsname%
10568 \csname#1\expandafter\endcsname\csname#2\endcsname%
10569 }
10570 \newcommand\SB@bdelims[3]{%
10571 \newcommand*#1{}%
10572 \SB@app\def\SB@allbarres{\SB@dobarre#1#2#3}%
10573 }
10574 \BarreDelims()
10575 \BarreDelims[]
10576 % \end{macrocode}
10577 % \end{macro}
10578 % \end{macro}
10579 %
10580 % \begin{macro}{\gtab}
10581 % \begin{macro}{\SB@gtab}
10582 % \changes{v2.9}{2009/03/27}{Fixed compatibility issue with Babel French}
10583 % A |\gtab| macro begins by setting catcodes suitable for parsing a chord
10584 % name as its first argument.
10585 % This allows tokens like |#| and |&| to be used for sharp and flat even
10586 % when |\gtab| is used outside a chord macro.
10587 % Colon is reset to a non-active character while processing the second
10588 % argument to avoid a potential conflict with \textsf{Babel} French.
10589 % \begin{macrocode}
10590 \newcommand\gtab{\SB@begincname\SB@gtab}
10591 \newcommand*\SB@gtab[1]{%
10592 \SB@endcname%
10593 \begingroup%
10594 \catcode`:12\relax%
10595 \SB@@gtab{#1}%
10596 }
10597 % \end{macrocode}
10598 % \end{macro}
10599 % \end{macro}
10600 %
10601 % \begin{macro}{\SB@@gtab}
10602 % If transposition is currently taking place, allow the user to customize
10603 % the behavior by redefining |\gtabtrans|.
10604 % Using |\gtab| within |\gtabtrans| should go directly to |\SB@@@gtab|
10605 % (otherwise an infinite loop would result!).
10606 % \begin{macrocode}
10607 \newcommand*\SB@@gtab[2]{%
10608 \endgroup%
10609 \ifnum\SB@transposefactor=\z@%
10610 \SB@@@gtab{#1}{#2}%
10611 \else%
10612 \begingroup%
10613 \let\gtab\SB@@@gtab%
10614 \gtabtrans{#1}{#2}%
10615 \endgroup%
10616 \fi%
10617 }
10618 % \end{macrocode}
10619 % \end{macro}
10620 %
10621 % \begin{macro}{\gtabtrans}\MainImpl{gtabtrans}
10622 % By default, transposed guitar tablatures just display the transposed
10623 % chord name and omit the diagram.
10624 % Transposing a tablature diagram requires manual judgment calls for most
10625 % stringed instruments, so we can't do it automatically.
10626 % \begin{macrocode}
10627 \newcommand\gtabtrans[2]{\transposehere{#1}}
10628 % \end{macrocode}
10629 % \end{macro}
10630 %
10631 % \begin{macro}{\SB@@@gtab}\MainImpl{gtab}
10632 % \changes{v2.13}{2011/04/16}{Added transposition for chord names}
10633 % Typeset a full tablature diagram.
10634 % Text \argp{1} is a chord name placed above the diagram.
10635 % Text \argp{2} consists of a colon-separated list of:
10636 % (1) an optional fret number placed to the left of the diagram;
10637 % (2) a sequence of tokens, each of which can be
10638 % |X| (to place an $\times$ above the string),
10639 % |0| or |O| (to place an $\circ$ above the string), or
10640 % one of |1| through |9| (to place a filled circle on that string at the
10641 % fret of the given number); and
10642 % (3) an optional sequence of tokens, each of which is either |0|
10643 % (no fingering information for that string),
10644 % or one of |1| through |4| (to place the given number under that string).
10645 % \begin{macrocode}
10646 \newcommand\SB@@@gtab[2]{%
10647 \let\SB@targfret\@empty%
10648 \let\SB@targstr\@empty%
10649 \let\SB@targfing\@empty%
10650 \SB@tabargs#2:::\SB@tabargs%
10651 \ifx\SB@targstr\@empty%
10652 \def\SB@targstr{\0\0\0\0\0\0}%
10653 \fi%
10654 \ifvmode\leavevmode\fi%
10655 \vbox{%
10656 \normalfont\normalsize%
10657 \setbox\SB@box\hbox{%
10658 \thinspace{\printchord{\transposehere{#1}\strut}}\thinspace%
10659 }%
10660 \setbox\SB@boxii\hbox{\SB@fretnum{\SB@targfret}}%
10661 \setbox\SB@boxiii\hbox{{%
10662 \let\X\SB@topX\let\0\SB@topO%
10663 \let\1\SB@topempty\let\2\1%
10664 \SB@gtinit%
10665 \let\SB@dobarre\SB@barresoff\SB@allbarres%
10666 \SB@targstr%
10667 }}%
10668 \hsize\wd\SB@box%
10669 \ifSB@gettabind%
10670 \global\SB@tabindent\wd\SB@boxii%
10671 \global\advance\[email protected]\SB@fretwidth%
10672 \global\advance\[email protected]\p@%
10673 \fi%
10674 \SB@dimen\wd\SB@boxii%
10675 \advance\SB@dimen\wd\SB@boxiii%
10676 \ifdim\hsize<\SB@dimen%
10677 \hsize\SB@dimen%
10678 \else\ifSB@gettabind%
10679 \SB@dimenii\hsize%
10680 \advance\SB@dimenii-\SB@dimen%
10681 \divide\SB@dimenii\tw@%
10682 \global\advance\SB@tabindent\SB@dimenii%
10683 \fi\fi%
10684 \hbox to\hsize{\hfil\unhbox\SB@box\hfil}%
10685 \kern-\p@\nointerlineskip%
10686 \hbox to\hsize{%
10687 \hfil%
10688 \vtop{\kern\p@\kern2\p@\box\SB@boxii}%
10689 \vtop{%
10690 \SB@dimen\wd\SB@boxiii%
10691 \box\SB@boxiii%
10692 \let\X\SB@fretempty\let\0\X%
10693 \let\1\SB@fretdot\def\2{\SB@fretempty\global\SB@testtrue}%
10694 \SB@gtinit%
10695 \let\SB@dobarre\SB@barreson\SB@allbarres%
10696 \SB@cnt\@ne%
10697 \loop%
10698 \SB@testfalse%
10699 \SB@fretbar\hbox{\SB@cntii\z@\SB@targstr\SB@fretend}%
10700 \ifnum\SB@cnt<\minfrets\SB@testtrue\fi%
10701 \ifSB@test\SB@gtinc\repeat%
10702 \SB@fretbar%
10703 \ifx\SB@targsfing\@empty\else%
10704 \kern1.5\p@%
10705 \hbox{\let\SB@do\SB@finger\SB@targfing}%
10706 \fi%
10707 }%
10708 \hfil%
10709 }%
10710 \kern3\p@%
10711 }%
10712 \SB@gettabindfalse%
10713 }
10714 % \end{macrocode}
10715 % \end{macro}
10716 %
10717 % \begin{macro}{\SB@tabargs}
10718 % \begin{macro}{\SB@@tabargs}
10719 % \begin{macro}{\SB@ctoken}
10720 % \changes{v3.1}{2017/06/23}{Allow macros within 2nd gtab arg}
10721 % Break the second argument to a |\gtab| macro into three sub-arguments.
10722 % The possible forms are:
10723 % (a) \Meta{strings},
10724 % (b) \Meta{fret}|:|\Meta{strings},
10725 % (c) \Meta{strings}|:|\Meta{fingering}, or
10726 % (d) \Meta{fret}|:|\Meta{strings}|:|\Meta{fingering}.
10727 % To distinguish forms (b) and (c), we count the number of tokens before
10728 % the first colon.
10729 % If there is only one token or group, we assume it must be form (b),
10730 % since frets larger than 9 and 1-stringed instruments are both rare.
10731 % Otherwise we assume form (c).
10732 % \begin{macrocode}
10733 \newcommand\SB@ctoken{} \def\SB@ctoken{:}
10734 \newcommand\SB@tabargs{}
10735 \def\SB@tabargs#1:#2:#3:#4\SB@tabargs{%
10736 \def\SB@temp{#4}%
10737 \ifx\SB@temp\@empty%
10738 \SB@doify\SB@targstr{#1}%
10739 \else\ifx\SB@temp\SB@ctoken%
10740 \SB@@tabargs#1\SB@@tabargs%
10741 \ifx\SB@temp\@empty%
10742 \def\SB@targfret{#1}%
10743 \SB@doify\SB@targstr{#2}%
10744 \else%
10745 \SB@doify\SB@targfing{#2}%
10746 \SB@doify\SB@targstr{#1}%
10747 \fi%
10748 \else%
10749 \def\SB@targfret{#1}%
10750 \SB@doify\SB@targfing{#3}%
10751 \SB@doify\SB@targstr{#2}%
10752 \fi\fi%
10753 }
10754 \newcommand\SB@@tabargs{}
10755 \def\SB@@tabargs#1#2\SB@@tabargs{\def\SB@temp{#2}}
10756 % \end{macrocode}
10757 % \end{macro}
10758 % \end{macro}
10759 % \end{macro}
10760 %
10761 % \subsection{Book Sectioning}
10762 %
10763 % The following macros divide the song book into distinct sections, each with
10764 % different headers, different song numbering styles, different indexes, etc.
10765 %
10766 % \begin{macro}{\songchapter}\MainImpl{songchapter}
10767 % \changes{v1.19}{2005/10/24}{Added}
10768 % Format the chapter header for a chapter in a song book.
10769 % By default, chapter headers on a song book omit the chapter number, but do
10770 % include an entry in the pdf index or table of contents.
10771 % Thus, the chapter has a number; it's just not displayed at the start of
10772 % the chapter.
10773 % \begin{macrocode}
10774 \newcommand\songchapter{%
10775 \let\SB@temp\@seccntformat%
10776 \def\@seccntformat##1{}%
10777 \@startsection{chapter}{0}{\z@}%
10778 {3.5ex\@plus1ex\@minus.2ex}%
10779 {.4ex\let\@seccntformat\SB@temp}%
10780 {\sffamily\bfseries\LARGE\centering}%
10781 }
10782 % \end{macrocode}
10783 % \end{macro}
10784 %
10785 % \begin{macro}{\songsection}\MainImpl{songsection}
10786 % \changes{v1.19}{2005/10/24}{Section headers changed to omit numbers}
10787 % Format the section header for a section in a song book.
10788 % This is the same as for chapter headers except at the section level.
10789 % \begin{macrocode}
10790 \newcommand\songsection{%
10791 \let\SB@temp\@seccntformat%
10792 \def\@seccntformat##1{}%
10793 \@startsection{section}{1}{\z@}%
10794 {3.5ex\@plus1ex\@minus.2ex}%
10795 {.4ex\let\@seccntformat\SB@temp}%
10796 {\sffamily\bfseries\LARGE\centering}%
10797 }
10798 % \end{macrocode}
10799 % \end{macro}
10800 %
10801 % \begin{environment}{songs}\MainEnvImpl{songs}
10802 % \changes{v1.19}{2005/10/24}{Song numbers now starts at one instead of zero}
10803 % Begin and end a book section.
10804 % The argument is a list of indexes with which to associate songs in this
10805 % section.
10806 % \begin{macrocode}
10807 \newenvironment{songs}[1]{%
10808 \ifSB@songsenv\SB@errnse\fi%
10809 \gdef\SB@indexlist{#1}%
10810 \SB@chkidxlst%
10811 \stepcounter{SB@songsnum}%
10812 \setcounter{songnum}{1}%
10813 \let\SB@sgroup\@empty%
10814 \ifinner\else\ifdim\pagetotal>\z@%
10815 \null\nointerlineskip%
10816 \fi\fi%
10817 \songcolumns\SB@numcols%
10818 \SB@songsenvtrue%
10819 }{%
10820 \commitsongs%
10821 \global\let\SB@indexlist\@empty%
10822 \ifinner\else\clearpage\fi%
10823 \SB@songsenvfalse%
10824 }
10825 % \end{macrocode}
10826 % \end{environment}
10827 %
10828 % Each |songs| section needs a unique number to aid in hyperlinking.
10829 % \begin{macrocode}
10830 \newcounter{SB@songsnum}
10831 % \end{macrocode}
10832 %
10833 % \subsection{Index Generation}
10834 % \label{sec:indexgen}
10835 %
10836 % The following macros generate the various types of indexes. At present there
10837 % are four types:
10838 % \begin{enumerate}
10839 % \item A ``large'' index has a separate section for each capital letter and
10840 % is printed in two columns.
10841 % \item A ``small'' index has only a single column, centered, and has no
10842 % sections.
10843 % \item A ``scripture'' index has three columns and each entry has a
10844 % comma-separated list of references.
10845 % \item An ``author'' index is like a large index except in bold and without
10846 % the sectioning.
10847 % \end{enumerate}
10848 % ``Large'' and ``small'' indexes will be chosen automatically based on the
10849 % number of index entries when building a song index. The other two types are
10850 % designated by the user.
10851 %
10852 % As is typical of \LaTeX{} indexes, generation of song book indexes requires
10853 % two passes of document compilation. During the first pass, data files are
10854 % generated with song titles, authors, and scripture references. An external
10855 % program is then used to produce \LaTeX{} source files from those data files.
10856 % During the second pass of document compilation, those source files are
10857 % imported to typeset all the indexes and display them in the document.
10858 %
10859 % Internally, this package code uses a \emph{four} step process to move
10860 % the index data from the source |.tex| file to the |.sxd| data files.
10861 % \begin{enumerate}
10862 % \item While the current song box is in the midst of construction,
10863 % the data is stored in a box of non-immediate write whatsit nodes.
10864 % \item The whatsits are migrated out to the top of the song box when
10865 % it is finalized at |\endsong|.
10866 % \item When the song box is shipped out to the output file, \TeX{} expands
10867 % the whatsits, causing the data to be written to the |.sxc| auxiliary file.
10868 % \item At the |\end{document}| line, the |.sxc| is processed multiple
10869 % times---once for each index---to split the data into the respective
10870 % |.sxd| files.
10871 % \end{enumerate}
10872 % The first and second steps allow index references to point to the
10873 % beginning of the song no matter where the indexing commands appear
10874 % within the song.
10875 % The third step allows \TeX{} to drop index entries that refer to
10876 % songs that do not actually appear in the output (e.g., because of
10877 % |\includeonlysongs|).
10878 % It also allows index entries to refer to information that is only decided
10879 % at shipout time, such as page numbers.
10880 % The fourth step allows all indexing to be accomplished with at most one
10881 % write register.
10882 % \LaTeX{} provides extremely few write registers, so using as
10883 % few as possible is essential for supporting books with many indexes.
10884 %
10885 % \begin{macro}{\songtarget}\MainImpl{songtarget}
10886 % This macro is invoked by each \mac{beginsong} environment with two arguments:
10887 % (1) a suggested pdf bookmark index level, and
10888 % (2) a target name to which hyperlinks for this song in the index will refer.
10889 % The macro is expected to produce a suitable pdf bookmark entry and/or
10890 % link target.
10891 % The default definition tries to use |\pdfbookmark| if generating a PDF,
10892 % and resorts to |\hypertarget| (if it exists) otherwise.
10893 % The user can redefine the macro to customize how and whether bookmarks
10894 % and/or links are created.
10895 % \begin{macrocode}
10896 \newcommand\songtarget[2]{%
10897 \ifnum\@ne=0\ifSB@pdf\ifx\pdfbookmark\undefined\else%
10898 \ifx\pdfbookmark\relax\else1\fi\fi\fi\relax%
10899 \pdfbookmark[#1]{\thesongnum. \songtitle}{#2}%
10900 \else\ifx\hypertarget\undefined%
10901 \else\ifx\hypertarget\relax\else%
10902 \hypertarget{#2}{\relax}%
10903 \fi\fi\fi%
10904 }
10905 % \end{macrocode}
10906 % \end{macro}
10907 %
10908 % \begin{macro}{\songlink}\MainImpl{songlink}
10909 % This macro is invoked by the index code to produce a link to a song target
10910 % created by \mac{songtarget}.
10911 % Its two arguments are:
10912 % (1) the target name (same as the second argument to \mac{songtarget}, and
10913 % (2) the text that is to be linked.
10914 % The default implementation uses |\hyperlink| if it exists; otherwise it
10915 % just leaves the text unlinked.
10916 % \begin{macrocode}
10917 \newcommand\songlink{%
10918 \ifnum\@ne=0\ifx\hyperlink\undefined\else%
10919 \ifx\hyperlink\relax\else1\fi\fi\relax%
10920 \expandafter\hyperlink%
10921 \else%
10922 \expandafter\@gobble%
10923 \fi%
10924 }
10925 % \end{macrocode}
10926 % \end{macro}
10927 %
10928 % \begin{macro}{\SB@indexlist}
10929 % This macro records the comma-separated list of the identifiers of indexes
10930 % associated with the current book section.
10931 % \begin{macrocode}
10932 \newcommand\SB@indexlist{}
10933 % \end{macrocode}
10934 % \end{macro}
10935 %
10936 % \begin{macro}{\SB@allindexes}
10937 % This macro records a comma-separated list of all the index identifiers
10938 % for the entire document.
10939 % \begin{macrocode}
10940 \newcommand\SB@allindexes{}
10941 \let\SB@allindexes\@empty
10942 % \end{macrocode}
10943 % \end{macro}
10944 %
10945 % \begin{macro}{\SB@out}
10946 % The |\SB@out| control sequence is reserved for the write register allocated
10947 % by the package code, if one is needed.
10948 % (It is allocated at the first index declaration.)
10949 % \begin{macrocode}
10950 \newcommand\SB@out{}
10951 \let\SB@out\relax
10952 % \end{macrocode}
10953 % \end{macro}
10954 %
10955 % \begin{macro}{\SB@newindex}
10956 % Initialize a new title, author, or scripture index.
10957 % \begin{macrocode}
10958 \newcommand\SB@newindex[4]{%
10959 \expandafter\newcommand\csname SB@idxfilename@#3\endcsname{#4}%
10960 \expandafter\newcommand\csname SB@idxsel@#3\endcsname[3]{###1}%
10961 \expandafter\newcommand\csname SB@idxref@#3\endcsname{\thesongnum}%
10962 \xdef\SB@allindexes{%
10963 \ifx\SB@allindexes\@empty\else\SB@allindexes,\fi#3%
10964 }%
10965 \if@filesw%
10966 \ifx\SB@out\relax%
10967 \SB@newwrite\SB@out%
10968 \immediate\openout\SB@out=\jobname.sxc\relax%
10969 \fi%
10970 \immediate\write\SB@out{\noexpand\SB@iwrite{#3}{#2}}%
10971 \fi%
10972 }
10973 % \end{macrocode}
10974 % \end{macro}
10975 %
10976 % \begin{macro}{\newindex}\MainImpl{newindex}
10977 % Define a new title index.
10978 % The first argument is an identifier for the index (used in constructing
10979 % index-specific control sequence names).
10980 % The second argument is a filename root; auxiliary file \argp{2}|.sxd| is
10981 % where the index data is stored at the end of processing.
10982 % \begin{macrocode}
10983 \newcommand\newindex{\SB@newindex1{TITLE INDEX DATA FILE}}
10984 \@onlypreamble\newindex
10985 % \end{macrocode}
10986 % \end{macro}
10987 %
10988 % \begin{macro}{\newscripindex}\MainImpl{newscripindex}
10989 % Define a new scripture index. This is exactly like |\newindex| except that
10990 % scripture references are added to the auxiliary file instead of titles.
10991 % \begin{macrocode}
10992 \newcommand\newscripindex{\SB@newindex2{SCRIPTURE INDEX DATA FILE}}
10993 \@onlypreamble\newscripindex
10994 % \end{macrocode}
10995 % \end{macro}
10996 %
10997 % \begin{macro}{\newauthorindex}\MainImpl{newauthorindex}
10998 % Define a new author index. This is exactly like |\newindex| except that
10999 % author info is added to the auxiliary file instead of titles.
11000 % \begin{macrocode}
11001 \newcommand\newauthorindex{\SB@newindex3{AUTHOR INDEX DATA FILE}}
11002 \@onlypreamble\newauthorindex
11003 % \end{macrocode}
11004 % \end{macro}
11005 %
11006 % \begin{macro}{\SB@cwrite}
11007 % Write index data to a Song indeX Combined (|.sxc|) auxiliary file.
11008 % The first argument is the identifier for the index to which the data
11009 % ultimately belongs.
11010 % The second argument is the data itself.
11011 % The write is non-immediate so that it is only output if its enclosing
11012 % song is ultimately shipped to the output file.
11013 % \begin{macrocode}
11014 \newcommand\SB@cwrite[2]{%
11015 \ifx\SB@out\relax\else%
11016 \protected@write\SB@out\SB@keepactive{\protect\SB@iwrite{#1}{#2}}%
11017 \fi%
11018 }
11019 % \end{macrocode}
11020 % \end{macro}
11021 %
11022 % \begin{macro}{\SB@keepactive}
11023 % By default, the |inputenc| package expands Unicode characters into macro
11024 % names when writing them to files.
11025 % This behavior must be inhibited when writing to the |.sxc| file, since
11026 % |songidx| needs the original Unicode characters for sorting.
11027 % To achieve this, we temporarily redefine most active characters so that
11028 % they expand to an unexpandable string version of themselves.
11029 % \begin{macrocode}
11030 \newcommand\SB@keepactive{}
11031 {\catcode`\~\active
11032 \catcode`\.12
11033 \def\\#1#2{%
11034 \endgroup
11035 \SB@app\gdef\SB@keepactive{\def#1{#2}}%
11036 }
11037 \def\SB@temp#1#2{%
11038 \SB@cnt#1\relax
11039 \loop
11040 \begingroup
11041 \uccode`\~\SB@cnt
11042 \uccode`\.\SB@cnt
11043 \uppercase{\\~.}
11044 \ifnum\SB@cnt<#2\relax
11045 \advance\SB@cnt\@ne
11046 \repeat
11047 }
11048 \SB@temp{1}{8}
11049 \SB@temp{11}{11}
11050 \SB@temp{14}{91}
11051 \SB@temp{93}{255}
11052 }
11053 % \end{macrocode}
11054 % \end{macro}
11055 %
11056 % \begin{macro}{\SB@iwrite}
11057 % The line contributed by |\SB@cwrite| to the |.sxc| file is an |\SB@iwrite|
11058 % macro that re-outputs the data to an appropriate |.sxd| file.
11059 % \begin{macrocode}
11060 \newcommand\SB@iwrite[2]{%
11061 \def\SB@tempii{#1}%
11062 \ifx\SB@temp\SB@tempii%
11063 \SB@toks{#2}%
11064 \immediate\write\SB@out{\the\SB@toks}%
11065 \fi%
11066 }
11067 % \end{macrocode}
11068 % \end{macro}
11069 %
11070 % \begin{macro}{\SB@uncombine}
11071 % At the end of the document, the |.sxc| file can be processed multiple
11072 % times to produce all the |.sxd| files without resorting to multiple write
11073 % registers.
11074 % Each pass activates the subset of the |\SB@iwrite| commands that apply to
11075 % one index.
11076 % \begin{macrocode}
11077 \newcommand\SB@uncombine{%
11078 \ifx\SB@out\relax\else%
11079 \immediate\closeout\SB@out%
11080 \ifsongindexes%
11081 \@for\SB@temp:=\SB@allindexes\do{%
11082 \immediate\openout\SB@out=%
11083 \csname SB@idxfilename@\SB@temp\endcsname.sxd\relax%
11084 \begingroup\makeatletter\catcode`\%12\relax%
11085 \input{\jobname.sxc}\endgroup%
11086 \immediate\closeout\SB@out%
11087 }%
11088 \fi%
11089 \fi%
11090 }
11091 \AtEndDocument{\SB@uncombine}
11092 % \end{macrocode}
11093 % \end{macro}
11094 %
11095 % \begin{macro}{\SB@songwrites}
11096 % The following box register stores index data until it can be migrated to
11097 % the top of the song box currently under construction.
11098 % \begin{macrocode}
11099 \SB@newbox\SB@songwrites
11100 % \end{macrocode}
11101 % \end{macro}
11102 %
11103 % \begin{macro}{\SB@addtoindex}
11104 % \changes{v2.8}{2009/02/03}{Writes made non-immediate}
11105 % Queue data \argp{2} associated with the current song for eventual writing
11106 % to the index whose identifier is given by \argp{1}.
11107 % \begin{macrocode}
11108 \newcommand\SB@addtoindex[2]{%
11109 \protected@edef\SB@tempii{#2}%
11110 \ifx\SB@tempii\@empty\else%
11111 \global\setbox\SB@songwrites\vbox{%
11112 \unvbox\SB@songwrites%
11113 \SB@cwrite{#1}{#2}%
11114 \SB@cwrite{#1}{\csname SB@idxref@#1\endcsname}%
11115 \SB@cwrite{#1}{song\theSB@songsnum-\thesongnum.%
11116 \ifnum\c@section=\z@1\else2\fi}%
11117 }%
11118 \fi%
11119 }
11120 % \end{macrocode}
11121 % \end{macro}
11122 %
11123 % \begin{macro}{\SB@addtoindexes}
11124 % Add \argp{1} to all title indexes, \argp{2} to all scripture indexes, and
11125 % \argp{3} to all author indexes.
11126 % \begin{macrocode}
11127 \newcommand\SB@addtoindexes[3]{%
11128 \@for\SB@temp:=\SB@indexlist\do{%
11129 \SB@addtoindex\SB@temp%
11130 {\csname SB@idxsel@\SB@temp\endcsname{#1}{#2}{#3}}%
11131 }%
11132 }
11133 % \end{macrocode}
11134 % \end{macro}
11135 %
11136 % \begin{macro}{\SB@addtotitles}
11137 % Add \argp{1} to all title indexes, but leave other indexes unaffected.
11138 % \begin{macrocode}
11139 \newcommand\SB@addtotitles[1]{%
11140 \@for\SB@temp:=\SB@indexlist\do{%
11141 \csname SB@idxsel@\SB@temp\endcsname%
11142 {\SB@addtoindex\SB@temp{#1}}{}{}%
11143 }%
11144 }
11145 % \end{macrocode}
11146 % \end{macro}
11147 %
11148 % \begin{macro}{\SB@chkidxlst}
11149 % \changes{v2.3}{2007/09/23}{Added.}
11150 % Check the current list of indexes and flag an error if any are undefined.
11151 % \begin{macrocode}
11152 \newcommand\SB@chkidxlst{%
11153 \let\SB@temp\SB@indexlist%
11154 \let\SB@indexlist\@empty%
11155 \@for\SB@tempii:=\SB@temp\do{%
11156 \@ifundefined{SB@idxsel@\SB@tempii}{\SB@errnoidx\SB@tempii}{%
11157 \ifx\SB@indexlist\@empty%
11158 \SB@toks\expandafter{\SB@tempii}%
11159 \else%
11160 \SB@toks\expandafter\expandafter\expandafter{%
11161 \expandafter\SB@indexlist\expandafter,\SB@tempii}%
11162 \fi%
11163 \edef\SB@indexlist{\the\SB@toks}%
11164 }%
11165 }%
11166 }
11167 % \end{macrocode}
11168 % \end{macro}
11169 %
11170 % \begin{macro}{\indexentry}\MainImpl{indexentry}
11171 % \changes{v2.3}{2007/09/23}{Optional argument added}
11172 % \begin{macro}{\SB@idxentry}
11173 % \begin{macro}{\SB@@idxentry}
11174 % |\SB@addtoindexes| will be called automatically for each song in a section.
11175 % However, |\indexentry| may be called by the user in order to add an
11176 % alternative index entry for the given song.
11177 % Usually this is done to index the song by its first line or some other
11178 % memorable line in a chorus or verse somewhere.
11179 % \begin{macrocode}
11180 \newcommand\indexentry{\@ifnextchar[{\SB@idxentry*}{\SB@@idxentry*}}
11181 \newcommand\SB@idxentry{}
11182 \def\SB@idxentry#1[#2]#3{{%
11183 \def\SB@indexlist{#2}%
11184 \SB@chkidxlst%
11185 \SB@addtoindexes{#1#3}{#3}{#3}%
11186 }}
11187 \newcommand\SB@@idxentry[2]{\SB@addtotitles{#1#2}}
11188 % \end{macrocode}
11189 % \end{macro}
11190 % \end{macro}
11191 % \end{macro}
11192 %
11193 % \begin{macro}{\indextitleentry}\MainImpl{indextitleentry}
11194 % \changes{v2.3}{2007/09/23}{Optional argument added}
11195 % |\indextitleentry| may be used to add an alternate title for the song to
11196 % the index.
11197 % (The only difference between the effects of |\indexentry| and
11198 % |\indextitleentry| is that the latter are italicized in the rendered index
11199 % and the former are not.)
11200 % \begin{macrocode}
11201 \newcommand\indextitleentry{%
11202 \@ifnextchar[{\SB@idxentry{}}{\SB@@idxentry{}}%
11203 }
11204 % \end{macrocode}
11205 % \end{macro}
11206 %
11207 % \begin{macro}{\indexsongsas}\MainImpl{indexsongsas}
11208 % \changes{v2.8}{2009/02/03}{Added.}
11209 % The following macro allows the user to change how songs are indexed on the
11210 % right side of index entries.
11211 % By default, the song's number is listed.
11212 % \begin{macrocode}
11213 \newcommand\indexsongsas[1]{%
11214 \@ifundefined{SB@idxref@#1}%
11215 {\SB@errnoidx{#1}\@gobble}%
11216 {\expandafter\renewcommand\csname SB@idxref@#1\endcsname}%
11217 }
11218 % \end{macrocode}
11219 % \end{macro}
11220 %
11221 % \begin{macro}{\SB@idxcmd}
11222 % \begin{macro}{\SB@@idxcmd}
11223 % \begin{macro}{\authsepword}\MainImpl{authsepword}
11224 % \begin{macro}{\authbyword}\MainImpl{authbyword}
11225 % \begin{macro}{\authignoreword}\MainImpl{authignoreword}
11226 % \begin{macro}{\titleprefixword}\MainImpl{titleprefixword}
11227 % \changes{v2.0}{2007/06/18}{Added.}
11228 % The |songidx| index-generation script understands several different
11229 % directives that each dictate various aspects of how index entries are
11230 % parsed, sorted, and displayed.
11231 % Such directives should typically appear at the start of the |.sxd|
11232 % file just after the header line that identifies the type of index.
11233 % \begin{macrocode}
11234 \newcommand\SB@idxcmd[3]{%
11235 \ifx\SB@allindexes\@empty%
11236 \SB@warnnoidx%
11237 \else\ifx\SB@out\relax\else%
11238 \@for\SB@temp:=\SB@allindexes\do{%
11239 \csname SB@idxsel@\SB@temp\endcsname%
11240 {\SB@@idxcmd{#1}}{\SB@@idxcmd{#2}}{\SB@@idxcmd{#3}}%
11241 }%
11242 \fi\fi%
11243 }
11244 \newcommand\SB@@idxcmd[1]{%
11245 \def\SB@tempii{#1}%
11246 \ifx\SB@tempii\@empty\else%
11247 \immediate\write\SB@out{%
11248 \noexpand\SB@iwrite{\SB@temp}{#1}%
11249 }%
11250 \fi%
11251 }
11252 \newcommand\authsepword[1]{}
11253 \newcommand\authbyword[1]{}
11254 \newcommand\authignoreword[1]{}
11255 \newcommand\titleprefixword[1]{}
11256 {\catcode`\%=12
11257 \gdef\authsepword#1{\SB@idxcmd{}{}{%sep #1}}
11258 \gdef\authbyword#1{\SB@idxcmd{}{}{%after #1}}
11259 \gdef\authignoreword#1{\SB@idxcmd{}{}{%ignore #1}}
11260 \gdef\titleprefixword#1{\SB@idxcmd{%prefix #1}{}{}}}
11261 \@onlypreamble\authsepword
11262 \@onlypreamble\authbyword
11263 \@onlypreamble\authignoreword
11264 \@onlypreamble\titleprefixword
11265 % \end{macrocode}
11266 % \end{macro}
11267 % \end{macro}
11268 % \end{macro}
11269 % \end{macro}
11270 % \end{macro}
11271 % \end{macro}
11272 %
11273 % \begin{macro}{\SB@idxlineskip}
11274 % Set the spacing between lines in an index.
11275 % \begin{macrocode}
11276 \newcommand\SB@idxlineskip[1]{%
11277 \vskip#1\p@\@plus#1\p@\@minus#1\p@%
11278 }
11279 % \end{macrocode}
11280 % \end{macro}
11281 %
11282 % When rendering an index entry $X\ldots Y$ that is too long to fit on one
11283 % physical line, we must break text $X$ and/or $Y$ up into multiple lines.
11284 % Text $X$ should be typeset as a left-justified paragraph with a right
11285 % margin of about 2em; however, its final line must not be so long that it
11286 % cannot fit even the first item of list $Y$.
11287 % Text $Y$ should be typeset as a right-justified paragraph whose first line
11288 % begins on the last line of $X$.
11289 % However, breaking $Y$ up the way paragraphs are normally broken up doesn't
11290 % work well because that causes most of $Y$ to be crammed into the first few
11291 % lines, leaving the last line very short.
11292 % This looks strange and is hard to read.
11293 % It looks much better to instead break $Y$ up in such a way that the portion
11294 % of $Y$ that is placed on each line is of approximately equal width (subject
11295 % to the constraint that we don't want to introduce any more lines than are
11296 % necessary).
11297 % This makes it visually clear that all of these lines are associated with $X$.
11298 % The following code performs the width computations that do this
11299 % horizontal-balancing of text.
11300 %
11301 % \begin{macro}{\SB@ellipspread}
11302 % Typeset an index entry of the form $X\ldots Y$.
11303 % In the common case, the entire entry fits on one line so we just typeset
11304 % it in the usual way.
11305 % If it doesn't fit on one line, we call |\SB@balancerows| for a more
11306 % sophisticated treatment.
11307 % \begin{macrocode}
11308 \newcommand\SB@ellipspread[2]{%
11309 \begingroup%
11310 \SB@dimen\z@%
11311 \def\SB@temp{#1}%
11312 \SB@toks{#2}%
11313 \setbox\SB@box\hbox{{%
11314 \SB@temp%
11315 \leaders\hbox to.5em{\hss.\hss}\hskip2em\@plus1fil%
11316 {\the\SB@toks}%
11317 }}%
11318 \ifdim\wd\SB@box>\hsize%
11319 \SB@balancerows%
11320 \else%
11321 \hbox to\hsize{\unhbox\SB@box}\par%
11322 \fi%
11323 \endgroup%
11324 }
11325 % \end{macrocode}
11326 % \end{macro}
11327 %
11328 % \begin{macro}{\SB@balancerows}
11329 % Typeset an index entry of the form $X\ldots Y$ that doesn't fit on one line,
11330 % where $X$ is the content of macro |\SB@temp| and
11331 % $Y$ is the content of token register |\SB@toks|.
11332 %
11333 % First, we must pre-compute the width $w_1$ of the final line of $X$ when
11334 % $X$ is typeset as a left-justified paragraph, storing it in |\SB@dimenii|.
11335 % This is necessary because in order to force \TeX{} to typeset the first
11336 % line of $Y$ at some chosen width $w_2$, we must insert leaders of width
11337 % $c-w_1-w_2$ into the paragraph between $X$ and $Y$, where $c$ is the column
11338 % width.
11339 %
11340 % Computing this width $w_1$ is a bit tricky.
11341 % We must tell \TeX{} that the last line of $X$ must not be so long that it
11342 % does not even have room for the first item of $Y$.
11343 % Thus, we must strip off the first item of $Y$ and add it (or a non-breaking
11344 % space of equivalent width) to the end of $X$ to typeset the paragraph.
11345 % Then we use |\lastbox| to pull off the final line and check its width.
11346 % \begin{macrocode}
11347 \newcommand\SB@balancerows{%
11348 \edef\SB@tempii{\the\SB@toks}%
11349 \setbox\SB@box\vbox{%
11350 \SB@toks\expandafter{\expandafter\\\the\SB@toks\\}%
11351 \SB@lop\SB@toks\SB@toks%
11352 \settowidth\SB@dimen{\the\SB@toks}%
11353 \advance\[email protected]%
11354 \leftskip.5cm%
11355 {\hbadness\@M\hfuzz\maxdimen%
11356 \hskip-.5cm\relax\SB@temp\unskip\nobreak%
11357 \hskip\SB@dimen\nobreak%
11358 \rightskip2em\@plus1fil\par}%
11359 \setbox\SB@box\lastbox%
11360 \setbox\SB@box\hbox{%
11361 \unhbox\SB@box%
11362 \unskip\unskip\unpenalty%
11363 \unpenalty\unskip\unpenalty%
11364 }%
11365 \expandafter%
11366 }%
11367 \expandafter\SB@dimenii\the\wd\SB@box\relax%
11368 % \end{macrocode}
11369 % Next, compute the smallest width $w_2$ such that the index entry text
11370 % produced by |\SB@multiline| with |\SB@dimen|=$w_2$ has no more lines than
11371 % with |\SB@dimen| set to the maximum available width for the right-hand side.
11372 % This effectively horizontal-balances the right-hand side of the index entry
11373 % text, making all lines of $Y$ roughly equal in width without introducing
11374 % any extra lines.
11375 % \begin{macrocode}
11376 \SB@dimen\hsize%
11377 \advance\[email protected]%
11378 \setbox\SB@box\vbox{%
11379 \SB@multiline{\hbadness\@M\hfuzz\maxdimen}%
11380 }%
11381 \[email protected]\SB@dimen%
11382 \SB@dimeniv\SB@dimeniii%
11383 \loop%
11384 \[email protected]\SB@dimeniv%
11385 \setbox\SB@boxii\vbox{%
11386 \SB@dimen\SB@dimeniii%
11387 \SB@multiline{\hbadness\@M\hfuzz\maxdimen}%
11388 }%
11389 \ifnum\SB@cnt<\@M%
11390 \ifdim\ht\SB@boxii>\ht\SB@box%
11391 \advance\SB@dimeniii\SB@dimeniv%
11392 \else%
11393 \SB@dimen\SB@dimeniii%
11394 \advance\SB@dimeniii-\SB@dimeniv%
11395 \fi%
11396 \else%
11397 \advance\SB@dimeniii\SB@dimeniv%
11398 \fi%
11399 \ifdim\SB@dimeniv>2\p@\repeat%
11400 \setbox\SB@box\box\voidb@x%
11401 \setbox\SB@boxii\box\voidb@x%
11402 % \end{macrocode}
11403 % Finally, typeset the results based on the quantities computed above.
11404 % \begin{macrocode}
11405 \SB@multiline\relax%
11406 }
11407 % \end{macrocode}
11408 % \end{macro}
11409 %
11410 % \begin{macro}{\SB@multiline}
11411 % Create a paragraph containing text $X\ldots Y$
11412 % where $X$ is the content of |\SB@temp|, $Y$ is the content of |\SB@tempii|,
11413 % and $Y$ is restricted to width |\SB@dimen| (but may span multiple
11414 % lines of that width).
11415 % Dimen register |\SB@dimenii| must be set with the expected width of the
11416 % final line of $X$.
11417 % The first argument contains any parameter definitions that should be in
11418 % effect when $X$ is processed.
11419 %
11420 % Note that the expansion of |\SB@tempii|, which may contain |\SB@idxitemsep|,
11421 % depends on |\SB@dimen|.
11422 % Therefore, the redefinition of |\SB@dimen| at the start of this macro must
11423 % not be removed!
11424 % \begin{macrocode}
11425 \newcommand\SB@multiline[1]{%
11426 \begingroup%
11427 \SB@dimen-\SB@dimen%
11428 \advance\SB@dimen\hsize%
11429 \SB@dimenii-\SB@dimenii%
11430 \advance\SB@dimenii\SB@dimen%
11431 {#1\hskip-.5cm\relax\SB@temp\unskip\nobreak%
11432 \SB@maxmin\SB@dimenii<{1.5em}%
11433 \leftskip.5cm\rightskip2em\@plus1fil%
11434 \interlinepenalty\@M%
11435 \leaders\hbox to.5em{\hss.\hss}\hskip\SB@dimenii\@plus1fill%
11436 \nobreak{\SB@tempii\kern-2em}%
11437 \par\global\SB@cnt\badness}%
11438 \endgroup%
11439 }%
11440 % \end{macrocode}
11441 % \end{macro}
11442 %
11443 % \begin{macro}{\SB@idxitemsep}
11444 % \changes{v1.11}{2005/04/21}{Changed macro name to avoid a name clash}
11445 % If text $Y$ in index entry $X\ldots Y$ has multiple items in a list, those
11446 % items should be separated by |\\| macros instead of by commas.
11447 % The |\\| macro will be assigned the definition of |\SB@idxitemsep| during
11448 % index generation, which produces the comma along with the complex spacing
11449 % required if $Y$ ends up being broken into multiple lines.
11450 % In particular, it forces each wrapped line of $Y$ to be right-justified
11451 % with left margin at least |\SB@dimen|.
11452 % \begin{macrocode}
11453 \newcommand\SB@idxitemsep{%
11454 ,\kern-2em\penalty-8\hskip2.33em\@minus.11em%
11455 \hskip-\SB@dimen\@plus-1fill%
11456 \vadjust{}\nobreak%
11457 \hskip\SB@dimen\@plus1fill\relax%
11458 }
11459 % \end{macrocode}
11460 % \end{macro}
11461 %
11462 % The following set of macros and environments are intended for use in the
11463 % |.sbx| files that are automatically generated by an index-generating
11464 % program; they shouldn't normally appear in the user's |.tex| or |.sbd|
11465 % files directly.
11466 % However, they are named as exported macros (no |@| symbols) since they are
11467 % used outside the package code and are therefore not stricly internal.
11468 %
11469 % \begin{environment}{idxblock}
11470 % Some indexes are divided into blocks (e.g., one for each letter of the
11471 % alphabet or one for each book of the bible).
11472 % Each such block should be enclosed between |\begin{idxblock}{X}| and
11473 % |\end{idxblock}| lines, where X is the title of the block. The actual
11474 % definition of the |idxblock| environment is set within the initialization
11475 % code for each type of index (below).
11476 % \begin{macrocode}
11477 \newenvironment{idxblock}[1]{}{}
11478 % \end{macrocode}
11479 % \end{environment}
11480 %
11481 % \begin{macro}{\idxentry}
11482 % \begin{macro}{\idxaltentry}
11483 % Within each |idxblock| environment there should be a series of |\idxentry|
11484 % and/or |\idxaltentry| macros, one for each line of the index. Again, the
11485 % exact definitions of these macros will vary between index types.
11486 % \begin{macrocode}
11487 \newcommand\idxentry[2]{}
11488 \newcommand\idxaltentry[2]{}
11489 % \end{macrocode}
11490 % \end{macro}
11491 % \end{macro}
11492 %
11493 % \begin{environment}{SB@lgidx}
11494 % \begin{environment}{SB@smidx}
11495 % Some indexes actually have two definitions for each |idxblock|
11496 % environment---one for use when there are few enough entries to permit a
11497 % small style index, and another for use in a large style index. These macros
11498 % will be redefined appropriately within the initialization code for each
11499 % type of index.
11500 % \begin{macrocode}
11501 \newenvironment{SB@lgidx}[1]{}{}
11502 \newenvironment{SB@smidx}[1]{}{}
11503 % \end{macrocode}
11504 % \end{environment}
11505 % \end{environment}
11506 %
11507 % \begin{macro}{\SB@idxsetup}
11508 % Set various parameters for a column of an index environment.
11509 % \begin{macrocode}
11510 \newcommand\SB@idxsetup{%
11511 \hsize\SB@colwidth%
11512 \parskip\z@skip\parfillskip\z@skip\parindent\z@%
11513 \baselineskip\f@size\p@\@plus\p@\@minus\p@%
11514 \lineskiplimit\z@\lineskip\p@\@plus\p@\@minus\p@%
11515 \hyphenpenalty\@M\exhyphenpenalty\@M%
11516 }
11517 % \end{macrocode}
11518 % \end{macro}
11519 %
11520 % \begin{macro}{\SB@makeidxcolumn}
11521 % Break off enough material from |\SB@box| to create one column of the
11522 % index.
11523 % \begin{macrocode}
11524 \newcommand\SB@makeidxcolumn{%
11525 \ifdim\ht\SB@box=\z@%
11526 \hskip\hsize\relax%
11527 \else%
11528 \splittopskip\z@skip\splitmaxdepth\maxdepth%
11529 \vsplit\SB@box to\SB@dimen%
11530 \global\setbox\SB@box\vbox{%
11531 \SB@idxsetup%
11532 \splitbotmark%
11533 \unvbox\SB@box%
11534 }%
11535 \fi%
11536 }
11537 % \end{macrocode}
11538 % \end{macro}
11539 %
11540 % \begin{macro}{\SB@oneidxpage}
11541 % Construct one full page of the index.
11542 % The definition of |\SB@oneidxpage| is generated dynamically based on the
11543 % type of index and number of columns.
11544 % \begin{macrocode}
11545 \newcommand\SB@oneidxpage{}
11546 % \end{macrocode}
11547 % \end{macro}
11548 %
11549 % \begin{macro}{\SB@displayindex}
11550 % \changes{v1.11}{2005/04/21}{Item separator macro now localized in scope to the index file}
11551 % \changes{v2.0}{2007/06/18}{Removed hyperref dependency}
11552 % \changes{v2.6}{2008/02/16}{Balance columns on final page}
11553 % \changes{v2.8}{2009/03/06}{Changed argument order}
11554 % Create an index with title \argp{2} and with \argp{1} columns (must be a
11555 % literal constant). Input the index contents from external file \argp{3},
11556 % which is expected to be a \TeX{} file.
11557 % \begin{macrocode}
11558 \newcommand\SB@displayindex[3]{%
11559 \ifsongindexes\begingroup%
11560 \SB@colwidth\hsize%
11561 \advance\SB@colwidth-#1\columnsep%
11562 \advance\SB@colwidth\columnsep%
11563 \divide\SB@colwidth#1%
11564 \setbox\SB@envbox\vbox{%
11565 \let\SB@temp\songsection%
11566 \ifx\chapter\undefined\else%
11567 \ifx\chapter\relax\else%
11568 \let\SB@temp\songchapter%
11569 \fi%
11570 \fi%
11571 \SB@temp{#2}%
11572 }%
11573 % \end{macrocode}
11574 % The |.sbx| index file might not exist (e.g., if this is the first pass
11575 % through the \TeX{} compiler).
11576 % If it exists, first try typesetting its content as a small index
11577 % (one column, centered, with no divisions).
11578 % \begin{macrocode}
11579 \IfFileExists{\csname SB@idxfilename@#3\endcsname.sbx}{%
11580 \ifsepindexes%
11581 \global\setbox\SB@box\vbox{%
11582 \null%
11583 \vfil%
11584 \unvcopy\SB@envbox%
11585 \vskip.5in\@minus.3in\relax%
11586 \hbox to\hsize{%
11587 \hfil%
11588 \vbox{%
11589 \SB@idxsetup%
11590 \renewenvironment{idxblock}[1]%
11591 {\begin{SB@smidx}{####1}}{\end{SB@smidx}}%
11592 \let\\\SB@idxitemsep%
11593 \input{\csname SB@idxfilename@#3\endcsname.sbx}%
11594 }%
11595 \hfil%
11596 }%
11597 \vskip\z@\@plus2fil\relax%
11598 }%
11599 % \end{macrocode}
11600 % Test whether the resulting small index fits within one page.
11601 % If not, re-typeset it as a large index.
11602 % \begin{macrocode}
11603 {\vbadness\@M\vfuzz\maxdimen%
11604 \splitmaxdepth\maxdepth\splittopskip\z@skip%
11605 \global\setbox\SB@boxii\vsplit\SB@box to\textheight}%
11606 \ifvoid\SB@box%
11607 \box\SB@boxii%
11608 \else%
11609 \SB@lgindex{#1}{#3}%
11610 \fi%
11611 \else%
11612 \SB@lgindex{#1}{#3}%
11613 \fi%
11614 }%
11615 % \end{macrocode}
11616 % If the |.sbx| file doesn't exist, then instead typeset a page with a
11617 % message on it indicating that the document must be compiled a second
11618 % time in order to generate the index.
11619 % \begin{macrocode}
11620 {%
11621 \ifsepindexes%
11622 \vbox to\textheight{%
11623 \vfil%
11624 \unvbox\SB@envbox%
11625 \vskip1em\relax%
11626 \hbox to\hsize{\hfil[Index not yet generated.]\hfil}%
11627 \vskip\z@\@plus2fil\relax%
11628 }%
11629 \else%
11630 \unvbox\SB@envbox%
11631 \hbox to\hsize{\hfil[Index not yet generated.]\hfil}%
11632 \fi%
11633 }%
11634 \ifsepindexes\clearpage\fi%
11635 \endgroup\fi%
11636 }
11637 % \end{macrocode}
11638 % \end{macro}
11639 %
11640 % \begin{macro}{\SB@lgindex}
11641 % Typeset a large-style index.
11642 % We begin by typesetting the entire index into a box.
11643 % \begin{macrocode}
11644 \newcommand\SB@lgindex[2]{%
11645 \global\setbox\SB@box\vbox{%
11646 \renewenvironment{idxblock}[1]%
11647 {\begin{SB@lgidx}{##1}}{\end{SB@lgidx}}%
11648 \let\\\SB@idxitemsep%
11649 \SB@idxsetup%
11650 \input{\csname SB@idxfilename@#2\endcsname.sbx}%
11651 \unskip%
11652 }%
11653 % \end{macrocode}
11654 % Next, we split the box into columns and pages until the last page is reached.
11655 % \begin{macrocode}
11656 \SB@toks{\SB@makeidxcolumn}%
11657 \SB@cnt#1\relax%
11658 \loop\ifnum\SB@cnt>\@ne%
11659 \SB@toks\expandafter{\the\SB@toks%
11660 \kern\columnsep\SB@makeidxcolumn}%
11661 \advance\SB@cnt\m@ne%
11662 \repeat%
11663 \edef\SB@oneidxpage{\the\SB@toks}%
11664 \unvbox\SB@envbox%
11665 \vskip.2in\relax%
11666 \nointerlineskip%
11667 \null%
11668 \nointerlineskip%
11669 \SB@cnt\vbadness\vbadness\@M%
11670 \SB@dimenii\vfuzz\vfuzz\maxdimen%
11671 \loop%
11672 \SB@dimen\textheight%
11673 \ifinner\else\kern\z@\advance\SB@dimen-\pagetotal\fi%
11674 \global\setbox\SB@boxii\copy\SB@box%
11675 \global\setbox\SB@boxiii\hbox{\SB@oneidxpage}%
11676 \ifdim\ht\SB@box>\z@%
11677 \box\SB@boxiii%
11678 \vfil\break%
11679 \repeat%
11680 % \end{macrocode}
11681 % The final page of the index should have all equal-height columns instead
11682 % of a few full columns followed by some short or empty columns at the end.
11683 % To achieve this, we re-typeset the final page, trying different column
11684 % heights until we find one that causes the material to span an equal
11685 % percentage of all the columns on the page.
11686 % \begin{macrocode}
11687 \SB@dimenii\ht\SB@boxii%
11688 \divide\SB@dimenii#1\relax%
11689 \SB@maxmin\SB@dimen>\SB@dimenii%
11690 \loop%
11691 \global\setbox\SB@box\copy\SB@boxii%
11692 \global\setbox\SB@boxiii\hbox{\SB@oneidxpage}%
11693 \ifdim\ht\SB@box>\z@%
11694 \advance\SB@dimen\p@%
11695 \repeat%
11696 \box\SB@boxiii%
11697 \global\setbox\SB@boxii\box\voidb@x%
11698 \vbadness\SB@cnt\vfuzz\SB@dimenii%
11699 }
11700 % \end{macrocode}
11701 % \end{macro}
11702 %
11703 % \begin{macro}{\showindex}\MainImpl{showindex}
11704 % \changes{v2.8}{2009/03/06}{Added optional argument}
11705 % Create an index with title \argp{2} based on the data associated with index
11706 % identifier \argp{3} (which was passed to |\newindex|).
11707 % Optional argument \argp{1} specifies the number of columns.
11708 % This macro calls the appropriate index-creation macro depending on the type
11709 % of index that \argp{3} was declared to be.
11710 % \begin{macrocode}
11711 \newcommand\showindex[3][0]{%
11712 \@ifundefined{SB@idxsel@#3}{\SB@errnoidx{#3}}{%
11713 \expandafter\let\expandafter\SB@temp\csname SB@idxsel@#3\endcsname%
11714 \SB@cnt#1\relax%
11715 \ifnum\SB@cnt<\@ne\SB@cnt\SB@temp232\relax\fi%
11716 \expandafter\SB@temp%
11717 \expandafter\SB@maketitleindex%
11718 \expandafter\SB@makescripindex%
11719 \expandafter\SB@makeauthorindex%
11720 \expandafter{\the\SB@cnt}%
11721 {#2}{#3}%
11722 }%
11723 }
11724 % \end{macrocode}
11725 % \end{macro}
11726 %
11727 % \begin{macro}{\SB@maketitleindex}
11728 % \changes{v2.8}{2009/03/06}{Added columns argument}
11729 % Create a song title index.
11730 % \argp{1} is a column count,
11731 % \argp{2} is the title, and
11732 % \argp{3} is the index identifier (which was passed to |\newindex|).
11733 % \begin{macrocode}
11734 \newcommand\SB@maketitleindex{%
11735 \ifnum\idxheadwidth>\z@%
11736 \renewenvironment{SB@lgidx}[1]{
11737 \hbox{\SB@colorbox\idxbgcolor{\vbox{%
11738 \hbox to\idxheadwidth{{\idxheadfont\relax##1}\hfil}%
11739 }}}%
11740 \nobreak\vskip3\p@\@plus2\p@\@minus2\p@\nointerlineskip%
11741 }{\penalty-50\vskip5\p@\@plus5\p@\@minus4\p@}%
11742 \else%
11743 \renewenvironment{SB@lgidx}[1]{}{}%
11744 \fi%
11745 \renewenvironment{SB@smidx}[1]{}{}%
11746 \renewcommand\idxentry[2]{%
11747 \SB@ellipspread{\idxtitlefont\relax\ignorespaces##1\unskip}%
11748 {{\idxrefsfont\relax##2}}%
11749 }%
11750 \renewcommand\idxaltentry[2]{%
11751 \SB@ellipspread{\idxlyricfont\relax\ignorespaces##1\unskip}%
11752 {{\idxrefsfont\relax##2}}%
11753 }%
11754 \SB@displayindex%
11755 }
11756 % \end{macrocode}
11757 % \end{macro}
11758 %
11759 % \begin{macro}{\SB@idxcolhead}
11760 % In a scripture index, this macro remembers the current book of the bible
11761 % we're in so that new columns can be headed with ``Bookname (continued)''.
11762 % \begin{macrocode}
11763 \newcommand\SB@idxcolhead{}
11764 % \end{macrocode}
11765 % \end{macro}
11766 %
11767 % \begin{macro}{\SB@idxheadsep}
11768 % Add vertical space following the header line that begins (or continues) a
11769 % section of a scripture index.
11770 % \begin{macrocode}
11771 \newcommand\SB@idxheadsep{{%
11772 \SB@dimen4\p@%
11773 \advance\SB@dimen-\prevdepth%
11774 \SB@maxmin\SB@dimen<\z@%
11775 \SB@dimenii\SB@dimen%
11776 \SB@maxmin\SB@dimenii>\p@%
11777 \vskip\SB@dimen\@plus\p@\@minus\SB@dimenii%
11778 }}
11779 % \end{macrocode}
11780 % \end{macro}
11781 %
11782 % \begin{macro}{\SB@idxcont}
11783 % Typeset the ``Bookname (continued)'' line that continues a scripture
11784 % index section when it spans a column break.
11785 % \begin{macrocode}
11786 \newcommand\SB@idxcont[1]{%
11787 \hbox to\hsize{{\idxcont{#1}}\hfil}%
11788 \nobreak%
11789 \SB@idxheadsep\nointerlineskip%
11790 }
11791 % \end{macrocode}
11792 % \end{macro}
11793 %
11794 % \begin{macro}{\SB@makescripindex}
11795 % \changes{v2.4}{2007/10/08}{Scripture index spacing made more uniform}
11796 % \changes{v2.8}{2009/03/06}{Added columns argument}
11797 % Create a scripture index.
11798 % \argp{1} is a column count,
11799 % \argp{1} is the title, and
11800 % \argp{2} is the index identifier (which was passed to |\newscripindex|).
11801 % \begin{macrocode}
11802 \newcommand\SB@makescripindex{%
11803 \renewenvironment{SB@lgidx}[1]{%
11804 \gdef\SB@idxcolhead{##1}%
11805 \hbox to\hsize{{\idxbook{##1}}\hfil}%
11806 \nobreak%
11807 \SB@idxheadsep\nointerlineskip%
11808 }{%
11809 \mark{\noexpand\relax}%
11810 \penalty-20\vskip3\p@\@plus3\p@\relax%
11811 }%
11812 \renewenvironment{SB@smidx}[1]
11813 {\begin{SB@lgidx}{##1}}{\end{SB@lgidx}}%
11814 \renewcommand\idxentry[2]{%
11815 \SB@ellipspread{\hskip.25cm\idxscripfont\relax##1}%
11816 {{\idxrefsfont\relax##2}}%
11817 \SB@toks\expandafter{\SB@idxcolhead}%
11818 \mark{\noexpand\SB@idxcont{\the\SB@toks}}%
11819 }%
11820 \renewcommand\idxaltentry[2]{\SB@erridx{a scripture}}%
11821 \SB@displayindex%
11822 }
11823 % \end{macrocode}
11824 % \end{macro}
11825 %
11826 % \begin{macro}{\SB@makeauthorindex}
11827 % \changes{v2.8}{2009/03/06}{Added columns argument}
11828 % Create an author index.
11829 % \argp{1} is a column count,
11830 % \argp{2} is the title, and
11831 % \argp{2} is the index identifier (which was passed to |\newauthindex|).
11832 % \begin{macrocode}
11833 \newcommand\SB@makeauthorindex{%
11834 \renewenvironment{SB@lgidx}[1]{}{}%
11835 \renewenvironment{SB@smidx}[1]{}{}%
11836 \renewcommand\idxentry[2]{%
11837 \SB@ellipspread{{\idxauthfont\relax\sfcode`.\@m##1}}%
11838 {{\idxrefsfont##2}}%
11839 }%
11840 \renewcommand\idxaltentry[2]{\SB@erridx{an author}}%
11841 \SB@displayindex%
11842 }
11843 % \end{macrocode}
11844 % \end{macro}
11845 %
11846 % \subsection{Error Messages}
11847 %
11848 % We break error messages out into separate macros here in order to reduce the
11849 % length (in tokens) of the more frequently used macros that do actual work.
11850 % This can result in a small speed improvement on slower machines.
11851 %
11852 % \begin{macro}{\SB@Error}
11853 % \begin{macro}{\SB@Warn}
11854 % All errors and warnings will be reported as coming from package ``songs''.
11855 % \begin{macrocode}
11856 \newcommand\SB@Error{\PackageError{songs}}
11857 \newcommand\SB@Warn{\PackageWarning{songs}}
11858 % \end{macrocode}
11859 % \end{macro}
11860 % \end{macro}
11861 %
11862 % \begin{macro}{\SB@errspos}
11863 % \begin{macrocode}
11864 \newcommand\SB@errspos{%
11865 \SB@Error{Illegal \protect\songpos\space argument}{The argume%
11866 nt to \protect\songpos\space must be a number from 0 to 3.}%
11867 }
11868 % \end{macrocode}
11869 % \end{macro}
11870 %
11871 % \begin{macro}{\SB@errnse}
11872 % \begin{macrocode}
11873 \newcommand\SB@errnse{%
11874 \SB@Error{Nested songs environments are not supported}{End th%
11875 e previous songs environment before beginning the next one.}%
11876 }
11877 % \end{macrocode}
11878 % \end{macro}
11879 %
11880 % \begin{macro}{\SB@errpl}
11881 % \begin{macrocode}
11882 \newcommand\SB@errpl{%
11883 \SB@Error{\protect\includeonlysongs\space not permitted with%
11884 in a songs environment}{\protect\includeonlysongs\space can o%
11885 nly be used in the document preamble or between songs environ%
11886 ments in the document body.}%
11887 }
11888 % \end{macrocode}
11889 % \end{macro}
11890 %
11891 % \begin{macro}{\SB@errrtopt}
11892 % \begin{macrocode}
11893 \newcommand\SB@errrtopt{%
11894 \SB@Error{Cannot display chords in a rawtext dump}{You have u%
11895 sed the rawtext option in the \protect\usepackage\space lin%
11896 e and have either used the chorded option as well or have use%
11897 d the \protect\chordson\space macro subsequently.}%
11898 }
11899 % \end{macrocode}
11900 % \end{macro}
11901 %
11902 % \begin{macro}{\SB@warnrc}
11903 % \begin{macrocode}
11904 \newcommand\SB@warnrc{%
11905 \SB@Warn{The \protect\repchoruses\space feature will not wor%
11906 k when the number of columns is set to zero}%
11907 }
11908 % \end{macrocode}
11909 % \end{macro}
11910 %
11911 % \begin{macro}{\SB@warnnoidx}
11912 % \begin{macrocode}
11913 \newcommand\SB@warnnoidx{%
11914 \SB@Warn{Index command has no effect since no indexes are ye%
11915 t declared}%
11916 }
11917 % \end{macrocode}
11918 % \end{macro}
11919 %
11920 % \begin{macro}{\SB@errboo}
11921 % \begin{macrocode}
11922 \newcommand\SB@errboo{%
11923 \SB@Error{Encountered \protect\beginsong\space without seein%
11924 g an \protect\endsong\space for the previous song}%
11925 {Song \thesongnum\space might be missing a%
11926 n \protect\endsong\space line.}%
11927 }
11928 % \end{macrocode}
11929 % \end{macro}
11930 %
11931 % \begin{macro}{\SB@errbor}
11932 % \begin{macrocode}
11933 \newcommand\SB@errbor{%
11934 \SB@Error{Encountered \protect\beginsong\space without seein%
11935 g an \protect\endscripture\space for the preceding scriptur%
11936 e quotation}{A scripture quotation appearing after son%
11937 g \thesongnum\space might be missing a%
11938 n \protect\endscripture\space line.}%
11939 }
11940 % \end{macrocode}
11941 % \end{macro}
11942 %
11943 % \begin{macro}{\SB@erreov}
11944 % \begin{macrocode}
11945 \newcommand\SB@erreov{%
11946 \SB@Error{Encountered \protect\endsong\space without seein%
11947 g an \protect\endverse\space for the preceding verse}{Son%
11948 g \thesongnum\space has a \protect\beginverse\space%
11949 line with no matching \protect\endverse\space line.}%
11950 }
11951 % \end{macrocode}
11952 % \end{macro}
11953 %
11954 % \begin{macro}{\SB@erreoc}
11955 % \begin{macrocode}
11956 \newcommand\SB@erreoc{%
11957 \SB@Error{Encountered \protect\endsong\space without seein%
11958 g an \protect\endchorus\space for the preceding chorus}{Son%
11959 g \thesongnum\space has a \protect\beginchorus\space%
11960 line with no matching \protect\endchorus\space line.}%
11961 }
11962 % \end{macrocode}
11963 % \end{macro}
11964 %
11965 % \begin{macro}{\SB@erreor}
11966 % \begin{macrocode}
11967 \newcommand\SB@erreor{%
11968 \SB@Error{Encountered \protect\endsong\space without seein%
11969 g an \protect\endscripture for the preceding scripture quot%
11970 e}{A scripture quote appearing before song \thesongnum\space%
11971 ended with \protect\endsong\space instead of wit%
11972 h \protect\endscripture.}%
11973 }
11974 % \end{macrocode}
11975 % \end{macro}
11976 %
11977 % \begin{macro}{\SB@erreot}
11978 % \begin{macrocode}
11979 \newcommand\SB@erreot{%
11980 \SB@Error{Encountered \protect\endsong\space with no matchin%
11981 g \protect\beginsong}{Before song \thesongnum\space there wa%
11982 s an \protect\endsong\space with no matchin%
11983 g \protect\beginsong.}%
11984 }
11985 % \end{macrocode}
11986 % \end{macro}
11987 %
11988 % \begin{macro}{\SB@errbvv}
11989 % \begin{macrocode}
11990 \newcommand\SB@errbvv{%
11991 \SB@Error{Encountered \protect\beginverse\space without seein%
11992 g an \protect\endverse\space for the preceding verse}{Son%
11993 g \thesongnum\space might have a verse that has n%
11994 o \protect\endendverse\space line.}%
11995 }
11996 % \end{macrocode}
11997 % \end{macro}
11998 %
11999 % \begin{macro}{\SB@errbvc}
12000 % \begin{macrocode}
12001 \newcommand\SB@errbvc{%
12002 \SB@Error{Encountered \protect\beginverse\space without seein%
12003 g an \protect\endchorus\space for the preceding chorus}{Son%
12004 g \thesongnum\space might have a chorus that has n%
12005 o \protect\endchorus\space line.}%
12006 }
12007 % \end{macrocode}
12008 % \end{macro}
12009 %
12010 % \begin{macro}{\SB@errbvt}
12011 % \begin{macrocode}
12012 \newcommand\SB@errbvt{%
12013 \SB@Error{Encountered \protect\beginverse\space without firs%
12014 t seeing a \protect\beginsong\space line}{Before son%
12015 g \thesongnum, there is a \protect\beginverse\space line no%
12016 t contained in any song.}%
12017 }
12018 % \end{macrocode}
12019 % \end{macro}
12020 %
12021 % \begin{macro}{\SB@errevc}
12022 % \begin{macrocode}
12023 \newcommand\SB@errevc{%
12024 \SB@Error{Encountered \protect\endverse\space while process%
12025 ing a chorus}{Song \thesongnum\space might hav%
12026 e a \protect\beginchorus\space concluded by a%
12027 n \protect\endverse\space instead of an \protect\endchorus.}%
12028 }
12029 % \end{macrocode}
12030 % \end{macro}
12031 %
12032 % \begin{macro}{\SB@errevo}
12033 % \begin{macrocode}
12034 \newcommand\SB@errevo{%
12035 \SB@Error{Encountered \protect\endverse\space without firs%
12036 t seeing a \protect\beginverse}{Song \thesongnum\space m%
12037 ight have an \protect\endverse\space with no matchin%
12038 g \protect\beginverse.}%
12039 }
12040 % \end{macrocode}
12041 % \end{macro}
12042 %
12043 % \begin{macro}{\SB@errevt}
12044 % \begin{macrocode}
12045 \newcommand\SB@errevt{%
12046 \SB@Error{Encountered an \protect\endverse\space outside o%
12047 f any song}{Before song \thesongnum, there is a%
12048 n \protect\endverse\space line not preceded b%
12049 y a \protect\beginsong\space line.}%
12050 }
12051 % \end{macrocode}
12052 % \end{macro}
12053 %
12054 % \begin{macro}{\SB@erretex}
12055 % \begin{macrocode}
12056 \newcommand\SB@erretex{%
12057 \SB@Error{The \protect\repchoruses\space feature requires e-%
12058 TeX compatibility}{Your version of LaTeX2e does not appear t%
12059 o be e-TeX compatible. Find a distribution that includes e-T%
12060 eX support in order to use this feature.}%
12061 }
12062 % \end{macrocode}
12063 % \end{macro}
12064 %
12065 % \begin{macro}{\SB@errbcv}
12066 % \begin{macrocode}
12067 \newcommand\SB@errbcv{%
12068 \SB@Error{Encountered \protect\beginchorus\space without see%
12069 ing an \protect\endverse\space for the preceding verse}{Son%
12070 g \thesongnum\space might hav%
12071 e a \protect\beginverse\space with no match%
12072 ing \protect\endverse.}%
12073 }
12074 % \end{macrocode}
12075 % \end{macro}
12076 %
12077 % \begin{macro}{\SB@errbcc}
12078 % \begin{macrocode}
12079 \newcommand\SB@errbcc{%
12080 \SB@Error{Encountered \protect\beginchorus\space without see%
12081 ing an \protect\endchorus\space for the preceding chorus}%
12082 {Song \thesongnum\space might have a \protect\beginchorus%
12083 \space with no matching \protect\endchorus.}%
12084 }
12085 % \end{macrocode}
12086 % \end{macro}
12087 %
12088 % \begin{macro}{\SB@errbct}
12089 % \begin{macrocode}
12090 \newcommand\SB@errbct{%
12091 \SB@Error{Encountered \protect\beginchorus\space without see%
12092 ing a \protect\beginsong\space line first}{After son%
12093 g \thesongnum\space there is a \protect\beginchorus\space%
12094 line outside of any song.}%
12095 }
12096 % \end{macrocode}
12097 % \end{macro}
12098 %
12099 % \begin{macro}{\SB@errecv}
12100 % \begin{macrocode}
12101 \newcommand\SB@errecv{%
12102 \SB@Error{Encountered an \protect\endchorus\space while proc%
12103 essing a verse}{Song \thesongnum\space might hav%
12104 e a \protect\beginverse\space concluded by \protect\endchorus%
12105 \space instead of \protect\endverse.}%
12106 }
12107 % \end{macrocode}
12108 % \end{macro}
12109 %
12110 % \begin{macro}{\SB@erreco}
12111 % \begin{macrocode}
12112 \newcommand\SB@erreco{%
12113 \SB@Error{Encountered \protect\endchorus\space without firs%
12114 t seeing a \protect\beginchorus}{Song \thesongnum\space m%
12115 ight have an \protect\endchorus\space with no match%
12116 ing \protect\beginchorus.}%
12117 }
12118 % \end{macrocode}
12119 % \end{macro}
12120 %
12121 % \begin{macro}{\SB@errect}
12122 % \begin{macrocode}
12123 \newcommand\SB@errect{%
12124 \SB@Error{Encountered an \protect\endchorus\space outside o%
12125 f any song}{Before song \thesongnum, there is a%
12126 n \protect\endchorus\space line not preceded b%
12127 y a \protect\beginsong\space line.}%
12128 }
12129 % \end{macrocode}
12130 % \end{macro}
12131 %
12132 % \begin{macro}{\SB@errbro}
12133 % \begin{macrocode}
12134 \newcommand\SB@errbro{%
12135 \SB@Error{Missing \protect\endsong}%
12136 {Nested song and intersong environments are not supported%
12137 . Song \thesongnum\space might be missing a%
12138 n \protect\endsong\space line.}%
12139 }
12140 % \end{macrocode}
12141 % \end{macro}
12142 %
12143 % \begin{macro}{\SB@errbrr}
12144 % \begin{macrocode}
12145 \newcommand\SB@errbrr{%
12146 \SB@Error{Nested intersong environments are not supported}%
12147 {A scripture quote or other intersong environment before s%
12148 ong \thesongnum\space is missing its ending line.}%
12149 }
12150 % \end{macrocode}
12151 % \end{macro}
12152 %
12153 % \begin{macro}{\SB@errero}
12154 % \begin{macrocode}
12155 \newcommand\SB@errero{%
12156 \SB@Error{Encountered an \protect\endscripture\space whil%
12157 e processing a song}{Song \thesongnum\space ends wit%
12158 h \protect\endscripture\space when it should end wit%
12159 h \protect\endsong.}%
12160 }
12161 % \end{macrocode}
12162 % \end{macro}
12163 %
12164 % \begin{macro}{\SB@errert}
12165 % \begin{macrocode}
12166 \newcommand\SB@errert{%
12167 \SB@Error{Encountered an \protect\endscripture\space with%
12168 out first seeing a \protect\beginscripture}{Before son%
12169 g \thesongnum, there is an \protect\endscripture\space w%
12170 ith no matching \protect\beginscripture.}%
12171 }
12172 % \end{macrocode}
12173 % \end{macro}
12174 %
12175 % \begin{macro}{\SB@errscrip}
12176 % \begin{macrocode}
12177 \newcommand\SB@errscrip[1]{%
12178 \SB@Error{Encountered a \protect#1\space outside a scriptu%
12179 re quote}{\protect#1\space can only appear betwee%
12180 n \protect\beginscripture\space an%
12181 d \protect\endscripture\space lines.}%
12182 }
12183 % \end{macrocode}
12184 % \end{macro}
12185 %
12186 % \begin{macro}{\SB@errchord}
12187 % \begin{macrocode}
12188 \newcommand\SB@errchord{%
12189 \SB@Error{Song \thesongnum\space seems to have chord%
12190 s that appear outside of any verse or chorus}{All chords a%
12191 nd lyrics should appear between \protect\beginverse\space%
12192 and \protect\endverse, or between \protect\beginchorus\space%
12193 and \protect\endchorus.}%
12194 }
12195 % \end{macrocode}
12196 % \end{macro}
12197 %
12198 % \begin{macro}{\SB@errreplay}
12199 % \begin{macrocode}
12200 \newcommand\SB@errreplay{%
12201 \SB@Error{Replayed chord has no matching chord}{Son%
12202 g \thesongnum\space uses \protect^ more times than the%
12203 re are chords in the previously memorized verse.}%
12204 }
12205 % \end{macrocode}
12206 % \end{macro}
12207 %
12208 % \begin{macro}{\SB@errreg}
12209 % \begin{macrocode}
12210 \newcommand\SB@errreg[1]{%
12211 \SB@Error{Unknown chord-replay register name: #1}{Chord-re%
12212 play registers must be declared with \protect\newchords.}%
12213 }
12214 % \end{macrocode}
12215 % \end{macro}
12216 %
12217 % \begin{macro}{\SB@errdup}
12218 % \begin{macrocode}
12219 \newcommand\SB@errdup[1]{%
12220 \SB@Error{Duplicate definition of chord-replay register%
12221 : #1}{\protect\newchords\space was used to declare the sa%
12222 me chord-replay register twice.}%
12223 }
12224 % \end{macrocode}
12225 % \end{macro}
12226 %
12227 % \begin{macro}{\SB@errmbar}
12228 % \begin{macrocode}
12229 \newcommand\SB@errmbar{%
12230 \SB@Error{Song \thesongnum\space seems to have measur%
12231 e bars that appear outside of any verse or chorus}{All mea%
12232 sure bars (produced with \protect\mbar\space or |) must ap%
12233 pear between \protect\beginverse\space an%
12234 d \protect\endverse, or between \protect\beginchorus\space%
12235 and \protect\endchorus.}%
12236 }
12237 % \end{macrocode}
12238 % \end{macro}
12239 %
12240 % \begin{macro}{\SB@errebar}
12241 % \begin{macrocode}
12242 \newcommand\SB@errebar[2]{%
12243 \SB@Error{Ignoring unbalanced \expandafter\@gobble\string#2 i%
12244 n \protect\gtab}{Found no \expandafter\@gobble\string#1 to ma%
12245 tch the \expandafter\@gobble\string#2.}%
12246 }
12247 % \end{macrocode}
12248 % \end{macro}
12249 %
12250 % \begin{macro}{\SB@errnoidx}
12251 % \begin{macrocode}
12252 \newcommand\SB@errnoidx[1]{%
12253 \SB@Error{Unknown index identifier: #1}{This index identifie%
12254 r was never declared using \protect\newindex.}%
12255 }
12256 % \end{macrocode}
12257 % \end{macro}
12258 %
12259 % \begin{macro}{\SB@erridx}
12260 % \begin{macrocode}
12261 \newcommand\SB@erridx[1]{%
12262 \SB@Error{\protect\idxaltentry\space not allowed in #1 index}%
12263 {This error should not occur. The index generation routines ha%
12264 ve malfunctioned. Try deleting all temporary files and then re%
12265 compiling.}%
12266 }
12267 % \end{macrocode}
12268 % \end{macro}
12269 %
12270 % \subsection{Option Processing}\label{sec:optproc}
12271 %
12272 % \begin{macro}{\ifchorded}
12273 % \begin{macro}{\iflyric}
12274 % \begin{macro}{\ifslides}
12275 % \begin{macro}{\ifmeasures}
12276 % \begin{macro}{\ifpartiallist}
12277 % \begin{macro}{\ifrepchorus}
12278 % \begin{macro}{\iftranscapos}
12279 % \begin{macro}{\ifnolyrics}
12280 % \begin{macro}{\ifrawtext}
12281 % \begin{macro}{\ifsongindexes}
12282 % \begin{macro}{\ifsepindexes}
12283 % \begin{macro}{\ifpagepreludes}
12284 % \begin{macro}{\ifSB@colorboxes}
12285 % \begin{macro}{\ifSB@omitscrip}
12286 % Reserve conditionals for all of the various option settings.
12287 % We wait to define these since if any are used earlier than this, it is
12288 % an error in the package code, and we'd rather get an error than continue.
12289 % \begin{macrocode}
12290 \newif\ifchorded
12291 \newif\iflyric\lyrictrue
12292 \newif\ifslides
12293 \newif\ifmeasures
12294 \newif\ifpartiallist
12295 \newif\ifrepchorus
12296 \newif\iftranscapos
12297 \newif\ifnolyrics
12298 \newif\ifrawtext
12299 \newif\ifsongindexes\songindexestrue
12300 \newif\ifsepindexes\sepindexestrue
12301 \newif\ifpagepreludes
12302 \newif\ifSB@colorboxes
12303 \IfFileExists{color.sty}\SB@colorboxestrue\SB@colorboxesfalse
12304 \newif\ifSB@omitscrip
12305 % \end{macrocode}
12306 % \end{macro}
12307 % \end{macro}
12308 % \end{macro}
12309 % \end{macro}
12310 % \end{macro}
12311 % \end{macro}
12312 % \end{macro}
12313 % \end{macro}
12314 % \end{macro}
12315 % \end{macro}
12316 % \end{macro}
12317 % \end{macro}
12318 % \end{macro}
12319 % \end{macro}
12320 %
12321 % \begin{macro}{\nolyrics}
12322 % \begin{macro}{\pagepreludes}
12323 % The |\nolyrics| and |\pagepreludes| macros are just shorthand for
12324 % |\nolyricstrue| and |\pagepreludestrue|, respectively.
12325 % \begin{macrocode}
12326 \newcommand\nolyrics{}
12327 \let\nolyrics\nolyricstrue
12328 \newcommand\pagepreludes{\pagepreludestrue\songpos0}
12329 % \end{macrocode}
12330 % \end{macro}
12331 % \end{macro}
12332 %
12333 % Finally we're ready to process all of the package options.
12334 % This is delayed until near the end because the option processing code
12335 % needs to execute various macros found in the previous sections.
12336 % \begin{macrocode}
12337 \SB@chordson
12338 \ProcessOptions\relax
12339 % \end{macrocode}
12340 %
12341 % \begin{macro}{\SB@colorbox}
12342 % Include the colors package and define colors, if requested.
12343 % \begin{macrocode}
12344 \ifSB@colorboxes
12345 \RequirePackage{color}
12346 \definecolor{SongbookShade}{gray}{.80}
12347 \newcommand\SB@colorbox[2]{%
12348 \ifx\@empty#1%
12349 \vbox{%
12350 \kern3\p@%
12351 \hbox{\kern3\p@{#2}\kern3\p@}%
12352 \kern3\p@%
12353 }%
12354 \else%
12355 \colorbox{#1}{#2}%
12356 \fi%
12357 }
12358 \else
12359 \newcommand\SB@colorbox[2]{\vbox{%
12360 \kern3\p@%
12361 \hbox{\kern3\p@{#2}\kern3\p@}%
12362 \kern3\p@%
12363 }}
12364 \fi
12365 % \end{macrocode}
12366 % \end{macro}
12367 %
12368 % \subsection{Rawtext Mode}
12369 %
12370 % If generating raw text, most of what has been defined previously is ignored
12371 % in favor of some very specialized macros that write all the song lyrics to
12372 % a text file.
12373 % \begin{macrocode}
12374 \ifrawtext
12375 \SB@newwrite\SB@txtout
12376 \immediate\openout\SB@txtout=\jobname.txt
12377 \newif\ifSB@doEOL
12378 {\catcode`\^^M12 %
12379 \catcode`\^^J12 %
12380 \gdef\SB@printEOL{\ifSB@doEOL^^M^^J\fi}}
12381 {\catcode`#12\gdef\SB@hash{#}}
12382 {\catcode`&12\gdef\SB@amp{&}}
12383 \renewcommand\SB@@@beginsong{%
12384 \begingroup%
12385 \def\'{}\def\`{}\def\v{}\def\u{}\def\={}\def\^{}%
12386 \def\.{}\def\H{}\def\~{}\def\"{}\def\t{}%
12387 \def\copyright{(c)}%
12388 \let~\space%
12389 \let\par\SB@printEOL%
12390 \let\#\SB@hash%
12391 \let\&\SB@amp%
12392 \catcode`|9 %
12393 \catcode`*9 %
12394 \catcode`^9 %
12395 \def\[##1]{}%
12396 \resettitles%
12397 \immediate\write\SB@txtout{\thesongnum. \songtitle}%
12398 \nexttitle%
12399 \foreachtitle{\immediate\write\SB@txtout{(\songtitle)}}%
12400 \ifx\songauthors\@empty\else%
12401 \immediate\write\SB@txtout{\songauthors}%
12402 \fi%
12403 \ifx\SB@rawrefs\@empty\else%
12404 \immediate\write\SB@txtout{\SB@rawrefs}%
12405 \fi%
12406 \immediate\write\SB@txtout{}%
12407 \SB@doEOLfalse%
12408 \obeylines%
12409 }
12410 \renewcommand\SB@endsong{%
12411 \SB@doEOLtrue%
12412 \immediate\write\SB@txtout{\songcopyright\space%
12413 \songlicense\SB@printEOL}%
12414 \endgroup%
12415 \SB@insongfalse%
12416 \stepcounter{songnum}%
12417 }
12418 \def\SB@parsesrefs#1{\def\songrefs{#1}}
12419 \long\def\beginverse#1#2\endverse{%
12420 \SB@doEOLtrue\begingroup%
12421 \def\textnote##1{##1}%
12422 \def\SB@temp{#1}%
12423 \def\SB@star{*}%
12424 \ifx\SB@temp\SB@star%
12425 \immediate\write\SB@txtout{\@gobble#2}%
12426 \else%
12427 \immediate\write\SB@txtout{#2}%
12428 \fi%
12429 \endgroup\SB@doEOLfalse}
12430 \long\def\beginchorus#1\endchorus{%
12431 \SB@doEOLtrue\begingroup%
12432 \def\textnote##1{##1}%
12433 \immediate\write\SB@txtout{Chorus:#1}%
12434 \endgroup\SB@doEOLfalse}
12435 \long\def\beginscripture#1\endscripture{}
12436 \def\musicnote#1{}
12437 \def\textnote#1{%
12438 \SB@doEOLtrue%
12439 \immediate\write\SB@txtout{#1\SB@printEOL}%
12440 \SB@doEOLfalse}
12441 \def\brk{}
12442 \def\rep#1{(x#1)}
12443 \def\echo#1{(#1)}
12444 \def\mbar#1#2{}
12445 \def\lrep{}
12446 \def\rrep{}
12447 \def\nolyrics{}
12448 \renewcommand\memorize[1][]{}
12449 \renewcommand\replay[1][]{}
12450 \fi
12451 % \end{macrocode}
12452 %
12453 % \Finale
12454 \endinput
12455