From f4304ad1f80aab94e5657360f8c1348366c9d1b9 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sat, 10 Jun 2017 21:36:05 +0000 Subject: songs (10jun17) git-svn-id: svn://tug.org/texlive/trunk@44553 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/source/latex/songs/songs.dtx | 3266 +++++++++++++----------- Master/texmf-dist/source/latex/songs/songs.ins | 4 +- 2 files changed, 1819 insertions(+), 1451 deletions(-) (limited to 'Master/texmf-dist/source') 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 @@ %\NeedsTeXFormat{LaTeX2e} %\ProvidesPackage{songs} %<*package> - [2012/03/17 v2.14 Songs package] + [2017/06/05 v3.0 Songs 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 " produces " 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 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 @@ % % \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}|}|©right 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}|}|©right 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,32 +1628,293 @@ % no special treatment; it leaves the ``ffi'' ligature intact when measure % bars are not being displayed. % -% \section{Between Songs}\label{sec:between} -% -% Never put any material directly into the top level of a \env{songs} -% environment. -% Doing so will disrupt the page-builder, usually producing strange page -% breaks and blank pages. -% To safely put material between songs, use one of the environments -% described in this section. -% -% \subsection{Intersong Displays}\label{sec:intersong} +% \section{Guitar Tablatures}\label{sec:tablatures} % -% \DescEnv{intersong} -% To put column-width material between the songs in a \env{songs} environment, -% use an |intersong| environment: +% \DescMacro{gtab} +% Guitar tablature diagrams can be created by using the construct % % \begin{codeblock} -% |\begin{intersong}| -% $\vdots$ -% |\end{intersong}| +% |\gtab{|\Meta{chord}|}{|\Meta{fret}|:|\Meta{strings}|:|\Meta{fingering}|}| % \end{codeblock} % % \noindent -% Material contributed in an |intersong| environment is subject to the same +% 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} +% environment. +% Doing so will disrupt the page-builder, usually producing strange page +% breaks and blank pages. +% To safely put material between songs, use one of the environments +% described in this section. +% +% \subsection{Intersong Displays}\label{sec:intersong} +% +% \DescEnv{intersong} +% To put column-width material between the songs in a \env{songs} environment, +% use an |intersong| environment: +% +% \begin{codeblock} +% |\begin{intersong}| +% $\vdots$ +% |\end{intersong}| +% \end{codeblock} +% +% \noindent +% 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. -% -% \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|. +% creates a title index named ``|mainindex|'' whose data is +% stored in files named |idxfile.sxd| and |idxfile.sbx|. % -% \DescMacro{notenames} -% You can use other note names as well. -% To define your own note names, type +% \DescMacro{showindex} +% To display the index in the document, use: % % \begin{codeblock} -% |\notenames{|\meta{nameA}|}{|\meta{nameB}|}|$\ldots$|{|\meta{nameG}|}| +% |\showindex[|\Meta{columns}|]{|\Meta{title}|}{|\Meta{id}|}| % \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: +% 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} -% |\notenames{LA}{TI}{DO}{RE}{MI}{FA}{SOL}| +% |\showindex[2]{Index of Song Titles}{mainindex}| % \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: +% \subsection{Index Entries}\label{sec:ientry} +% +% 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} -% |\notenamesin{A}{B}{C}{D}{E}{F}{G}| -% |\notenamesout{LA}{SI}{DO}{RE}{MI}{FA}{SOL}| +% \mac{beginsong}|{Doxology}| +% | [index={Praise God from Whom all blessings flow}]| % \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. +% 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{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, +% \paragraph{Indexing Extra Song Titles.} +% \DescEnv{ititle=} +% To add a regular index entry typeset in italics to the title +% index(es), use: % % \begin{codeblock} -% |\newcommand{\mychord}{F|\mac{shrp}| sus4/C|\mac{shrp}|}| -% \mac{transpose}|{4}| -% |\[\mychord]|\eat\] +% |ititle={|\Meta{title}|}| % \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: +% 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{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}{\transposehere{F|\mac{shrp}| sus4/C|\mac{shrp}|}}| +% |pdflatex mybook.tex| % \end{codeblock} % -% \DescMacro{notrans} -% Transposition can be suppressed within material that would otherwise be -% transposed by using the |\notrans| macro. -% For example, writing +% 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} -% \mac{transposehere}|{G = \notrans{G}}| +% |texlua songidx.lua |\textcolor{black}{[}|-b| \Meta{canon}|.can|\textcolor{black}{]} \Meta{filename}|.sxd| \Meta{filename}|.sbx| % \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}|). +% 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. % -% \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 +% For example, if your song book |.tex| file contains the lines % % \begin{codeblock} -% |\renewcommand{\gtabtrans}[2]{|\mac{gtab}|{|\mac{notrans}|{#1}}{#2}}| +% \mac{newindex}|{titleidx}{titlfile}| +% \mac{newauthorindex}|{authidx}{authfile}| +% \mac{newscripindex}|{scripidx}{scrpfile}| % \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 +% then to generate indexes sorted according to a Christian English bible, +% execute: % % \begin{codeblock} -% |\renewcommand{\gtabtrans}[2]{|\mac{transposehere}|{#1}}| +% |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} +% +% Once the indexes are generated, generate the final book by invoking +% \LaTeX{} one more time: +% +% \begin{codeblock} +% |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 @@ -3304,105 +3482,19 @@ % |\foreachtitle{, |\mac{songtitle}|}| % \end{codeblock} % -% \DescMacro{songlist} -% When \mac{includeonlysongs} is used to extract a partial list of songs, the -% |\songlist| macro expands to the comma-separated list of songs that is being -% extracted. -% Redefining |\songlist| within the document preamble alters the list of -% 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. +% \DescMacro{songlist} +% When \mac{includeonlysongs} is used to extract a partial list of songs, the +% |\songlist| macro expands to the comma-separated list of songs that is being +% extracted. +% Redefining |\songlist| within the document preamble alters the list of +% songs to be extracted. +% Redefining it after the preamble may have unpredictable results. % % \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@@outertest{} -\expandafter\def\expandafter\SB@@outertest% -\expandafter#\expandafter1\string\outer#2\SB@@outertest{% +\newcommand\SB@otesta{} +\edef\SB@otesta#1:#2\SB@otesta{% + \noexpand\SB@otestb% + #1\string\outer% + \noexpand\SB@otestb% +} +\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 % diff --git a/Master/texmf-dist/source/latex/songs/songs.ins b/Master/texmf-dist/source/latex/songs/songs.ins index f6f4cdbd77e..6e67a1990d4 100644 --- a/Master/texmf-dist/source/latex/songs/songs.ins +++ b/Master/texmf-dist/source/latex/songs/songs.ins @@ -1,4 +1,4 @@ -%% 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 @@ -27,7 +27,7 @@ This is a generated file. -Copyright (C) 2012 by Kevin W. Hamlen +Copyright (C) 2017 by Kevin W. Hamlen This file may be distributed and/or modified under the conditions of the LaTeX Project Public License, either version 1.3a of this license -- cgit v1.2.3