summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/songbook/songbook.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/songbook/songbook.dtx')
-rw-r--r--Master/texmf-dist/source/latex/songbook/songbook.dtx111
1 files changed, 99 insertions, 12 deletions
diff --git a/Master/texmf-dist/source/latex/songbook/songbook.dtx b/Master/texmf-dist/source/latex/songbook/songbook.dtx
index b34404fc6a4..2047d67196c 100644
--- a/Master/texmf-dist/source/latex/songbook/songbook.dtx
+++ b/Master/texmf-dist/source/latex/songbook/songbook.dtx
@@ -1,12 +1,12 @@
% \iffalse meta-comment % -*- LaTeX -*-
-% rcsid = @(#)$Id: songbook.dtx,v 1.12 2006/10/15 15:49:50 rathc Exp $
+% rcsid = @(#)$Id: songbook.dtx,v 1.13 2007/02/04 04:12:40 rathc Exp $
%
%
% songbook.sty - Generic SongBook style.
%
-% Version 4.2, 13 October, 2006
+% Version 4.3, 02 February, 2007
%
-% Copyright 1992--2006 Christopher Rath <christopher@rath.ca>
+% Copyright 1992--2007 Christopher Rath <christopher@rath.ca>
%
% This package is free software; you can redistribute it and/or
% modify it under the terms of version 2.1 of the GNU Lesser
@@ -21,7 +21,7 @@
%
% \fi
%
-% \CheckSum{2178}
+% \CheckSum{2190}
%% \CharacterTable
%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
@@ -52,6 +52,8 @@
% was throwing an error when the \textsf{SBRef} and
% \textsf{SBMargNote} commands were used.}
% \changes{v4.2}{2006/10/13}{Added abilty to create an index by song artist.}
+% \changes{v4.3}{2007/02/03}{Corrected problem with xlatn environment introduced in v4.2
+% and added a new songTranslation environment.}
%\fi
%
% \hyphenation{make-index}
@@ -142,10 +144,23 @@
% \tableofcontents
% }
%
+% \section*{Preface to version 4.3}
+% What's new in version~4.3:
+% \begin{itemize}
+% \item found a problem with the optional parameter to the xlatn environment
+% added in Release 4.2; that optional parameter has been removed
+% \item a new songTranslation environment added to provide the required
+% capability for the Artist index option
+% \item added a new song to the sample songbook to act as a test case
+% for translation
+% \end{itemize}
+%
% \section*{Preface to version 4.2}
% What's new in version~4.2:
% \begin{itemize}
% \item added a new Artist index option
+% \item added a new optional parameter to the xlatn environment; in
+% support of the new Artist index option
% \end{itemize}
%
% \section*{Preface to version 4.1a}
@@ -528,10 +543,30 @@
% parameters are left empty then the string defined by the
% |\SBUnknownTag| macro used (instead of leaving whitespace
% in the song header.
+%
+% \item |\begin{songTranslation}{|\meta{1}|}|\ \ldots|{|\meta{4}|}|\ \meta{\ldots
+% the translation\ldots}|\end{songTranslation}|\DescribeEnv{songTranslation}
+% is the new song translation environment. The parameter list is defined
+% as:
+% \begin{enumerate}
+% \item \ Translation language;
+% \item \ Translated song title (in the foreign language);
+% \item \ Translation permission;
+% \item \ Who performed the translation.
+% \end{enumerate}
+% The |songTranslation| environment always occurs within a |song| environment;
+% it resets the verse counter, causes the title and other parameter
+% information to be displayed, and makes the appropriate index and
+% table of contents entries. It is important for the |songTranslation|
+% environment to occur within a song environment, because the |songTranslation|
+% environment inherits the song environment's |\everypar| definition.
%
% \item |\begin{xlatn}{|\meta{1}|}|\ \ldots|{|\meta{3}|}|\ \meta{\ldots
% the translation\ldots}|\end{xlatn}|\DescribeEnv{xlatn}
-% is the song translation environment. The parameter list is defined
+% is the old song translation environment---this environment is
+% considered obsolete and will be removed in a future relase of the
+% \Songbook{} macros; it has been replaced by the |songTranslation|
+% environment. The parameter list is defined
% as:
% \begin{enumerate}
% \item \ Translated song title (in the foreign language);
@@ -929,6 +964,11 @@
% by the |\OHContPgHdr| command. The default value for this is
% ``|\theSBSongCnt\ --- \theSongTitle, continued\ldots|''.
%
+% \item |\SBBaseLang| \DescribeMacro{\SBBaseLang} tag is the name of the
+% language of all songs not specified within an |songTranslation| environment, and
+% also as the default value of the |songTranslation| environment's optional song language
+% parameter. The default value for this is ``|English|''.
+%
% \item |\SBBridgeTag| \DescribeMacro{\SBBridgeTag} the Bridge Tag to
% insert before the start of a bridge. The default value for this is
% ``|Bridge:|''.
@@ -1647,11 +1687,11 @@
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
-%% rcsid = @(#)$Id: songbook.dtx,v 1.12 2006/10/15 15:49:50 rathc Exp $
+%% rcsid = @(#)$Id: songbook.dtx,v 1.13 2007/02/04 04:12:40 rathc Exp $
%%
\NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{songbook}[2006/10/13 v4.2 All purpose Songbook style]
-\typeout{Document Subclass: songbook 2006/10/13 v4.2 All purpose Songbook style}
+\ProvidesPackage{songbook}[2007/02/03 v4.3 All purpose Songbook style]
+\typeout{Document Subclass: songbook 2007/02/03 v4.3 All purpose Songbook style}
% \end{macrocode}
%
% \section{Initial Code Part}
@@ -3245,6 +3285,13 @@
% The default value for this is
% ``|\theSBSongCnt\ --- \theSongTitle, continued\ldots|''.
%
+% \begin{macro}{\SBBaseLang}
+% The |\SBBaseLang| tag is the name of the language of all songs
+% not specified within an |songTranslation| environment, and also as the
+% default value of the |songTranslation| environment's optional song language
+% parameter.
+% The default value for this is ``|English|''.
+%
% \begin{macro}{\SBBridgeTag}
% The |\SBBridgeTag| tag is inserted before the start of a bridge.
% The default value for this is ``|Bridge:|''.
@@ -3295,6 +3342,7 @@
% \begin{macrocode}
\newcommand{\OHContPgFtrTag} {continued on next page\ldots}
\newcommand{\OHContPgHdrTag} {\theSBSongCnt\ --- \theSongTitle, continued\ldots}
+\newcommand{\SBBaseLang} {English}
\newcommand{\SBBridgeTag} {Bridge:}
\newcommand{\SBChorusTag} {Ch:}
\newcommand{\SBContinueTag} {cont\ldots}
@@ -3319,6 +3367,7 @@
% \end{macro}
% \end{macro}
% \end{macro}
+% \end{macro}
%
% \paragraph{Internal Song Variables}
% Declare song attribute variables.
@@ -3359,6 +3408,9 @@
% \begin{macro}{\theXlatnBy}
% |\theXlatnBy| is who translated the song.
%
+% \begin{macro}{\theXlatnLang}
+% |\theXlatnLang| is the language the song has been translated into.
+%
% \begin{macro}{\theXlatnPerm}
% |\theXlatnPerm| is the permission details for the last song
% translation. This variable is reset to an empty
@@ -3378,6 +3430,7 @@
\newcommand{\theSongScriptRef}{the Scripture}
\newcommand{\theSongTitle}{the Title}
\newcommand{\theXlatnBy}{the Translator}
+\newcommand{\theXlatnLang}{the Language}
\newcommand{\theXlatnPerm}{the Permission}
\newcommand{\theXlatnTitle}{the Translation Title}
@@ -3392,6 +3445,7 @@
% \end{macro}
% \end{macro}
% \end{macro}
+% \end{macro}
%
% \subsubsection{Special Characters}
% Some macros to ease the entry of special characters in songbooks.
@@ -4053,7 +4107,7 @@
% is nil or blank when one of these |\the| macros is passed instead of
% the native parameter itself.
%
-% We \emph{clear} the translation macros now, since the |xlatn| environment
+% We \emph{clear} the translation macros now, since the |songTranslation| environment
% is only valid inside a |song| environment, and we are now declaring a new
% |song|.
%
@@ -4070,6 +4124,7 @@
\renewcommand{\theSongScriptRef}{#6} %
\renewcommand{\theSongTitle}{#2} %
\renewcommand{\theXlatnBy}{} %
+ \renewcommand{\theXlatnLang}{\SBBaseLang} %
\renewcommand{\theXlatnPerm}{} %
\renewcommand{\theXlatnTitle}{} %
%
@@ -4229,13 +4284,16 @@
% \end{macro}
%
% \begin{macro}{xlatn}
-% |xlatn|\parm{1}\parm{2}\parm{3} is the song-translation environment.
+% |xlatn|\parm{1}\parm{2}\parm{3} is the old song-translation environment.
% \begin{ParameterList}
% \item[\meta{1}] Title of the translated song.
% \item[\meta{2}] Translation permission.
% \item[\meta{3}] Who performed the translation.
% \end{ParameterList}
%
+% The |xlatn| environment is considered obsolete and will be removed from
+% a future release of the \Songbook{} macros.
+%
% The xlatn environment always occurs within a song environment.
% We reset the verse counter then cause the title and other
% parameter information to be displayed.
@@ -4269,7 +4327,34 @@
\setcounter{SBVerseCnt}{0}%
\setcounter{SBSectionCnt}{0}%
}{\relax}
-
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{songTranslation}
+% |songTranslation|\parm{1}\parm{2}\parm{3} is the song-translation environment.
+% \begin{ParameterList}
+% \item[\meta{1}] Language of translated song.
+% \item[\meta{2}] Title of the translated song.
+% \item[\meta{3}] Translation permission.
+% \item[\meta{4}] Who performed the translation.
+% \end{ParameterList}
+%
+% The |songTranslation| environment always occurs within a |song| environment.
+% We reset the verse counter then cause the title and other
+% parameter information to be displayed.
+%
+% The |xlatn| environment was the original song translation environment, but
+% with the addition of an additional parameter (the ``Language of translated
+% song.'' parameter) it made most sense to create a new environment which
+% simply deals with the new parameter and then calls the old environment. At
+% some point in the future, when the |xlatn| environment is removed, the |xlatn|
+% code will be moved here.
+%
+% \begin{macrocode}
+\newenvironment{songTranslation}[4]{% Comment marker negates the newline.
+ \renewcommand{\theXlatnBy}{#4}%
+ \begin{xlatn}{#2}{#3}{#4}%
+}{\end{xlatn}}
% \end{macrocode}
% \end{macro}
%
@@ -5107,7 +5192,9 @@
% \end{macrocode}
%
-% There are no obsolete macros in this release.
+% The |xlatn| environment is obsolete, but for the sake of
+% code-clarity the code has not been moved into the
+% Obsolete Macros section of this document.
%
% \subsubsection{Deprecated Macros}
%