| 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}|}|©right 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 |
|