summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/songs/songs.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/songs/songs.dtx')
-rw-r--r--Master/texmf-dist/source/latex/songs/songs.dtx3210
1 files changed, 1789 insertions, 1421 deletions
diff --git a/Master/texmf-dist/source/latex/songs/songs.dtx b/Master/texmf-dist/source/latex/songs/songs.dtx
index d2ef70a9d26..bb244a631ad 100644
--- a/Master/texmf-dist/source/latex/songs/songs.dtx
+++ b/Master/texmf-dist/source/latex/songs/songs.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 2012 Kevin W. Hamlen
+% Copyright (C) 2017 Kevin W. Hamlen
%
% This program is free software; you can redistribute it and/or
% modify it under the terms of the GNU General Public License
@@ -14,8 +14,8 @@
%
% You should have received a copy of the GNU General Public License
% along with this program; if not, write to the Free Software
-% Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
-% MA 02110-1301, USA.
+% Foundation, Inc., 51 Franklin Street, 5th Floor, Boston,
+% MA 02110-1301, USA.
%
% The latest version of this program can be obtained from
% http://songs.sourceforge.net.
@@ -29,99 +29,161 @@
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{songs}
%<*package>
- [2012/03/17 v2.14 Songs package]
+ [2017/06/05 v3.0 Songs package]
%</package>
%
%<*driver>
\documentclass{ltxdoc}
-\usepackage[bookmarks]{hyperref}
+
+% This documentation compiles as part of the Songs self-installer, so it
+% needs to work even on tiny LaTeX installations with few packages. We
+% therefore try to be especially robust to missing package failures.
+\newcommand\trypackage[4][]{\IfFileExists{#2.sty}{\usepackage[#1]{#2}#3}{#4}}
+\trypackage{microtype}{\linepenalty=20 \parfillskip=0pt plus\textwidth\relax}{}
+\trypackage{lmodern}{\usepackage[T1]{fontenc}}{}
+\trypackage{ifpdf}{}{\expandafter\newif\csname ifpdf\endcsname\pdffalse}
+\trypackage{color}{}{}
+\ifpdf
+ \trypackage[bookmarks,linkbordercolor={.6 0 0}]{hyperref}{}{}
+\fi
\usepackage[nopdfindex]{songs}
-\let\oldSE\StopEventually
+
+% Provide back-up hyperlinking and color macros that do nothing,
+% in case the hyperref and/or color packages are absent.
+\providecommand\href[2]{#2}
+\providecommand\url[1]{#1}
+\providecommand\pdfbookmark[3][]{}
+\providecommand\hyperdef[3]{}
+\providecommand\hyperlink[2]{#2}
+\providecommand\texorpdfstring[2]{#1}
+\providecommand\definecolor[3]{}
+\providecommand\color[1]{}
+\providecommand\textcolor[2]{#2}
+\providecommand\microtypesetup[1]{}
% Configure the document:
+\let\oldSE\StopEventually
\EnableCrossrefs
\CodelineIndex
\RecordChanges
%\OnlyDescription
-% Create the \Songs logo, if appropriate fonts are available:
-\IfFileExists{harmony.sty}{
- \usepackage{harmony}
- \usepackage{graphics}
- \newcommand\Songs{\texorpdfstring{{\sffamily s\kern.07ex\resizebox{!}{1ex}{\Ganz}\kern-.09ex ngs}}{songs}}
-}{
- \newcommand\Songs{\texorpdfstring{{\sffamily songs}}{songs}}
-}
+% Create the \Songs logo, if the musix13 font is available:
+\newcommand\Songs{\texorpdfstring{{\sffamily songs}}{songs}}
+\newcount\imode
+\imode=\interactionmode
+\batchmode
+\newfont\musicfont{musix13}
+\interactionmode=\imode
+\ifx\musicfont\nullfont\else
+ \newdimen\msize
+ \newcommand\wholenote{%
+ \msize4ex
+ \expandafter\ifx\csname musicfont\the\msize\endcsname\relax
+ \expandafter\newfont\csname musicfont\the\msize\endcsname
+ {musix13 at \the\msize}%
+ \fi
+ \kern.13ex
+ \raise.5ex\hbox{{\csname musicfont\the\msize\endcsname\symbol9}}%
+ \kern1.53ex
+ }
+ \renewcommand\Songs{\texorpdfstring{{\sffamily s\wholenote ngs}}{songs}}
+\fi
% Create the logo for Christopher Rath's Songbook package:
\newcommand{\Rath}{{\sffamily Song$\flat$ook}}
+% Colors
+\definecolor{myred}{rgb}{0.6,0,0}
+\definecolor{myblu}{rgb}{0,0,0.6}
+\definecolor{mygra}{gray}{0.33}
+\def\PrintDescribeMacro#1{\strut{\MacroFont\color{myred}\string#1}\ }
+\let\PrintMacroName\PrintDescribeMacro
+\def\PrintDescribeEnv#1{\strut{\MacroFont\color{myred}#1}\ }
+\let\PrintEnvName\PrintDescribeEnv
+{\makeatletter\gdef\verbatim@font{\normalfont\color{myblu}\ttfamily}}
+
+% For some reason, doc.sty removes the \verbatim@font customization hook
+% for \verb|...|. (Why??) That's not nice, so we put it back:
+{\makeatletter
+ \gdef\verb {\relax\ifmmode\hbox\else\leavevmode\null\fi
+ \bgroup \let\do\do@noligs \verbatim@nolig@list
+ \verbatim@font \verb@eol@error \let\do\@makeother \dospecials
+ \@ifstar{\@sverb}{\@vobeyspaces \frenchspacing \@sverb}}
+}
+
% Define some environments to simulate the interior of a verse,
% for showing samples in the documentation:
{\makeatletter
\gdef\likeverse{%
- \SB@insongtrue\SB@inversetrue%
- \SB@loadactives%
- \global\SB@ctail\SB@cr@%
+ \SB@insongtrue\SB@inversetrue
+ \SB@loadactives
+ \global\SB@ctail\SB@cr@
}
\gdef\chordheight{\SB@setbaselineskip}
}
% Typeset a block of LaTeX code:
+\newcommand\pfs{\parfillskip0pt plus1fil\relax}
\newenvironment{codeblock}{%
- \medskip%
- \vbox\bgroup\begingroup%
- \narrower\rightskip=0pt plus1fil%
- \parindent=0pt%
- \obeylines%
+ \medskip
+ \begingroup
+ \ifdim\parindent=0pt \parindent=20pt\fi
+ \indent\vbox\bgroup
+ \hsize\linewidth
+ \advance\hsize-\parindent
+ \rightskip=0pt plus1fil\pfs
+ \parindent=0pt
+ \color{myblu}%
+ \obeylines
}{%
- \endgroup\egroup%
- \medskip%
+ \egroup\endgroup
+ \medskip
}
% Typeset a sample song or scripture quotation:
\songcolumns{0}
\newenvironment{sample}{%
- \medskip%
- \noindent\hfil%
- \vbox\bgroup%
- \hsize.5\hsize%
- \advance\hsize-.5\columnsep%
- \versesep=5pt%
+ \medskip
+ \noindent\hfil
+ \vbox\bgroup
+ \hsize.5\hsize
+ \advance\hsize-.5\columnsep
+ \versesep=5pt
+ \pfs
}{%
- \egroup%
- \medskip%
+ \egroup{\pfs\par}\medskip
}
% Typeset a sample lyric book fragment:
\newenvironment{lyrics}{%
- \medskip%
- \noindent\hfil%
- \vbox\bgroup\begingroup%
- \hsize=.7\textwidth%
- \leftskip=20pt\rightskip=0pt plus1fil%
- \parindent=-20pt%
- \likeverse\obeylines%
+ \medskip
+ \noindent\hfil
+ \vbox\bgroup\begingroup
+ \hsize=.7\textwidth
+ \leftskip=20pt\rightskip=0pt plus1fil\pfs
+ \parindent=-20pt
+ \likeverse\obeylines
}{%
- \par\endgroup\egroup%
- \hfil\par%
- \medskip%
+ \par\endgroup\egroup
+ \hfil{\pfs\par}
+ \medskip
}
% Typeset a sample chord book fragment:
\newenvironment{chorded}{%
- \medskip%
- \noindent\hfil%
- \vbox\bgroup\begingroup%
- \hsize=.7\textwidth%
- \leftskip=20pt\rightskip=0pt plus1fil%
- \parindent=-20pt%
- \likeverse\obeylines%
- \versesep=5pt\chordheight%
+ \medskip
+ \noindent\hfil
+ \vbox\bgroup\begingroup
+ \hsize=.7\textwidth
+ \leftskip=20pt\rightskip=0pt plus1fil\pfs
+ \parindent=-20pt
+ \likeverse\obeylines
+ \versesep=5pt\chordheight
}{%
- \par\endgroup\egroup%
- \hfil\par%
- \medskip%
+ \par\endgroup\egroup
+ \hfil{\pfs\par}
+ \medskip
}
% Typeset a "<code> produces <text>" example:
@@ -129,103 +191,107 @@
\setlength{\prodlen}{2.7in}
\newbox\prodbox
\newcommand{\example}{%
- \medskip\setbox\prodbox\hbox\bgroup%
+ \medskip\setbox\prodbox\hbox\bgroup\begingroup\color{myblu}%
}
\newcommand{\produces}{%
- \egroup%
- \indent%
- \vbox{\hbox to\prodlen{\unhbox\prodbox\hfil}}%
- \ {\it produces}\quad%
- \afterassignment\prodprefix%
- \setbox\prodbox\hbox}
+ \endgroup\egroup
+ \indent
+ \vbox{\hbox to\prodlen{\unhbox\prodbox\hfil}}
+ \ {\it produces}\quad
+ \afterassignment\prodprefix
+ \setbox\prodbox\hbox
+}
\newcommand{\prodprefix}{%
- \likeverse\chordheight%
- \aftergroup\prodsuffix}
-\newcommand{\prodsuffix}{\unhbox\prodbox\par\medskip}
+ \likeverse\chordheight
+ \aftergroup\prodsuffix
+}
+\newcommand{\prodsuffix}{\unhbox\prodbox{\pfs\par}\medskip}
\newbox\vcbox
\newdimen\vcadjust
\newcommand{\vcenterbox}[1]{%
\setbox\vcbox\vbox{\hbox{#1}}%
- \vcadjust=.5\ht\vcbox%
- \advance\vcadjust by-6pt%
- \lower\vcadjust\box\vcbox%
+ \vcadjust=.5\ht\vcbox
+ \advance\vcadjust by-6pt
+ \lower\vcadjust\box\vcbox
}
% Recode \DescribeMacro and \DescribeEnv to make nice pdfbookmark entries.
% Also create some \MainImpl macros that make pdfbookmarks to help the reader
% find the "real" implementations of important macros.
-\newcount\seclevel%
-\newcommand{\getseclevel}{%
- \ifnum\value{subsection}=0 \seclevel=2 %
- \else\ifnum\value{subsubsection}=0 \seclevel=3 %
- \else\seclevel=4 \fi\fi%
+\newcount\seclevel
+\newcommand\mybookmark[2]{%
+ \ifnum\value{subsection}=0 \seclevel=2
+ \else\ifnum\value{subsubsection}=0 \seclevel=3
+ \else\seclevel=4 \fi\fi
+ \setcounter{tocdepth}{4}%
+ \pdfbookmark[\the\seclevel]{#1}{#2}%
+ \setcounter{tocdepth}{3}%
}
{\makeatletter
\xdef\bschar{\@backslashchar}
\global\let\For\@for}
\newcommand\DescMacro[1]{%
- \getseclevel%
- \pdfbookmark[\the\seclevel]{\bschar\bschar#1}{macdef-#1}%
+ \ifhmode\unskip\fi
+ \mybookmark{\bschar\bschar#1}{macdef-#1}%
\expandafter\DescribeMacro\expandafter{\csname#1\endcsname}%
- \hyperdef{macro}{#1}{}\kern0pt%
+ \hyperdef{macro}{#1}{}\unpenalty
+ \ignorespaces
}
\newcommand\DescMacroGroup[3]{%
- \getseclevel%
- \pdfbookmark[\the\seclevel]{\bschar\bschar#2}{macdef-#1}%
+ \ifhmode\unskip\fi
+ \mybookmark{\bschar\bschar#2}{macdef-#1}%
\expandafter\DescribeMacro\expandafter{\csname#2\endcsname}%
- \For\temp:=#3\do{\hyperdef{macro}{\temp}{}}%
+ \For\temp:=#3\do{\hyperdef{macro}{\temp}{}}\unpenalty
+ \ignorespaces
}
\newcommand\MainImpl[1]{%
\pdfbookmark[3]{\bschar\bschar#1}{mimpl-#1}%
}
\newcommand{\DescEnv}[1]{%
- \getseclevel%
- \pdfbookmark[\the\seclevel]{#1}{envdef-#1}%
+ \ifhmode\unskip\fi
+ \mybookmark{#1}{envdef-#1}%
\DescribeEnv{#1}%
- \hyperdef{env}{#1}{}\kern0pt%
+ \hyperdef{env}{#1}{}\unpenalty
+ \ignorespaces
}
\newcommand{\MainEnvImpl}[1]{%
- \getseclevel%
- \pdfbookmark[\the\seclevel]{#1}{eimpl-#1}%
+ \mybookmark{#1}{eimpl-#1}%
}
% Create macros to hyperlink macro and environment names to their
% documentation points.
-\newcommand{\mac}[1]{{\tt\hyperlink{macro.#1}{\char92 #1}}}
-\newcommand{\env}[1]{{\tt\hyperlink{env.#1}{#1}}}
+\newcommand{\mac}[1]{{\tt\hyperlink{macro.#1}{\textcolor{myblu}{\char92 #1}}}}
+\newcommand{\env}[1]{{\tt\hyperlink{env.#1}{\textcolor{myblu}{#1}}}}
% Defining bookmarks for definitions of active characters is a little trickier
% because many of these characters have special meanings either to TeX or to
% PDF. The only reliable way is to insert an "\ooo" escape sequence into the
% bookmark text, where ooo is the ascii number of the character expressed in
% octal. To achieve this, we use `\string<symbol> to obtain the decimal
-% ascii number d of the symbol, then do some math (implemented in \octalize)
-% to compute the decimal number n whose digits correspond to the octal
-% representation of d, and then write n to the bookmark text using \the.
+% ascii number d of the symbol, then do some math (implemented in \octal)
+% to compute and tokenize each octal digit of d into the bookmark text.
\newcount\cnta
\newcount\cntb
-\newcount\cntc
-\newcommand{\octalize}[2]{%
+\newcommand\ooo{}
+\newcommand\octal{%
\cntb\cnta
- \divide\cntb#1
- \multiply\cntb#2
- \advance\cntc\cntb
- \divide\cntb#2
- \multiply\cntb#1
- \advance\cnta-\cntb
+ \divide\cnta8
+ \multiply\cnta-8
+ \advance\cntb\cnta
+ \edef\ooo{\the\cntb\ooo}%
+ \divide\cnta-8
}
\newcommand{\DescChar}[2]{%
+ \ifhmode\unskip\fi
\expandafter\let\csname string#1\expandafter\endcsname
\expandafter=\string#2%
- \getseclevel
\cnta\expandafter`\string#2%
- \cntc0
- \octalize{64}{100}%
- \octalize{8}{10}%
- \octalize{1}{1}%
- \pdfbookmark[\the\seclevel]{\bschar\the\cntc}{#1def}%
- \expandafter\DescribeEnv\string#2%
- \hyperdef{env}{#1}{}\kern0pt%
+ \def\ooo{}\octal\octal\octal
+ \mybookmark{\bschar\ooo}{#1def}%
+ {\def\SpecialUsageIndex##1{}%
+ \expandafter\DescribeMacro\string#2}%
+ \hyperdef{env}{#1}{}\unpenalty
+ \ignorespaces
}
\newcommand{\refchar}[1]{{\tt\hyperlink{env.#1}{\csname string#1\endcsname}}}
@@ -236,8 +302,8 @@
\IndexPrologue{%
\subsection{Codeline Index}%
- Numbers underlined refer to the code line where the corresponding entry
- is defined; numbers in roman refer to the code lines where the entry
+ Underlined numbers refer to the code line where the corresponding entry
+ is defined; other numbers refer to the code lines where the entry
is used.}
{\makeatletter
@@ -251,6 +317,7 @@
\mathsurround0pt
\parfillskip0pt
\small
+ \microtypesetup{protrusion=false}%
\def\@idxitem{\par\hangindent15pt}%
\def\subitem{\@idxitem\hspace*{15pt}}%
\def\subsubitem{\@idxitem\hspace*{25pt}}%
@@ -269,21 +336,21 @@
% Create a conditional that typesets its first argument if we're including
% the implementation section, otherwise typesets its second argument.
\newcommand\ImplOrDesc[2]{%
- \ifx\StopEventually\oldSE#1\else#2\fi%
+ \ifx\StopEventually\oldSE#1\else#2\fi
}
% Hyphenating the word "choruses" looks weird. No "ruses" please!
-\hyphenation{choruses}
+\hyphenation{choruses white-space}
% An environment for describing the implementation of a package option:
\let\oldsmei\SpecialMainEnvIndex
\newenvironment{option}[1]{%
- \let\SpecialMainEnvIndex\SpecialMainOptIndex%
+ \let\SpecialMainEnvIndex\SpecialMainOptIndex
\begin{environment}{#1}%
- \let\SpecialMainEnvIndex\oldsmei%
+ \let\SpecialMainEnvIndex\oldsmei
}{%
\end{environment}%
- \let\SpecialMainEnvIndex\oldsmei%
+ \let\SpecialMainEnvIndex\oldsmei
}
% Describe the default setting for an option:
@@ -293,8 +360,9 @@
\newcommand{\chord}[1]{{\sffamily\slshape#1}}
% Here are a few macros to produce nice syntax parameters:
-\newcommand{\argp}[1]{\meta{arg#1}}
-\newcommand\Meta[1]{\textrm{\meta{#1}}}
+\newcommand\Meta[1]{{\color{mygra}\meta{#1}}}
+\newcommand\argp[1]{\Meta{arg#1}}
+\newcommand\Metarm[1]{\textrm{\Meta{#1}}}
\newcommand\OR{\,$\mid$\,}
\newcommand\SPC{\char`\ }
@@ -303,9 +371,9 @@
\global\let\oldamp=\@addmarginpar
\global\let\oldlwnl=\@latex@warning@no@line
\gdef\@addmarginpar{%
- \let\@latex@warning@no@line\@gobble%
- \oldamp%
- \let\@latex@warning@no@line\oldlwnl%
+ \let\@latex@warning@no@line\@gobble
+ \oldamp
+ \let\@latex@warning@no@line\oldlwnl
}
}
@@ -319,7 +387,7 @@
%</driver>
% \fi
%
-% \CheckSum{8597}
+% \CheckSum{8792}
%
% \CharacterTable
% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
@@ -359,12 +427,11 @@
% \DoNotIndex{\hfil,\hfilneg,\hskip,\hss,\indent,\kern,\nobreak,\noindent,\nointerlineskip,\offinterlineskip,\par,\penalty,\strut,\thinspace,\vadjust,\vfil,\vfilneg,\vphantom,\vskip}
% \DoNotIndex{\@octets,\four,\three,\two,\UTFviii@,\UTFviii@zero@octets,\0,\1,\2,\3,\4,\5,\6,\7,\8,\9,\X,\O}
%
-%
% \GetFileInfo{songs.dtx}
%
-% \title{The \Songs\ package\thanks{This document corresponds to
+% \title{The \Songs{} package\thanks{This manual documents
% \textsf{songs}~\fileversion, dated~\filedate,
-% \copyright~2012 Kevin W.~Hamlen, and
+% \copyright~2017 Kevin W.~Hamlen, and
% distributed under version~2 the GNU General Public License
% as published by the Free Software Foundation.}}
% \author{Kevin W. Hamlen}
@@ -372,10 +439,10 @@
% \maketitle
%
% \begin{abstract}
-% The \Songs\ package produces songbooks that contain lyrics and chords
+% The \Songs{} package produces songbooks that contain lyrics and chords
% (but not full sheet music).
% It allows lyric books, chord books, overhead slides, and digital projector
-% slides to all be maintained and generated from a single \LaTeX\ source
+% slides to all be maintained and generated from a single \LaTeX{} source
% document.
% Automatic transposition, guitar tablature diagrams, handouts, and
% a variety of specialized song indexes are supported.
@@ -383,14 +450,14 @@
%
% \section{Introduction}
%
-% The \Songs\ \LaTeX\ package produces books of songs that contain lyrics and
+% The \Songs{} \LaTeX{} package produces books of songs that contain lyrics and
% (optionally) chords.
% A single source document yields a lyric book for singers, a chord book for
% musicians, and overhead or digital projector slides for corporate singing.
%
% The software is especially well suited for churches and religious
% fellowships desiring to create their own books of worship songs.
-% Rather than purchasing a fixed hymnal of songs, the \Songs\ package allows
+% Rather than purchasing a fixed hymnal of songs, the \Songs{} package allows
% worship coordinators to maintain a constantly evolving repertoire of music
% to which they can add and remove songs over time.
% As the book content changes, the indexes, spacing, and other formatting
@@ -402,7 +469,7 @@
% \section{Terms of Use}
%
% \noindent
-% The \Songs\ package is free software; you can redistribute it and/or
+% The \Songs{} package is free software; you can redistribute it and/or
% modify it under the terms of the GNU General Public License
% as published by the Free Software Foundation; either version~2
% of the License, or (at your option) any later version.
@@ -414,15 +481,15 @@
% This program is distributed in the hope that it will be useful,
% but {\sc without any warranty}; without even the implied warranty of
% {\sc merchantability} or {\sc fitness for a particular purpose}. See the
-% GNU General Public License in \S\ref{sec:license} for more details.
+% GNU General Public License in \S\ref{sec:license} for details.
% A copy of the license can also be obtained by writing to the
-% Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
-% Boston, MA 02110-1301, USA.
+% Free Software Foundation, Inc., 51 Franklin Street, 5th Floor,
+% Boston, MA 02110-1301, USA.
%
% \medskip
%
% \noindent
-% This software is copyright \copyright~2012 Kevin W.~Hamlen.
+% This software is copyright \copyright~2017 Kevin W.~Hamlen.
% For contact information or the latest version, see the project webpage at:
%
% \vskip1.5ex
@@ -434,27 +501,26 @@
%
% For those who would like to start making song books quickly, the
% following is a sample document that yields a simple song book with
-% one song and one title index.
+% one song.
% Starting from this template, you can begin to add songs and customizations
% to create a larger book.
% Instructions for compiling this sample song book follow the listing.
%
+% \begingroup\color{myblu}
% \begin{verbatim}
% \documentclass{article}
% \usepackage[chorded]{songs}
%
-% \newindex{titleidx}{titleidx}
% \noversenumbers
%
% \begin{document}
-% \showindex{Complete Index of Songs}{titleidx}
+%
% \songsection{Worship Songs}
%
-% \begin{songs}{titleidx}
+% \begin{songs}{}
% \beginsong{Doxology}[by={Louis Bourgeois and Thomas Ken},
% sr={Revelation 5:13},
-% cr={Public domain.},
-% index={Praise God, from Whom all blessings flow}]
+% cr={Public domain.}]
% \beginverse
% \[G]Praise God, \[D]from \[Em]Whom \[Bm]all \[Em]bless\[D]ings \[G]flow;
% \[G]Praise Him, all \[D]crea\[Em]tures \[C]here \[G]be\[D]low;
@@ -467,9 +533,9 @@
%
% \end{document}
% \end{verbatim}
+% \endgroup\nointerlineskip\vskip-6pt plus0pt minus0pt
%
-% To compile this book, execute three commands.
-% First, use \LaTeX\ (|pdflatex| is recommended) to compile the document:
+% To compile this book, run \LaTeX{} (|pdflatex| is recommended):
%
% \begin{codeblock}
% |pdflatex mybook.tex|
@@ -477,25 +543,12 @@
%
% \noindent
% (where |mybook.tex| is the name of the source document above).
-% Next, use the |songidx| program provided with this distribution to
-% generate the indexes:
-%
-% \begin{codeblock}
-% |songidx titleidx.sxd titleidx.sbx|
-% \end{codeblock}
-%
-% \noindent
-% Finally, regenerate the document using \LaTeX\ so that the newly
-% generated index data will be included:
-%
-% \begin{codeblock}
-% |pdflatex mybook.tex|
-% \end{codeblock}
-%
-% \noindent
% The final document is named |mybook.pdf| if you use |pdflatex| or
% |mybook.dvi| if you use regular |latex|.
%
+% Note that compiling a document that includes indexes requires extra steps.
+% See \S\ref{sec:compiling} for details.
+%
% \begin{figure}
% \noindent\vbox{\begingroup\hsize=352pt
% \versesep=12pt\columnsep=7pt\parindent=20pt
@@ -579,34 +632,35 @@
%
% \section{Initialization and Options}\label{sec:options}
%
-% Each \LaTeX\ document that uses the \Songs\ package should contain a
+% Each \LaTeX{} document that uses the \Songs{} package should contain a
% line like the following near the top of the document:
%
% \begin{codeblock}
-% |\usepackage[|\meta{options}|]{songs}|
+% |\usepackage[|\Meta{options}|]{songs}|
% \end{codeblock}
%
% \noindent
-% Supported \meta{options} include the following:
+% Supported \Meta{options} include the following:
%
% \paragraph{Output Type.}
% \DescEnv{lyric}
% \DescEnv{chorded}
% \DescEnv{slides}
% \DescEnv{rawtext}
-% The \Songs\ package can produce four kinds of books: lyric books, chord
+% The \Songs{} package can produce four kinds of books: lyric books, chord
% books, books of overhead slides, and raw text output.
% You can specify which kind of book is to be produced by specifying one of
% |lyric|, |chorded|, |slides|, or |rawtext| as an option.
-% If none of these are specified, |chorded| is the default.
+% The |slides| and |chorded| options can be used together to create chorded
+% slides.
+% If no output options are specified, |chorded| is the default.
%
% Lyric books omit all chords, whereas chord books include chords and
% additional information for musicians (specified using \mac{musicnote}).
-% Books of overhead slides omit all chords and typeset
-% one song per page in a large font, centered.
+% Books of overhead slides typeset one song per page in a large font, centered.
%
-% Raw text output yields an ascii text file named \meta{jobname}|.txt|
-% (where \meta{jobname} is the root filename) containing lyrics without chords.
+% Raw text output yields an ascii text file named \Meta{jobname}|.txt|
+% (where \Meta{jobname} is the root filename) containing lyrics without chords.
% This can be useful for importing song books into another program, such as a
% spell-checker.
%
@@ -626,7 +680,7 @@
% \DescEnv{showmeasures}
% \DescMacro{measureson}
% \DescMacro{measuresoff}
-% The \Songs\ package includes a facility for placing measure bars in chord
+% The \Songs{} package includes a facility for placing measure bars in chord
% books (see \S\ref{sec:measures}).
% To omit these measure bars, use the |nomeasures| option;
% to display them, use the |showmeasures| option (the default).
@@ -636,14 +690,14 @@
% \paragraph{Transposition.}
% \DescEnv{transposecapos}
% The |transposecapos| option changes the effect of the \mac{capo} macro.
-% Normally, using |\capo{|\meta{n}|}| within a song environment produces a
+% Normally, using |\capo{|\Meta{n}|}| within a song environment produces a
% textual note in chord books that suggests the use of a guitar capo on fret
-% \meta{n}.
+% \Meta{n}.
% However, when the |transposecapos| option is active, these textual notes
-% are omitted and instead the effect of |\capo{|\meta{n}|}| is the
-% same as for \mac{transpose}|{|\meta{n}|}|.
+% are omitted and instead the effect of |\capo{|\Meta{n}|}| is the
+% same as for \mac{transpose}|{|\Meta{n}|}|.
% That is, chords between the \mac{capo} macro and the end of the song are
-% automatically transposed up by \meta{n} half-steps.
+% automatically transposed up by \Meta{n} half-steps.
% This can be useful for adapting a chord book for guitarists to one that can
% be used by pianists, who don't have the luxury of capos.
% See \S\ref{sec:notes} and \S\ref{sec:transpose} for more information on the
@@ -658,9 +712,9 @@
% |\indexesoff| macros.
%
% \DescEnv{nopdfindex}
-% The |nopdfindex| option suppresses the creation of the pdf bookmark index
-% that is normally included in |.pdf| files.
-% If not generating a |.pdf| file, this option has no effect.
+% PDF bookmark entries and hyperlinks can be suppressed with the |nopdfindex|
+% option.
+% For finer control of PDF indexes, see \S\ref{sec:idxcust}.
%
% \paragraph{Scripture Quotations.}
% \DescEnv{noscripture}
@@ -683,9 +737,9 @@
% Often it is useful to be able to extract a subset of songs from the master
% document---e.g.~to create a handout or set of overhead slides for a specific
% worship service.
-% To do this, you can type |\includeonlysongs{|\meta{songlist}|}| in the
+% To do this, you can type |\includeonlysongs{|\Meta{songlist}|}| in the
% document preamble (i.e., before the |\begin{document}| line), where
-% \meta{songlist} is a comma-separated list of the song numbers to include.
+% \Meta{songlist} is a comma-separated list of the song numbers to include.
% For example,
%
% \begin{codeblock}
@@ -701,142 +755,13 @@
% between songs unless they are followed by a star (e.g., \mac{nextcol}|*|).
% To force a column- or page-break at a specific point in a partial book,
% add the word |nextcol|, |brk|, |sclearpage|, or |scleardpage| at the
-% corresponding point in the \meta{songlist}.
+% corresponding point in the \Meta{songlist}.
%
% The |\includeonlysongs| macro only reorders songs within each
% \env{songs} environment (see \S\ref{sec:songs}), not between different
% \env{songs} environments.
% It also cannot be used in conjunction with the \env{rawtext} option.
%
-% \section{Book Sections}\label{sec:sections}
-%
-% \paragraph{Section Titles.}
-% \DescMacro{songsection}
-% \DescMacro{songchapter}
-% Section titles in a song book can be produced with
-%
-% \begin{codeblock}
-% |\songsection{|\meta{title}|}|
-% \end{codeblock}
-%
-% \noindent
-% which acts like \LaTeX's |\section| command except that it centers
-% the \meta{title} text in sans serif font and omits the section number.
-% When using the |book| document class, use |\songchapter|
-% instead of |\songsection|.
-%
-% \paragraph{Indexes.}
-% \DescMacro{newindex}
-% \DescMacro{newauthorindex}
-% \DescMacro{newscripindex}
-% The \Songs\ package supports three kinds of indexes: indexes by title and/or
-% notable lyrics, indexes by author, and indexes by scripture reference.
-% To generate an index, first declare the index in the document preamble
-% (i.e., before the |\begin{document}| line) with one of the following:
-%
-% \begin{codeblock}
-% |\newindex{|\meta{id}|}{|\meta{filename}|}|
-% |\newauthorindex{|\meta{id}|}{|\meta{filename}|}|
-% |\newscripindex{|\meta{id}|}{|\meta{filename}|}|
-% \end{codeblock}
-%
-% \noindent
-% The \meta{id} should be an alphabetic identifier that will be used to
-% identify the index in other macros that reference it.
-% The \meta{filename} should be a string that, when appended with an
-% extension, constitutes a valid filename on the system.
-% Auxiliary files named \meta{filename}|.sxd| and \meta{filename}|.sbx|
-% are generated during the automatic index generation process.
-% For example:
-%
-% \begin{codeblock}
-% |\newindex{mainindex}{idxfile}|
-% \end{codeblock}
-%
-% \noindent
-% creates a title index named ``|mainindex|'' whose data is
-% stored in files named |idxfile.sxd| and |idxfile.sbx|.
-%
-% \DescMacro{showindex}
-% To display the index in the document, use:
-%
-% \begin{codeblock}
-% |\showindex[|\meta{columns}|]{|\meta{title}|}{|\meta{id}|}|
-% \end{codeblock}
-%
-% \noindent
-% where \meta{id} is the same identifier used in the \mac{newindex},
-% \mac{newauthorindex}, or \mac{newscripindex} command, and where
-% the \meta{title} is the title of the index, which should consist only of
-% simple text (no font or formatting macros, since those cannot be used in
-% pdf bookmark indexes).
-% The |[|\meta{columns}|]| part is optional; if specified it dictates the
-% number of columns if the index can't fit in a single column.
-% For example, for a 2-column title index, write:
-%
-% \begin{codeblock}
-% |\showindex[2]{Index of Song Titles}{mainindex}|
-% \end{codeblock}
-%
-% \section{Compiling}\label{sec:compiling}
-%
-% As with a typical \LaTeX\ document, compiling a song book document requires
-% three steps.
-% First, use \LaTeX\ (|pdflatex| is recommended) to generate auxiliary files
-% from the |.tex| file:
-%
-% \begin{codeblock}
-% |pdflatex mybook.tex|
-% \end{codeblock}
-%
-% Second, use the |songidx| program to generate an index for each index that
-% you declared with \mac{newindex}, \mac{newauthorindex}, or
-% \mac{newscripindex}.
-% The syntax of the |songidx| command is:
-%
-% \begin{codeblock}
-% |songidx |[|-b| \meta{canon}|.can|] \meta{filename}|.sxd| \meta{filename}|.sbx|
-% \end{codeblock}
-%
-% \noindent
-% where \meta{filename} is the same \meta{filename} that was used in the
-% \mac{newindex}, \mac{newauthorindex}, or \mac{newscripindex} macro.
-% If the index was declared with \mac{newscripindex}, then the |-b| option
-% is used to specify which version of the bible you wish to use as a basis
-% for sorting your scripture index.
-% The \meta{canon} part can be any of the |.can| files provided with
-% the |songidx| distribution.
-% If you are using a Protestant, Catholic, or Greek Orthodox Christian bible
-% with book names in English, then the |bible.can| canon file should work
-% well.
-% For other bibles, you should create your own |.can| file by copying and
-% modifying one of the existing |.can| files.
-%
-% For example, if your song book |.tex| file contains the lines
-%
-% \begin{codeblock}
-% \mac{newindex}|{titleidx}{titlfile}|
-% \mac{newauthorindex}|{authidx}{authfile}|
-% \mac{newscripindex}|{scripidx}{scrpfile}|
-% \end{codeblock}
-%
-% \noindent
-% then the commands to generate indexes sorted according to a Christian
-% English bible are:
-%
-% \begin{codeblock}
-% |songidx titlfile.sxd titlfile.sbx|
-% |songidx authfile.sxd authfile.sbx|
-% |songidx -b bible.can scrpfile.sxd scrpfile.sbx|
-% \end{codeblock}
-%
-% Once the indexes are generated, generate the final book by invoking
-% \LaTeX\ one more time:
-%
-% \begin{codeblock}
-% |pdflatex mybook.tex|
-% \end{codeblock}
-%
% \section{Songs}\label{sec:songs}
%
% \subsection{Beginning a Song}
@@ -847,19 +772,19 @@
% Each |songs| environment begins and ends with:
%
% \begin{codeblock}
-% |\begin{songs}{|\meta{indexes}|}|
+% |\begin{songs}{|\Meta{indexes}|}|
% $\vdots$
% |\end{songs}|
% \end{codeblock}
%
% \noindent
-% \meta{indexes} is a comma-separated list of index identifiers
-% (the \meta{id}'s specified with \mac{newindex})---one identifier
-% for each index that is to include songs in this song set.
+% \Meta{indexes} is a comma-separated list of index \Meta{id}'s
+% (see \S\ref{sec:indexes})---one identifier for each index that is to
+% include songs in this song set.
% Between the |\begin{songs}| and |\end{songs}| lines of
-% a song section can appear only songs (see below)
-% or inter-song environments (see \S\ref{sec:between}).
-% No text in a |songs| environment may lie outside of these environments.
+% a song section only songs (see below) or inter-song environments
+% (see \S\ref{sec:between}) may appear.
+% No text in a |songs| environment may appear outside of these environments.
%
% \paragraph{Songs.}
% \DescMacro{beginsong}
@@ -867,7 +792,7 @@
% A song begins and ends with:
%
% \begin{codeblock}
-% |\beginsong{|\meta{titles}|}[|\meta{otherinfo}|]|
+% |\beginsong{|\Meta{titles}|}[|\Meta{otherinfo}|]|
% $\vdots$
% |\endsong|
% \end{codeblock}
@@ -876,25 +801,25 @@
% Songs should appear only within \env{songs} environments (see above)
% unless you are supplying your own page-builder (see \S\ref{sec:layout}).
%
-% In the \mac{beginsong} line, \meta{titles} is one or more song titles
+% In the \mac{beginsong} line, \Meta{titles} is one or more song titles
% separated by |\\|.
% If multiple titles are provided, the first is typeset normally
% atop the song and the rest are each typeset in parentheses on
% separate lines.
%
-% The |[|\meta{otherinfo}|]| part is an optional comma-separated list of
-% key-value pairs (keyvals) of the form \meta{key}|=|\meta{value}.
+% The |[|\Meta{otherinfo}|]| part is an optional comma-separated list of
+% key-value pairs (keyvals) of the form \Meta{key}|=|\Meta{value}.
% The possible keys and their values are:
%
% \medskip
% \noindent\hfil\vbox{\halign{#\hfil&\kern2em{\it#}\hfil\cr
-% |by={|\meta{authors}|}|&authors, composers, and other contributors\cr
-% |cr={|\meta{copyright}|}|&copyright information\cr
-% |li={|\meta{license}|}|&licensing information\cr
-% |sr={|\meta{refs}|}|&related scripture references\cr
-% |index={|\meta{lyrics}|}|&an extra index entry for a line of lyrics\cr
-% |ititle={|\meta{title}|}|&an extra index entry for a hidden title\cr}}
-% \medskip
+% |by={|\Meta{authors}|}|&authors, composers, and other contributors\cr
+% |cr={|\Meta{copyright}|}|&copyright information\cr
+% |li={|\Meta{license}|}|&licensing information\cr
+% |sr={|\Meta{refs}|}|&related scripture references\cr
+% |index={|\Meta{lyrics}|}|&an extra index entry for a line of lyrics\cr
+% |ititle={|\Meta{title}|}|&an extra index entry for a hidden title\cr}}
+% {\pfs\par}\medskip
%
% \noindent
% For example, a song that begins and ends with
@@ -911,7 +836,7 @@
% \setcounter{songnum}{1}%
% \vskip1pt%
% \beginsong{Title1 \\ Title2}[by={Joe Smith}, sr={Job 3},
-% cr={\copyright~\the\year\ XYZ.}, li={Used with permission.}]
+% cr={\copyright~\the\year{} XYZ.}, li={Used with permission.}]
% \endsong
% \end{sample}
%
@@ -922,7 +847,7 @@
%
% \paragraph{Song Authors.}
% \DescEnv{by=}
-% The |by={|\meta{authors}|}| keyval lists one or more authors,
+% The |by={|\Meta{authors}|}| keyval lists one or more authors,
% composers, translators, etc.
% An entry is added to each author index associated with the current
% \env{songs} environment for each contributor listed.
@@ -944,7 +869,7 @@
%
% \paragraph{Copyright Info.}
% \DescEnv{cr=}
-% The |cr={|\meta{copyright}|}| keyval specifies the copyright-holder of the
+% The |cr={|\Meta{copyright}|}| keyval specifies the copyright-holder of the
% song, if any.
% For example:
%
@@ -958,13 +883,13 @@
% \paragraph{Licensing Info.}
% \DescEnv{li=}
% \DescMacro{setlicense}
-% Licensing information is provided by |li={|\meta{license}|}|, where
-% \meta{license} is any text.
+% Licensing information is provided by |li={|\Meta{license}|}|, where
+% \Meta{license} is any text.
% Licensing information is displayed in fine print under the song just
% after the copyright information (if any).
-% Alternatively, writing |\setlicense{|\meta{license}|}| anywhere between
+% Alternatively, writing |\setlicense{|\Meta{license}|}| anywhere between
% the \mac{beginsong} and \mac{endsong} lines is equivalent to using
-% |li={|\meta{license}|}| in the \mac{beginsong} line.
+% |li={|\Meta{license}|}| in the \mac{beginsong} line.
%
% When many songs in a book are covered by a common license, it is
% usually convenient to create a macro to abbreviate the licensing
@@ -983,45 +908,45 @@
%
% \paragraph{Scripture References.}
% \DescEnv{sr=}
-% The \Songs\ package has extensive support for scripture citations and
+% The \Songs{} package has extensive support for scripture citations and
% indexes of scripture citations.
% To cite scripture references for the song, use the keyval
-% |sr={|\meta{refs}|}|, where \meta{refs} is a list of scripture
+% |sr={|\Meta{refs}|}|, where \Meta{refs} is a list of scripture
% references.
% Index entries are added to all scripture indexes associated
% with the current \env{songs} environment for each such reference.
-% The |songidx| index generation program expects \meta{refs} to be a list
-% of references in which semicolons are used to separate references to
-% different books, and commas are used to separate references to to
-% different chapters and verses within the same book.
+% The |songidx| index generation script (see \S\ref{sec:compiling}) expects
+% \Meta{refs} to be a list of references in which semicolons are used to
+% separate references to different books, and commas are used to separate
+% references to to different chapters and verses within the same book.
% For example, one valid scripture citation is
%
% \begin{codeblock}
% |sr={John 3:16,17, 4:1-5; Jude 3}|
% \end{codeblock}
%
-% The full formal syntax of a valid \meta{refs} argument is given in
+% The full formal syntax of a valid \Meta{refs} argument is given in
% Figure~\ref{fig:srsyntax}.
% \begin{figure}
% \noindent\hfil\vbox{\advance\baselineskip2pt
% \halign{\hfil{\tt#}\,$\longrightarrow$\,&{\tt#}\hfil\cr
-% \Meta{refs}&\Meta{nothing}\OR\Meta{ref};\SPC\Meta{ref};$\ldots$;\SPC\Meta{ref}\cr
-% \Meta{ref}&\Meta{many-chptr-book}\SPC\Meta{chapters}\OR\Meta{one-chptr-book}\SPC\Meta{verses}\cr
-% \Meta{many-chptr-book}&Genesis\OR Exodus\OR Leviticus\OR Numbers\OR $\ldots$\cr
-% \Meta{one-chptr-book}&Obadiah\OR Philemon\OR 2 John\OR 3 John\OR Jude\cr
-% \Meta{chapters}&\Meta{chref},\SPC\Meta{chref},$\ldots$,\SPC\Meta{chref}\cr
-% \Meta{chref}&\Meta{chapter}\OR\Meta{chapter}-\Meta{chapter}\OR\Meta{chapter}:\Meta{verses}\OR\cr
-% \omit&\quad\Meta{chapter}:\Meta{verse}-\Meta{chapter}:\Meta{verse}\cr
-% \Meta{verses}&\Meta{vref},\Meta{vref},$\ldots$,\Meta{vref}\cr
-% \Meta{vref}&\Meta{verse}\OR\Meta{verse}-\Meta{verse}\cr}}
+% \Metarm{refs}&\Metarm{nothing}\OR\Metarm{ref};\SPC\Metarm{ref};$\ldots$;\SPC\Metarm{ref}\cr
+% \Metarm{ref}&\Metarm{many-chptr-book}\SPC\Metarm{chapters}\OR\Metarm{one-chptr-book}\SPC\Metarm{verses}\cr
+% \Metarm{many-chptr-book}&Genesis\OR Exodus\OR Leviticus\OR Numbers\OR $\ldots$\cr
+% \Metarm{one-chptr-book}&Obadiah\OR Philemon\OR 2 John\OR 3 John\OR Jude\cr
+% \Metarm{chapters}&\Metarm{chref},\SPC\Metarm{chref},$\ldots$,\SPC\Metarm{chref}\cr
+% \Metarm{chref}&\Metarm{chapter}\OR\Metarm{chapter}-\Metarm{chapter}\OR\Metarm{chapter}:\Metarm{verses}\OR\cr
+% \omit&\quad\Metarm{chapter}:\Metarm{verse}-\Metarm{chapter}:\Metarm{verse}\cr
+% \Metarm{verses}&\Metarm{vref},\Metarm{vref},$\ldots$,\Metarm{vref}\cr
+% \Metarm{vref}&\Metarm{verse}\OR\Metarm{verse}-\Metarm{verse}\cr}}
% \caption{Formal syntax rules for song scripture references}\label{fig:srsyntax}
% \end{figure}
-% In those syntax rules, \meta{chapter} and \meta{verse} stand for arabic
+% In those syntax rules, \Meta{chapter} and \Meta{verse} stand for arabic
% numbers denoting a valid chapter number for the given book, and a valid
% verse number for the given chapter, respectively.
% Note that when referencing a book that has only one chapter,
% one should list only its verses after the book name
-% (rather than |1:|\meta{verses}).
+% (rather than |1:|\Meta{verses}).
%
% \subsection{Verses and Choruses}
%
@@ -1066,53 +991,6 @@
% Lines that are too long to fit are wrapped with hanging indentation
% of width |\parindent|.
%
-% \paragraph{Repeating Choruses.}
-% \DescMacro{repchoruses}
-% When making overhead slides, it is often convenient to repeat the song's
-% chorus after the first verse on each page, so that the projector-operator
-% need not flip back to the first slide each time the chorus is to be sung.
-% You can say |\repchoruses| to automate this process.
-% This causes the first chorus in each song to be automatically repeated
-% after the first verse on each subsequent page of the song (unless that
-% verse is already immediately followed by a chorus).
-% If the first chorus is part of a set of two or more consecutive choruses,
-% then the whole set of choruses is repeated.
-% (A set of choruses is assumed to consist of things like pre-choruses that
-% should always be repeated along with the chorus.)
-% Choruses are not automatically inserted immediately after unnumbered
-% verses (i.e., verses that begin with \mac{beginverse}|*|).
-% Unnumbered verses are assumed to be bridges or endings that aren't
-% followed by a chorus.
-%
-% \DescMacro{norepchoruses}
-% The above covers the common cases, but some songs have more complex forms
-% that demand a manual approach.
-% Before a song with irregular form, say |\norepchoruses| to turn automatic
-% chorus-repeating off.
-% Then, at points within the song where you want a chorus to be repeated on
-% the overhead slides, type a construction like,
-%
-% \begin{codeblock}
-% \mac{ifslides}
-% \mac{beginchorus}
-% $\vdots$
-% \mac{endchorus}
-% |\fi|
-% \end{codeblock}
-%
-% \noindent
-% and copy and paste the desired chorus into the middle.
-% This inserts a repeated chorus at that point when generating slides,
-% but not when generating a lyric book or chord book.
-% After the song is concluded, type
-%
-% \begin{codeblock}
-% \mac{ifslides}\mac{repchoruses}|\fi|
-% \end{codeblock}
-%
-% \noindent
-% to turn automatic chorus-repeating back on, if desired.
-%
% \subsection{Chords}\label{sec:chords}
%
% \DescMacro{[}
@@ -1120,9 +998,9 @@
% \DescChar{amp}{&}
% Between the \mac{beginverse} and \mac{endverse} lines, or between
% the \mac{beginchorus} and \mac{endchorus} lines,
-% chords can be produced using the macro |\[|\meta{chordname}|]|\eat\].
+% chords can be produced using the macro |\[|\Meta{chordname}|]|\eat\].
% Chords only appear in chord books; they are omitted from lyric books.
-% The \meta{chordname} may consist of arbitrary text.
+% The \Meta{chordname} may consist of arbitrary text.
% To produce sharp and flat symbols, use |#| and |&| respectively.
%
% Any text that immediately follows the |\[]|\eat\] macro with no
@@ -1135,7 +1013,7 @@
% \eat\]
%
% \noindent
-% If whitespace (a space or \meta{return}) immediately follows,
+% If whitespace (a space or \Meta{return}) immediately follows,
% then the chord name be typeset without any lyric text
% below it, indicating that the chord is to be struck between
% any surrounding words.
@@ -1215,19 +1093,19 @@
% \paragraph{Symbols Under Chords.}
% \DescMacro{DeclareLyricChar}
% If you are typesetting songs in a language whose alphabet contains symbols
-% that \LaTeX\ treats as punctuation, you can use the |\DeclareLyricChar|
-% macro to instruct the \Songs\ package to treat the symbol as
+% that \LaTeX{} treats as punctuation, you can use the |\DeclareLyricChar|
+% macro to instruct the \Songs{} package to treat the symbol as
% non-chord-ending, so that it is included under chords by default just
% like an alphabetic character.
%
% \begin{codeblock}
-% |\DeclareLyricChar{|\meta{token}|}|
+% |\DeclareLyricChar{|\Meta{token}|}|
% \end{codeblock}
%
% \noindent
-% Here, \meta{token} must be a single \TeX\ macro control sequence,
-% active character, letter (something \TeX\ assigns catcode 11), or
-% punctuation symbol (something \TeX\ assigns catcode 12).
+% Here, \Meta{token} must be a single \TeX{} macro control sequence,
+% active character, letter (something \TeX{} assigns catcode 11), or
+% punctuation symbol (something \TeX{} assigns catcode 12).
% For example, by default,
%
% \example|\[Fmaj7]s\dag range|\produces{\[Fmaj7]s\dag range}
@@ -1253,7 +1131,7 @@
% Likewise, you can type
%
% \begin{codeblock}
-% |\DeclareNonLyric{|\meta{token}|}|
+% |\DeclareNonLyric{|\Meta{token}|}|
% \end{codeblock}
%
% \noindent
@@ -1263,7 +1141,7 @@
%
% \DescMacro{DeclareNoHyphen}
% To declare a token to be lyric-ending but without the added hyphenation,
-% use |\DeclareNoHyphen{|\meta{token}|}| instead.
+% use |\DeclareNoHyphen{|\Meta{token}|}| instead.
% Such tokens are pushed out away from long chord names so that they never
% fall under the chord, but hyphenation is not added to the resulting gap.
%
@@ -1315,11 +1193,11 @@
% |\newcommand{\Csharp}{C\shrp}|
% \end{codeblock}
%
-% \subsection{Replaying Chords}\label{sec:replay}
+% \subsection{Replaying Chords and Choruses}\label{sec:replay}
%
% \DescChar{hat}{^}
% Many songs consist of multiple verses that use the same chords.
-% The \Songs\ package simplifies this common case by providing a means to
+% The \Songs{} package simplifies this common case by providing a means to
% replay the chord sequence of a previous verse without having to retype
% all the chords.
% To replay a chord from a previous verse, type a hat symbol (|^|) anywhere
@@ -1402,7 +1280,7 @@
% other chords that you wish to replay.
%
% \paragraph{Memorizing Multiple Chord Sequences.}
-% By default, the \Songs\ package only memorizes one sequence of chords
+% By default, the \Songs{} package only memorizes one sequence of chords
% at a time and \refchar{hat} replays chords from that most recently
% memorized sequence.
% However, you can memorize and replay multiple independent sequences
@@ -1413,18 +1291,18 @@
% To declare a new chord-replay register, type
%
% \begin{codeblock}
-% |\newchords{|\meta{regname}|}|
+% |\newchords{|\Meta{regname}|}|
% \end{codeblock}
%
% \noindent
-% where \meta{regname} is any unique alphabetic name.
+% where \Meta{regname} is any unique alphabetic name.
%
% Once you've declared a register, you can memorize into that register
-% by providing the \meta{regname} as an optional argument to
+% by providing the \Meta{regname} as an optional argument to
% \mac{memorize}:
%
% \begin{codeblock}
-% \mac{memorize}|[|\meta{regname}|]|
+% \mac{memorize}|[|\Meta{regname}|]|
% \end{codeblock}
%
% \noindent
@@ -1432,21 +1310,60 @@
% register with the new chord sequence.
%
% \DescMacro{replay}
-% To replay chord from a particular register, type
+% To replay chords from a particular register, type
%
% \begin{codeblock}
-% |\replay[|\meta{regname}|]|
+% |\replay[|\Meta{regname}|]|
% \end{codeblock}
%
% \noindent
% Subsequent uses of \refchar{hat} reproduce chords from the sequence
-% stored in register \meta{regname}.
+% stored in register \Meta{regname}.
%
% Register contents are global, so you can memorize a chord sequence from one
% song and replay it in others.
% You can also use |\replay| multiple times in the same verse or chorus to
% replay a sequence more than once.
%
+% \paragraph{Replaying Choruses.}
+% \DescMacro{repchoruses}
+% When making overhead slides, it is often convenient to repeat the song's
+% chorus after the first verse on each page, so that the projector-operator
+% need not flip back to the first slide each time the chorus is to be sung.
+% You can say |\repchoruses| to automate this process.
+% This causes the first chorus in each subsequent song to be automatically
+% repeated after the first verse on each subsequent page of the song (unless
+% that verse is already immediately followed by a chorus).
+% If the first chorus is part of a set of two or more consecutive choruses,
+% then the whole set of choruses is repeated.
+% (A set of choruses is assumed to consist of things like pre-choruses that
+% should always be repeated along with the chorus.)
+% Choruses are not automatically inserted immediately after unnumbered
+% verses (i.e., verses that begin with \mac{beginverse}|*|).
+% Unnumbered verses are assumed to be bridges or endings that aren't
+% followed by a chorus.
+%
+% \DescMacro{norepchoruses}
+% Writing |\norepchoruses| turns off chorus repetition for subsequent songs.
+%
+% If you need finer control over where replayed choruses appear, use the
+% conditional macros covered in \S\ref{sec:conditionals} instead of
+% |\repchoruses|.
+% For example, to manually insert a chorus into only slide books at a
+% particular point (without affecting other versions of your book),
+% you could write:
+%
+% \begin{codeblock}
+% \mac{ifslides}
+% \mac{beginchorus}
+% $\vdots$
+% \mac{endchorus}
+% |\fi|
+% \end{codeblock}
+%
+% \noindent
+% and copy and paste the desired chorus into the middle.
+%
% \subsection{Line and Column Breaks}
%
% \paragraph{Line Breaking.}
@@ -1517,7 +1434,7 @@
%
% \paragraph{Echo Parts.}
% \DescMacro{echo}
-% To typeset an echo part, use |\echo{|\meta{lyrics and chords}|}|.
+% To typeset an echo part, use |\echo{|\Meta{lyrics and chords}|}|.
% Echo parts are parenthesized and italicized.
% For example,
%
@@ -1527,7 +1444,7 @@
% \paragraph{Repeated Lines.}
% \DescMacro{rep}
% To indicate that a line should be sung multiple times by all singers, put
-% |\rep{|\meta{n}|}| at the end of the line.
+% |\rep{|\Meta{n}|}| at the end of the line.
% For example,
%
% \example|Alleluia! \rep{4}|\produces{Alleluia! \rep{4}}
@@ -1564,15 +1481,15 @@
% it to indicate the time signature of the piece.
% By default, these numbers are 4/4, denoting four quarter notes
% per measure.
-% To change the default, type |\meter{|\meta{n}|}{|\meta{d}|}|
+% To change the default, type |\meter{|\Meta{n}|}{|\Meta{d}|}|
% somewhere after the \mac{beginsong} line of the song but before the
-% first measure bar, to declare a time signature of \meta{n} \meta{d}th
+% first measure bar, to declare a time signature of \Meta{n} \Meta{d}th
% notes per measure.
%
% \DescMacro{mbar}
% You can also change meters mid-song either by using |\meter| in the
-% middle of the song or by typing |\mbar{|\meta{n}|}{|\meta{d}|}|
-% to produce a measure bar with a time signature of \meta{n}/\meta{d}.
+% middle of the song or by typing |\mbar{|\Meta{n}|}{|\Meta{d}|}|
+% to produce a measure bar with a time signature of \Meta{n}/\Meta{d}.
% For example,
%
% \begin{codeblock}
@@ -1599,18 +1516,18 @@
% and chord books, use:
%
% \begin{codeblock}
-% |\textnote{|\meta{text}|}|
+% |\textnote{|\Meta{text}|}|
% \end{codeblock}
%
% \noindent
% To create a textual note that is displayed only in chord books, use:
%
% \begin{codeblock}
-% |\musicnote{|\meta{text}|}|
+% |\musicnote{|\Meta{text}|}|
% \end{codeblock}
%
% \noindent
-% Both of these create a shaded box containing \meta{text}.
+% Both of these create a shaded box containing \Meta{text}.
% For example,
%
% \begin{codeblock}
@@ -1631,71 +1548,13 @@
% \DescMacro{capo}
% One special kind of textual note suggests to guitarists a fret on which
% they should put their capos.
-% Macro |\capo{|\meta{n}|}| should be used for this purpose.
-% It normally has the same effect as \mac{musicnote}|{capo |\meta{n}|}|;
+% Macro |\capo{|\Meta{n}|}| should be used for this purpose.
+% It normally has the same effect as \mac{musicnote}|{capo |\Meta{n}|}|;
% however, if the \env{transposecapos} option is active then it
-% instead has the effect of \mac{transpose}|{|\meta{n}|}|.
+% instead has the effect of \mac{transpose}|{|\Meta{n}|}|.
% See \S\ref{sec:transpose} for more information on automatic chord
% transposition.
%
-% \subsection{Index Entries}\label{sec:ientry}
-%
-% Every song automatically gets entries in the current section's title
-% index(es).
-% However, you can also add extra index entries for a song to any index.
-%
-% \paragraph{Indexing Lyrics.}
-% \DescEnv{index=}
-% For example, title indexes often have entries for memorable lines
-% of lyrics in a song in addition to the song's title.
-% You can add an index entry for the current song to the section's
-% title index(es) by adding |index={|\meta{lyrics}|}| to the song's
-% \mac{beginsong} line.
-% For example,
-%
-% \begin{codeblock}
-% \mac{beginsong}|{Doxology}|
-% | [index={Praise God from Whom all blessings flow}]|
-% \end{codeblock}
-%
-% \noindent
-% causes the song to be indexed both as ``\textit{Doxology}'' and as
-% ``Praise God from Whom all blessings flow'' in the section's title index(es).
-% You can use |index=| multiple times in a \mac{beginsong} line to produce
-% multiple additional index entries.
-% Index entries produced with |index={|\meta{lyrics}|}| are
-% typeset in an upright font instead of in italics to distinguish
-% them from song titles.
-%
-% \paragraph{Indexing Extra Song Titles.}
-% \DescEnv{ititle=}
-% To add a regular index entry typeset in italics to the title
-% index(es), use:
-%
-% \begin{codeblock}
-% |ititle={|\meta{title}|}|
-% \end{codeblock}
-%
-% \noindent
-% in the \mac{beginsong} line instead.
-% Like \env{index=} keyvals, |ititle=| can be used multiple times to produce
-% multiple additional index entries.
-%
-% \DescMacro{indexentry}
-% \DescMacro{indextitleentry}
-% You can also create index entries by saying
-% |\indexentry[|\meta{indexes}|]{|\meta{lyrics}|}| (which creates an
-% entry like \env{index=}) or
-% |\indextitleentry[|\meta{indexes}|]{|\meta{title}|}| (which
-% creates an entry like \env{ititle=}).
-% These two macros can be used anywhere between the song's \mac{beginsong}
-% and \mac{endsong} lines, and can be used multiple times to produce
-% multiple entries.
-% If specified, \meta{indexes} is a comma-separated list of the identifiers
-% of indexes to which the entry should be added.
-% Otherwise the new entry is added to all of the title indexes for the current
-% \env{songs} environment.
-%
% \subsection{Chords in Ligatures}
%
% This subsection covers an advanced topic and can probably be
@@ -1704,30 +1563,30 @@
% The \mac{[\eat]} macro is the normal means by which chords should be inserted
% into a song; however, a special case occurs when a chord falls within a
% ligature.
-% Ligatures are combinations of letters or symbols that \TeX\ normally
+% Ligatures are combinations of letters or symbols that \TeX{} normally
% typesets as a single font character so as to produce cleaner-looking
% output.
% The only ligatures in English are: ff, fi, fl, ffi, and ffl.
-% Other languages have additional ligatures like \ae\ and \oe.
+% Other languages have additional ligatures like \ae{} and \oe.
% Notice that in each of these cases, the letters are ``squished''
% together to form a single composite symbol.
%
% \DescMacro{ch}
-% When a chord macro falls inside a ligature, \LaTeX\ fails to compact
+% When a chord macro falls inside a ligature, \LaTeX{} fails to compact
% the ligature into a single font character even in non-chorded versions of
% the book.
-% To avoid this minor typograhpical error, use the |\ch| macro to typeset
+% To avoid this minor typographical error, use the |\ch| macro to typeset
% the chord:
%
% \begin{codeblock}
-% |\ch{|\meta{chord}|}{|\meta{pre}|}{|\meta{post}|}{|\meta{full}|}|
+% |\ch{|\Meta{chord}|}{|\Meta{pre}|}{|\Meta{post}|}{|\Meta{full}|}|
% \end{codeblock}
%
% \noindent
-% where \meta{chord} is the chord text, \meta{pre} is the text to
+% where \Meta{chord} is the chord text, \Meta{pre} is the text to
% appear before the hyphen if the ligature is broken by auto-hyphenation,
-% \meta{post} is the text to appear after the hyphen if the ligature
-% is broken by auto-hyphenation, and \meta{full} is the full ligature
+% \Meta{post} is the text to appear after the hyphen if the ligature
+% is broken by auto-hyphenation, and \Meta{full} is the full ligature
% if it is not broken by hyphenation.
% For example, to correctly typeset |\[Gsus4]dif\[G]ficult|\eat\],
% in which the \chord{G} chord falls in the middle of the ``ffi''
@@ -1739,7 +1598,7 @@
% This causes the ``ffi'' ligature to appear intact yet still correctly
% places the \chord{G} chord over the second f.
% To use the |\ch| macro with a replayed chord name (see \S\ref{sec:replay}),
-% use |^| as the \meta{chord}.
+% use |^| as the \Meta{chord}.
%
% \DescMacro{mch}
% The |\mch| macro is exactly like the \mac{ch} macro except that it
@@ -1769,6 +1628,267 @@
% no special treatment; it leaves the ``ffi'' ligature intact when measure
% bars are not being displayed.
%
+% \section{Guitar Tablatures}\label{sec:tablatures}
+%
+% \DescMacro{gtab}
+% Guitar tablature diagrams can be created by using the construct
+%
+% \begin{codeblock}
+% |\gtab{|\Meta{chord}|}{|\Meta{fret}|:|\Meta{strings}|:|\Meta{fingering}|}|
+% \end{codeblock}
+%
+% \noindent
+% where the \Meta{fret} and \Meta{fingering} parts are both optional
+% (and you may omit any colon that borders an omitted argument).
+%
+% \Meta{chord} is a chord name to be placed above the diagram.
+%
+% \Meta{fret} is an optional digit from 2 to 9 placed to the
+% left of the diagram.
+%
+% \Meta{strings} should be a series of symbols, one for each string
+% of the guitar from lowest pitch to highest.
+% Each symbol should be one of:
+% |X| if that string is not to be played,
+% |0| (zero or the letter O) if that string is to be played open, or
+% one of |1| through |9| if that string is to be played on the given
+% numbered fret.
+%
+% \Meta{fingering} is an optional series of digits, one for each
+% string of the guitar from lowest pitch to highest.
+% Each digit should be one of:
+% |0| if no fingering information is to be displayed for that string (e.g., if
+% the string is not being played or is being played open), or
+% one of |1| through |4| to indicate that the given numbered finger is to be
+% used to hold down that string.
+%
+% Here are some examples to illustrate:
+%
+% \example|\gtab{A}{X02220:001230}|\produces{\vcenterbox{\gtab{A}{{\hphantom{4}}:X02220:001230}}}
+% \example|\gtab{C#sus4}{4:XX3341}|\produces{\vcenterbox{\gtab{C\shrp sus4}{4:XX3341}}}
+% \example|\gtab{B&}{X13331}|\produces{\vcenterbox{\gtab{B\flt}{{\hphantom{4}}:X13331:}}}
+%
+% \DescMacro{minfrets}
+% By default, tablature diagrams always consist of at least 4 fret rows
+% (more if the \Meta{strings} argument contains a number larger than 4).
+% To change the minimum number of fret rows, change the value of |\minfrets|.
+% For example, typing
+%
+% \begin{codeblock}
+% |\minfrets=1|
+% \end{codeblock}
+%
+% \noindent
+% causes tablature diagrams to have only as many rows are required to
+% accommodate the largest digit appearing in the \Meta{strings} argument.
+%
+% \section{Automatic Transposition}\label{sec:transpose}
+%
+% \DescMacro{transpose}
+% You can automatically transpose some or all of the chords in a song up by
+% \Meta{n} half-steps by adding the line
+%
+% \begin{codeblock}
+% |\transpose{|\Meta{n}|}|
+% \end{codeblock}
+%
+% \noindent
+% somewhere between the song's \mac{beginsong} line and the first chord to
+% be transposed.
+% For example, if a song's first chord is |\[D]|\eat\], and the line
+% |\transpose{2}| appears before it, then the chord appears as an
+% \chord{E} in the resulting document.
+% Specifying a negative number for \Meta{n} transposes subsequent chords
+% down instead of up.
+%
+% The |\transpose| macro affects all chords appearing after it until the
+% \mac{endsong} line.
+% If two |\transpose| macros appear in the same song, their effects are
+% cumulative.
+%
+% When the \env{transposecapos} option is active, the \mac{capo}
+% macro acts like |\transpose|.
+% See \S\ref{sec:notes} for more information.
+%
+% \paragraph{Enharmonics.}
+% \DescMacro{preferflats}
+% \DescMacro{prefersharps}
+% When using \mac{transpose} to automatically transpose the chords of a song,
+% the \Songs{} package code chooses between enharmonically equivalent
+% names for ``black key'' notes based on the first chord of the song.
+% For example, if |\transpose{1}| is used, and if the first chord of the
+% song is an \chord{E}, then all \chord{A} chords that appear in
+% the song are transcribed as \chord{B\flt} chords rather than
+% \chord{A\shrp} chords, since the key of \chord{F}-major (\chord{E}
+% transposed up by one half-step) has a flatted key signature.
+% Usually this guess produces correct results, but if not, you can use
+% either |\preferflats| or |\prefersharps| after the \mac{transpose} line
+% to force all transcription to use flatted names or sharped names
+% respectively, when resolving enharmonic equivalents.
+%
+% \paragraph{Modulated Verses.}
+% Automatic transposition can be used in conjunction with chord-replaying
+% (see \S\ref{sec:chords}) to produce modulated verses.
+% For example,
+%
+% \begin{codeblock}
+% \mac{beginverse}\mac{memorize}
+% |\[F#]This is a \[B/F#]memorized \[F#]verse. \[E&7]|\eat\]
+% \mac{endverse}
+% \mac{transpose}|{2}|
+% \mac{beginverse}
+% |^This verse is ^modulated up two ^half-steps.|
+% \mac{endverse}
+% \end{codeblock}
+%
+% \noindent produces
+%
+% \begin{chorded}\memorize
+% \[F#]This is a \[B/F#]memorized \[F#]verse. \[E&7]\eat\]
+% \vskip5pt\replay\transpose{2}%
+% ^This verse is ^modulated up two ^half-steps.
+% \transpose{-2}%
+% \end{chorded}
+%
+% \paragraph{Both Keys.}
+% \DescMacro{trchordformat}
+% By default, when chords are automatically transposed using \mac{transpose},
+% only the transposed chords are printed.
+% However, in some cases you may wish to print the old chords and the
+% transposed chords together so that musicians playing transposing and
+% non-transposing instruments can play from the same piece of music.
+% This can be achieved by redefining the |\trchordformat| macro, which
+% receives two arguments---the original chord name and the transposed chord
+% name, respectively.
+% For example, to print the old chord above the new chord above each lyric,
+% define
+%
+% \begin{codeblock}
+% |\renewcommand{\trchordformat}[2]{\vbox{\hbox{#1}\hbox{#2}}}|
+% \end{codeblock}
+%
+% \paragraph{Changing Note Names.}
+% \DescMacro{solfedge}
+% \DescMacro{alphascale}
+% In many countries it is common to use the solfedge names for the notes of
+% the scale (\chord{LA, SI, DO, RE, MI, FA, SOL\/}) instead of the
+% alphabetic names (\chord{A, B, C, D, E, F, G\/}).
+% By default, the transposition logic only understands alphabetic names, but
+% you can tell it to look for solfedge names by typing |\solfedge|.
+% To return to alphabetic names, type |\alphascale|.
+%
+% \DescMacro{notenames}
+% You can use other note names as well.
+% To define your own note names, type
+%
+% \begin{codeblock}
+% |\notenames{|\Meta{nameA}|}{|\Meta{nameB}|}|$\ldots$|{|\Meta{nameG}|}|
+% \end{codeblock}
+%
+% \noindent
+% where each of \Meta{nameA} through \Meta{nameG} must consist entirely of
+% a sequence of one or more \emph{uppercase} letters.
+% For example, some solfedge musicians use \chord{TI} instead of \chord{SI}
+% for the second note of the scale.
+% To automatically transpose such music, use:
+%
+% \begin{codeblock}
+% |\notenames{LA}{TI}{DO}{RE}{MI}{FA}{SOL}|
+% \end{codeblock}
+%
+% \DescMacro{notenamesin}
+% \DescMacro{notenamesout}
+% The \Songs{} package can also automatically convert one set of note names
+% to another.
+% For example, suppose you have a large song book in which chords have been
+% typed using alphabetic note names, but you wish to produce a book that
+% uses the equivalent solfedge names.
+% You could achieve this by using the |\notenamesin| macro to tell the
+% \Songs{} package which note names you typed in the input file, and then
+% using |\notenamesout| to tell the \Songs{} package how you want it to
+% typeset each note name in the output file.
+% The final code looks like this:
+%
+% \begin{codeblock}
+% |\notenamesin{A}{B}{C}{D}{E}{F}{G}|
+% |\notenamesout{LA}{SI}{DO}{RE}{MI}{FA}{SOL}|
+% \end{codeblock}
+%
+% \noindent
+% The syntaxes of |\notenamesin| and |\notenamesout| are identical to that
+% of \mac{notenames} (see above), except that the arguments of |\notenamesout|
+% can consist of any \LaTeX{} code that is legal in horizontal mode, not just
+% uppercase letters.
+%
+% To stop converting between note names, use \mac{alphascale}, \mac{solfedge},
+% or \mac{notenames} to reset all note names back to identical input and
+% output scales.
+%
+% \paragraph{Transposing Chords In Macros.}
+% \DescMacro{transposehere}
+% The automatic transposition logic does not find chord names that are hidden
+% inside macro bodies.
+% For example, if you abbreviate a chord by typing,
+%
+% \begin{codeblock}
+% |\newcommand{\mychord}{F|\mac{shrp}| sus4/C|\mac{shrp}|}|
+% \mac{transpose}|{4}|
+% |\[\mychord]|\eat\]
+% \end{codeblock}
+%
+% \noindent
+% then the \mac{transpose} macro fails to transpose it; the
+% resulting chord is still an \chord{F\shrp sus4/C\shrp} chord.
+% To fix the problem, you can use |\transposehere| in your macros to
+% explicitly invoke the transposition logic on chord names embedded in
+% macro bodies.
+% The above example could be corrected by instead defining:
+%
+% \begin{codeblock}
+% |\newcommand{\mychord}{\transposehere{F|\mac{shrp}| sus4/C|\mac{shrp}|}}|
+% \end{codeblock}
+%
+% \DescMacro{notrans}
+% Transposition can be suppressed within material that would otherwise be
+% transposed by using the |\notrans| macro.
+% For example, writing
+%
+% \begin{codeblock}
+% \mac{transposehere}|{G = \notrans{G}}|
+% \end{codeblock}
+%
+% \noindent
+% would typeset a transposed \chord{G} followed by a non-transposed
+% \chord{G} chord.
+% This does not suppress note name conversion (see \mac{notenames}).
+% To suppress both transposition and note name conversion, just use
+% braces (e.g., |{G}| instead of |\notrans{G}|).
+%
+% \paragraph{Transposing Guitar Tablatures.}
+% \DescMacro{gtabtrans}
+% The songs package cannot automatically transpose tablature diagrams
+% (see \S\ref{sec:tablatures}).
+% Therefore, when automatic transposition is taking place, only the chord
+% names of \mac{gtab} macros are displayed (and transposed); the diagrams
+% are omitted.
+% To change this default, redefine the |\gtabtrans| macro, whose two
+% arguments are the two arguments to \mac{gtab}.
+% For example, to display original tablatures without transposing them even
+% when transposition has been turned on, write
+%
+% \begin{codeblock}
+% |\renewcommand{\gtabtrans}[2]{|\mac{gtab}|{|\mac{notrans}|{#1}}{#2}}|
+% \end{codeblock}
+%
+% \noindent
+% To transpose the chord name but not the diagram under it, replace
+% \mac{notrans}|{#1}| with simply |#1| in the above.
+% To restore the default behavior, write
+%
+% \begin{codeblock}
+% |\renewcommand{\gtabtrans}[2]{|\mac{transposehere}|{#1}}|
+% \end{codeblock}
+%
% \section{Between Songs}\label{sec:between}
%
% Never put any material directly into the top level of a \env{songs}
@@ -1794,7 +1914,7 @@
% Material contributed in an |intersong| environment is subject to the same
% column-breaking rules as songs (see \S\ref{sec:layout}), but all other
% formatting is up to you.
-% By default, \LaTeX\ inserts interline glue below the last line of an
+% By default, \LaTeX{} inserts interline glue below the last line of an
% |intersong| environment.
% To suppress this, end the |intersong| content with |\par\nointerlineskip|.
%
@@ -1841,16 +1961,16 @@
% Scripture quotations begin and end with
%
% \begin{codeblock}
-% |\beginscripture{|\meta{ref}|}|
+% |\beginscripture{|\Meta{ref}|}|
% $\vdots$
% |\endscripture|
% \end{codeblock}
%
% \noindent
-% where \meta{ref} is a scripture reference that is
+% where \Meta{ref} is a scripture reference that is
% typeset at the end of the quotation.
-% The \meta{ref} argument should conform to the same syntax
-% rules as for the \meta{ref} arguments passed to \mac{beginsong}
+% The \Meta{ref} argument should conform to the same syntax
+% rules as for the \Meta{ref} arguments passed to \mac{beginsong}
% macros (see \S\ref{sec:songs}).
%
% The text of the scripture quotation between the |\beginscripture| and
@@ -1968,265 +2088,199 @@
% \endscripture
% \end{sample}
%
-% \section{Guitar Tablatures}\label{sec:tablatures}
+% \section{Chapters and Sections}\label{sec:sectioning}
%
-% \DescMacro{gtab}
-% Guitar tablature diagrams can be created by using the construct
+% \DescMacro{songsection}
+% \DescMacro{songchapter}
+% Song books can be divided into chapters and sections using all the usual
+% macros provided by \LaTeX{} (e.g., |\chapter|, |\section|, etc.) and by
+% other macro packages.
+% In addition, the \Songs{} package provides two helpful built-in sectioning
+% macros:
%
% \begin{codeblock}
-% |\gtab{|\meta{chord}|}{|\meta{fret}|:|\meta{strings}|:|\meta{fingering}|}|
+% |\songchapter{|\Meta{title}|}|
+% |\songsection{|\Meta{title}|}|
% \end{codeblock}
%
% \noindent
-% where the \meta{fret} and \meta{fingering} parts are both optional
-% (and you may omit any colon that borders an omitted argument).
-%
-% \meta{chord} is a chord name to be placed above the diagram.
-%
-% \meta{fret} is an optional digit (any number from 2 to 9) placed to the
-% left of the diagram.
-%
-% \meta{strings} should be a series of symbols, one for each string
-% of the guitar from lowest pitch to highest.
-% Each symbol should be one of:
-% |X| if that string is not to be played,
-% |0| (zero or the letter O) if that string is to be played open, or
-% one of |1| through |9| if that string is to be played on the given
-% numbered fret.
-%
-% \meta{fingering} is an optional series of digits, one for each
-% string of the guitar from lowest pitch to highest.
-% Each digit should be one of:
-% |0| if no fingering information is to be displayed for that string (e.g., if
-% the string is not being played or is being played open), or
-% one of |1| through |4| to indicate that the given numbered finger is to be
-% used to hold down that string.
+% which act like \LaTeX's |\chapter| and |\section| commands except that they
+% center the \Meta{title} text in sans serif font and omit the chapter/section
+% number.
+% The |\songchapter| macro only works in document classes that support
+% |\chapter| (e.g., the |book| class).
%
-% Here are some examples to illustrate:
+% \section{Indexes}
%
-% \example|\gtab{A}{X02220:001230}|\produces{\vcenterbox{\gtab{A}{{\hphantom{4}}:X02220:001230}}}
-% \example|\gtab{C#sus4}{4:XX3341}|\produces{\vcenterbox{\gtab{C\shrp sus4}{4:XX3341}}}
-% \example|\gtab{B&}{X13331}|\produces{\vcenterbox{\gtab{B\flt}{{\hphantom{4}}:X13331:}}}
+% \subsection{Index Creation}\label{sec:indexes}
%
-% \DescMacro{minfrets}
-% By default, tablature diagrams always consist of at least 4 fret rows
-% (more if the \meta{strings} argument contains a number larger than 4).
-% To change the minimum number of fret rows, change the value of |\minfrets|.
-% For example, typing
+% \DescMacro{newindex}
+% \DescMacro{newauthorindex}
+% \DescMacro{newscripindex}
+% The \Songs{} package supports three kinds of indexes: indexes by title and/or
+% notable lyrics, indexes by author, and indexes by scripture reference.
+% To generate an index, first declare the index in the document preamble
+% (i.e., before the |\begin{document}| line) with one of the following:
%
% \begin{codeblock}
-% |\minfrets=1|
+% |\newindex{|\Meta{id}|}{|\Meta{filename}|}|
+% |\newauthorindex{|\Meta{id}|}{|\Meta{filename}|}|
+% |\newscripindex{|\Meta{id}|}{|\Meta{filename}|}|
% \end{codeblock}
%
% \noindent
-% causes tablature diagrams to have only as many rows are required to
-% accommodate the largest digit appearing in the \meta{strings} argument.
-%
-% \section{Automatic Transposition}\label{sec:transpose}
-%
-% \DescMacro{transpose}
-% You can automatically transpose some or all of the chords in a song up by
-% \meta{n} half-steps by adding the line
+% The \Meta{id} should be an alphabetic identifier that will be used to
+% identify the index in other macros that reference it.
+% The \Meta{filename} should be a string that, when appended with an
+% extension, constitutes a valid filename on the system.
+% Auxiliary files named \Meta{filename}|.sxd| and \Meta{filename}|.sbx|
+% are generated during the automatic index generation process.
+% For example:
%
% \begin{codeblock}
-% |\transpose{|\meta{n}|}|
+% |\newindex{mainindex}{idxfile}|
% \end{codeblock}
%
% \noindent
-% somewhere between the song's \mac{beginsong} line and the first chord to
-% be transposed.
-% For example, if a song's first chord is |\[D]|\eat\], and the line
-% |\transpose{2}| appears before it, then the chord appears as an
-% \chord{E} in the resulting document.
-% Specifying a negative number for \meta{n} transposes subsequent chords
-% down instead of up.
-%
-% The |\transpose| macro affects all chords appearing after it until the
-% \mac{endsong} line.
-% If two |\transpose| macros appear in the same song, their effects are
-% cumulative.
-%
-% When the \env{transposecapos} option is active, the \mac{capo}
-% macro acts like |\transpose|.
-% See \S\ref{sec:notes} for more information.
-%
-% \paragraph{Enharmonics.}
-% \DescMacro{preferflats}
-% \DescMacro{prefersharps}
-% When using \mac{transpose} to automatically transpose the chords of a song,
-% the \Songs\ package code chooses between enharmonically equivalent
-% names for ``black key'' notes based on the first chord of the song.
-% For example, if |\transpose{1}| is used, and if the first chord of the
-% song is an \chord{E}, then all \chord{A} chords that appear in
-% the song are transcribed as \chord{B\flt} chords rather than
-% \chord{A\shrp} chords, since the key of \chord{F}-major (\chord{E}
-% transposed up by one half-step) has a flatted key signature.
-% Usually this guess produces correct results, but if not, you can use
-% either |\preferflats| or |\prefersharps| after the \mac{transpose} line
-% to force all transcription to use flatted names or sharped names
-% respectively, when resolving enharmonic equivalents.
+% creates a title index named ``|mainindex|'' whose data is
+% stored in files named |idxfile.sxd| and |idxfile.sbx|.
%
-% \paragraph{Modulated Verses.}
-% Automatic transposition can be used in conjunction with chord-replaying
-% (see \S\ref{sec:chords}) to produce modulated verses.
-% For example,
+% \DescMacro{showindex}
+% To display the index in the document, use:
%
% \begin{codeblock}
-% \mac{beginverse}\mac{memorize}
-% |\[F#]This is a \[B/F#]memorized \[F#]verse. \[E&7]|\eat\]
-% \mac{endverse}
-% \mac{transpose}|{2}|
-% \mac{beginverse}
-% |^This verse is ^modulated up two ^half-steps.|
-% \mac{endverse}
+% |\showindex[|\Meta{columns}|]{|\Meta{title}|}{|\Meta{id}|}|
% \end{codeblock}
%
-% \noindent produces
-%
-% \begin{chorded}\memorize
-% \[F#]This is a \[B/F#]memorized \[F#]verse. \[E&7]\eat\]
-% \vskip5pt\replay\transpose{2}%
-% ^This verse is ^modulated up two ^half-steps.
-% \transpose{-2}%
-% \end{chorded}
-%
-% \paragraph{Both Keys.}
-% \DescMacro{trchordformat}
-% By default, when chords are automatically transposed using \mac{transpose},
-% only the transposed chords are printed.
-% However, in some cases you may wish to print the old chords and the
-% transposed chords together so that musicians playing transposing and
-% non-transposing instruments can play from the same piece of music.
-% This can be achieved by redefining the |\trchordformat| macro, which
-% receives two arguments---the original chord name and the transposed chord
-% name, respectively.
-% For example, to print the old chord above the new chord above each lyric,
-% define
+% \noindent
+% where \Meta{id} is the same identifier used in the \mac{newindex},
+% \mac{newauthorindex}, or \mac{newscripindex} command, and where
+% the \Meta{title} is the title of the index, which should consist only of
+% simple text (no font or formatting macros, since those cannot be used in
+% pdf bookmark indexes).
+% The |[|\Meta{columns}|]| part is optional; if specified it dictates the
+% number of columns if the index can't fit in a single column.
+% For example, for a 2-column title index, write:
%
% \begin{codeblock}
-% |\renewcommand{\trchordformat}[2]{\vbox{\hbox{#1}\hbox{#2}}}|
+% |\showindex[2]{Index of Song Titles}{mainindex}|
% \end{codeblock}
%
-% \paragraph{Changing Note Names.}
-% \DescMacro{solfedge}
-% \DescMacro{alphascale}
-% In many countries it is common to use the solfedge names for the notes of
-% the scale (\chord{LA, SI, DO, RE, MI, FA, SOL\/}) instead of the
-% alphabetic names (\chord{A, B, C, D, E, F, G\/}).
-% By default, the transposition logic only understands alphabetic names, but
-% you can tell it to look for solfedge names by typing |\solfedge|.
-% To return to alphabetic names, type |\alphascale|.
+% \subsection{Index Entries}\label{sec:ientry}
%
-% \DescMacro{notenames}
-% You can use other note names as well.
-% To define your own note names, type
+% Every song automatically gets entries in the current \env{songs}
+% environment's list of title index(es) (see \S\ref{sec:songs}).
+% However, you can also add extra index entries for a song to any index.
+%
+% \paragraph{Indexing Lyrics.}
+% \DescEnv{index=}
+% For example, title indexes often have entries for memorable lines
+% of lyrics in a song in addition to the song's title.
+% You can add an index entry for the current song to the section's
+% title index(es) by adding |index={|\Meta{lyrics}|}| to the song's
+% \mac{beginsong} line.
+% For example,
%
% \begin{codeblock}
-% |\notenames{|\meta{nameA}|}{|\meta{nameB}|}|$\ldots$|{|\meta{nameG}|}|
+% \mac{beginsong}|{Doxology}|
+% | [index={Praise God from Whom all blessings flow}]|
% \end{codeblock}
%
% \noindent
-% where each of \meta{nameA} through \meta{nameG} must consist entirely of
-% a sequence of one or more \emph{uppercase} letters.
-% For example, some solfedge musicians use \chord{TI} instead of \chord{SI}
-% for the second note of the scale.
-% To automatically transpose such music, use:
-%
-% \begin{codeblock}
-% |\notenames{LA}{TI}{DO}{RE}{MI}{FA}{SOL}|
-% \end{codeblock}
+% causes the song to be indexed both as ``\textit{Doxology}'' and as
+% ``Praise God from Whom all blessings flow'' in the section's title index(es).
+% You can use |index=| multiple times in a \mac{beginsong} line to produce
+% multiple additional index entries.
+% Index entries produced with |index={|\Meta{lyrics}|}| are
+% typeset in an upright font instead of in italics to distinguish
+% them from song titles.
%
-% \DescMacro{notenamesin}
-% \DescMacro{notenamesout}
-% The \Songs\ package can also automatically convert one set of note names
-% to another.
-% For example, suppose you have a large song book in which chords have been
-% typed using alphabetic note names, but you wish to produce a book that
-% uses the equivalent solfedge names.
-% You could achieve this by using the |\notenamesin| macro to tell the
-% \Songs\ package which note names you typed in the input file, and then
-% using |\notenamesout| to tell the \Songs\ package how you want it to
-% typeset each note name in the output file.
-% The final code looks like this:
+% \paragraph{Indexing Extra Song Titles.}
+% \DescEnv{ititle=}
+% To add a regular index entry typeset in italics to the title
+% index(es), use:
%
% \begin{codeblock}
-% |\notenamesin{A}{B}{C}{D}{E}{F}{G}|
-% |\notenamesout{LA}{SI}{DO}{RE}{MI}{FA}{SOL}|
+% |ititle={|\Meta{title}|}|
% \end{codeblock}
%
% \noindent
-% The syntaxes of |\notenamesin| and |\notenamesout| are identical to that
-% of \mac{notenames} (see above), except that the arguments of |\notenamesout|
-% can consist of any \LaTeX\ code that is legal in horizontal mode, not just
-% uppercase letters.
+% in the \mac{beginsong} line instead.
+% Like \env{index=} keyvals, |ititle=| can be used multiple times to produce
+% multiple additional index entries.
%
-% To stop converting between note names, use \mac{alphascale}, \mac{solfedge},
-% or \mac{notenames} to reset all note names back to identical input and
-% output scales.
+% \DescMacro{indexentry}
+% \DescMacro{indextitleentry}
+% You can also create index entries by saying
+% |\indexentry[|\Meta{indexes}|]{|\Meta{lyrics}|}| (which creates an
+% entry like \env{index=}) or
+% |\indextitleentry[|\Meta{indexes}|]{|\Meta{title}|}| (which
+% creates an entry like \env{ititle=}).
+% These two macros can be used anywhere between the song's \mac{beginsong}
+% and \mac{endsong} lines, and can be used multiple times to produce
+% multiple entries.
+% If specified, \Meta{indexes} is a comma-separated list of the identifiers
+% of indexes to which the entry should be added.
+% Otherwise the new entry is added to all of the title indexes for the current
+% \env{songs} environment.
%
-% \paragraph{Transposing Chords In Macros.}
-% \DescMacro{transposehere}
-% The automatic transposition logic won't find chord names that are hidden
-% inside macro bodies.
-% For example, if you abbreviate a chord by typing,
+% \subsection{Compiling}\label{sec:compiling}
+%
+% As with a typical \LaTeX{} document, compiling a song book document with
+% indexes requires three steps.
+% First, use \LaTeX{} (|pdflatex| is recommended) to generate auxiliary files
+% from the |.tex| file:
%
% \begin{codeblock}
-% |\newcommand{\mychord}{F|\mac{shrp}| sus4/C|\mac{shrp}|}|
-% \mac{transpose}|{4}|
-% |\[\mychord]|\eat\]
+% |pdflatex mybook.tex|
% \end{codeblock}
%
-% \noindent
-% then the \mac{transpose} macro fails to transpose it; the
-% resulting chord is still an \chord{F\shrp sus4/C\shrp} chord.
-% To fix the problem, you can use |\transposehere| in your macros to
-% explicitly invoke the transposition logic on chord names embedded in
-% macro bodies.
-% The above example could be corrected by instead defining:
+% Second, use the |songidx.lua| script to generate an index for each index that
+% you declared with \mac{newindex}, \mac{newauthorindex}, or
+% \mac{newscripindex}.
+% The script can be launched using Lua\TeX, using the following syntax:
%
% \begin{codeblock}
-% |\newcommand{\mychord}{\transposehere{F|\mac{shrp}| sus4/C|\mac{shrp}|}}|
+% |texlua songidx.lua |\textcolor{black}{[}|-b| \Meta{canon}|.can|\textcolor{black}{]} \Meta{filename}|.sxd| \Meta{filename}|.sbx|
% \end{codeblock}
%
-% \DescMacro{notrans}
-% Transposition can be suppressed within material that would otherwise be
-% transposed by using the |\notrans| macro.
-% For example, writing
+% \noindent
+% where \Meta{filename} is the same \Meta{filename} that was used in the
+% \mac{newindex}, \mac{newauthorindex}, or \mac{newscripindex} macro.
+% If the index was declared with \mac{newscripindex}, then the |-b| option
+% is used to specify which version of the bible you wish to use as a basis
+% for sorting your scripture index.
+% The \Meta{canon} part can be any of the |.can| files provided with
+% the |songidx| distribution.
+% If you are using a Protestant, Catholic, or Greek Orthodox Christian bible
+% with book names in English, then the |bible.can| canon file should work
+% well.
+% For other bibles, you should create your own |.can| file by copying and
+% modifying one of the existing |.can| files.
+%
+% For example, if your song book |.tex| file contains the lines
%
% \begin{codeblock}
-% \mac{transposehere}|{G = \notrans{G}}|
+% \mac{newindex}|{titleidx}{titlfile}|
+% \mac{newauthorindex}|{authidx}{authfile}|
+% \mac{newscripindex}|{scripidx}{scrpfile}|
% \end{codeblock}
%
% \noindent
-% would typeset a transposed \chord{G} followed by a non-transposed
-% \chord{G} chord.
-% This does not suppress note name conversion (see \mac{notenames}).
-% To suppress both transposition and note name conversion, just use
-% braces (e.g., |{G}| instead of |\notrans{G}|).
-%
-% \paragraph{Transposing Guitar Tablatures.}
-% \DescMacro{gtabtrans}
-% The songs package cannot automatically transpose tablature diagrams
-% (see \S\ref{sec:tablatures}).
-% Therefore, when automatic transposition is taking place, only the chord
-% names of \mac{gtab} macros are displayed (and transposed); the diagrams
-% are omitted.
-% To change this default, redefine the |\gtabtrans| macro, whose two
-% arguments are the two arguments to \mac{gtab}.
-% For example, to display original tablatures without transposing them even
-% when transposition has been turned on, write
+% then to generate indexes sorted according to a Christian English bible,
+% execute:
%
% \begin{codeblock}
-% |\renewcommand{\gtabtrans}[2]{|\mac{gtab}|{|\mac{notrans}|{#1}}{#2}}|
+% |texlua songidx.lua titlfile.sxd titlfile.sbx|
+% |texlua songidx.lua authfile.sxd authfile.sbx|
+% |texlua songidx.lua -b bible.can scrpfile.sxd scrpfile.sbx|
% \end{codeblock}
%
-% \noindent
-% To transpose the chord name but not the diagram under it, replace
-% \mac{notrans}|{#1}| with simply |#1| in the above.
-% To restore the default behavior, write
+% Once the indexes are generated, generate the final book by invoking
+% \LaTeX{} one more time:
%
% \begin{codeblock}
-% |\renewcommand{\gtabtrans}[2]{|\mac{transposehere}|{#1}}|
+% |pdflatex mybook.tex|
% \end{codeblock}
%
% \section{Customizing the Book}
@@ -2373,21 +2427,26 @@
%
% \DescMacro{stitlefont}
% Song titles are typeset in a sans-serif, slanted font by default
-% (sans-serif, upright if producing slides).
+% (sans-serif, upright if producing slides), with minimal line spacing.
% You can change this default by redefining |\stitlefont|.
-% For example, to cause titles to be typeset in a roman font, you could
-% define
+% For example, to cause titles to be typeset in a roman font with lines
+% spaced 20 points apart, you could define
%
% \begin{codeblock}
-% |\renewcommand{\stitlefont}{\rmfont\Large}|
+% |\renewcommand{\stitlefont}{|
+% | \rmfont\Large\baselineskip=20pt\lineskiplimit=0pt|
+% |}|
% \end{codeblock}
%
% \DescMacro{versefont}
% \DescMacro{chorusfont}
+% \DescMacro{meterfont}
+% \DescMacro{echofont}
% \DescMacro{notefont}
-% You can apply additional font changes to verses, choruses, and
-% textual notes produced with \mac{textnote} and \mac{musicnote} by
-% redefining |\versefont|, |\chorusfont|, and |\notefont|, respectively.
+% You can apply additional font changes to verses, choruses, meter numbers,
+% echo parts produced with \mac{echo}, and textual notes produced with
+% \mac{textnote} and \mac{musicnote}, by redefining |\versefont|,
+% |\chorusfont|, |\meterfont|, |\echofont|, and |\notefont|, respectively.
% For example, to typeset choruses in italics, you could define
%
% \begin{codeblock}
@@ -2469,7 +2528,7 @@
%
% \DescMacro{baselineadj}
% The vertical distance between the baselines of consecutive lines of
-% lyrics is computed by the \Songs\ package based on several factors
+% lyrics is computed by the \Songs{} package based on several factors
% including the lyric font size, the chord font size (if in \env{chorded}
% mode), and whether \env{slides} mode is currently active.
% You can adjust the results of this computation by redefining skip
@@ -2485,7 +2544,7 @@
% \DescMacro{clineparams}
% To change the vertical distance between chords and the lyrics below them,
% redefine the |\clineparams| macro with a definition that adjusts the
-% \LaTeX\ parameters |\baselineskip|, |\lineskiplimit|, and |\lineskip|.
+% \LaTeX{} parameters |\baselineskip|, |\lineskiplimit|, and |\lineskip|.
% For example, to cause the baselines of chords and their lyrics to be
% 12 points apart with at least 1 point of space between the bottom of the
% chord and the top of the lyric, you could write:
@@ -2566,7 +2625,7 @@
% For complete control over the appearance of the header and footer material
% that precedes and concludes each song, you can redefine the macros
% |\makeprelude| and |\makepostlude|.
-% When typesetting a song, the \Songs\ package code invokes both of these
+% When typesetting a song, the \Songs{} package code invokes both of these
% macros once (after processing all the material between the \mac{beginsong}
% and \mac{endsong} lines), placing the results within vboxes.
% The resulting vboxes are placed atop and below the song content.
@@ -2575,6 +2634,21 @@
% |\makepostlude| displays the song's copyright and licensing information in
% fine print.
%
+% As a simple example, the following causes each song to start with its
+% number and title(s), centered, in a large, boldface font, and then centers
+% the rest of the prelude material (e.g., references and authors) below that
+% (using \mac{extendprelude}).
+%
+% \begin{codeblock}
+% |\renewcommand\makeprelude{%|
+% | |\mac{resettitles}
+% | \centering|
+% | {\Large\bfseries|\mac{thesongnum}|. |\mac{songtitle}|\par|
+% | |\mac{nexttitle}\mac{foreachtitle}|{(|\mac{songtitle}|)\par}}%|
+% | |\mac{extendprelude}
+% |}|
+% \end{codeblock}
+%
% \paragraph{Page- and Column-breaking.}
% \DescMacro{vvpenalty}
% \DescMacro{ccpenalty}
@@ -2591,7 +2665,7 @@
% a verse, respectively;
% and penalties of value |\brkpenalty| are inserted wherever \mac{brk} is
% used on a line by itself.
-% The higher the penalty, the less likely \TeX\ is to place a
+% The higher the penalty, the less likely \TeX{} is to place a
% page- or column-break at that site.
% If any are set to $-10000$ or lower, breaks are forced there.
% By default, |\interlinepenalty| is set to 1000 and the rest are set to 200
@@ -2621,7 +2695,7 @@
% \DescMacro{chorusjustify}
% \DescMacro{justifyleft}
% \DescMacro{justifycenter}
-% To cause verse or chorus text to be justified flush-left or centered, set
+% To left-justify or center the lines of verses or choruses, redefine
% |\versejustify| or |\chorusjustify| to |\justifyleft| or |\justifycenter|,
% respectively.
% For example, to cause choruses to be centered, one could type:
@@ -2686,14 +2760,14 @@
% For example, a musician's chord book might include extra verses with
% alternate chordings.
%
-% \DescMacroGroup{if}{if...}{ifchorded,iflyric,ifslides,ifpartiallist,ifsongindexes,ifmeasures,ifpdfindex,ifrawtext,iftranscapos,ifnolyrics,ifvnumbered}
-% A conditional block begins with a macro named |\if|\meta{type}, where
-% \meta{type} is one of the types listed in the first column of
+% \DescMacroGroup{if}{if...}{ifchorded,iflyric,ifslides,ifpartiallist,ifsongindexes,ifmeasures,ifrawtext,iftranscapos,ifnolyrics,ifpagepreludes,ifvnumbered}
+% A conditional block begins with a macro named |\if|\Meta{type}, where
+% \Meta{type} is one of the types listed in the first column of
% Table~\ref{tab:conditionals}.
% \begin{table}
% \newcommand\tablerule{\noalign{\hrule}}
-% \newskip\oldbaselineskip \oldbaselineskip\baselineskip
-% \newskip\oldlineskip \oldlineskip\lineskip
+% \newlength\oldbaselineskip \oldbaselineskip\baselineskip
+% \newlength\oldlineskip \oldlineskip\lineskip
% \newdimen\oldlineskiplimit \oldlineskiplimit\lineskiplimit
% \newcommand\oninterlineskip{%
% \baselineskip\oldbaselineskip
@@ -2711,30 +2785,30 @@
% a partial list of songs&\cr\tablerule
% &|songindexes|&&the \env{noindexes} option is not active&\cr\tablerule
% &|measures|&&the \env{nomeasures} option is not active&\cr\tablerule
-% &|pdfindex|&&the \env{nopdfindex} option is not active&\cr\tablerule
% &|rawtext|&&the \env{rawtext} option is active&\cr\tablerule
% &|transcapos|&&the \env{transposecapos} option is active&\cr\tablerule
% &|nolyrics|&&the \mac{nolyrics} macro is in effect&\cr\tablerule
+% &|pagepreludes|&&the \mac{pagepreludes} macro is in effect&\cr\tablerule
% &|vnumbered|&&the current verse is numbered (i.e., it was started
% with \mac{beginverse} instead of \mac{beginverse}|*|)&\cr}
% \hrule}
% \caption{Conditional macros}\label{tab:conditionals}
% \end{table}
% The conditional block concludes with the macro |\fi|.
-% Between the |\if|\meta{type} and the |\fi| may also appear an |\else|.
+% Between the |\if|\Meta{type} and the |\fi| may also appear an |\else|.
% For example, in the construction
%
% \begin{codeblock}
% |\ifchorded|
-% \quad\meta{A}
+% \quad\Meta{A}
% |\else|
-% \quad\meta{B}
+% \quad\Meta{B}
% |\fi|
% \end{codeblock}
%
% \noindent
-% material \meta{A} is only included if the \env{chorded} option is active,
-% and material \meta{B} is only included if the \env{chorded} option is not
+% material \Meta{A} is only included if the \env{chorded} option is active,
+% and material \Meta{B} is only included if the \env{chorded} option is not
% active.
%
% \subsection{Page Layout}\label{sec:layout}
@@ -2781,10 +2855,18 @@
% (see \mac{songpos} below).
% \item Indexes produced with \mac{showindex} are typeset to the width of
% the enclosing environment.
-% Thus, you should be sure to reset \LaTeX\ back to one column (via
+% Thus, you should be sure to reset \LaTeX{} back to one column (via
% |\onecolumn|) before executing \mac{showindex}.
% \end{itemize}
%
+% \DescMacro{pagepreludes}
+% Song preludes (i.e., the material atop each song, including the title) are
+% typeset by default at column width.
+% Writing |\pagepreludes| typesets subsequent preludes at page width atop
+% fresh pages, with the rest of the song in multiple columns beneath its title.
+% (To prohibit separation of songs from their preludes, it also sets
+% \mac{songpos} to 0.)
+%
% \DescMacro{columnsep}
% The horizontal distance between consecutive columns is controlled by
% the |\columnsep| dimension.
@@ -2795,7 +2877,7 @@
% \end{codeblock}
%
% \DescMacro{colbotglue}
-% When \LaTeX\ ends each column it inserts glue equal to |\colbotglue|.
+% When \LaTeX{} ends each column it inserts glue equal to |\colbotglue|.
% In lyric books this macro is set to |0pt| so that each column ends flush with
% the bottom of the page.
% In other books that have ragged bottoms, it is set to stretchable
@@ -2819,14 +2901,14 @@
% \end{codeblock}
%
% \DescMacro{songpos}
-% The \Songs\ package uses a song-positioning algorithm that
+% The \Songs{} package uses a song-positioning algorithm that
% moves songs to the next column or page in order to avoid column- or
% page-breaks within songs.
% The algorithm has four levels of aggressiveness, numbered from 0 to 3.
% You can change the aggressiveness level by typing
%
% \begin{codeblock}
-% |\songpos{|\meta{level}|}|
+% |\songpos{|\Meta{level}|}|
% \end{codeblock}
%
% \noindent
@@ -2838,7 +2920,7 @@
% songs.
% Level 1 avoids only page-turns within songs.
% Level 0 turns off the song-positioning algorithm entirely.
-% This causes songs to be positioned wherever \TeX\ thinks is best
+% This causes songs to be positioned wherever \TeX{} thinks is best
% based on penalty settings (see \mac{vvpenalty} and \mac{spenalty}).
%
% \DescMacro{spenalty}
@@ -2852,25 +2934,20 @@
%
% \subsection{Indexes}\label{sec:idxcust}
%
-% \paragraph{Index Appearance.}
-% \DescMacro{indexsongsas}
-% By default, the right-hand side of each index entry contains a list of
-% one or more song numbers.
-% To instead list page numbers, use the |\indexsongsas| macro:
+% \subsubsection{Index Appearance}
+%
+% \paragraph{Index Titles.}
+% To customize the appearance of index titles, redefine the \mac{songsection}
+% and/or \mac{songchapter} macros from \S\ref{sec:sectioning}.
+% For example, to use \LaTeX's built-in |\section| and |\chapter| macros
+% instead, you could write:
%
% \begin{codeblock}
-% |\indexsongsas{|\meta{id}|}{\thepage}|
+% |\renewcommand{|\mac{songchapter}|}{\chapter}|
+% |\renewcommand{|\mac{songsection}|}{\section}|
% \end{codeblock}
%
-% \noindent
-% where \meta{id} is the same identifier used in the \mac{newindex},
-% \mac{newauthorindex}, or \mac{newscripindex} macro that created the index.
-% The second argument must always be something that expands into raw text
-% without any formatting, since this text gets output to auxiliary files that
-% are lexographically sorted by the index-generation program.
-% To go back to indexing songs by song number, use \mac{thesongnum} in place
-% of |\thepage| in the above.
-%
+% \paragraph{Layout and page divisions.}
% \DescMacro{sepindexestrue}
% \DescMacro{sepindexesfalse}
% Indexes are by default typeset on separate pages, and when an index is
@@ -2880,6 +2957,18 @@
% starting unnecessary new pages.
% To re-enable the defaults, use |\sepindexestrue|.
%
+% \DescMacro{idxheadwidth}
+% The |\idxheadwidth| length defines the width of the shaded boxes that
+% begin each alphabetic block of a large title index.
+% Setting it to 0pt suppresses the boxes entirely.
+% For example, to set the width of those boxes to 1 centimeter, you could
+% define
+%
+% \begin{codeblock}
+% |\setlength{\idxheadwidth}{1cm}|
+% \end{codeblock}
+%
+% \paragraph{Fonts and colors.}
% \DescMacro{idxrefsfont}
% To control the formatting of the list of references on the right-hand side
% of index entries, redefine |\idxrefsfont|.
@@ -2922,16 +3011,6 @@
% |\renewcommand{\idxbgcolor}{red}|
% \end{codeblock}
%
-% \DescMacro{idxheadwidth}
-% The |\idxheadwidth| length defines the width of the shaded boxes that
-% begin each alphabetic block of a large title index.
-% For example, to set the width of those boxes to 1 centimeter, you could
-% define
-%
-% \begin{codeblock}
-% |\setlength{\idxheadwidth}{1cm}|
-% \end{codeblock}
-%
% \DescMacro{idxauthfont}
% The font used to typeset entries of an author index is controlled by
% |\idxauthfont|.
@@ -2963,16 +3042,119 @@
% \DescMacro{idxcont}
% In a scripture index, when a column break separates a block of entries
% devoted to a book of the bible, the new column is titled
-% ``\meta{bookname} (continued)'' by default.
+% ``\Meta{bookname} (continued)'' by default.
% You can change this default by redefining the |\idxcont| macro, which
-% receives the \meta{bookname} as its single argument.
+% receives the \Meta{bookname} as its single argument.
% For example, to typeset an index in German, one might define
%
% \begin{codeblock}
% |\renewcommand{\idxcont}[1]{\small\textbf{#1} (fortgefahren)}|
% \end{codeblock}
%
-% \paragraph{Alphabetization Options.}
+% \subsubsection{Entry References}
+%
+% \DescMacro{indexsongsas}
+% By default, the right-hand side of each index entry contains a list of
+% one or more song numbers.
+% To instead list page numbers, use the |\indexsongsas| macro:
+%
+% \begin{codeblock}
+% |\indexsongsas{|\Meta{id}|}{\thepage}|
+% \end{codeblock}
+%
+% \noindent
+% where \Meta{id} is the same identifier used in the \mac{newindex},
+% \mac{newauthorindex}, or \mac{newscripindex} macro that created the index.
+% The second argument must always be something that expands into raw text
+% without any formatting, since this text gets output to auxiliary files that
+% are lexographically sorted by the index-generation program.
+% To go back to indexing songs by song number, use \mac{thesongnum} in place
+% of |\thepage| in the above.
+%
+% \subsubsection{PDF Bookmarks and Links}
+%
+% \DescMacro{songtarget}
+% \DescMacro{songlink}
+% Each \mac{beginsong} environment adds a PDF bookmark (if generating a PDF)
+% and hyperlink target (if using the |hyperref| package) for the
+% song by invoking |\songtarget| with two arguments:
+% (1) a suggested PDF bookmark level, and (2) a link target name.
+% Links in indexes to these targets are created by |\songlink|, which
+% also gets two arguments:
+% (1) the link target name (same as the second argument to \mac{songtarget}),
+% and (2) the text to be linked.
+%
+% Redefine these macros to customize or suppress these bookmarks, targets,
+% and links.
+% For example, to enable both bookmarks and links (the default behavior) use:
+%
+% \begin{codeblock}
+% |\renewcommand{\songtarget}[2]|
+% | {\pdfbookmark[#1]{|\mac{thesongnum}|. |\mac{songtitle}|}{#2}}|
+% |\renewcommand{\songlink}[2]{\hyperlink{#1}{#2}}|
+% \end{codeblock}
+%
+% \noindent
+% To enable links but not bookmarks, use:
+%
+% \begin{codeblock}
+% |\renewcommand{\songtarget}[2]{\hypertarget{#2}{\relax}}|
+% |\renewcommand{\songlink}[2]{\hyperlink{#1}{#2}}|
+% \end{codeblock}
+%
+% \noindent
+% To disable both bookmarks and links, use:
+%
+% \begin{codeblock}
+% |\renewcommand{\songtarget}[2]{}|
+% |\renewcommand{\songlink}[2]{#2}|
+% \end{codeblock}
+%
+% \subsubsection{Sort Order}
+%
+% The alphabetic ordering of entries in title and author indexes is dictated
+% by the computer system on which the \Songs{} software is installed.
+% Different languages and regions have different sorting conventions, so the
+% |songidx| Lua script delegates decisions about order to your operating system.
+% If the default ordering proves inadequate, you can modify it by changing your
+% operating system's \emph{locale} (see your system's local help files).
+% Alternatively, you can explicitly tell the |songidx| program which locale to
+% use in one of three ways:
+%
+% \begin{itemize}
+% \item \emph{Windows:}
+% Edit the |generate.bat| file in the |Sample| folder (or your working folder)
+% with any plain text editor (e.g., Vim or Notepad).
+% Near the top, find the line that says |SET locale=|.
+% After the |=|, type any valid locale name.
+% For a list of valid locale names on Windows, please see the ``Language name
+% abbreviation'' column of Microsoft's online National Language Support (NLS)
+% API Reference:
+%
+% {\centering\url{http://msdn.microsoft.com/en-us/goglobal/bb896001.aspx}\par}
+%
+% \item \emph{Unix:}
+% Create an environment variable named |SONGIDX_LOCALE| and set it equal to
+% the desired locale name.
+% The command |locale -a| lists all valid locale names on most Unix systems.
+%
+% \item \emph{Command-line:}
+% If you are executing the |songidx| script manually, use the |-l| option to
+% specify the locale:
+%
+% \begin{codeblock}
+% |texlua songidx -l sv_SE myindex.sxd myindex.sbx|
+% \end{codeblock}
+%
+% \end{itemize}
+%
+% \subsubsection{Special Words In Song Info}
+%
+% The following macros control how certain keywords are treated when parsing
+% and sorting index entries.
+% They only affect indexes that have already been declared, so put them
+% strictly after all your index creation commands (see \S\ref{sec:indexes}).
+%
% \DescMacro{titleprefixword}
% In English, when a title begins with ``The'' or ``A'', it is traditional to
% move these words to the end of the title and sort the entry by the following
@@ -2996,10 +3178,9 @@
% This macro may only be used in the document preamble but may be used
% multiple times to declare multiple prefix words.
%
-% \paragraph{Special Words In Song Info.}
% \DescMacro{authsepword}
% When parsing author index entries, the word ``and'' is recognized by the
-% |songidx| program as a conjunctive that separates author names.
+% |songidx| script as a conjunctive that separates author names.
% To override this default and specify a different conjunctive, use the
% |\authsepword| macro one or more times in the document preamble.
% For example, to instead treat ``und'' as a conjunctive, you could say,
@@ -3012,9 +3193,6 @@
% The first use of |\authsepword| and each of the following macros overrides
% the default, so if you also want to continue to treat ``and'' as a
% conjunctive, you must also say |\authsepword{and}| explicitly.
-% The |\authsepword| macro and each of the following macros may only be used
-% in the document preamble but may be used multiple times to declare multiple
-% special words.
%
% \DescMacro{authbyword}
% When parsing author index entries, the word ``by'' is recognized as a
@@ -3052,15 +3230,15 @@
% The headers and footers are then defined so as to refer to the first
% and/or last invisible mark that ends up on each page once the document
% is divided into pages.
-% This section describes the marks made available by the \Songs\ package.
+% This section describes the marks made available by the \Songs{} package.
% For more detailed information about the marks already provided by
-% \LaTeX\ and how to use them, consult any \LaTeX\ user manual.
+% \LaTeX{} and how to use them, consult any \LaTeX{} user manual.
%
% \DescMacro{songmark}
% \DescMacro{versemark}
% \DescMacro{chorusmark}
% To add song information to page headings and footers, redefine |\songmark|,
-% |\versemark|, or |\chorusmark| to add the necessary \TeX\ marks to the
+% |\versemark|, or |\chorusmark| to add the necessary \TeX{} marks to the
% current page whenever a new song, verse, or chorus begins.
% These macros expect no arguments; to access the current song's
% information including titles, use the macros documented in
@@ -3084,19 +3262,19 @@
% To do so, use the |\newsongkey| macro, which has the syntax
%
% \begin{codeblock}
-% |\newsongkey{|\meta{keyname}|}{|\meta{initcode}|}[|\meta{default}|]{|\meta{setcode}|}|
+% |\newsongkey{|\Meta{keyname}|}{|\Meta{initcode}|}[|\Meta{default}|]{|\Meta{setcode}|}|
% \end{codeblock}
%
% \noindent
-% Here, \meta{keyname} is the name of the new key for the keyval,
-% \meta{initcode} is \LaTeX\ code that is executed at the start of each
+% Here, \Meta{keyname} is the name of the new key for the keyval,
+% \Meta{initcode} is \LaTeX{} code that is executed at the start of each
% \mac{beginsong} line before the \mac{beginsong} arguments are processed,
-% \meta{default} (if specified) is the default value used for the keyval when
-% \meta{keyname} appears in \mac{beginsong} without a value,
-% and \meta{setcode} is macro code that is executed whenever
-% \meta{key} is parsed as part of the \mac{beginsong} keyval arguments.
-% In \meta{setcode}, |#1| expands to the value given by the user for the
-% keyval (or to \meta{default} if no value was given).
+% \Meta{default} (if specified) is the default value used for the keyval when
+% \Meta{keyname} appears in \mac{beginsong} without a value,
+% and \Meta{setcode} is macro code that is executed whenever
+% \Meta{key} is parsed as part of the \mac{beginsong} keyval arguments.
+% In \Meta{setcode}, |#1| expands to the value given by the user for the
+% keyval (or to \Meta{default} if no value was given).
%
% For example, to define a new song key called |arr| which stores its
% value in a macro called |\arranger|, one could write:
@@ -3146,12 +3324,12 @@
%
% For more detailed information about keyvals and how they work, consult the
% documentation for David Carlisle's |keyval| package, which comes standard
-% with most \LaTeXe\ installations.
+% with most \LaTeXe{} installations.
%
% \subsection{Font Kerning Corrections}
%
% \paragraph{Chord Overstriking.}
-% In order to conserve space and keep songs readable, the \Songs\ package
+% In order to conserve space and keep songs readable, the \Songs{} package
% pushes chords down very close to the lyrics with which they are paired.
% Unfortunately, this can sometimes cause low-hanging characters in chord
% names to overstrike the lyrics they sit above.
@@ -3169,7 +3347,7 @@
% minimizes low-hanging symbols; but if you lack such a font, then the
% following trick works pretty well.
% Somewhere in the preamble of your document, you can write the following
-% \LaTeX\ code:
+% \LaTeX{} code:
%
% \begin{codeblock}
% |\renewcommand{\chordlocals}{\catcode`(\active|
@@ -3220,7 +3398,7 @@
%
% \paragraph{Scripture Font Quotation Marks.}
% \DescMacro{shiftdblquotes}
-% The \Songs\ package compensates for a kerning problem in the Zaph Chancery
+% The \Songs{} package compensates for a kerning problem in the Zaph Chancery
% font (used to typeset scripture quotations) by redefining the |``| and |''|
% token sequences to be active characters that yield double-quotes shifted
% 1.1 points and 2 points left, respectively, of their normal positions.
@@ -3291,7 +3469,7 @@
% (or sets |\songtitle| to |\relax| if there are no more titles).
%
% \DescMacro{foreachtitle}
-% The |\foreachtitle| macro accepts \LaTeX\ code as its single
+% The |\foreachtitle| macro accepts \LaTeX{} code as its single
% argument and executes it once for each (remaining) song title.
% Within the provided code, use |\songtitle| to get the current title.
% For example, the following code generates a comma-separated list of all
@@ -3312,97 +3490,11 @@
% songs to be extracted.
% Redefining it after the preamble may have unpredictable results.
%
-% \section{Index Generation}
-%
-% The material in this section describes macros provided by the \Songs\
-% package that are used during the automatic generation of the song book
-% indexes.
-% Since index generation is automatic, document authors should not
-% normally need to use any of these macros directly.
-% The documentation in this section is therefore provided purely for
-% completeness and for informational purposes.
-% For instructions on how to automatically generate indexes when compiling
-% a song book, see \S\ref{sec:compiling}.
-% For info on how to customize the appearance of indexes, see
-% \S\ref{sec:idxcust}.
-%
-% Automatic generation of song book indexes is a three stage process:
-%
-% \begin{enumerate}
-%
-% \item
-% Each time a song book \LaTeX\ file is compiled, an auxiliary file named
-% \meta{filename}|.sxd| is written out for each \meta{filename}
-% defined using \mac{newindex}, \mac{newauthorindex}, or \mac{newscripindex}.
-% These |.sxd| files are plain text files that can be viewed using any
-% standard text editor.
-% They begin with a line identifying the type of index (title, author, or
-% scripture) and then contain triples of lines, one triple for each song to
-% appear in the index.
-% The first line of a triple has the information by which the song is to be
-% indexed (a title, author, or scripture reference).
-% The second line has the song's number in the book (yielded by
-% \mac{thesongnum}).
-% The third line is an identifying label for the song used in hyperlinking.
-%
-% \item
-% Once the |.sxd| files have been generated, an external program is used
-% to transform each |.sxd| file into a |.sbx| file.
-% Since the standard |makeindex| program provided with \LaTeX\ is not powerful
-% enough to sort scripture references, distributions of \Songs\ package come
-% with a specialized |songidx| program to do this.
-%
-% \item
-% The |.sbx| files produced by the |songidx| program are then read
-% in by the \mac{showindex} macro next time the source document is
-% compiled using \LaTeX.
-% These |.sbx| files consist of the macros and environments described below.
-%
-% \end{enumerate}
-%
-% \DescEnv{idxblock}
-% In indexes that are blocked off into sections, one for each letter of the
-% alphabet, the \meta{filename}|.sbx| files generated for that index
-% consist of a series of |idxblock| environments, one for each such section.
-% An |idxblock| environment begins and ends with
-%
-% \begin{codeblock}
-% |\begin{idxblock}{|\meta{letter}|}|
-% $\vdots$
-% |\end{idxblock}|
-% \end{codeblock}
-%
-% \noindent
-% where \meta{letter} is the letter of the alphabet for that block.
-%
-% \DescMacro{idxentry}
-% \DescMacro{idxaltentry}
-% The index entries themselves are created by lines of the form
-%
-% \begin{codeblock}
-% |\idxentry{|\meta{leftside}|}{|\meta{rightside}|}|
-% |\indexaltentry{|\meta{leftside}|}{|\meta{rightside}|}|
-% \end{codeblock}
-%
-% \noindent
-% each of which creates an index entry with \meta{leftside} on the left,
-% followed by a series of dots, followed by \meta{rightside} on the
-% right.
-% The |\indexentry| macro is used for ``normal'' entries (e.g., titles in a
-% title index), and |\indexaltentry| is used for ``alternate'' entries
-% (e.g., lyric lines in a title index).
-%
-% Within \meta{rightside}, multiple items are separated with |\\|
-% macros instead of commas.
-% When used in an index |.sbx| file, the |\\| macro produces a comma followed
-% by some complex spacing that allows index lines to be broken suitably if
-% they are too long to fit in one physical line.
-%
% \section{Other Resources}
%
-% There are a number of other \LaTeX\ packages available for typesetting
+% There are a number of other \LaTeX{} packages available for typesetting
% songs, tablature diagrams, or song books.
-% Probably the best of these is the \Rath\ package by Christopher Rath
+% Probably the best of these is the \Rath{} package by Christopher Rath
% (\href{http://rath.ca/Misc/Songbook/}{{\tt http://rath.ca/Misc/Songbook/}}).
% Most of the differences between other packages and this one are intentional;
% the following is a summary of where I've adopted various differing design
@@ -3411,50 +3503,50 @@
% \bigskip
%
% \paragraph{Ease of Song Entry.}
-% Much of the \Songs\ package programming is devoted to easing the burden of
+% Much of the \Songs{} package programming is devoted to easing the burden of
% typing chords.
-% With most \LaTeX\ song book packages the user types chords using a standard
-% \LaTeX\ macro syntax like |\chord{|\meta{chord}|}{|\meta{lyric}|}|.
-% The \Songs\ package uses a less conventional
-% |\[|\meta{chord}|]|\meta{lyric}\eat\] syntax for several
+% With most \LaTeX{} song book packages the user types chords using a standard
+% \LaTeX{} macro syntax like |\chord{|\Meta{chord}|}{|\Meta{lyric}|}|.
+% The \Songs{} package uses a less conventional
+% |\[|\Meta{chord}|]|\Meta{lyric}\eat\] syntax for several
% reasons detailed below.
%
-% First, macros in the standard \LaTeX\ syntax require more key-presses
-% than macros in the \Songs\ package's syntax.
+% First, macros in the standard \LaTeX{} syntax require more key-presses
+% than macros in the \Songs{} package's syntax.
% This can become become very taxing when typing up a large book.
% Chords often appear as frequently as one per syllable, especially in hymns,
% so keeping the syntax as brief as possible is desirable.
%
-% Second, the standard \LaTeX\ macro syntax requires the user to estimate how
-% much of the \meta{lyric} will lie below the chord (because the \meta{lyric}
-% part must be enclosed in braces) whereas the \Songs\ package's syntax does
+% Second, the standard \LaTeX{} macro syntax requires the user to estimate how
+% much of the \Meta{lyric} will lie below the chord (because the \Meta{lyric}
+% part must be enclosed in braces) whereas the \Songs{} package's syntax does
% not.
% Estimating this accurately can be quite difficult, since in many cases the
-% \meta{lyric} part must include punctuation or multiple words to get proper
+% \Meta{lyric} part must include punctuation or multiple words to get proper
% results.
-% The \Songs\ package automates this for the user, significantly easing the
+% The \Songs{} package automates this for the user, significantly easing the
% task of chord-entry.
%
-% Third, unlike the standard \LaTeX\ chord syntax, the \Songs\ package's
+% Third, unlike the standard \LaTeX{} chord syntax, the \Songs{} package's
% syntax handles all hyphenation of chorded lyrics fully automatically.
% Extra hyphenation must be introduced in chord books wherever a chord
% is wider than the syllable it sits above.
-% With the standard \LaTeX\ chord syntax such hyphenation must be
+% With the standard \LaTeX{} chord syntax such hyphenation must be
% introduced manually by the user (usually via a special hyphenation macro),
-% but the \Songs\ package does this automatically.
+% but the \Songs{} package does this automatically.
%
% Fourth and finally, some other packages allow the user to use ``|b|''
-% in a \meta{chord} to produce a flat symbol, whereas the \Songs\ package
+% in a \Meta{chord} to produce a flat symbol, whereas the \Songs{} package
% requires an ``|&|'' instead.
% Using ``|b|'' is more intuitive but prevents the
-% use of ``|b|'' for any other purpose within a \meta{chord}, such as to
+% use of ``|b|'' for any other purpose within a \Meta{chord}, such as to
% produce a literal ``b'' or to type another macro name like |\hbox| that
% contains a ``b''.
-% Consequently, the \Songs\ package uses the less obvious ``|&|'' symbol to
+% Consequently, the \Songs{} package uses the less obvious ``|&|'' symbol to
% produce flat symbols.
%
% \paragraph{Song Structure.}
-% The \Songs\ package provides a relatively small number of macros for
+% The \Songs{} package provides a relatively small number of macros for
% typesetting high-level song structure, including verses, choruses,
% textual comments, and conditional macros that indicate that certain sections
% should go in chord books but not lyric books.
@@ -3465,7 +3557,7 @@
% users to learn.
%
% \paragraph{Multiple columns.}
-% The \Songs\ package was designed from the ground up to produce song books
+% The \Songs{} package was designed from the ground up to produce song books
% with many songs per page, arranged in multiple columns.
% As a result, it includes elaborate support for many features not found in
% most other packages, such as automatic column balancing, completely
@@ -3473,12 +3565,12 @@
% beautiful scripture quotations to fill in gaps between songs.
%
% \paragraph{Indexes.}
-% Another major feature of the \Songs\ package is its support for a variety
+% Another major feature of the \Songs{} package is its support for a variety
% of different index types, most notably indexes arranged by scripture
% reference.
% Scripture indexes can be invaluable for planning services around particular
% sermons or topics.
-% The \Songs\ package allows book authors to specify the names and preferred
+% The \Songs{} package allows book authors to specify the names and preferred
% ordering of books of the bible, and automatically handles complex issues
% like overlapping verse ranges to produce an easy-to-read, compact, and
% well-ordered index.
@@ -3486,26 +3578,26 @@
% notable lines of lyrics.
%
% \paragraph{Automatic Transposition.}
-% The \Songs\ package has a facility for automatically transposing songs, and
+% The \Songs{} package has a facility for automatically transposing songs, and
% even generating chord books that print the chords in multiple keys (e.g., so
% that a pianist and guitarist using a capo can play together from the same
% book).
%
% \bigskip
%
-% The \Songs\ package was developed entirely independently of all other
-% \LaTeX\ song book packages.
-% I originally developed the set of \LaTeX\ macros that eventually became
-% the \Songs\ package in order to typeset a song book for the Graduate
+% The \Songs{} package was developed entirely independently of all other
+% \LaTeX{} song book packages.
+% I originally developed the set of \LaTeX{} macros that eventually became
+% the \Songs{} package in order to typeset a song book for the Graduate
% Christian Fellowship (GCF) at Cornell University, and the Cornell
% International Christian Fellowship (CICF).
% Once I had fine-tuned my package to be sufficiently versatile, I decided
% to release it for public use.
-% At that time I noticed the \Rath\ package and others, and wrote this
+% At that time I noticed the \Rath{} package and others, and wrote this
% summary of the most prominent differences.
%
% For information on more song-typesetting resources for \LaTeX, I recommend
-% consulting the documentation provided with the \Rath\ package.
+% consulting the documentation provided with the \Rath{} package.
% It includes an excellent list of other resources that might be of interest
% to creators of song books.
%
@@ -3780,7 +3872,7 @@
% \clearpage
% \section{Implementation}
%
-% The following provides the verbatim implementation of the \Songs\ \LaTeX\
+% The following provides the verbatim implementation of the \Songs{} \LaTeX{}
% package, along with commentary on how it works.
% In general, macro names that contain a |@| symbol are not intended to be
% directly accessible by the outside world; they are for purely internal use.
@@ -3797,11 +3889,11 @@
% challenging features:
% \begin{itemize}
% \item Putting chords above lyrics fully automatically requires building an
-% entire lyric-parser in \LaTeX\ (see \S\ref{sec:lyricscan}).
+% entire lyric-parser in \LaTeX{} (see \S\ref{sec:lyricscan}).
% \item Avoiding page-turns within songs without prohibiting column-breaks
% requires building a completely new page-breaking algorithm
% (see \S\ref{sec:pagebuilder}).
-% \item The package must be able to generate an astonishing number of document
+% \item The package must be able to generate a daunting number of document
% variants from a common source: lyric-only books, chorded books, digital
% slides, transparency slides, selected song subsets, transposed songs, and
% combinations of the above.
@@ -3812,20 +3904,22 @@
%
% \subsection{Initialization}
%
-% The code in this section detects any \TeX\ versioning or configuration
+% The code in this section detects any \TeX{} versioning or configuration
% settings that are relevant to the rest of the song book code.
%
% \begin{macro}{\ifSB@etex}
-% Numerous enhancements are possible when using an $\varepsilon$-\TeX\
+% Numerous enhancements are possible when using an $\varepsilon$-\TeX{}
% compatible version of \LaTeX.
-% We start by checking to see if $\varepsilon$-\TeX\ primitives are
+% We start by checking to see whether $\varepsilon$-\TeX{} primitives are
% available.
% \begin{macrocode}
\newif\ifSB@etex
\ifx\eTeXversion\undefined\else
\ifx\eTeXversion\relax\else
\SB@etextrue
- \IfFileExists{etex.sty}{\RequirePackage{etex}}{}
+ \ifx\e@alloc\@undefined
+ \IfFileExists{etex.sty}{\RequirePackage{etex}}{}
+ \fi
\fi
\fi
% \end{macrocode}
@@ -3858,6 +3952,7 @@
% \end{macro}
%
% \begin{macro}{\ifSB@test}
+% \begin{macro}{\ifSB@testii}
% \begin{macro}{\SB@temp}
% \begin{macro}{\SB@tempii}
% \begin{macro}{\SB@tempiii}
@@ -3866,6 +3961,7 @@
% Reserve some control sequence names for scratch use.
% \begin{macrocode}
\newif\ifSB@test
+\newif\ifSB@testii
\newcommand\SB@temp{}
\newcommand\SB@tempii{}
\newcommand\SB@tempiii{}
@@ -3878,6 +3974,31 @@
% \end{macro}
% \end{macro}
% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\SB@newcount}
+% \begin{macro}{\SB@newdimen}
+% \begin{macro}{\SB@newbox}
+% \begin{macro}{\SB@newtoks}
+% \begin{macro}{\SB@newwrite}
+% Create macros for safely allocating count, dimen, box, token, and write
+% registers with detection for name-clashes.
+% For some reason, the default allocation macros provided by the \LaTeX{}
+% kernel do not detect name-clashes(!), which means that packages that use them
+% might accidentally overwrite our registers, causing all sorts of problems.
+% But at least we can do our best to avoid overwriting their registers.
+% \begin{macrocode}
+\newcommand\SB@newcount[1]{\@ifdefinable#1{\newcount#1}}
+\newcommand\SB@newdimen[1]{\@ifdefinable#1{\newdimen#1}}
+\newcommand\SB@newbox[1]{\@ifdefinable#1{\newbox#1}}
+\newcommand\SB@newtoks[1]{\@ifdefinable#1{\newtoks#1}}
+\newcommand\SB@newwrite[1]{\@ifdefinable#1{\newwrite#1}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
%
% \begin{macro}{\SB@dimen}
% \begin{macro}{\SB@dimenii}
@@ -3892,17 +4013,17 @@
% \begin{macro}{\SB@skip}
% Reserve some temp registers for various purposes.
% \begin{macrocode}
-\newdimen\SB@dimen
-\newdimen\SB@dimenii
-\newdimen\SB@dimeniii
-\newdimen\SB@dimeniv
-\newbox\SB@box
-\newbox\SB@boxii
-\newbox\SB@boxiii
-\newtoks\SB@toks
-\newcount\SB@cnt
-\newcount\SB@cntii
-\newskip\SB@skip
+\SB@newdimen\SB@dimen
+\SB@newdimen\SB@dimenii
+\SB@newdimen\SB@dimeniii
+\SB@newdimen\SB@dimeniv
+\SB@newbox\SB@box
+\SB@newbox\SB@boxii
+\SB@newbox\SB@boxiii
+\SB@newtoks\SB@toks
+\SB@newcount\SB@cnt
+\SB@newcount\SB@cntii
+\newlength\SB@skip
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -3916,12 +4037,30 @@
% \end{macro}
% \end{macro}
%
+% \begin{macro}{\SB@envbox}
+% Also reserve a slightly less volatile box register for per-environment use.
+% In scripture environments it holds the scripture citation.
+% In indexes it holds the index title text.
+% \begin{macrocode}
+\SB@newbox\SB@envbox
+% \end{macrocode}
+% \end{macro}
+%
% Load David Carlisle's |keyval| package for processing
-% \meta{key}=\meta{value} style macro arguments.
+% \Meta{key}=\Meta{value} style macro arguments.
% \begin{macrocode}
\RequirePackage{keyval}
% \end{macrocode}
%
+% \begin{macro}{\SB@app}
+% Utility macro: Append some text to the definition of another macro.
+% \begin{macrocode}
+\newcommand\SB@app[3]{%
+ \expandafter#1\expandafter#2\expandafter{#2#3}%
+}
+% \end{macrocode}
+% \end{macro}
+%
% \subsection{Default Parameters}\label{sec:impparams}
%
% This section defines macros and lengths that will typically be executed or
@@ -3941,7 +4080,7 @@
% Define the font style to use for formatting song titles.
% \begin{macrocode}
\newcommand\stitlefont{%
- \ifslides\sffamily\Huge\else\sffamily\slshape\Large\fi%
+ \sffamily\ifslides\Huge\else\slshape\Large\fi%
}
% \end{macrocode}
% \end{macro}
@@ -3949,17 +4088,34 @@
% \begin{macro}{\versefont}\MainImpl{versefont}
% \begin{macro}{\chorusfont}\MainImpl{chorusfont}
% \begin{macro}{\notefont}\MainImpl{notefont}
+% \begin{macro}{\meterfont}\MainImpl{meterfont}
% \changes{v2.1}{2007/08/02}{Added}
% By default, verses, choruses, and textual notes just allow the |\lyricfont|
% style to continue.
+% Meter numbers are in tiny, sans-serif, upright font.
+% Echo parts toggle slanted and upright fonts.
% \begin{macrocode}
\newcommand\versefont{}
\newcommand\chorusfont{}
\newcommand\notefont{}
+\newcommand\meterfont{\tiny\sffamily\upshape}
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\echofont}\MainImpl{echofont}
+% \changes{v2.18}{2014/06/28}{Added}
+% Echo parts toggle between oblique and upright shapes like |\emph|, but we
+% use |\slshape| instead of |\itshape| because it tends to look nicer with the
+% larger fonts used in slides mode.
+% \begin{macrocode}
+\newcommand\echofont{%
+ \ifdim\fontdimen\@ne\font>\z@\upshape\else\slshape\fi%
+}
+% \end{macrocode}
+% \end{macro}
%
% \begin{macro}{\scripturefont}\MainImpl{scripturefont}
% \changes{v1.13}{2005/05/12}{Added kerning correction for double-quote ligatures}
@@ -3986,7 +4142,7 @@
% \begin{macro}{\idxbgcolor}\MainImpl{idxbgcolor}
% Define the background color used for shaded boxes containing
% song numbers, textual notes, and index section headers, respectively.
-% To turn off all shading for a box type, use |\def|\meta{macroname}|{}|.
+% To turn off all shading for a box type, use |\def|\Meta{macroname}|{}|.
% \begin{macrocode}
\newcommand\snumbgcolor{SongbookShade}
\newcommand\notebgcolor{SongbookShade}
@@ -4000,7 +4156,7 @@
% \begin{macro}{\chorusjustify}\MainImpl{chorusjustify}
% \changes{v2.1}{2007/08/02}{Added}
% Verses and choruses are both left-justified with hanging indentation equal
-% to |\parindent|,
+% to |\parindent|.
% \begin{macrocode}
\newcommand\versejustify{\justifyleft}
\newcommand\chorusjustify{\justifyleft}
@@ -4119,8 +4275,8 @@
% \end{macrocode}
% \end{macro}
%
-% \label{sec:chordlocals}
% \begin{macro}{\chordlocals}\MainImpl{chordlocals}
+% \label{sec:chordlocals}
% This hook is expanded at the start of the scoping group that surrounds
% every chord name.
% Thus, it can be used to set any catcodes or definitions that should be
@@ -4136,7 +4292,7 @@
% it by the end of the document preamble, it gets redefined to something
% sensible based on other settings.
% \begin{macrocode}
-\newskip\versesep
+\newlength\versesep
\versesep123456789sp\relax
% \end{macrocode}
% \end{macro}
@@ -4147,9 +4303,9 @@
% and postlude material from the body of the song by adjusting the following
% two macros.
% \begin{macrocode}
-\newskip\afterpreludeskip
+\newlength\afterpreludeskip
\afterpreludeskip=2\p@\@plus4\p@
-\newskip\beforepostludeskip
+\newlength\beforepostludeskip
\beforepostludeskip=2\p@\@plus4\p@
% \end{macrocode}
% \end{macro}
@@ -4161,7 +4317,7 @@
% Setting this to zero accepts the default baseline distance computed by the
% songs package.
% \begin{macrocode}
-\newskip\baselineadj
+\newlength\baselineadj
\baselineadj\z@skip
% \end{macrocode}
% \end{macro}
@@ -4267,11 +4423,11 @@
% The default |\vbadness| setting starts issuing warnings at badness 1000,
% so we set the penalties below to $1000-800=200$.
% \begin{macrocode}
-\newcount\vvpenalty\vvpenalty200
-\newcount\ccpenalty\ccpenalty200
-\newcount\vcpenalty\vcpenalty200
-\newcount\cvpenalty\cvpenalty200
-\newcount\brkpenalty\brkpenalty200
+\SB@newcount\vvpenalty\vvpenalty200
+\SB@newcount\ccpenalty\ccpenalty200
+\SB@newcount\vcpenalty\vcpenalty200
+\SB@newcount\cvpenalty\cvpenalty200
+\SB@newcount\brkpenalty\brkpenalty200
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -4287,7 +4443,7 @@
% so for now it defaults to 100.
% To start each song on a fresh column/page, set it to $-10000$ or below.
% \begin{macrocode}
-\newcount\spenalty\spenalty100
+\SB@newcount\spenalty\spenalty100
% \end{macrocode}
% \end{macro}
%
@@ -4296,9 +4452,9 @@
% \begin{macro}{\versemark}\MainImpl{versemark}
% \begin{macro}{\chorusmark}\MainImpl{chorusmark}
% \changes{v2.1}{2007/08/02}{Added.}
-% The user can redefine the following macros to add \TeX\ marks for each
+% The user can redefine the following macros to add \TeX{} marks for each
% song, each verse, or each chorus.
-% Such marks are used by \LaTeX\ to define page headers and footers.
+% Such marks are used by \LaTeX{} to define page headers and footers.
% \begin{macrocode}
\newcommand\songmark{}
\newcommand\versemark{}
@@ -4418,7 +4574,7 @@
% Define the minimum number of fret rows that should appear in tablature
% diagrams.
% \begin{macrocode}
-\newcount\minfrets\minfrets4
+\SB@newcount\minfrets\minfrets4
% \end{macrocode}
% \end{macro}
%
@@ -4428,7 +4584,7 @@
% The user shouldn't set this one directly, but some users might want to
% refer to it in calculations.
% \begin{macrocode}
-\newdimen\SB@colwidth
+\SB@newdimen\SB@colwidth
% \end{macrocode}
% \end{macro}
%
@@ -4512,7 +4668,7 @@
% \begin{option}{unouter}\MainEnvImpl{unouter}
% \begin{macro}{\SB@outer}
% \optdef{off}
-% Several macros provided by the \Songs\ package are, by default, declared
+% Several macros provided by the \Songs{} package are, by default, declared
% |\outer| to aid in debugging.
% However, unusual documents may need to use these macros within larger
% constructs.
@@ -4538,17 +4694,6 @@
% \end{macrocode}
% \end{option}
%
-% \begin{option}{nopdfindex}\MainEnvImpl{nopdfindex}
-% \optdef{off}
-% Inhibit the creation of the bookmark index in pdf files.
-% This option can only be set in the |\usepackage| line because initializing
-% the pdfbookmark library at all causes a (possibly empty) bookmark index to
-% be created.
-% \begin{macrocode}
-\DeclareOption{nopdfindex}{\pdfindexfalse}
-% \end{macrocode}
-% \end{option}
-%
% \begin{option}{noshading}\MainEnvImpl{noshading}
% \optdef{off}
% Inhibit all shaded boxes (e.g., if the color package is unavailable).
@@ -4578,6 +4723,17 @@
% \end{macro}
% \end{option}
%
+% \begin{option}{nopdfindex}\MainEnvImpl{nopdfindex}
+% \optdef{off}
+% Suppress creation of PDF bookmark entries and hyperlinks.
+% \begin{macrocode}
+\DeclareOption{nopdfindex}{%
+ \let\songtarget\@gobbletwo%
+ \let\songlink\@secondoftwo%
+}
+% \end{macrocode}
+% \end{option}
+%
% \begin{macro}{\ifSB@measurespec}
% \begin{macro}{\ifSB@chordedspec}
% The |showmeasures| and |chorded| options interact in the sense that by
@@ -4585,9 +4741,9 @@
% well.
% However, if the user explicitly says that one should be on or off, then
% switching the other shouldn't affect it.
-% To produce this behavior, we need two extra conditionals to remember if
-% each of these options has been explicitly specified by the user or if it
-% is still in a default state.
+% To produce this behavior, we need two extra conditionals to remember whether
+% each of these options has been explicitly specified by the user or whether
+% it is still in a default state.
% \begin{macrocode}
\newif\ifSB@measurespec
\newif\ifSB@chordedspec
@@ -4807,7 +4963,7 @@
% \changes{v2.1}{2007/08/02}{Added.}
% Using |\repchoruses| causes choruses to be automatically repeated on
% subsequent pages of the song.
-% The feature requires $\varepsilon$-\TeX\ because the supporting code needs
+% The feature requires $\varepsilon$-\TeX{} because the supporting code needs
% an extended mark register class.
% \begin{macrocode}
\ifSB@etex
@@ -4875,7 +5031,7 @@
% The most recently processed song (or scripture quotation) is stored in this
% box.
% \begin{macrocode}
-\newbox\SB@songbox
+\SB@newbox\SB@songbox
% \end{macrocode}
% \end{macro}
%
@@ -4884,8 +5040,8 @@
% Reserve two count registers to hold the total number of columns and the
% current column number, respectively.
% \begin{macrocode}
-\newcount\SB@numcols\SB@numcols\tw@
-\newcount\SB@colnum
+\SB@newcount\SB@numcols\SB@numcols\tw@
+\SB@newcount\SB@colnum
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -4893,14 +5049,14 @@
% \begin{macro}{\SB@colbox}
% Reserve a box register to hold the current column in progress.
% \begin{macrocode}
-\newbox\SB@colbox
+\SB@newbox\SB@colbox
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\SB@colbox}
+% \begin{macro}{\SB@pgbox}
% Reserve a box register to hold the current page in progress.
% \begin{macrocode}
-\newbox\SB@pgbox
+\SB@newbox\SB@pgbox
% \end{macrocode}
% \end{macro}
%
@@ -4908,7 +5064,7 @@
% Reserve a box register to hold marks that migrate out of songs as they
% get split into columns and pages.
% \begin{macrocode}
-\newbox\SB@mrkbox
+\SB@newbox\SB@mrkbox
% \end{macrocode}
% \end{macro}
%
@@ -4931,51 +5087,69 @@
% process.
% The macro arguments are:
% \begin{enumerate}
-% \item the box $b$ to split (must not be |\SB@box|, which is used as a
-% temp register),
-% \item a count register $i$ equaling column index (zero or greater)
-% where the content of $b$ is to begin, and
+% \item an integer (positive or zero) indicating whether box $b$ should be
+% fully emptied and committed as columns (if positive), or whether its
+% final less-than-column-height remainder should be reserved as an in-progress
+% column (if zero);
+% \item the box $b$ to split;
+% \item a count register $i$ equaling the column index (zero or greater)
+% where the content of $b$ is to begin; and
% \item the desired column height.
% \end{enumerate}
% Box $b$ is split and $i$ is incremented until $i$ reaches
-% |\SB@numcols| or $b$ is emptied, whichever occurs first.
-% If $b$ is emptied first, the final column is \emph{not} contributed;
-% instead it is left in $b$ and $i$ is left equal to the index
+% |\SB@numcols| or $b$ is emptied.
+% If $b$ is emptied and the first argument is 0, the final column is \emph{not}
+% contributed; instead it is left in $b$ and $i$ is left equal to the index
% of the column that would have been added if $b$ had been emptied.
% This allows the next call to reconsider whether to end the
% current column here or add some or all of the next contribution to it.
+% Otherwise, if $b$ is emptied and the first argument is positive, the final
+% column is contributed and $i$ is set to one greater than the index of that
+% column.
+% (If $i$ reaches |\SB@numcols| before $b$ is emptied, the first argument is
+% ignored.)
+%
% Box $b$ and count register $i$ are globally modified.
% If |\SB@updatepage| is not redefined, boxes |\SB@pgbox| and |\SB@mrkbox|
% are also globally modified based on the results of the split.
-% \begin{macrocode}
-\newcommand\SB@mkpage[3]{%
- \begingroup%
+%
+% The implementation takes two special steps to avoid pre-committing
+% in-progress columns (when the first macro argument is zero):
+% First, the final split that empties box $b$ is ``undone'' by reverting to a
+% backup copy made before each split.
+% Second, any underfull box warnings for this final split are suppressed by
+% temporarily adding infinite-stretch |\vfil| glue to the bottom of the box.
+% This strategy preserves underfull and overfull box warnings for the columns
+% that are actually committed, but suppresses faux warnings for the last split
+% that is undone.
+% \begin{macrocode}
+\newcommand\SB@mkpage[4]{%
+ \ifvoid#2\else\begingroup%
+ \edef\SB@temp{\ifnum#2=\SB@box\SB@boxii\else\SB@box\fi}%
+ \edef\SB@tempii{\ifnum#2=\SB@boxiii\SB@boxii\else\SB@boxiii\fi}%
\splitmaxdepth\maxdepth\splittopskip\z@skip%
- \global\setbox#1\vbox{%
- \unvbox#1%
- \nointerlineskip%
- \null%
- \vfil%
- }%
- \loop\ifnum#2<\SB@numcols%
- \setbox\SB@box\vsplit#1to#3\relax%
- \ifvoid#1%
- #2\SB@numcols%
+ \ifnum#1=\z@\global\setbox#2\vbox{\unvbox#2\vfil}\fi%
+ \loop\ifnum#3<\SB@numcols%
+ \ifnum#1=\z@\setbox\SB@tempii\copy#2\fi%
+ \setbox\SB@temp\vsplit#2to#4\relax%
+ \ifvoid#2%
+ \ifnum#1=\z@%
+ \global\setbox#2\box\SB@tempii%
+ \else%
+ \SB@updatepage%
+ \global\advance#3\@ne%
+ \fi%
+ #3\SB@numcols%
\else%
\SB@updatepage%
- \global\advance#2\@ne%
+ \global\advance#3\@ne%
\ifrepchorus\ifvoid\SB@chorusbox\else%
- \SB@insertchorus#1%
+ \SB@insertchorus#2%
\fi\fi%
\fi%
\repeat%
- \global\setbox#1\vbox{%
- \unvbox\SB@box%
- \unvbox#1%
- \unskip%
- \setbox\SB@box\lastbox%
- }%
- \endgroup%
+ \ifnum#1=\z@\global\setbox#2\vbox{\unvbox#2\unskip}\fi%
+ \endgroup\fi%
}
% \end{macrocode}
% \end{macro}
@@ -5009,7 +5183,7 @@
\advance\SB@dimen-\wd\SB@pgbox%
\unhbox\SB@pgbox%
\ifdim\SB@dimen=\z@\else\hskip\SB@dimen\relax\fi%
- \box\SB@box%
+ \box\SB@temp%
}%
}
% \end{macrocode}
@@ -5021,7 +5195,7 @@
% This allows |\SB@mkpage| to be called by the song-positioning algorithm
% as a trial run without outputting anything.
% \begin{macrocode}
-\newcommand\SB@droppage{\setbox\SB@box\box\voidb@x}
+\newcommand\SB@droppage{\setbox\SB@temp\box\voidb@x}
% \end{macrocode}
% \end{macro}
%
@@ -5030,22 +5204,31 @@
% It repeatedly calls |\SB@mkpage|, emitting pages as they are completed,
% until the remaining content of box |\SB@colbox| is not enough to fill a
% column.
-% This final, in-progress column is left unfinished, pending future
-% contributions.
+% If the macro argument is 0, this final, in-progress column is left
+% unfinished, pending future contributions.
+% If the argument is positive, the final material is committed as a column.
+% If the argument is two or greater, the entire in-progress page is also
+% committed and the column number reset.
% \begin{macrocode}
-\newcommand\SB@output{%
+\newcommand\SB@output[1]{%
\ifnum\SB@numcols>\z@\begingroup%
\loop%
\SB@dimen\textheight%
\ifinner\else\advance\SB@dimen-\pagetotal\fi%
- \SB@mkpage\SB@colbox\SB@colnum\SB@dimen%
- \ifnum\SB@colnum<\SB@numcols\else%
+ \SB@mkpage#1\SB@colbox\SB@colnum\SB@dimen%
+ \SB@testfalse\SB@testiitrue%
+ \ifnum#1>\@ne\ifvoid\SB@colbox\ifnum\SB@colnum>\z@%
+ \SB@testtrue\SB@testiifalse%
+ \fi\fi\fi%
+ \ifnum\SB@colnum<\SB@numcols\SB@testiifalse\else\SB@testtrue\fi%
+ \ifSB@test%
\unvbox\SB@mrkbox%
\ifinner\else\kern\z@\fi%
\box\SB@pgbox%
\ifinner\else\vfil\break\vskip\vsize\relax\fi%
\global\SB@colnum\z@%
- \repeat%
+ \fi%
+ \ifSB@testii\repeat%
\endgroup\else%
\unvbox\SB@colbox\unskip%
\fi%
@@ -5056,7 +5239,7 @@
% \begin{macro}{\SB@putboxes}
% Create a vertical list consisting of the already committed contents of the
% current column plus the most recently submitted song box.
-% The \LaTeX\ primitive that should be used to contribute each box is
+% The \LaTeX{} primitive that should be used to contribute each box is
% specified in the first argument.
% \begin{macrocode}
\newcommand\SB@putboxes[1]{%
@@ -5105,7 +5288,7 @@
\advance\SB@cnt\m@ne%
\repeat%
}%
- \SB@output%
+ \SB@output1%
\else%
\ifnum\lastpenalty=-\@M\null\fi%
\break%
@@ -5145,7 +5328,7 @@
\ifinner\else\advance\SB@dimen-\pagetotal\fi%
\setbox\SB@boxii\vbox{\SB@putboxes\unvcopy}%
\SB@cntii\SB@colnum%
- \SB@mkpage\SB@boxii\SB@cntii\SB@dimen%
+ \SB@mkpage0\SB@boxii\SB@cntii\SB@dimen%
\SB@spos%
\global\SB@cnt\SB@cnt%
\endgroup%
@@ -5161,21 +5344,21 @@
\newcommand\SB@spbegnew{%
\setbox\SB@boxiii\copy\SB@songbox%
\SB@cntii\z@%
- \SB@mkpage\SB@boxiii\SB@cntii\textheight%
+ \SB@mkpage0\SB@boxiii\SB@cntii\textheight%
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SB@spextold}
% Tentatively extend the song previously typeset on the current even page to
-% the next odd page to see if it fits on a double-page.
+% the next odd page to see whether it fits on a double-page.
% If the current page is odd-numbered, do nothing since extending the song
% to the next page would introduce a page-turn.
% \begin{macrocode}
\newcommand\SB@spextold{%
\ifodd\c@page\else%
\SB@cntii\z@%
- \SB@mkpage\SB@boxii\SB@cntii\textheight%
+ \SB@mkpage0\SB@boxii\SB@cntii\textheight%
\fi%
}
% \end{macrocode}
@@ -5183,11 +5366,11 @@
%
% \begin{macro}{\SB@spextnew}
% Extend the trial typesetting started with |\SB@spbegnew| to a second
-% page to see if the song fits on a fresh double-page.
+% page to see whether the song fits on a fresh double-page.
% \begin{macrocode}
\newcommand\SB@spextnew{%
\SB@cntii\z@%
- \SB@mkpage\SB@boxiii\SB@cntii\textheight%
+ \SB@mkpage0\SB@boxiii\SB@cntii\textheight%
}
% \end{macrocode}
% \end{macro}
@@ -5267,7 +5450,7 @@
\advance\SB@cnt\@ne%
\ifnum\SB@cnt<\SB@numcols%
\setbox\SB@boxiii\copy\SB@songbox%
- \SB@mkpage\SB@boxiii\SB@cnt\SB@dimen%
+ \SB@mkpage0\SB@boxiii\SB@cnt\SB@dimen%
\advance\SB@cnt\m@ne%
\fi%
\ifnum\SB@cnt>\SB@colnum%
@@ -5319,14 +5502,21 @@
% \begin{macro}{\SB@clearpage}
% Output all contributed material as a new page unless there is no contributed
% material. In that case do nothing (i.e., don't produce a blank page).
+% The |\SB@colbox| is tested for zero height and depth rather than voidness,
+% since sometimes it contains zero-length |\splittopskip| glue.
% \begin{macrocode}
\newcommand\SB@clearpage{%
\SB@testtrue%
- \ifvoid\SB@pgbox\ifvoid\SB@colbox\SB@testfalse\fi\fi%
+ \ifvoid\SB@pgbox%
+ \ifdim\ht\SB@colbox=\z@\ifdim\dp\SB@colbox=\z@%
+ \SB@testfalse%
+ \fi\fi%
+ \fi%
\ifSB@test%
\SB@cnt\SB@numcols%
\advance\SB@cnt-\SB@colnum%
\SB@nextcol\SB@cnt\lastcolglue%
+ \SB@output2%
\fi%
}
% \end{macrocode}
@@ -5344,6 +5534,7 @@
\SB@clearpage%
\if@twoside\ifodd\c@page%
\SB@nextcol\SB@numcols\@flushglue%
+ \SB@output2%
\fi\fi%
}
% \end{macrocode}
@@ -5371,7 +5562,7 @@
\ifnum\SB@numcols>\z@%
\SB@selectcol%
\global\setbox\SB@colbox\vbox{\SB@putboxes\unvbox}%
- \SB@output%
+ \SB@output0%
\else%
\unvbox\voidb@x%
\SB@breakpoint\spenalty%
@@ -5387,15 +5578,26 @@
% \begin{macro}{\SB@styppage}
% Page-submissions go directly to the top of the nearest fresh page unless
% the current page has all page-width material so far.
+%
+% Implementation notes:
+% The |\null| is needed because the page builder consults |\pagetotal|,
+% which isn't updated by \TeX{} until a box is contributed (|\unvbox| doesn't
+% count).
+% Both |\nointerlineskip|s are needed because |\unvbox| fails to update
+% |\prevdepth|, and it doesn't make sense to inherit its value from whatever
+% preceeded this contribution.
+% Authors who want interline glue must therefore insert it explicitly at the
+% bottom of their contributed text.
% \begin{macrocode}
\newcommand\SB@styppage{%
\ifnum\SB@numcols>\z@%
\SB@clearpage%
\unvbox\SB@songbox%
- \null\nointerlineskip%
+ \nointerlineskip\null%
\else%
\unvbox\SB@songbox%
\fi%
+ \nointerlineskip%
}
% \end{macrocode}
% \end{macro}
@@ -5420,7 +5622,27 @@
% The song itself has number 0.
% Environments that come after the song are numbered increasingly from 1.
% \begin{macrocode}
-\newcount\SB@groupcnt
+\SB@newcount\SB@groupcnt
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\SB@clearpboxes}
+% This dynamically constructed macro clears the content of all boxes created
+% by the workings of |\includeonlysongs|.
+% \begin{macrocode}
+\newcommand\SB@clearpboxes{}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\SB@partbox}
+% Save a box of full-song or chorus material for later output when producing
+% a partial list using |\includeonlysongs|.
+% \begin{macrocode}
+\newcommand\SB@partbox[1]{%
+ \SB@newbox#1%
+ \SB@app\gdef\SB@clearpboxes{\setbox#1\box\voidb@x}%
+ \global\setbox#1\box%
+}
% \end{macrocode}
% \end{macro}
%
@@ -5431,21 +5653,19 @@
% \begin{macrocode}
\newcommand\SB@submitpart{%
\ifx\SB@sgroup\@empty\else%
- \@for\SB@temp:=\songlist\do{%
- \ifx\SB@temp\SB@sgroup%
- \edef\SB@tempii{\SB@sgroup @\the\SB@groupcnt}%
- \expandafter\newbox\csname songbox@\SB@tempii\endcsname%
- \global\expandafter\setbox
- \csname songbox@\SB@tempii\endcsname\box\SB@songbox%
- \global\expandafter\let%
- \csname stype@\SB@tempii\endcsname\SB@stype%
- \ifrepchorus\ifvoid\SB@chorusbox\else%
- \expandafter\newbox\csname chbox@\SB@tempii\endcsname%
- \global\expandafter\setbox%
- \csname chbox@\SB@tempii\endcsname\box\SB@chorusbox%
- \fi\fi%
- \fi%
- }%
+ \SB@testfalse
+ \@for\SB@temp:=\songlist\do{\ifx\SB@temp\SB@sgroup\SB@testtrue\fi}%
+ \ifSB@test%
+ \edef\SB@tempii{\SB@sgroup @\the\SB@groupcnt}%
+ \expandafter\SB@partbox
+ \csname songbox@\SB@tempii\endcsname\SB@songbox%
+ \global\expandafter\let%
+ \csname stype@\SB@tempii\endcsname\SB@stype%
+ \ifrepchorus\ifvoid\SB@chorusbox\else%
+ \expandafter\SB@partbox
+ \csname chbox@\SB@tempii\endcsname\SB@chorusbox%
+ \fi\fi%
+ \fi%
\global\advance\SB@groupcnt%
\ifnum\SB@groupcnt<\z@\m@ne\else\@ne\fi%
\fi%
@@ -5469,6 +5689,18 @@
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}{\SB@submitenv}
+% Submit the |\SB@envbox| box as a page-width contribution.
+% \begin{macrocode}
+\newcommand\SB@submitenv{%
+ \begingroup%
+ \let\SB@songbox\SB@envbox%
+ \SB@styppage%
+ \endgroup%
+}
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macro}{\SB@songlistbrk}
% \begin{macro}{\SB@songlistnc}
% \begin{macro}{\SB@songlistcp}
@@ -5529,6 +5761,7 @@
\fi\fi\fi\fi%
}%
\fi%
+ \SB@clearpboxes%
\fi%
\SB@clearpage%
}
@@ -5544,13 +5777,13 @@
\loop\edef\SB@tempii{\SB@temp @\the\SB@groupcnt}%
\expandafter\ifx%
\csname songbox@\SB@tempii\endcsname\relax\else%
- \setbox\SB@songbox\expandafter\box%
+ \setbox\SB@songbox\expandafter\copy%
\csname songbox@\SB@tempii\endcsname%
\expandafter\ifx\csname chbox@\SB@tempii\endcsname\relax%
\repchorusfalse%
\else%
\repchorustrue%
- \setbox\SB@chorusbox\expandafter\box%
+ \setbox\SB@chorusbox\expandafter\copy%
\csname chbox@\SB@tempii\endcsname%
\fi%
\csname stype@\SB@tempii\endcsname%
@@ -5701,8 +5934,8 @@
% These registers hold the full list of titles for the current song and
% the tail list of titles that has not yet been iterated over.
% \begin{macrocode}
-\newtoks\SB@titlelist
-\newtoks\SB@titletail
+\SB@newtoks\SB@titlelist
+\SB@newtoks\SB@titletail
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -5829,8 +6062,7 @@
% \begin{macrocode}
\newcommand\SB@clearbskeys{}
\newcommand\newsongkey[2]{%
- \expandafter\gdef\expandafter\SB@clearbskeys\expandafter%
- {\SB@clearbskeys#2}%
+ \SB@app\gdef\SB@clearbskeys{#2}%
\define@key{beginsong}{#1}%
}
% \end{macrocode}
@@ -5919,7 +6151,7 @@
\nexttitle%
\foreachtitle{\expandafter\SB@addtotitles\expandafter{\songtitle}}%
\resettitles%
- \lyricfont%
+ \lyricfont\relax%
\SB@setbaselineskip%
}
% \end{macrocode}
@@ -5949,42 +6181,47 @@
\fi\fi%
\fi\fi%
\endgroup\egroup%
- \setbox\SB@songbox\vbox{%
- \songmark%
- \unvbox\SB@songwrites%
- \ifnum\SB@numcols>\z@\hsize\SB@colwidth\fi%
+ \begingroup%
+ \ifnum\SB@numcols>\z@%
+ \hsize\ifpagepreludes\textwidth\else\SB@colwidth\fi%
+ \fi%
\leftskip\z@skip\rightskip\z@skip%
\parfillskip\@flushglue\parskip\z@skip\parindent\z@%
- \ifdim\sbarheight>\z@%
- \hrule\@height\sbarheight\@width\hsize%
- \nobreak\vskip5\p@%
- \fi%
- \ifpdfindex\begingroup%
- \ifx\pdfbookmark\undefined\else%
- \ifx\pdfbookmark\relax\else%
- \resettitles%
- \pdfbookmark[\ifnum\c@section=\z@1\else2\fi]%
- {\thesongnum. \songtitle}%
- {song\theSB@songsnum-\thesongnum}%
+ \global\setbox\SB@envbox\vbox{%
+ \songmark%
+ \unvbox\SB@songwrites%
+ \ifpagepreludes\else\ifdim\sbarheight>\z@%
+ \hrule\@height\sbarheight\@width\hsize%
+ \nobreak\vskip5\p@\relax%
\fi\fi%
- \endgroup\fi%
- \vbox{\makeprelude}%
- \nobreak\vskip\SB@skip%
- \vskip\afterpreludeskip\relax%
- \unvbox\SB@songbox%
- \nobreak\vskip\SB@skip%
- \vskip\beforepostludeskip\relax%
- \nointerlineskip%
- \vbox{\makepostlude}%
- \ifdim\sbarheight>\z@%
- \nobreak\vskip2\p@\@plus\p@%
+ \resettitles%
+ \begingroup%
+ \songtarget{\ifnum\c@section=\z@1\else2\fi}%
+ {song\theSB@songsnum-\thesongnum}%
+ \endgroup%
+ \vbox{\makeprelude}%
+ \nobreak\vskip\SB@skip%
+ \vskip\afterpreludeskip\relax%
+ }%
+ \ifnum\SB@numcols>\z@\hsize\SB@colwidth\fi%
+ \global\setbox\SB@songbox\vbox{%
+ \ifpagepreludes\else\unvbox\SB@envbox\fi%
+ \unvbox\SB@songbox%
+ \nobreak\vskip\SB@skip%
+ \vskip\beforepostludeskip\relax%
\nointerlineskip%
- \hbox{\vrule\@height\sbarheight\@width\hsize}%
- \fi%
- }%
+ \vbox{\makepostlude}%
+ \ifdim\sbarheight>\z@%
+ \nobreak\vskip2\p@\@plus\p@%
+ \nointerlineskip%
+ \hbox{\vrule\@height\sbarheight\@width\hsize}%
+ \fi%
+ }%
+ \endgroup%
\SB@insongfalse%
\edef\SB@sgroup{\thesongnum}%
\global\SB@groupcnt\z@%
+ \ifpagepreludes\SB@submitenv\fi%
\SB@submitsong%
\ifnum\SB@grouplvl=\z@\let\SB@sgroup\@empty\fi%
\stepcounter{songnum}%
@@ -6031,7 +6268,7 @@
\edef\SB@tempii{\the\versesep}%
\ifx\SB@temp\SB@tempii%
\begingroup%
- \lyricfont%
+ \lyricfont\relax%
\SB@dimen\f@size\p@%
\ifchorded%
\setbox\SB@box\hbox{{\printchord{ABCDEFG\shrp\flt/j7}}}%
@@ -6056,13 +6293,26 @@
% Generate the material that begins each song.
% This macro is invoked at |\endsong| so that its code can access song info
% defined throughout the song.
+%
+% Note that if you are redefining |\makeprelude|, you can probably replace
+% everything below with something much simpler.
+% The code below is lengthy because it accommodates all of the many different
+% options that various authors may adjust to customize their books.
+% If you redefine it, you can replace all of this with smaller, more
+% specialized programming that just outputs the prelude format you desire.
% \begin{macrocode}
\newcommand\makeprelude{%
\resettitles%
+% \end{macrocode}
+% In slides mode, the title, references, and authors are simply centered on
+% the page with no song number.
+% Only the first of the song titles is included.
+% The references and authors only span the middle 50\% of the page, since
+% letting them span the whole page width stretches them out too much and makes
+% their fine print too hard to read.
+% \begin{macrocode}
\ifslides%
- \hbox to\hsize{{%
- \hfil\stitlefont\songtitle\hfil%
- }}%
+ \hbox to\hsize{{\hfil\stitlefont\relax\songtitle\hfil}}%
\vskip5\p@%
\hbox to\hsize{%
\hfil%
@@ -6073,6 +6323,16 @@
\hfil%
}%
\else%
+% \end{macrocode}
+% In non-slides mode, we write the song number in a shaded box to the left
+% (if |\songnumwidth| is positive) and everything else in left-justified
+% paragraphs to the right of it (or centered if |\pagepreludes| is on).
+% The height of the shaded box that contains the song number depends on
+% which is higher: the natural height of the song number, or everything else
+% that goes to the right of it.
+% To find out which is higher, we start by putting the song number in its
+% own box (|\SB@boxii|).
+% \begin{macrocode}
\ifdim\songnumwidth>\z@%
\setbox\SB@boxii\hbox{{\SB@colorbox\snumbgcolor{%
\hbox to\songnumwidth{%
@@ -6080,14 +6340,22 @@
}%
}}}%
\fi%
+% \end{macrocode}
+% Now we know the width $w$ of the song number box, so we typeset everything
+% else in a box (|\SB@box|) of width $c-w$, where $c$ is the column width.
+% (If |\pagepreludes| is on, we instead use width $c-2w$ so that the material
+% stays centered on the page.)
+% \begin{macrocode}
\setbox\SB@box\vbox{%
- \ifnum\SB@numcols>\z@\hsize\SB@colwidth\fi%
\ifdim\songnumwidth>\z@%
- \advance\hsize-\wd\SB@boxii%
- \advance\hsize-3\p@%
+ \SB@dimen\wd\SB@boxii%
+ \advance\SB@dimen3\p@%
+ \ifpagepreludes\multiply\SB@dimen\tw@\fi%
+ \advance\hsize-\SB@dimen%
\fi%
- \SB@raggedright\offinterlineskip\lineskip\p@%
- {\stitlefont%
+ \ifpagepreludes\centering\else\SB@raggedright\fi%
+ \offinterlineskip\lineskip\p@%
+ {\stitlefont\relax%
\songtitle\par%
\nexttitle%
\foreachtitle{(\songtitle)\par}}%
@@ -6096,6 +6364,16 @@
\extendprelude%
\kern\z@%
}%
+% \end{macrocode}
+% If the song number is being printed (i.e., |\songnumwidth| is positive),
+% and its height is greater than the height of the other material, then we
+% just put |\SB@boxii| and |\SB@box| side-by-side.
+% If the song number is being printed but its height is less, then we
+% re-typeset it at height equal to the other material, and place the boxes
+% side-by-side.
+% Finally, if the song number is not being printed at all, we just unbox
+% |\SB@box| onto the vertical list.
+% \begin{macrocode}
\ifdim\songnumwidth>\z@%
\hbox{%
\ifdim\ht\SB@boxii>\ht\SB@box%
@@ -6124,6 +6402,9 @@
% \changes{v1.15}{2005/05/26}{Added to make song trailer format customizable.}
% \changes{v2.0}{2007/06/18}{Arguments removed to support keyval syntax.}
% Generate the material that ends each song.
+% The default implementation just prints the copyright and licensing
+% information (if any) as a single, left-justified, non-indentended paragraph
+% in fine print.
% \begin{macrocode}
\newcommand\makepostlude{%
\SB@raggedright\baselineskip\z@skip\parskip\z@skip\parindent\z@%
@@ -6133,7 +6414,11 @@
% \end{macro}
%
% \begin{macro}{\showauthors}\MainImpl{showauthors}
-% Display the author line in the prelude.
+% Display the author information in the prelude.
+% This macro is only called by |\extendprelude|, which is only called by
+% |\makeprelude|; so if you redefine either of those, you don't need this.
+% The default implementation prints the authors in boldface and shortens the
+% spacing after periods so that they don't look like ends of sentences.
% \begin{macrocode}
\newcommand\showauthors{%
\setbox\SB@box\hbox{\bfseries\sfcode`.\@m\songauthors}%
@@ -6144,6 +6429,10 @@
%
% \begin{macro}{\showrefs}\MainImpl{showrefs}
% Display the scripture references in the prelude.
+% This macro is only called by |\extendprelude|, which is only called by
+% |\makeprelude|; so if you redefine either of those, you don't need this.
+% The default implementation prints the scripture references in slanted
+% (oblique) font.
% \begin{macrocode}
\newcommand\showrefs{%
\setbox\SB@box\hbox{\slshape\songrefs\vphantom,}%
@@ -6183,7 +6472,7 @@
% into a larger macro is harder than it seems:
% If you write the following code but with an explicit control sequence
% instead of |#1|, then the space immediately following the name will get
-% stripped by the \TeX\ parser.
+% stripped by the \TeX{} parser.
% But invoking the following macro with a control sequence as an argument
% works fine, because in that case the explicit space has already been
% tokenized when this macro was first defined and won't be stripped as it
@@ -6204,33 +6493,38 @@
\global\SB@titlelist{\\}%
\SB@toks{}%
\let\\\SB@titlesep%
- \let\SB@dothis\SB@pthead%
- \SB@ptstart#1\SB@endparse%
+ \SB@pthead#1\SB@endparse%
\endgroup%
}
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\SB@ptstart}
-% The iterator of the title parser loop just scans the next token.
-% \begin{macrocode}
-\newcommand\SB@ptstart{\futurelet\SB@next\SB@dothis}
-% \end{macrocode}
-% \end{macro}
-%
% \begin{macro}{\SB@pthead}
+% \begin{macro}{\SB@@pthead}
+% \begin{macro}{\SB@@@pthead}
% While processing tokens at the head of a title, we skip over all spaces
% until we reach a non-space token.
% \begin{macrocode}
-\newcommand\SB@pthead{%
- \ifcat\noexpand\SB@next\noexpand\@sptoken%
- \expandafter\SB@ptsp%
+\newcommand\SB@pthead{\futurelet\SB@next\SB@@pthead}
+\newcommand\SB@@pthead{%
+ \ifcat\noexpand\SB@next\@sptoken%
+ \expandafter\SB@@@pthead%
\else%
- \SB@toks{}%
- \let\SB@dothis\SB@ptmain%
\expandafter\SB@ptmain%
\fi%
}
+\newcommand\SB@@@pthead{%
+ \afterassignment\SB@pthead%
+ \let\SB@next= }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\SB@ptloop}
+% The iterator of the title parser loop just scans the next token.
+% \begin{macrocode}
+\newcommand\SB@ptloop{\futurelet\SB@next\SB@ptmain}
% \end{macrocode}
% \end{macro}
%
@@ -6240,22 +6534,20 @@
% of each title.
% \begin{macrocode}
\newcommand\SB@ptmain{%
- \ifcat\noexpand\SB@next\noexpand\@sptoken%
+ \ifcat\noexpand\SB@next\@sptoken%
\let\SB@donext\SB@ptsp%
- \else\ifcat\noexpand\SB@next\noexpand\bgroup%
+ \else\ifcat\noexpand\SB@next\bgroup%
\let\SB@donext\SB@ptbg%
\else\ifx\SB@next\SB@endparse%
\global\SB@titlelist\expandafter{\the\SB@titlelist\\}%
\let\SB@donext\@gobble%
+ \else\ifx\SB@next\\%
+ \SB@toks{}%
+ \def\SB@donext{\SB@ptstep\SB@pthead}%
\else%
- \ifx\SB@next\\%
- \SB@toks{}%
- \let\SB@dothis\SB@pthead%
- \fi%
- \let\SB@donext\SB@ptstep%
- \fi\fi\fi%
- \SB@donext%
-}
+ \def\SB@donext{\SB@ptstep\SB@ptloop}%
+ \fi\fi\fi\fi%
+ \SB@donext}
% \end{macrocode}
% \end{macro}
%
@@ -6264,12 +6556,11 @@
% title.
% If any spaces preceded it, add those too.
% \begin{macrocode}
-\newcommand\SB@ptstep[1]{%
+\newcommand\SB@ptstep[2]{%
\global\SB@titlelist\expandafter\expandafter\expandafter{%
- \expandafter\the\expandafter\SB@titlelist\the\SB@toks#1}%
+ \expandafter\the\expandafter\SB@titlelist\the\SB@toks#2}%
\SB@toks{}%
- \SB@ptstart%
-}
+ #1}
% \end{macrocode}
% \end{macro}
%
@@ -6278,7 +6569,7 @@
% It should be balanced, so consume the entire group and add it (along with
% its surrounding braces) as-is to the current title.
% \begin{macrocode}
-\newcommand\SB@ptbg[1]{\SB@ptstep{{#1}}}
+\newcommand\SB@ptbg[1]{\SB@ptstep\SB@ptloop{{#1}}}
% \end{macrocode}
% \end{macro}
%
@@ -6293,7 +6584,7 @@
% \begin{macrocode}
\newcommand\SB@ptsp{
\SB@appendsp\SB@toks%
- \afterassignment\SB@ptstart%
+ \afterassignment\SB@ptloop%
\let\SB@next= }
% \end{macrocode}
% \end{macro}
@@ -6318,32 +6609,6 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\SB@testdigit}
-% \begin{macro}{\SB@@testdigit}
-% The following decides whether a token or |\let|-defined control sequence
-% is a digit and sets conditional |\ifSB@test| accordingly.
-% \begin{macrocode}
-\newcommand\SB@testdigit[1]{%
- \SB@testfalse%
- \ifcat1\noexpand#1\SB@@testdigit#1\fi%
-}
-\newcommand\SB@@testdigit[1]{%
- \ifx0#1\SB@testtrue\else%
- \ifx1#1\SB@testtrue\else%
- \ifx2#1\SB@testtrue\else%
- \ifx3#1\SB@testtrue\else%
- \ifx4#1\SB@testtrue\else%
- \ifx5#1\SB@testtrue\else%
- \ifx6#1\SB@testtrue\else%
- \ifx7#1\SB@testtrue\else%
- \ifx8#1\SB@testtrue\else%
- \ifx9#1\SB@testtrue%
- \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi%
-}
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
% \begin{macro}{\SB@parsesrefs}
% \changes{v1.14}{2005/05/15}{Added}
% Assign the |\songrefs| macro a processed version of a scripture reference in
@@ -6363,10 +6628,10 @@
% Unfortunately, the catcodes of everything in the text were set back when
% the full keyval list was digested as an argument to |\beginsong|, so we
% must unset and reset the catcodes.
-% One obvious solution is to use |\scantokens| from $\varepsilon$-\TeX\ to
+% One obvious solution is to use |\scantokens| from $\varepsilon$-\TeX{} to
% do this, but that doesn't allow us to suppress the re-catcoding process
% within groups, and we'd like to avoid intoducing features that require
-% $\varepsilon$-\TeX\ anyway for compatibility reasons.
+% $\varepsilon$-\TeX{} anyway for compatibility reasons.
% Therefore, we build the following small scanner instead.
%
% The scanner walks through the text token by token, replacing each important
@@ -6402,13 +6667,13 @@
\fi%
}
\newcommand\SB@@prstep{%
- \ifcat\noexpand\SB@next\noexpand\@sptoken%
+ \ifcat\noexpand\SB@next\@sptoken%
\let\SB@donext\SB@prspace%
\else\ifx\SB@next-%
\let\SB@donext\SB@prhyphen%
\else\ifx\SB@next,%
\let\SB@donext\SB@prcomma%
- \else\ifx\SB@next\SB@endparse
+ \else\ifx\SB@next\SB@endparse%
\let\SB@donext\@gobble%
\else\ifcat\noexpand\SB@next\bgroup%
\let\SB@donext\SB@prgr%
@@ -6644,13 +6909,13 @@
% Unbox a vbox and follow it by vertical glue if its depth is unusually
% shallow.
% This ensures that verses and choruses will look equally spaced even if
-% one of them has a final line with no letters that dangle below the baseline.
+% one of them has a final line with no descenders.
% \begin{macrocode}
\newcommand\SB@putbox[2]{%
\begingroup%
\SB@dimen\dp#2%
#1#2%
- \setbox\SB@box\hbox{{\lyricfont p}}%
+ \setbox\SB@box\hbox{{\lyricfont\relax p}}%
\ifdim\SB@dimen<\dp\SB@box%
\advance\SB@dimen-\dp\SB@box%
\vskip-\SB@dimen%
@@ -6663,14 +6928,14 @@
%
% \begin{macro}{\SB@obeylines}
% Within verses and choruses we would like to use |\obeylines| so that each
-% \meta{return} in the source file ends a paragraph without having to say
+% \Meta{return} in the source file ends a paragraph without having to say
% |\par| explicitly.
-% The \LaTeX\ base code establishes the convention that short-term changes to
+% The \LaTeX{} base code establishes the convention that short-term changes to
% |\par| will restore |\par| by setting it equal to |\@par|.
% Long-term (i.e., environment-long) changes to |\par| should therefore
% redefine |\@par| to restore the desired long-term definition.
% The following code starts a long-term redefinition of |\par| adhering to
-% these conventions, and extends that definition to \meta{return} as well.
+% these conventions, and extends that definition to \Meta{return} as well.
% \begin{macrocode}
\newcommand\SB@obeylines{%
\let\par\SB@par%
@@ -6733,7 +6998,7 @@
% \changes{v1.12}{2005/05/10}{Added}
% Reserve a length to remember the current |\parindent|.
% \begin{macrocode}
-\newdimen\SB@parindent
+\SB@newdimen\SB@parindent
% \end{macrocode}
% \end{macro}
%
@@ -6797,7 +7062,7 @@
% Begin a new verse.
% This can be done by beginning a |verse| environment or by using the
% |\beginverse| macro.
-% The latter must check for a trailing star to determine if this
+% The latter must check for a trailing star to determine whether this
% verse should be numbered.
% We use |\@ifstar| to scan ahead for the star, but this needs to be done
% carefully because while scanning we might encounter tokens that
@@ -6858,15 +7123,13 @@
\ifvnumbered%
\protected@edef\@currentlabel{\p@versenum\theversenum}%
\def\SB@everypar{%
- \setbox\SB@box\hbox{{%
- \printversenum{\theversenum}%
- }}%
+ \setbox\SB@box\hbox{{\printversenum{\theversenum}}}%
\ifdim\wd\SB@box<\versenumwidth%
\setbox\SB@box%
\hbox to\versenumwidth{\unhbox\SB@box\hfil}%
\fi%
\ifchorded\vrule\@height\baselineskip\@width\z@\@depth\z@\fi%
- {\placeversenum\SB@box}%
+ \placeversenum\SB@box%
\gdef\SB@everypar{}%
}%
\else%
@@ -6876,7 +7139,7 @@
}%
\fi%
\everypar{\SB@everypar\everypar{}}%
- \versefont\versejustify%
+ \versefont\relax\SB@setbaselineskip\versejustify%
\SB@loadactives%
\SB@obeylines%
\penalty12345 %
@@ -6922,7 +7185,7 @@
% When |\repchoruses| is used, the first sequence of consecutive choruses
% is remembered in the following box register.
% \begin{macrocode}
-\newbox\SB@chorusbox
+\SB@newbox\SB@chorusbox
% \end{macrocode}
% \end{macro}
%
@@ -6942,7 +7205,7 @@
% We use the |\newmarks| macro to allocate these classes, if it's
% available.
% If |\newmarks| doesn't exist, then that means the user has an
-% $\varepsilon$-\TeX\ compatible version of \LaTeX, but no |etex| style
+% $\varepsilon$-\TeX{} compatible version of \LaTeX, but no |etex| style
% file to go with it;
% we just have to pick two mark classes and hope that nobody else is
% using them.
@@ -6973,8 +7236,8 @@
% |\SB@cmark| is used to mark places where a chorus might be inserted between
% verses, and |\SB@lastcmark| marks a place where a chorus might be inserted
% after the last verse of the song.
-% Both marks are $\varepsilon$-\TeX\ marks of class |\SB@cmarkclass|,
-% to avoid disrupting the use of standard \TeX\ marks.
+% Both marks are $\varepsilon$-\TeX{} marks of class |\SB@cmarkclass|,
+% to avoid disrupting the use of standard \TeX{} marks.
% Each time a chorus is automatically inserted, |\SB@nocmark| is inserted
% with mark class |\SB@nocmarkclass| just above it (and at the top of each
% additional page it spans).
@@ -7052,7 +7315,7 @@
}%
\everypar{\SB@everypar\everypar{}}%
\fi%
- \chorusfont\chorusjustify%
+ \chorusfont\relax\SB@setbaselineskip\chorusjustify%
\SB@loadactives%
\SB@obeylines%
\penalty12345 %
@@ -7172,7 +7435,7 @@
% \end{macro}
%
% \begin{macro}{\brk}\MainImpl{brk}
-% Placing |\brk| within a line in a verse or chorus tells \TeX\ to break the
+% Placing |\brk| within a line in a verse or chorus tells \TeX{} to break the
% line at that point (if it needs to be broken at all).
%
% Placing |\brk| on a line by itself within a chorus stops the chorus (and its
@@ -7227,7 +7490,7 @@
% justification.
% \begin{macrocode}
\newcommand\SB@boxup[1]{%
- \setbox\SB@box\hbox{{\notefont#1}}%
+ \setbox\SB@box\hbox{{\notefont\relax#1}}%
\SB@dimen\wd\SB@box%
\advance\SB@dimen6\p@%
\advance\SB@dimen\leftskip%
@@ -7302,10 +7565,7 @@
% \changes{v1.21}{2006/09/17}{Customized fonts now preserved.}
% \changes{v2.1}{2007/08/02}{Toggles instead of forces slanted font.}
% Typeset an echo part in the lyrics.
-% Echo parts will be oblique and parenthesized.
-% We toggle between oblique and upright shapes like |\emph|, but we
-% use |\slshape| instead of |\itshape| because it tends to look nicer
-% with the larger fonts used in slides mode.
+% Echo parts are in a user-customizable font and parenthesized.
%
% The |\echo| macro must be able to accept chords in its argument.
% This complicates the implementation because chord macros should change
@@ -7314,9 +7574,9 @@
% This would disallow chord name abbreviations like |#| and |&| within
% |\echo| parts.
%
-% If we're using $\varepsilon$-\TeX\ then the solution is easy: we use
+% If we're using $\varepsilon$-\TeX{} then the solution is easy: we use
% |\scantokens| to re-scan the argument and thereby re-assign the catcodes.
-% (One subtlety: Whenever \LaTeX\ consumes an argument to a macro, it changes
+% (One subtlety: Whenever \LaTeX{} consumes an argument to a macro, it changes
% |#| to |##| so that when the argument text is substituted into the body of
% the macro, the replacement text will not contain unsubstituted parameters
% (such as |#1|).
@@ -7325,7 +7585,7 @@
% \emph{output}, which was not the intent.
% To avoid this problem, we use |\@sanitize| before consuming the argument to
% |\echo|, which sets the catcodes of most special tokens (including |#|) to
-% 12, so that \LaTeX\ will not recognize any of them as parameters and will
+% 12, so that \LaTeX{} will not recognize any of them as parameters and will
% therefore not double any of them.)
% \begin{macrocode}
\ifSB@etex
@@ -7333,7 +7593,7 @@
\newcommand\SB@echo[1]{%
\endgroup%
\begingroup%
- \ifdim\fontdimen\@ne\font>\z@\upshape\else\slshape\fi%
+ \echofont\relax%
\endlinechar\m@ne%
\scantokens{(#1)}%
\endgroup%
@@ -7349,11 +7609,11 @@
% chord name atop a short lyric, the closing parenthesis will float out away
% from the lyric instead of being sucked under the chord.
% I can find no solution to this problem, so to avoid it users must find a
-% version of \LaTeX\ that is $\varepsilon$-\TeX\ compatible.
+% version of \LaTeX{} that is $\varepsilon$-\TeX{} compatible.
% \begin{macrocode}
\newcommand\echo{%
\begingroup%
- \ifdim\fontdimen\@ne\font>\z@\upshape\else\slshape\fi%
+ \echofont\relax%
\afterassignment\SB@echo%
\setbox\SB@box\hbox%
}
@@ -7367,8 +7627,8 @@
%
% \begin{macro}{\rep}\MainImpl{rep}
% \changes{v1.21}{2006/09/17}{Changed to avoid math mode.}
-% Place |\rep{|\meta{n}|}| at the end of a line to indicate that it should be
-% sung \meta{n} times.
+% Place |\rep{|\Meta{n}|}| at the end of a line to indicate that it should be
+% sung \Meta{n} times.
% \begin{macrocode}
\newcommand\rep[1]{%
(\raise.25ex\hbox{%
@@ -7405,7 +7665,7 @@
% \begin{macro}{\SB@grouplvl}
% Count the |songgroup| environment nesting depth.
% \begin{macrocode}
-\newcount\SB@grouplvl
+\SB@newcount\SB@grouplvl
% \end{macrocode}
% \end{macro}
%
@@ -7475,14 +7735,6 @@
% \end{macrocode}
% \end{environment}
%
-% \begin{macro}{\SB@srbox}
-% The following box register holds the citation information that is to be
-% typeset at the end of a scripture quotation.
-% \begin{macrocode}
-\newbox\SB@srbox
-% \end{macrocode}
-% \end{macro}
-%
% \begin{environment}{scripture}\MainEnvImpl{scripture}
% \begin{macro}{\beginscripture}
% Begin a scripture quotation.
@@ -7495,13 +7747,13 @@
\newcommand\beginscripture[1]{%
\begin{intersong}%
\SB@parsesrefs{#1}%
- \setbox\SB@srbox\hbox{{\printscrcite\songrefs}}%
+ \setbox\SB@envbox\hbox{{\printscrcite\songrefs}}%
\def\SB@closeall{\endscripture}%
\nobreak\vskip5\p@%
\SB@parindent\parindent\parindent\z@%
\parskip\z@skip\parfillskip\@flushglue%
\leftskip\SB@parindent\rightskip\SB@parindent\relax%
- \scripturefont%
+ \scripturefont\relax%
\baselineskip\f@size\p@\@plus\p@\relax%
\advance\baselineskip\p@\relax%
\emergencystretch.3em%
@@ -7530,7 +7782,7 @@
% line, but at times the user might want to invoke this macro explicitly
% at a more suitable point.
% A good example is when something near the end of the scripture quotation
-% drops \TeX\ into vertical mode.
+% drops \TeX{} into vertical mode.
% In such cases, it is often better to issue the citation before leaving
% horizontal mode.
%
@@ -7541,20 +7793,20 @@
% However, if we're now in vertical mode, the problem is a little harder.
% We do the best we can by using |\lastbox| to remove the last line, then
% adding the reference and re-typesetting it.
-% This isn't as good as the horizontal mode solution because \TeX\ only
+% This isn't as good as the horizontal mode solution because \TeX{} only
% gets to reevaluate the last line instead of the whole paragraph, but
% usually the results are passable.
% \begin{macrocode}
\newcommand\scitehere{%
\ifSB@intersong%
- \ifvoid\SB@srbox\else%
+ \ifvoid\SB@envbox\else%
\ifvmode%
\setbox\SB@box\lastbox%
\nointerlineskip\noindent\hskip-\leftskip%
\unhbox\SB@box\unskip%
\fi%
\unskip\nobreak\hfil\penalty50\hskip.8em\null\nobreak\hfil%
- \box\SB@srbox\kern-\SB@parindent%
+ \box\SB@envbox\kern-\SB@parindent%
{\parfillskip\z@\finalhyphendemerits2000\par}%
\fi%
\else%
@@ -7577,8 +7829,8 @@
%
% \begin{macro}{\SB@colon}
% Begin a group of temporary definitions that will end at the next
-% \meta{return}.
-% The \meta{return} will end the paragraph and close the local scope.
+% \Meta{return}.
+% The \Meta{return} will end the paragraph and close the local scope.
% \begin{macrocode}
\newcommand\SB@colon[2]{%
\ifSB@intersong\else%
@@ -7714,7 +7966,7 @@
% This counter identifies the requested number of halfsteps by which chords are
% to be transposed (from $-11$ to $+11$).
% \begin{macrocode}
-\newcount\SB@transposefactor
+\SB@newcount\SB@transposefactor
% \end{macrocode}
% \end{macro}
%
@@ -7765,7 +8017,7 @@
% \begin{macro}{\printnoteG}
% These control sequences are what the transposition logic actually
% outputs to denote each scale degree.
-% They can include any \LaTeX\ code that is legal in horizontal mode.
+% They can include any \LaTeX{} code that is legal in horizontal mode.
% \begin{macrocode}
\newcommand\printnoteA{}
\newcommand\printnoteB{}
@@ -7854,7 +8106,7 @@
% The first chord seen is usually the best indicator of the key of the song.
% (Even when the first chord isn't the tonic, it will often be the dominant
% or subdominant, which usually has the same kind of accidental in its key
-% signatures as the actual key.) This conditional remembers if the current
+% signatures as the actual key.) This conditional remembers whether the current
% chord is the first one seen in the song, and should therefore be used to
% guess the key of the song.
% \begin{macrocode}
@@ -7931,7 +8183,7 @@
%
% \begin{macro}{\notrans}\MainImpl{notrans}
% Suppress chord transposition without suppressing note name conversion.
-% When a |\notrans{|\meta{text}|}| macro appears within text undergoing
+% When a |\notrans{|\Meta{text}|}| macro appears within text undergoing
% transposition, the |\notrans| macro and the group will be preserved
% verbatim by the transposition parser.
% When it is then expanded after parsing, we must therefore re-invoke
@@ -7982,7 +8234,7 @@
% \end{macro}
%
% \begin{macro}{\SB@trmain}
-% Test to see if the token was a begin-brace, end-brace, or space.
+% Test to see whether the token was a begin-brace, end-brace, or space.
% These tokens require special treatment because they cannot be
% accepted as implicit arguments to macros.
% \begin{macrocode}
@@ -7992,7 +8244,7 @@
\else\ifx\SB@next\egroup%
\SB@toks\expandafter{\the\SB@toks\egroup}%
\let\SB@donext\SB@trskip%
- \else\ifcat\noexpand\SB@next\noexpand\@sptoken%
+ \else\ifcat\noexpand\SB@next\@sptoken%
\SB@appendsp\SB@toks%
\let\SB@donext\SB@trskip%
\else%
@@ -8030,8 +8282,8 @@
%
% \begin{macro}{\SB@trstep}
% A non-grouping token lies next in the input stream.
-% Consume it as an argument to this macro, and then test it to see if it's a
-% note letter or some other recognized item.
+% Consume it as an argument to this macro, and then test it to see whether
+% it's a note letter or some other recognized item.
% If so, process it; otherwise just append it to the token list and continue
% scanning.
% \begin{macrocode}
@@ -8057,8 +8309,8 @@
% \begin{macro}{\SB@trnote}
% We're in the midst of processing a sequence of uppercase letters that
% might comprise a note name.
-% Check to see if the next token is an accidental (sharp or flat), or yet
-% another letter.
+% Check to see whether the next token is an accidental (sharp or flat),
+% or yet another letter.
% \begin{macrocode}
\newcommand\SB@trnote{%
\ifcat\noexpand\SB@next A%
@@ -8083,13 +8335,13 @@
%
% \begin{macro}{\SB@trnotestep}
% The next token is a letter.
-% Consume it and test to see if it is an uppercase letter.
+% Consume it and test to see whether it is an uppercase letter.
% If so, add it to the note name being assembled; otherwise reinsert it into
% the input stream and jump directly to the transposition logic.
% \begin{macrocode}
\newcommand\SB@trnotestep[1]{%
\ifnum\uccode`#1=`#1%
- \expandafter\def\expandafter\SB@temp\expandafter{\SB@temp#1}%
+ \SB@app\def\SB@temp{#1}%
\expandafter\SB@trscan%
\else%
\SB@cnt\z@%
@@ -8246,8 +8498,8 @@
% there needs to be a way to pull a vbox off the current list and determine
% whether or not it is a box that contains a measure bar. The solution is to
% insert a mark (|\SB@measuremark|) at the top of each measure bar vbox.
-% We can then see if this measure bar immediately follows another measure bar
-% by using |\vsplit| on |\lastbox|.
+% We can then see whether this measure bar immediately follows another measure
+% bar by using |\vsplit| on |\lastbox|.
% \begin{macrocode}
\newcommand\SB@measuremark{SB@IsMeasure}
% \end{macrocode}
@@ -8284,22 +8536,22 @@
\fi%
\fi%
\ifvmode\leavevmode\fi%
- \setbox\SB@box\hbox{\tiny\sffamily{#1}}%
- \setbox\SB@boxii\hbox{\tiny\sffamily{#2}}%
- \ifdim\wd\SB@box>\wd\SB@boxii%
- \SB@dimen\wd\SB@box\relax%
- \else%
- \SB@dimen\wd\SB@boxii\relax%
- \fi%
- \ifdim\SB@dimen<.5\p@%
- \SB@dimen.5\p@%
- \fi%
+ \setbox\SB@box\hbox{{\meterfont\relax#1}}%
+ \setbox\SB@boxii\hbox{{\meterfont\relax#2}}%
+ \SB@dimen\wd\ifdim\wd\SB@box>\wd\SB@boxii\SB@box\else\SB@boxii\fi%
\SB@dimenii\baselineskip%
\advance\SB@dimenii-2\p@%
\advance\SB@dimenii-\ht\SB@box%
\advance\SB@dimenii-\dp\SB@box%
\advance\SB@dimenii-\ht\SB@boxii%
\advance\SB@dimenii-\dp\SB@boxii%
+ \let\SB@temp\relax%
+ \ifdim\SB@dimen>\z@%
+ \advance\SB@dimenii-.75\p@%
+ \def\SB@temp{\kern.75\p@}%
+ \fi%
+ \SB@maxmin\SB@dimen<{.5\p@}%
+ \SB@maxmin\SB@dimenii<\z@%
\vbox{%
\mark{\SB@measuremark}%
\hbox to\SB@dimen{%
@@ -8313,6 +8565,7 @@
\box\SB@boxii%
\hfil%
}%
+ \SB@temp%
\nointerlineskip%
\hbox to\SB@dimen{%
\hfil%
@@ -8320,6 +8573,7 @@
\hfil%
}%
}%
+ \meter{}{}%
}
% \end{macrocode}
% \end{macro}
@@ -8339,7 +8593,6 @@
% \begin{macrocode}
\newcommand\measurebar{%
\mbar\SB@metertop\SB@meterbot%
- \meter{}{}%
}
% \end{macrocode}
% \end{macro}
@@ -8391,15 +8644,15 @@
%
% The obvious way to create a chord macro is as a normal macro with
% two arguments, one for the chord name and one for the lyrics to go
-% under the chord---e.g.~|\chord{|\meta{chordname}|{|\meta{lyric}|}|.
+% under the chord---e.g.~|\chord{|\Meta{chordname}|}{|\Meta{lyric}|}|.
% However, in practice such a macro is extremely cumbersome and
% difficult to use.
% The problem is that in order to use such a macro properly, the user
% must remember a bunch of complex style rules that govern what
-% part of the lyric text needs to go in the \meta{lyric} parameter and
+% part of the lyric text needs to go in the \Meta{lyric} parameter and
% what part should be typed after the closing brace.
% To avoid separating a word from its trailing punctuation, the
-% \meta{lyric} parameter must often include punctuation but not certain
+% \Meta{lyric} parameter must often include punctuation but not certain
% special punctuation like hyphens, should include the rest of the
% word but not if there's another chord in the word, should omit
% measure bars but only if measure bars are being shown, etc.
@@ -8415,7 +8668,7 @@
%
% \begin{macro}{\ifSB@wordends}
% \begin{macro}{\ifSB@brokenword}
-% Chord macros must look ahead in the input stream to see if this chord
+% Chord macros must look ahead in the input stream to see whether this chord
% is immediately followed by whitespace or the remainder of a word.
% If the latter, hyphenation might need to be introduced.
% These macros keep track of the need for hyphenation, if any.
@@ -8430,7 +8683,7 @@
% Lyrics appearing after a chord are scanned into the following token list
% register.
% \begin{macrocode}
-\newtoks\SB@lyric
+\SB@newtoks\SB@lyric
% \end{macrocode}
% \end{macro}
%
@@ -8439,7 +8692,7 @@
% The following counter counts the number of explicit hyphens ending
% the lyric syllable that follows the current chord.
% \begin{macrocode}
-\newcount\SB@numhyps
+\SB@newcount\SB@numhyps
% \end{macrocode}
% \end{macro}
%
@@ -8447,7 +8700,7 @@
% When a lyric syllable under a chord ends in exactly one hyphen, the
% following token register is set to be the syllable without the hyphen.
% \begin{macrocode}
-\newtoks\SB@lyricnohyp
+\SB@newtoks\SB@lyricnohyp
% \end{macrocode}
% \end{macro}
%
@@ -8456,8 +8709,8 @@
% The following two boxes hold the part of the lyric text that is to be
% typeset under the chord, and the chord text that is to be typeset above.
% \begin{macrocode}
-\newbox\SB@lyricbox
-\newbox\SB@chordbox
+\SB@newbox\SB@lyricbox
+\SB@newbox\SB@chordbox
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -8475,6 +8728,7 @@
% \begin{macro}{\SB@setchord}
% \changes{v2.3}{2007/09/23}{Support replayed chords over ligatures}
% \changes{v2.7}{2009/01/08}{Extend rather than replace chordbox}
+% \changes{v3.0}{2017/04/19}{Fix transposition of replayed chord over ligature}
% The following macro typesets its argument as a chord and stores the
% result in box |\SB@chordbox| for later placement into the document.
% The hat token (|^|) is redefined so that outside of math mode it
@@ -8490,18 +8744,15 @@
\newcommand\SB@setchord{}
{
\catcode`^\active
- \catcode`!7
\gdef\SB@setchord#1{%
\SB@gettabindtrue\SB@nohattrue%
\setbox\SB@chordbox\hbox{%
\unhbox\SB@chordbox%
\begingroup%
\ifSB@trackch%
- \def\SB@activehat{\ifmmode!\else\global\SB@nohatfalse\fi}%
+ \let\SB@activehat\SB@hat@tr%
\else%
- \def\SB@activehat{%
- \ifmmode!\else\SB@lop\SB@ctail\SB@toks\the\SB@toks\fi%
- }%
+ \let\SB@activehat\SB@hat@notr%
\fi%
\let^\SB@activehat%
\printchord{%
@@ -8523,38 +8774,45 @@
% \end{macro}
%
% \begin{macro}{\SB@outertest}
-% \begin{macro}{\SB@@outertest}
-% The lyric-scanning code must preemptively determine if the next token is
-% a macro declared |\outer| before it tries to accept that token as an
+% \begin{macro}{\SB@otesta}
+% \begin{macro}{\SB@otestb}
+% The lyric-scanning code must preemptively determine whether the next token
+% is a macro declared |\outer| before it tries to accept that token as an
% argument.
-% Otherwise \TeX\ will abort with a parsing error.
-% Macros declared |\outer| are not allowed in arguments, so determining if a
-% token is |\outer| is a delicate process.
+% Otherwise \TeX{} will abort with a parsing error.
+% Macros declared |\outer| are not allowed in arguments, so determining
+% whether a token is |\outer| is a delicate process.
% The following does so by consulting |\meaning|.
+% A macro can be identified as |\outer| if its meaning has the
+% word ``|\outer|'' before the first colon.
% \begin{macrocode}
-\newcommand\SB@outertest{}
-\edef\SB@outertest#1{%
- \noexpand\SB@@outertest#1%
- \string\outer%
- \noexpand\SB@@outertest%
+\newcommand\SB@outertest{%
+ \expandafter\SB@otesta\meaning\SB@next:\SB@otesta%
+}
+\newcommand\SB@otesta{}
+\edef\SB@otesta#1:#2\SB@otesta{%
+ \noexpand\SB@otestb%
+ #1\string\outer%
+ \noexpand\SB@otestb%
}
-\newcommand\SB@@outertest{}
-\expandafter\def\expandafter\SB@@outertest%
-\expandafter#\expandafter1\string\outer#2\SB@@outertest{%
+\newcommand\SB@otestb{}
+\expandafter\def\expandafter\SB@otestb%
+\expandafter#\expandafter1\string\outer#2\SB@otestb{%
\def\SB@temp{#2}%
- \ifx\SB@temp\@empty\else\SB@testtrue\fi%
+ \ifx\SB@temp\@empty\SB@testfalse\else\SB@testtrue\fi%
}
% \end{macrocode}
% \end{macro}
% \end{macro}
+% \end{macro}
%
% \begin{macro}{\SB@UTFtest}
-% \begin{macro}{\SB@two}
-% \begin{macro}{\SB@three}
-% \begin{macro}{\SB@four}
-% \begin{macro}{\SB@UTFtester}
+% \begin{macro}{\SB@U@two}
+% \begin{macro}{\SB@U@three}
+% \begin{macro}{\SB@U@four}
+% \begin{macro}{\SB@@UTFtest}
% \changes{v1.22}{2007/05/15}{Added.}
-% To support UTF-8 encoded \LaTeX\ source files, we need to be able to
+% To support UTF-8 encoded \LaTeX{} source files, we need to be able to
% identify multibyte characters during the lyric scanning process.
% Alas, the |utf8.def| file provides no clean way of identifying the
% macros it defines for this purpose.
@@ -8563,29 +8821,22 @@
% \begin{macrocode}
\newcommand\SB@UTFtest{}
\edef\SB@UTFtest#1{%
- \noexpand\SB@UTFtester#1%
+ \noexpand\expandafter%
+ \noexpand\SB@@UTFtest%
+ \noexpand\meaning#1%
\string\UTFviii@zero@octets%
- \noexpand\SB@UTFtester%
-}
-\begingroup
- \escapechar\m@ne
- \xdef\SB@two{\string\two}
- \xdef\SB@three{\string\three}
- \xdef\SB@four{\string\four}
- \xdef\SB@temp{\string\@octets}
-\endgroup
-\edef\SB@temp{##1\string\UTFviii@##2\SB@temp##3}
-\expandafter\def\expandafter\SB@UTFtester\SB@temp\SB@UTFtester{%
- \def\SB@temp{#2}%
- \ifx\SB@temp\SB@two%
- \SB@cnt\tw@%
- \else\ifx\SB@temp\SB@three%
- \SB@cnt\thr@@%
- \else\ifx\SB@temp\SB@four%
- \SB@cnt4 %
- \else%
- \SB@cnt\z@%
- \fi\fi\fi%
+ \noexpand\SB@@UTFtest%
+}
+\newcommand\SB@U@two{\global\SB@cnt\tw@}
+\newcommand\SB@U@three{\global\SB@cnt\thr@@}
+\newcommand\SB@U@four{\global\SB@cnt4\relax}
+\newcommand\SB@@UTFtest{}
+{\escapechar\m@ne
+ \xdef\SB@temp{\string\@octets}}
+\edef\SB@temp{##1\string\UTFviii@##2\SB@temp}
+\expandafter\def\expandafter\SB@@UTFtest\SB@temp#3\SB@@UTFtest{%
+ \SB@cnt\z@%
+ {\csname SB@U@#2\endcsname}%
}
% \end{macrocode}
% \end{macro}
@@ -8610,30 +8861,26 @@
% \begin{macrocode}
\newcommand\SB@declare[3]{%
\afterassignment\iffalse\let\SB@next= #3\relax\fi%
- \expandafter\SB@UTFtest\expandafter{\meaning\SB@next}%
+ \SB@UTFtest\SB@next%
\ifcase\SB@cnt%
\ifcat\noexpand#3\relax%
\SB@addNtest\SB@macrotests#1#2#3%
\else\ifcat\noexpand#3.%
- \SB@addDtest\SB@othertests#1#2#3%
+ \SB@addDtest\SB@othertests#1#2%
\else\ifcat\noexpand#3A%
- \SB@addDtest\SB@lettertests#1#2#3%
+ \SB@addDtest\SB@lettertests#1#2%
\else%
- \SB@addDtest\relax0#2#3%
+ \SB@addDtest\relax0#2%
\fi\fi\fi%
\or%
\SB@addNtest\SB@macrotests#1#2#3%
\else%
- \SB@addMtest\SB@multitests#1#2{#3}%
+ \SB@addMtest\SB@multitests#1#2#3\relax\relax\relax%
\fi%
}
\newcommand\DeclareLyricChar{\SB@declare\SB@testtrue0}
-\newcommand\DeclareNonLyric{%
- \SB@declare\SB@testfalse\SB@testfalse%
-}
-\newcommand\DeclareNoHyphen{%
- \SB@declare\SB@testfalse\SB@testtrue%
-}
+\newcommand\DeclareNonLyric{\SB@declare\SB@testfalse\SB@testfalse}
+\newcommand\DeclareNoHyphen{\SB@declare\SB@testfalse\SB@testtrue}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -8644,7 +8891,6 @@
% \begin{macro}{\SB@macrotests}
% \begin{macro}{\SB@multitests}
% \begin{macro}{\SB@othertests}
-% \begin{macro}{\SB@hyphtests}
% For speed, token tests introduced by |\DeclareLyricChar| and friends
% are broken out into separate macros based on category codes.
% \begin{macrocode}
@@ -8652,39 +8898,32 @@
\newcommand\SB@macrotests{}
\newcommand\SB@multitests{}
\newcommand\SB@othertests{}
-\newcommand\SB@hyphtests{}
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
-% \end{macro}
%
% The following macros add tests to the test macros defined above.
% In each, \argp{1} is the test macro to which the test should be added,
% \argp{2} and \argp{3} is the code to be executed at scanning-time and
% at hyphenation-time if the test succeeds (or ``0'' if no action is to
% be performed), and \argp{4} is the token to which the currently scanned
-% token should be compared to determine if it matches.
-%
-% \begin{macro}{\SB@addtest}
-% Append the top-level expansion of \argp{2} to the control sequence name
-% given by \argp{1}.
-% \begin{macrocode}
-\newcommand\SB@addtest[2]{%
- \expandafter\gdef\expandafter#1\expandafter{#1#2}%
-}
-% \end{macrocode}
-% \end{macro}
+% token should be compared to determine whether it matches.
%
% \begin{macro}{\SB@addDtest}
-% A definition-test: The test succeeds if the \emph{definition} at test-time
-% of the next lyric token matches the \emph{definition at test-time} of
-% the control sequence that was given to the |\Declare| macro.
+% A definition-test: The test succeeds if the next lyric token has the same
+% meaning (at test-time) of the non-macro, non-active character token that
+% was given to the |\Declare| macro.
% \begin{macrocode}
-\newcommand\SB@addDtest[4]{%
- \ifx0#2\else\SB@addtest#1{\ifx\SB@next#4#2\fi}\fi%
- \ifx0#3\else\SB@addtest\SB@hyphtests{\ifx\SB@next#4#3\fi}\fi%
+\newcommand\SB@addDtest[3]{%
+ \ifx0#2\else%
+ \def#1{{\csname SB@!\meaning\SB@next\endcsname}}%
+ \expandafter\def\csname SB@!\meaning\SB@next\endcsname{\global#2}%
+ \fi%
+ \ifx0#3\else%
+ \expandafter\def\csname SB@HT@\meaning\SB@next\endcsname{\global#3}%
+ \fi%
}
% \end{macrocode}
% \end{macro}
@@ -8697,14 +8936,11 @@
% \begin{macrocode}
\newcommand\SB@addNtest[4]{%
\ifx0#2\else%
- \SB@addtest#1{%
- \edef\SB@temp{\string#4}\ifx\SB@temp\SB@nextname#2\fi%
- }%
+ \def#1{{\csname SB@!\SB@nextname\endcsname}}%
+ \expandafter\def\csname SB@!\string#4\endcsname{\global#2}%
\fi%
\ifx0#3\else%
- \SB@addtest\SB@hyphtests{%
- \edef\SB@temp{\string#4}\ifx\SB@temp\SB@nextname#3\fi%
- }%
+ \expandafter\def\csname SB@HT@\string#4\endcsname{\global#3}%
\fi%
}
% \end{macrocode}
@@ -8715,19 +8951,26 @@
% beginning of a UTF-8 encoded multibyte character sequence that matches
% the multibyte sequence given to the |\Declare| macro.
% \begin{macrocode}
-\newcommand\SB@addMtest[4]{%
+\newcommand\SB@addMtest[7]{%
+ \edef\SB@temp{%
+ \string#4%
+ \ifx\relax#5\else\string#5\fi%
+ \ifx\relax#6\else\string#6\fi%
+ \ifx\relax#7\else\string#7\fi%
+ }%
\ifx0#2\else%
- \SB@addtest#1{\def\SB@temp{#4}\ifx\SB@next\SB@temp#2\fi}%
+ \def#1{{\csname SB@!\SB@nextname\endcsname}}%
+ \expandafter\def\csname SB@!\SB@temp\endcsname{\global#2}%
\fi%
- \ifx0#3\else\SB@addtest\SB@hyphtests{%
- \def\SB@temp{#4}\ifx\SB@next\SB@temp#3\fi}%
+ \ifx0#3\else%
+ \expandafter\def\csname SB@HT@\SB@temp\endcsname{\global#3}%
\fi%
}
% \end{macrocode}
% \end{macro}
%
% The following code declares the common intra-word macros provided by
-% \TeX\ (as listed on p.~52 of The \TeX book) to be lyric-continuing.
+% \TeX{} (as listed on p.~52 of The \TeX book) to be lyric-continuing.
% \begin{macrocode}
\DeclareLyricChar\`
\DeclareLyricChar\'
@@ -8795,9 +9038,9 @@
% To accomplish this, |\SB@begincname| must always be invoked before any
% macro whose argument is a chord name, and |\SB@endcname| must be invoked
% at the start of the body of any macro whose argument is a chord name.
-% To aid in debugging, we also temporarily set \meta{return} characters and
+% To aid in debugging, we also temporarily set \Meta{return} characters and
% chord macros |\outer|.
-% This will cause \TeX\ to halt with a runaway argument error on the correct
+% This will cause \TeX{} to halt with a runaway argument error on the correct
% source line if the user forgets to type a closing end-brace (a common typo).
% Colon characters are also set non-active to avoid a conflict between the
% \textsf{Babel} French package and the |\gtab| macro.
@@ -8810,7 +9053,7 @@
\catcode`:12\relax%
\catcode`\^^M\active\SB@outer\def^^M{}%
\SB@outer\def\[{}%
- \chordlocals%
+ \chordlocals\relax%
}
}
\newcommand\SB@endcname{}
@@ -8879,8 +9122,8 @@
\newcommand\MultiwordChords{%
\def\SB@spcinit{%
\let\SB@chdone\SB@chlyrdone%
- \def\SB@chimpspace{\let\SB@donext\SB@chdone}%
- \def\SB@chexpspace{\let\SB@donext\SB@chdone}%
+ \let\SB@chimpspace\SB@chnxtdone%
+ \let\SB@chexpspace\SB@chnxtdone%
\let\SB@chespace\SB@chendspace%
}%
}
@@ -8904,12 +9147,27 @@
% \end{macro}
% \end{macro}
%
+% \begin{macro}{\SB@chnxtrelax}
+% \begin{macro}{\SB@chnxtstep}
+% \begin{macro}{\SB@chnxtdone}
+% To shorten the lyric parser macros that follow and thereby improve their
+% speed, we here define some abbreviations for common logic in untaken
+% branches.
+% \begin{macrocode}
+\newcommand\SB@chnxtrelax{\let\SB@donext\relax}
+\newcommand\SB@chnxtstep{\let\SB@donext\SB@chstep}
+\newcommand\SB@chnxtdone{\let\SB@donext\SB@chdone}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
% Warning: In the lyric-scanner macros that follow, |\SB@next|
% might be a macro declared |\outer|.
% This means that it must \emph{never} be passed as an argument to
% a macro and it must never explicitly appear in any untaken branch
% of a conditional.
-% If it does, the \TeX\ parser will complain of a runaway argument
+% If it does, the \TeX{} parser will complain of a runaway argument
% when it tries to skip over an |\outer| macro while consuming tokens
% at high speed.
%
@@ -8925,20 +9183,13 @@
% left-quote or left-double-quote symbol, which looks better.
% \begin{macrocode}
\newcommand\SB@chstart{%
- \ifx\SB@next\[%
- \let\SB@donext\relax%
- \else\ifx\SB@next\SB@activehat%
- \let\SB@donext\relax%
- \else\ifx\SB@next\ch%
- \let\SB@donext\relax%
- \else\ifx\SB@next\mch%
- \let\SB@donext\relax%
- \else\ifx\SB@next`%
- \let\SB@donext\SB@chstep%
- \else\ifx\SB@next'%
- \let\SB@donext\SB@chstep%
- \else\ifx\SB@next"%
- \let\SB@donext\SB@chstep%
+ \ifx\SB@next\[\SB@chnxtrelax%
+ \else\ifx\SB@next\SB@activehat\SB@chnxtrelax%
+ \else\ifx\SB@next\ch\SB@chnxtrelax%
+ \else\ifx\SB@next\mch\SB@chnxtrelax%
+ \else\ifx\SB@next`\SB@chnxtstep%
+ \else\ifx\SB@next'\SB@chnxtstep%
+ \else\ifx\SB@next"\SB@chnxtstep%
\else%
\the\SB@lyric%
\SB@lyric{}%
@@ -8953,16 +9204,16 @@
%
% \begin{macro}{\SB@chnorm}
% \changes{v2.0}{2007/06/18}{Rewritten for speed}
-% First, check to see if the lyric token is a letter.
+% First, check to see whether the lyric token is a letter.
% Since that's the most common case, we do this check first for speed.
% \begin{macrocode}
\newcommand\SB@chnorm{%
\ifcat\noexpand\SB@next A%
\SB@testtrue\SB@lettertests%
\ifSB@test%
- \SB@chespace\let\SB@donext\SB@chstep%
+ \SB@chespace\SB@chnxtstep%
\else%
- \let\SB@donext\SB@chdone%
+ \SB@chnxtdone%
\fi%
\else%
\SB@chtrymacro%
@@ -8972,7 +9223,7 @@
% \end{macro}
%
% \begin{macro}{\SB@chtrymacro}
-% Next, check to see if it's a macro or active character.
+% Next, check to see whether it's a macro or active character.
% We do these checks next because these are the only cases when the
% token might be |\outer|.
% Once we eliminate that ugly possibility, we can write the rest of
@@ -8998,26 +9249,26 @@
% we can be sure that the token isn't |\outer| at this point.
% \begin{macrocode}
\newcommand\SB@chother{%
- \ifcat\noexpand\SB@next\noexpand\@sptoken%
+ \ifcat\noexpand\SB@next\@sptoken%
\SB@chexpspace%
- \else\ifcat\noexpand\SB@next\noexpand\bgroup%
+ \else\ifcat\noexpand\SB@next\bgroup%
\SB@chespace\let\SB@donext\SB@chbgroup%
- \else\ifcat\noexpand\SB@next\noexpand\egroup%
+ \else\ifcat\noexpand\SB@next\egroup%
\SB@chespace\let\SB@donext\SB@chegroup%
\else\ifx\SB@next-%
\SB@numhyps\@ne\relax%
\SB@lyricnohyp\expandafter{\the\SB@lyric}%
\let\SB@dothis\SB@chhyph%
- \SB@chespace\let\SB@donext\SB@chstep%
+ \SB@chespace\SB@chnxtstep%
\else\ifcat\noexpand\SB@next.%
\SB@testtrue\SB@othertests%
\ifSB@test%
- \SB@chespace\let\SB@donext\SB@chstep%
+ \SB@chespace\SB@chnxtstep%
\else%
- \let\SB@donext\SB@chdone%
+ \SB@chnxtdone%
\fi%
\else%
- \SB@chespace\let\SB@donext\SB@chstep%
+ \SB@chespace\SB@chnxtstep%
\fi\fi\fi\fi\fi%
}
% \end{macrocode}
@@ -9029,10 +9280,9 @@
% If it's |\outer|, it should never be used in an argument, so stop here.
% \begin{macrocode}
\newcommand\SB@chmacro{%
- \SB@testfalse%
- \expandafter\SB@outertest\expandafter{\meaning\SB@next}%
+ \SB@outertest%
\ifSB@test%
- \let\SB@donext\SB@chdone%
+ \SB@chnxtdone%
\else%
\let\SB@donext\SB@chgetname%
\fi%
@@ -9055,16 +9305,16 @@
% \begin{macro}{\SB@@chmacro}
% The lyric-scanner has encountered a non-|\outer| macro or active character.
% Its |\string|ified name has been stored in |\SB@nextname|.
-% Test to see if it's a known macro or the beginning of a multibyte-encoded
-% international character.
+% Test to see whether it's a known macro or the beginning of a
+% multibyte-encoded international character.
% If the former, dispatch some macro-specific code to handle it.
% If the latter, grab the full multibyte sequence and include it in the lyric.
% \begin{macrocode}
\newcommand\SB@@chmacro{%
\ifx\SB@next\SB@activehat%
- \let\SB@donext\SB@chdone%
+ \SB@chnxtdone%
\else\ifx\SB@next\SB@par%
- \let\SB@donext\SB@chdone%
+ \SB@chnxtdone%
\else\ifx\SB@next\measurebar%
\SB@chmbar%
\else\ifx\SB@next\mbar%
@@ -9078,7 +9328,7 @@
\else\ifx\SB@next\SB@nbsp%
\SB@chimpspace%
\else%
- \expandafter\SB@UTFtest\expandafter{\meaning\SB@next}%
+ \SB@UTFtest\SB@next%
\ifcase\SB@cnt\SB@chothermac%
\or\or\SB@chespace\let\SB@donext\SB@chsteptwo%
\or\SB@chespace\let\SB@donext\SB@chstepthree%
@@ -9093,8 +9343,8 @@
% The lyric-scanner has encountered a macro or active character that is
% not |\outer|, not a known macro that requires special treatment,
% and not a multibyte international character.
-% First, check the macro's name (stored in |\SB@nextname|) to see if it begins
-% with a non-escape character.
+% First, check the macro's name (stored in |\SB@nextname|) to see whether it
+% begins with a non-escape character.
% If so, it's probably an accenting or punctuation character made active
% by the |inputenc| or |babel| packages.
% Most such characters should be included in the lyric, so include it by
@@ -9108,9 +9358,9 @@
\ifnum\the\catcode\SB@cnt=\z@\else\SB@testtrue\fi%
\SB@macrotests%
\ifSB@test%
- \SB@chespace\let\SB@donext\SB@chstep%
+ \SB@chespace\SB@chnxtstep%
\else%
- \let\SB@donext\SB@chdone%
+ \SB@chnxtdone%
\fi%
}
% \end{macrocode}
@@ -9133,12 +9383,16 @@
\SB@lyric\expandafter{\the\SB@lyric#1}%
\SB@chscan%
}
-\newcommand\SB@chsteptwo[2]{\SB@chmulti{#1#2}}
-\newcommand\SB@chstepthree[3]{\SB@chmulti{#1#2#3}}
-\newcommand\SB@chstepfour[4]{\SB@chmulti{#1#2#3#4}}
-\newcommand\SB@chmulti[1]{%
+\newcommand\SB@chsteptwo[2]{\SB@chmulti{#1#2}{\string#1\string#2}}
+\newcommand\SB@chstepthree[3]{%
+ \SB@chmulti{#1#2#3}{\string#1\string#2\string#3}%
+}
+\newcommand\SB@chstepfour[4]{%
+ \SB@chmulti{#1#2#3#4}{\string#1\string#2\string#3\string#4}%
+}
+\newcommand\SB@chmulti[2]{%
\def\SB@next{#1}%
- \let\SB@nextname\relax%
+ \edef\SB@nextname{#2}%
\SB@testtrue\SB@multitests%
\ifSB@test%
\SB@lyric\expandafter{\the\SB@lyric#1}%
@@ -9164,9 +9418,9 @@
\newcommand\SB@chhyph{%
\ifx\SB@next-%
\advance\SB@numhyps\@ne\relax%
- \let\SB@donext\SB@chstep%
+ \SB@chnxtstep%
\else%
- \let\SB@donext\SB@chdone%
+ \SB@chnxtdone%
\fi%
}
% \end{macrocode}
@@ -9178,8 +9432,10 @@
% Normally this just ends the lyric, but if |\MultiwordChords| is
% active, these macros both get redefined to process the space.
% \begin{macrocode}
-\newcommand\SB@chimpspace{\let\SB@donext\SB@chdone}
-\newcommand\SB@chexpspace{\let\SB@donext\SB@chdone}
+\newcommand\SB@chimpspace{}
+\let\SB@chimpspace\SB@chnxtdone
+\newcommand\SB@chexpspace{}
+\let\SB@chexpspace\SB@chnxtdone
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -9244,12 +9500,12 @@
\ifdim\wd\SB@lyricbox<\wd\SB@chordbox%
\let\SB@chbstok= \SB@next%
\def\SB@chexpspace{\let\SB@donext\SB@chgetspace}%
- \def\SB@chimpspace{\let\SB@donext\SB@chstep}%
+ \let\SB@chimpspace\SB@chnxtstep%
\let\SB@chespace\SB@chendspace%
\let\SB@chdone\SB@chspcdone%
\else%
- \def\SB@chimpspace{\let\SB@donext\SB@chdone}%
- \def\SB@chexpspace{\let\SB@donext\SB@chdone}%
+ \let\SB@chimpspace\SB@chnxtdone%
+ \let\SB@chexpspace\SB@chnxtdone%
\fi%
}
\newcommand\SB@chgetspace{%
@@ -9268,9 +9524,9 @@
% \begin{macrocode}
\newcommand\SB@chmbar{%
\ifmeasures%
- \let\SB@donext\SB@chdone%
+ \SB@chnxtdone%
\else%
- \SB@chespace\let\SB@donext\SB@chstep%
+ \SB@chespace\SB@chnxtstep%
\fi%
}
% \end{macrocode}
@@ -9319,8 +9575,7 @@
\fi%
}
\newcommand\SB@chegrpouter{%
- \SB@testfalse%
- \expandafter\SB@outertest\expandafter{\meaning\SB@next}%
+ \SB@outertest%
\ifSB@test%
\expandafter\SB@chegrpdone%
\else%
@@ -9347,13 +9602,15 @@
% Consume it and all of its arguments, and load them into some
% registers for future processing.
% (Part of the ligature might fall into this lyric text or might
-% not, depending on if we decide to add hyphenation.)
+% not, depending on whether we decide to add hyphenation.)
% Then end the lyric text here.
% \begin{macrocode}
\newcommand\SB@chlig[5]{%
\gdef\SB@ligpre{{#3}}%
\gdef\SB@ligpost{\[#2]{#4}}%
- \gdef\SB@ligfull{\[\SB@noreplay{\hphantom{{\lyricfont#3}}}#2]{#5}}%
+ \gdef\SB@ligfull{%
+ \[\SB@noreplay{\hphantom{{\lyricfont\relax#3}}}#2]{#5}%
+ }%
\SB@chdone%
}
\newcommand\SB@mchlig[5]{%
@@ -9446,16 +9703,18 @@
\newcommand\SB@emitchord{%
\ifSB@inverse\else\ifSB@inchorus\else\SB@errchord\fi\fi%
\SB@testfalse%
- \ifcat\noexpand\SB@next\noexpand\@sptoken\SB@testtrue\fi%
+ \ifcat\noexpand\SB@next\@sptoken\SB@testtrue\fi%
\ifcat\noexpand\SB@next.\SB@testtrue\fi%
\ifx\SB@next\SB@par\SB@testtrue\fi%
\ifx\SB@next\egroup\SB@testtrue\fi%
\ifx\SB@next\endgroup\SB@testtrue\fi%
- \SB@hyphtests%
+ {\csname%
+ SB@HT@\ifx\SB@nextname\relax\meaning\SB@next\else\SB@nextname\fi%
+ \endcsname}%
\ifSB@test\SB@wordendstrue\else\SB@wordendsfalse\fi%
% \end{macrocode}
% Next, compare the width of the lyric to the width of the chord to
-% determine if hyphenation might be necessary.
+% determine whether hyphenation might be necessary.
% The original lyric text might have ended in a string of one or more
% explicit hyphens, enumerated by |\SB@numhyps|.
% If it ended in exactly one, the lyric-scanning code suppresses that hyphen
@@ -9513,7 +9772,8 @@
\advance\SB@dimen.5em%
\hbox to\SB@dimen{\unhbox\SB@chordbox\hfil}%
\hbox to\SB@dimen{%
- \unhcopy\SB@lyricbox\hfil\char\hyphenchar\font\hfil%
+ \unhcopy\SB@lyricbox\hfil
+ \ifnum\hyphenchar\font>\m@ne\char\hyphenchar\font\hfil\fi%
}%
\global\SB@cnt\@m%
\gdef\SB@temp{\expandafter\SB@clearlig\SB@ligpost}%
@@ -9534,7 +9794,7 @@
% difficult to read.
% If the chord has a lyric but it doesn't end on a word boundary, insert
% an appropriate penalty to prevent linebreaking without hyphenation.
-% Also preserve the spacefactor in this case, which allows \LaTeX\ to
+% Also preserve the spacefactor in this case, which allows \LaTeX{} to
% fine-tune the spacing between consecutive characters in the word that
% contains the chord.
% \begin{macrocode}
@@ -9614,7 +9874,7 @@
% do not render well in arbitrary sizes.
% To solve the problem, we must therefore choose an appropriate size
% individually for each possible base font size $b$.
-% This is the solution adopted by the rest of \LaTeX\ for such things.
+% This is the solution adopted by the rest of \LaTeX{} for such things.
% For example, \LaTeX's |\DeclareMathSizes| macro defines an appropriate
% superscript size for each possible base font size.
% The macro below creates a similar macro that that defines an appropriate
@@ -9727,6 +9987,31 @@
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}{\SB@hat@tr}
+% In verses/choruses where chords are being memorized, |\SB@activehat|
+% gets set to this definition, which marks the current chord as immune to
+% memorization.
+% \begin{macrocode}
+\newcommand\SB@hat@tr{%
+ \ifmmode^\else\global\SB@nohatfalse\fi%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\SB@hat@notr}
+% In verses/choruses where chords are being replayed, |\SB@activehat|
+% get set to the following, which replays the next memorized chord and
+% subjects it to any required transposition and/or note conversion.
+% \begin{macrocode}
+\newcommand\SB@hat@notr{%
+ \ifmmode^\else%
+ \SB@lop\SB@ctail\SB@toks%
+ \expandafter\transposehere\expandafter{\the\SB@toks}%
+ \fi%
+}
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macro}{\SB@loadactives}
% It's cumbersome to have to type |\shrp|, |\flt|, and |\mbar| every time you
% want a sharp, flat, or measure bar, so within verses and choruses we allow
@@ -9768,8 +10053,8 @@
% \begin{macro}{\SB@cr@}
% Reserve token registers to record a history of the chords seen in a verse.
% \begin{macrocode}
-\newtoks\SB@cr@
-\newtoks\SB@ctail
+\SB@newtoks\SB@cr@
+\SB@newtoks\SB@ctail
% \end{macrocode}
% \end{macro}
%
@@ -9787,7 +10072,7 @@
% \begin{macrocode}
\newcommand\newchords[1]{%
\@ifundefined{SB@cr@#1}{%
- \expandafter\newtoks\csname SB@cr@#1\endcsname%
+ \expandafter\SB@newtoks\csname SB@cr@#1\endcsname%
\global\csname SB@cr@#1\endcsname{\\}%
}{\SB@errdup{#1}}%
}
@@ -10010,7 +10295,7 @@
% properly.
% \begin{macrocode}
\newif\ifSB@gettabind\SB@gettabindfalse
-\newdimen\SB@tabindent
+\SB@newdimen\SB@tabindent
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -10020,8 +10305,8 @@
% \begin{macro}{\SB@targfing}
% Reserve some macro names in which to store the three pieces of the
% second argument to the |\gtab| macro.
-% The first is for the fret number, the second is for the \meta{strings}
-% info, and the last is for the \meta{fingering} info.
+% The first is for the fret number, the second is for the \Meta{strings}
+% info, and the last is for the \Meta{fingering} info.
% \begin{macrocode}
\newcommand\SB@targfret{}
\newcommand\SB@targstr{}
@@ -10038,7 +10323,7 @@
% $\varepsilon$-\TeX).
%
% We therefore adopt the alternative strategy of converting each token
-% in the \meta{strings} and \meta{fingering} arguments of a |\gtab| macro
+% in the \Meta{strings} and \Meta{fingering} arguments of a |\gtab| macro
% into a control sequence (using |\csname|).
% We can then temporarily assign meanings to those control sequences and
% replay the arguments to achieve various effects.
@@ -10107,7 +10392,7 @@
%
% \begin{macro}{\SB@gtmax}
% To compute the height of the tablature diagram, we must identify the
-% maximum fret number in the \meta{strings} argument.
+% maximum fret number in the \Meta{strings} argument.
% This is accomplished by using the following macro in combination with
% |\SB@gtset| above.
% \begin{macrocode}
@@ -10248,10 +10533,10 @@
% \begin{macro}{\SB@ctoken}
% Break the second argument to a |\gtab| macro into three sub-arguments.
% The possible forms are:
-% (a) \meta{strings},
-% (b) \meta{fret}|:|\meta{strings},
-% (c) \meta{strings}|:|\meta{fingering}, or
-% (d) \meta{fret}|:|\meta{strings}|:|\meta{fingering}.
+% (a) \Meta{strings},
+% (b) \Meta{fret}|:|\Meta{strings},
+% (c) \Meta{strings}|:|\Meta{fingering}, or
+% (d) \Meta{fret}|:|\Meta{strings}|:|\Meta{fingering}.
% To distinguish forms (b) and (c), we count the number of tokens before
% the first colon.
% If there is only one token, we assume it must be form (b), since frets
@@ -10375,10 +10660,10 @@
% number of index entries when building a song index. The other two types are
% designated by the user.
%
-% As is typical of \LaTeX\ indexes, generation of song book indexes requires
+% As is typical of \LaTeX{} indexes, generation of song book indexes requires
% two passes of document compilation. During the first pass, data files are
% generated with song titles, authors, and scripture references. An external
-% program is then used to produce \LaTeX\ source files from those data files.
+% program is then used to produce \LaTeX{} source files from those data files.
% During the second pass of document compilation, those source files are
% imported to typeset all the indexes and display them in the document.
%
@@ -10389,7 +10674,7 @@
% the data is stored in a box of non-immediate write whatsit nodes.
% \item The whatsits are migrated out to the top of the song box when
% it is finalized at |\endsong|.
-% \item When the song box is shipped out to the output file, \TeX\ expands
+% \item When the song box is shipped out to the output file, \TeX{} expands
% the whatsits, causing the data to be written to the |.sxc| auxiliary file.
% \item At the |\end{document}| line, the |.sxc| is processed multiple
% times---once for each index---to split the data into the respective
@@ -10398,16 +10683,59 @@
% The first and second steps allow index references to point to the
% beginning of the song no matter where the indexing commands appear
% within the song.
-% The third step allows \TeX\ to drop index entries that refer to
+% The third step allows \TeX{} to drop index entries that refer to
% songs that do not actually appear in the output (e.g., because of
% |\includeonlysongs|).
% It also allows index entries to refer to information that is only decided
% at shipout time, such as page numbers.
% The fourth step allows all indexing to be accomplished with at most one
% write register.
-% \LaTeX\ provides extremely few write registers, so using as
+% \LaTeX{} provides extremely few write registers, so using as
% few as possible is essential for supporting books with many indexes.
%
+% \begin{macro}{\songtarget}\MainImpl{songtarget}
+% This macro is invoked by each \mac{beginsong} environment with two arguments:
+% (1) a suggested pdf bookmark index level, and
+% (2) a target name to which hyperlinks for this song in the index will refer.
+% The macro is expected to produce a suitable pdf bookmark entry and/or
+% link target.
+% The default definition tries to use |\pdfbookmark| if generating a PDF,
+% and resorts to |\hypertarget| (if it exists) otherwise.
+% The user can redefine the macro to customize how and whether bookmarks
+% and/or links are created.
+% \begin{macrocode}
+\newcommand\songtarget[2]{%
+ \ifnum\@ne=0\ifSB@pdf\ifx\pdfbookmark\undefined\else%
+ \ifx\pdfbookmark\relax\else1\fi\fi\fi\relax%
+ \pdfbookmark[#1]{\thesongnum. \songtitle}{#2}%
+ \else\ifx\hypertarget\undefined%
+ \else\ifx\hypertarget\relax\else%
+ \hypertarget{#2}{\relax}%
+ \fi\fi\fi%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\songlink}\MainImpl{songlink}
+% This macro is invoked by the index code to produce a link to a song target
+% created by \mac{songtarget}.
+% Its two arguments are:
+% (1) the target name (same as the second argument to \mac{songtarget}, and
+% (2) the text that is to be linked.
+% The default implementation uses |\hyperlink| if it exists; otherwise it
+% just leaves the text unlinked.
+% \begin{macrocode}
+\newcommand\songlink{%
+ \ifnum\@ne=0\ifx\hyperlink\undefined\else%
+ \ifx\hyperlink\relax\else1\fi\fi\relax%
+ \expandafter\hyperlink%
+ \else%
+ \expandafter\@gobble%
+ \fi%
+}
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macro}{\SB@indexlist}
% This macro records the comma-separated list of the identifiers of indexes
% associated with the current book section.
@@ -10447,7 +10775,7 @@
}%
\if@filesw%
\ifx\SB@out\relax%
- \newwrite\SB@out%
+ \SB@newwrite\SB@out%
\immediate\openout\SB@out=\jobname.sxc\relax%
\fi%
\immediate\write\SB@out{\noexpand\SB@iwrite{#3}{#2}}%
@@ -10496,12 +10824,46 @@
% \begin{macrocode}
\newcommand\SB@cwrite[2]{%
\ifx\SB@out\relax\else%
- \protected@write\SB@out{}{\protect\SB@iwrite{#1}{#2}}%
+ \protected@write\SB@out\SB@keepactive{\protect\SB@iwrite{#1}{#2}}%
\fi%
}
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}{\SB@keepactive}
+% By default, the |inputenc| package expands Unicode characters into macro
+% names when writing them to files.
+% This behavior must be inhibited when writing to the |.sxc| file, since
+% |songidx| needs the original Unicode characters for sorting.
+% To achieve this, we temporarily redefine most active characters so that
+% they expand to an unexpandable string version of themselves.
+% \begin{macrocode}
+\newcommand\SB@keepactive{}
+{\catcode`\~\active
+ \catcode`\.12
+ \def\\#1#2{%
+ \endgroup
+ \SB@app\gdef\SB@keepactive{\def#1{#2}}%
+ }
+ \def\SB@temp#1#2{%
+ \SB@cnt#1\relax
+ \loop
+ \begingroup
+ \uccode`\~\SB@cnt
+ \uccode`\.\SB@cnt
+ \uppercase{\\~.}
+ \ifnum\SB@cnt<#2\relax
+ \advance\SB@cnt\@ne
+ \repeat
+ }
+ \SB@temp{1}{8}
+ \SB@temp{11}{11}
+ \SB@temp{14}{91}
+ \SB@temp{93}{255}
+}
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macro}{\SB@iwrite}
% The line contributed by |\SB@cwrite| to the |.sxc| file is an |\SB@iwrite|
% macro that re-outputs the data to an appropriate |.sxd| file.
@@ -10545,7 +10907,7 @@
% The following box register stores index data until it can be migrated to
% the top of the song box currently under construction.
% \begin{macrocode}
-\newbox\SB@songwrites
+\SB@newbox\SB@songwrites
% \end{macrocode}
% \end{macro}
%
@@ -10674,19 +11036,21 @@
% \begin{macro}{\authignoreword}\MainImpl{authignoreword}
% \begin{macro}{\titleprefixword}\MainImpl{titleprefixword}
% \changes{v2.0}{2007/06/18}{Added.}
-% The |songidx| index-generation program understands several different
+% The |songidx| index-generation script understands several different
% directives that each dictate various aspects of how index entries are
% parsed, sorted, and displayed.
% Such directives should typically appear at the start of the |.sxd|
% file just after the header line that identifies the type of index.
% \begin{macrocode}
\newcommand\SB@idxcmd[3]{%
- \ifx\SB@out\relax\else%
+ \ifx\SB@allindexes\@empty%
+ \SB@warnnoidx%
+ \else\ifx\SB@out\relax\else%
\@for\SB@temp:=\SB@allindexes\do{%
\csname SB@idxsel@\SB@temp\endcsname%
{\SB@@idxcmd{#1}}{\SB@@idxcmd{#2}}{\SB@@idxcmd{#3}}%
}%
- \fi%
+ \fi\fi%
}
\newcommand\SB@@idxcmd[1]{%
\def\SB@tempii{#1}%
@@ -10701,9 +11065,9 @@
\newcommand\authignoreword[1]{}
\newcommand\titleprefixword[1]{}
{\catcode`\%=12
- \gdef\authsepword#1{\SB@idxcmd{}{%sep #1}{}}
- \gdef\authbyword#1{\SB@idxcmd{}{%after #1}{}}
- \gdef\authignoreword#1{\SB@idxcmd{}{%ignore #1}{}}
+ \gdef\authsepword#1{\SB@idxcmd{}{}{%sep #1}}
+ \gdef\authbyword#1{\SB@idxcmd{}{}{%after #1}}
+ \gdef\authignoreword#1{\SB@idxcmd{}{}{%ignore #1}}
\gdef\titleprefixword#1{\SB@idxcmd{%prefix #1}{}{}}}
\@onlypreamble\authsepword
\@onlypreamble\authbyword
@@ -10717,13 +11081,6 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}{\SB@idxtitlebox}
-% Define a box to hold the index title.
-% \begin{macrocode}
-\newbox\SB@idxtitlebox
-% \end{macrocode}
-% \end{macro}
-%
% \begin{macro}{\SB@idxlineskip}
% Set the spacing between lines in an index.
% \begin{macrocode}
@@ -10736,7 +11093,7 @@
% When rendering an index entry $X\ldots Y$ that is too long to fit on one
% physical line, we must break text $X$ and/or $Y$ up into multiple lines.
% Text $X$ should be typeset as a left-justified paragraph with a right
-% margin of about 2em; however, it's final line must not be so long that it
+% margin of about 2em; however, its final line must not be so long that it
% cannot fit even the first item of list $Y$.
% Text $Y$ should be typeset as a right-justified paragraph whose first line
% begins on the last line of $X$.
@@ -10786,13 +11143,13 @@
%
% First, we must pre-compute the width $w_1$ of the final line of $X$ when
% $X$ is typeset as a left-justified paragraph, storing it in |\SB@dimenii|.
-% This is necessary because in order to force \TeX\ to typeset the first
+% This is necessary because in order to force \TeX{} to typeset the first
% line of $Y$ at some chosen width $w_2$, we must insert leaders of width
% $c-w_1-w_2$ into the paragraph between $X$ and $Y$, where $c$ is the column
% width.
%
% Computing this width $w_1$ is a bit tricky.
-% We must tell \TeX\ that the last line of $X$ must not be so long that it
+% We must tell \TeX{} that the last line of $X$ must not be so long that it
% does not even have room for the first item of $Y$.
% Thus, we must strip off the first item of $Y$ and add it (or a non-breaking
% space of equivalent width) to the end of $X$ to typeset the paragraph.
@@ -11007,7 +11364,7 @@
% \changes{v2.8}{2009/03/06}{Changed argument order}
% Create an index with title \argp{2} and with \argp{1} columns (must be a
% literal constant). Input the index contents from external file \argp{3},
-% which is expected to be a \TeX\ file.
+% which is expected to be a \TeX{} file.
% \begin{macrocode}
\newcommand\SB@displayindex[3]{%
\ifsongindexes\begingroup%
@@ -11015,7 +11372,7 @@
\advance\SB@colwidth-#1\columnsep%
\advance\SB@colwidth\columnsep%
\divide\SB@colwidth#1%
- \setbox\SB@idxtitlebox\vbox{%
+ \setbox\SB@envbox\vbox{%
\let\SB@temp\songsection%
\ifx\chapter\undefined\else%
\ifx\chapter\relax\else%
@@ -11026,18 +11383,16 @@
}%
% \end{macrocode}
% The |.sbx| index file might not exist (e.g., if this is the first pass
-% through the \TeX\ compiler).
+% through the \TeX{} compiler).
% If it exists, first try typesetting its content as a small index
% (one column, centered, with no divisions).
% \begin{macrocode}
\IfFileExists{\csname SB@idxfilename@#3\endcsname.sbx}{%
- \ifx\hyperlink\undefined\let\hyperlink\@secondoftwo\fi%
- \ifx\hyperlink\relax\let\hyperlink\@secondoftwo\fi%
\ifsepindexes%
\global\setbox\SB@box\vbox{%
\null%
\vfil%
- \unvcopy\SB@idxtitlebox%
+ \unvcopy\SB@envbox%
\vskip.5in\@minus.3in\relax%
\hbox to\hsize{%
\hfil%
@@ -11077,13 +11432,13 @@
\ifsepindexes%
\vbox to\textheight{%
\vfil%
- \unvbox\SB@idxtitlebox%
+ \unvbox\SB@envbox%
\vskip1em\relax%
\hbox to\hsize{\hfil[Index not yet generated.]\hfil}%
\vskip\z@\@plus2fil\relax%
}%
\else%
- \unvbox\SB@idxtitlebox%
+ \unvbox\SB@envbox%
\hbox to\hsize{\hfil[Index not yet generated.]\hfil}%
\fi%
}%
@@ -11117,7 +11472,7 @@
\advance\SB@cnt\m@ne%
\repeat%
\edef\SB@oneidxpage{\the\SB@toks}%
- \unvbox\SB@idxtitlebox%
+ \unvbox\SB@envbox%
\vskip.2in\relax%
\nointerlineskip%
\null%
@@ -11188,12 +11543,16 @@
% \argp{3} is the index identifier (which was passed to |\newindex|).
% \begin{macrocode}
\newcommand\SB@maketitleindex{%
- \renewenvironment{SB@lgidx}[1]{
- \hbox{\SB@colorbox\idxbgcolor{\vbox{%
- \hbox to\idxheadwidth{{\idxheadfont\relax##1}\hfil}%
- }}}%
- \nobreak\vskip3\p@\@plus2\p@\@minus2\p@\nointerlineskip%
- }{\penalty-50\vskip5\p@\@plus5\p@\@minus4\p@}%
+ \ifnum\idxheadwidth>\z@%
+ \renewenvironment{SB@lgidx}[1]{
+ \hbox{\SB@colorbox\idxbgcolor{\vbox{%
+ \hbox to\idxheadwidth{{\idxheadfont\relax##1}\hfil}%
+ }}}%
+ \nobreak\vskip3\p@\@plus2\p@\@minus2\p@\nointerlineskip%
+ }{\penalty-50\vskip5\p@\@plus5\p@\@minus4\p@}%
+ \else%
+ \renewenvironment{SB@lgidx}[1]{}{}%
+ \fi%
\renewenvironment{SB@smidx}[1]{}{}%
\renewcommand\idxentry[2]{%
\SB@ellipspread{\idxtitlefont\relax\ignorespaces##1\unskip}%
@@ -11360,6 +11719,15 @@
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}{\SB@warnnoidx}
+% \begin{macrocode}
+\newcommand\SB@warnnoidx{%
+ \SB@Warn{Index command has no effect since no indexes are ye%
+ t declared}%
+}
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macro}{\SB@errboo}
% \begin{macrocode}
\newcommand\SB@errboo{%
@@ -11721,9 +12089,9 @@
% \begin{macro}{\iftranscapos}
% \begin{macro}{\ifnolyrics}
% \begin{macro}{\ifrawtext}
-% \begin{macro}{\ifpdfindex}
% \begin{macro}{\ifsongindexes}
% \begin{macro}{\ifsepindexes}
+% \begin{macro}{\ifpagepreludes}
% \begin{macro}{\ifSB@colorboxes}
% \begin{macro}{\ifSB@omitscrip}
% Reserve conditionals for all of the various option settings.
@@ -11739,10 +12107,11 @@
\newif\iftranscapos
\newif\ifnolyrics
\newif\ifrawtext
-\newif\ifpdfindex\pdfindextrue
\newif\ifsongindexes\songindexestrue
\newif\ifsepindexes\sepindexestrue
-\newif\ifSB@colorboxes\SB@colorboxestrue
+\newif\ifpagepreludes
+\newif\ifSB@colorboxes
+\IfFileExists{color.sty}\SB@colorboxestrue\SB@colorboxesfalse
\newif\ifSB@omitscrip
% \end{macrocode}
% \end{macro}
@@ -11761,12 +12130,16 @@
% \end{macro}
%
% \begin{macro}{\nolyrics}
-% The |\nolyrics| macro is just shorthand for |\nolyricstrue|.
+% \begin{macro}{\pagepreludes}
+% The |\nolyrics| and |\pagepreludes| macros are just shorthand for
+% |\nolyricstrue| and |\pagepreludestrue|, respectively.
% \begin{macrocode}
\newcommand\nolyrics{}
\let\nolyrics\nolyricstrue
+\newcommand\pagepreludes{\pagepreludestrue\songpos0}
% \end{macrocode}
% \end{macro}
+% \end{macro}
%
% Finally we're ready to process all of the package options.
% This is delayed until near the end because the option processing code
@@ -11776,11 +12149,6 @@
\ProcessOptions\relax
% \end{macrocode}
%
-% If we're not generating a pdf, then don't generate the pdf index.
-% \begin{macrocode}
-\ifSB@pdf\else\pdfindexfalse\fi
-% \end{macrocode}
-%
% \begin{macro}{\SB@colorbox}
% Include the colors package and define colors, if requested.
% \begin{macrocode}
@@ -11815,7 +12183,7 @@
% a text file.
% \begin{macrocode}
\ifrawtext
- \newwrite\SB@txtout
+ \SB@newwrite\SB@txtout
\immediate\openout\SB@txtout=\jobname.txt
\newif\ifSB@doEOL
{\catcode`\^^M12 %