diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/leadsheets/leadsheets_en.tex |
Initial commit
Diffstat (limited to 'macros/latex/contrib/leadsheets/leadsheets_en.tex')
-rw-r--r-- | macros/latex/contrib/leadsheets/leadsheets_en.tex | 2256 |
1 files changed, 2256 insertions, 0 deletions
diff --git a/macros/latex/contrib/leadsheets/leadsheets_en.tex b/macros/latex/contrib/leadsheets/leadsheets_en.tex new file mode 100644 index 0000000000..c11f660e5c --- /dev/null +++ b/macros/latex/contrib/leadsheets/leadsheets_en.tex @@ -0,0 +1,2256 @@ +% !arara: pdflatex: { shell: on , action: nonstopmode } +% arara: biber +% arara: pdflatex +% arara: pdflatex +% -------------------------------------------------------------------------- +% the LEADSHEETS package +% +% typesetting leadsheets and songbooks +% +% -------------------------------------------------------------------------- +% Clemens Niederberger +% E-Mail: contact@mychemistry.eu +% -------------------------------------------------------------------------- +% Copyright 2014-2017 Clemens Niederberger +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% This work has the LPPL maintenance status `maintained'. +% +% The Current Maintainer of this work is Clemens Niederberger. +% -------------------------------------------------------------------------- +\documentclass[load-preamble+]{cnltx-doc} +\usepackage{leadsheets,bookmark} +\setcnltx{ + package = leadsheets , + info = Typesetting leadsheets and songbooks , + authors = Clemens Niederberger , + email = contact@mychemistry.eu , + url = https://github.com/cgnieder/leadsheets/ , + add-cmds = { + choir , chord , chordname , + definesongtitletemplate , + defineversetypetemplate , + expandcode , + ifallsongproperties , + ifanysongproperty , + ifobeylines , + ifsongmeasuring , + ifsongpropertiesequal , + ifsongproperty , + ifversenamed , + ifversenumbered , + ifversestarred , + includeleadsheet , + instruction , + leadsheetstranslate , + lsenparen , + mkchoir , + mkinstruction , + mklsenparen , + mklsenparens , + newversetype , + printsongpropertylist , + setchords , + setleadsheets , + songproperty , + useleadsheetslibraries , + useleadsheetslibrary , + verseafterlabel , + verselabel , + verselabelformat , + versename , + versenumber , + writechord + } , + add-silent-cmds = { + @itemdepth , + arraybackslash , + endmdframed , + mdframed , + newfontfamily , + newrobustcmd , + musejazz + } , + add-envs = { + bridge , + chorus , chorus* , + flushleft , + flushright , + info , + interlude , + intro , intro* , + outro , outro * , + prechorus , prechorus* , + solo , solo* , + song , + verse + } , + index-setup = { othercode=\footnotesize, level=\section , noclearpage } , + makeindex-setup = { columns=3, columnsep=1em } +} + +\defbibheading{bibliography}{\section{References}} +\addbibresource{\jobname.bib} + +\usepackage{filecontents} +\begin{filecontents}{\jobname.bib} +@book{book:realbook, + author = {Various} , + title = {The Real Book} , + volume = {I} , + subtitle = {C Edition} , + publisher = {Hal Leonard Publishing Corporation} , + isbn = {978-0634060380} , + date = {2000-01-01} , + edition = {6th edition} +} +@book{book:newrealbook, + author = {Various} , + title = {The New Real Book} , + volume = {I} , + subtitle = {C Edition} , + publisher = {Ama Verlag} , + isbn = {978-0961470142} , + date = {2009-02-12} , + edition = {1st edition} +} +\end{filecontents} + +\usepackage{booktabs} + +\newidxcmd\library{\code{#1}}[ (library)] +\AtEndPreamble{% + \pdfstringdefDisableCommands{% + \def\library*#1{``#1''}% + }% +} +\newrobustcmd*\musicsymbols{\library{musicsymbols}} +\newrobustcmd*\chords{\library{chords}} +\newrobustcmd*\musejazz{\library{musejazz}} + +\setchords{format=\libertineLF} + +\makeatletter +\colorlet{property}{cnltxgreen} +\newenvironment{properties} + {% + \def\prop{\@cnltx@option@item\propval}% + \cnltxlist + } + {\endcnltxlist} + +\newrobustcmd*\propval{\@ifstar{\cnltx@prop@star}{\cnltx@prop@nostar}} + +\newrobustcmd*\cnltx@prop@star{% + \cnltx@ifdash + {\cnltx@prop@aux*\meta} + {\cnltx@prop@aux*\marg}% +} +\newrobustcmd*\cnltx@prop@nostar{% + \cnltx@ifdash + {\cnltx@prop@aux{}\meta} + {\cnltx@prop@aux{}\marg}% +} +\newcommand*\cnltx@prop@aux[4]{% + \code{\property#1{#3}\cnltx@isvalue#2{#4}}% +} +\makeatother + +\newidxcmd\property{\code{\textcolor{property}{#1}}} + +\newrobustcmd*\symarg[1]{\textcolor{argument}{\code{#1}}} + +\newidxcmd\titletemplate{\textit{\sffamily#1}}[\ (songtitle template)] +\newidxcmd\versetemplate{\textit{\sffamily#1}}[\ (verse-type template)] +\newidxcmd\shortcut{\code{#1}}[ (shortcut)] +\newidxcmd\pkgopt{\code{#1}}[ (package option)] +\newnote*\packageoption[1]{Package option: \pkgopt{#1}} + +\newrobustcmd*\barsymbol{|} + +\AfterPackage{hyperref}{% +\pdfstringdefDisableCommands{% + \def\property#1{#1}% +}} + +\renewcommand*\dictumauthorformat[1]{#1} +\renewcommand*\raggeddictumtext{} + +\begin{document} + +\part{About the Package} +\dictum[Tom Waits]{% + I like beautiful melodies telling me terrible things.% +} + +\section{License and Requirements} + +\license + +\leadsheets{} requires the bundles \bnd{l3kernel}~\cite{bnd:l3kernel} and +\bnd{l3packages}~\cite{bnd:l3packages} to be available. It also needs the +package \pkg{translations}~\cite{pkg:translations}. + +\section{Background} + +Over the years I repeatedly wanted to typeset simple leadsheets of songs, \ie, +song lyrics and the corresponding chords\footnote{I also have had the need (or + let's say: wish) to typeset leadsheets in the style of the + \citetitle{book:realbook} -- but this is a task where other software than + \LaTeX{} usually is far easier.}. This is not too hard with standard +\LaTeX{} commands and environments but it is not very convenient\ldots{} so +looking for existing packages is the logical next step and I found two very +promising packages: \pkg{songs}~\cite{pkg:songs} and +\pkg{songbook}~\cite{pkg:songbook}. However, both were note \emph{quite} what +I wanted. Just a bit too inflexible in the wrong places, needing tweaking +here and there, and so on. On the other hand I had quite some code lying on +my hard drive with various attempts of typesetting leadsheets. This package +is now the attempt to have a clean, documented and customisable version of my +code\footnote{Plus new things!}. + +\section{The Structure of the Package} +\leadsheets{} is a modular package and consists of several +libraries\footnote{This did seem like a good idea for maintenance when I first + came up with it. Now I'm not so sure any more but I am way too lazy to + change it back. So here we are\ldots}. If you just say +\begin{sourcecode} + \usepackage{leadsheets} +\end{sourcecode} +then the \library{songs} library is loaded\footnote{Which currently means that + \emph{all} libraries are loaded as the \library{songs} library needs them.}. +If you want to ensure that \emph{every} library is loaded\packageoption{full} +so you don't have to think about it any more you can use +\begin{sourcecode} + \usepackage[full]{leadsheets} +\end{sourcecode} +This actually loads every library except the \library{musejazz} library. + +If you instead use\packageoption{minimal} +\begin{sourcecode} + \usepackage[minimal]{leadsheets} +\end{sourcecode} +then \emph{no} libraries are loaded. In this case you have to load the +libraries yourself in order to use the package. +\begin{commands} + \command{useleadsheetslibraries}[\marg{comma list of libraries}] + With this command one or several of \leadsheets' libraries can be loaded. + \command{useleadsheetslibrary}[\marg{library}] + With this command one of \leadsheets' libraries can be loaded. +\end{commands} + +The libraries are divided into two parts: libraries to be loaded by users and +auxiliary libraries loaded by other libraries but not to be loaded directly by +users. + +The user-libraries are the following ones: +\begin{description} + \item[\library{musicsymbols}] \packageoption{musicsymbols}This library makes + the music symbol font provided by MusiX\TeX{} available as text font. It + is described in part~\ref{part:musicsymbols-library}. + \item[\library{chords}] \packageoption{chords}This library defines a + few macros for typesetting of chord symbols. It is described in + part~\ref{part:chords-library}. It also loads the + \library{musicsymbols}library. + \item[\library{musejazz}] \packageoption{musejazz}extends the \chords\ + library to use MuseScore's \enquote{MuseJazz} font, see + section~\ref{sec:musejazz-libr}. It loads the \library{chords} + library. + \item[\library{songs}] \packageoption{songs}This is the \emph{main + library}. It defines everything necessary for the typesetting of the + leadsheets. It currently loads \emph{all other libraries}, \ie, user + libraries \emph{and} internal libraries, except for the \library{musejazz} + library. This library is described in part~\ref{part:leadsheets-songs-library}. + \item[\library{external}] \packageoption{external}enables to include + external leadsheet documents using the \cls{leadsheets} class into a main + document, see part~\ref{part:external-leadsheet} for details. +\end{description} +Those libraries can also be loaded as a package option. If you say +\begin{sourcecode} + \usepackage[musicsymbols]{leadsheets} +\end{sourcecode} +then \emph{only} the \library{musicsymbols} library is loaded. Saying +\begin{sourcecode} + \usepackage[songs]{leadsheets} +\end{sourcecode} +is the same as using the package \emph{without} any options. ``Without any'' +also means that neither \library{musicsymbols}, \library{chords} nor +\library{songs} has been given as class option! + +There is also a number of auxiliary libraries which are all needed by +the \library{songs} library. The libraries are usually not described in +sections of their own but as part of the \library{songs} library. However, +the following list gives hints to where some of the concepts are explained: +\begin{description} + \item[\library{properties}] This is an auxiliary library not meant to be + loaded directly by users. It defines the necessary macros for song + properties. See section~\ref{sec:song-properties} for more details on the + concept. + \item[\library{shorthands}] This is an auxiliary library not meant to be + loaded directly by users. It provides means for defining shorthand + characters. + \item[\library{transposing}] This is an auxiliary library not meant to be + loaded directly by users. It defines a transposing mechanism for chord + symbols. See section~\ref{sec:transposing} for further details. + \item[\library{chordnames}] This is an auxiliary library not meant to be + loaded directly by users. It defines the necessary macros for printing + chords. + \item[\library{templates}] This is an auxiliary library not meant to be + loaded directly by users. It defines the necessary macros for + \leadsheets' template mechanism. See section~\ref{sec:templates} for + details on the concept. + \item[\library{translations}] This is an auxiliary library not meant to be + loaded directly by users. It provides a few translations for a number of + printed strings. See section~\ref{sec:internationalization} for more + information. +\end{description} + +\part{The \library*{musicsymbols} Library}\label{part:musicsymbols-library} +\dictum[Victor Hugo]{% + Music expresses that which cannot be said and on which it is impossible to + be silent.% +} +\vspace*{\baselineskip}\csname @afterheading\endcsname + +The \musicsymbols{} library is a very small library that makes the music +symbol font provided by MusiX\TeX{} available as text font and then uses it to +define a number of symbols. This redefines the macros \cs{sharp}, \cs{flat} +and \cs{natural}. All defined symbols are listed in +table~\ref{tab:musicsymbols}. + +If you want to use the library standalone then you can say: +\begin{sourcecode} + \usepackage[minimal]{leadsheets} + \useleadsheetslibraries{musicsymbols} +\end{sourcecode} + +\musicsymbols{} defines three further commands, namely \cs{musix}, +\cs{textmusix} -- a font switch and a text font command -- and +\cs{musicsymbol}. Those commands are meant for internal use only which is why +they're not explained here. + +\begin{table}[htbp] + \centering + \newcommand*\showsymbol[1]{\cs{#1}&\csuse{#1}} + \caption{Symbols defined by \musicsymbols.} + \begin{tabular}{llll} + \toprule + \bfseries Command & \bfseries Symbol & + \bfseries Command & \bfseries Symbol \\ + \midrule + \showsymbol{sharp} & \showsymbol{flat} \\ + \showsymbol{doublesharp} & \showsymbol{doubleflat} \\ + \showsymbol{natural} \\ + \midrule + \showsymbol{trebleclef} & \showsymbol{bassclef} \\ + \showsymbol{altoclef} \\ + \midrule + \showsymbol{allabreve} & \showsymbol{meterC} \\ + \midrule + \showsymbol{wholerest} & \showsymbol{halfrest} \\ + \showsymbol{quarterrest} & \showsymbol{eighthrest} \\ + \showsymbol{sixteenthrest} \\ + \midrule + \showsymbol{Break} \\ + \bottomrule + \end{tabular} + \label{tab:musicsymbols} +\end{table} + +\musicsymbols{} also defines a number of macros for denoting bars. Those +macros are listed in table~\ref{tab:bar-symbols}. + +\begin{table}[htbp] + \centering + \newcommand*\showsymbol[1]{\cs{#1}&\csuse{#1}} + \caption{Bar symbols.} + \begin{tabular}{llll} + \toprule + \bfseries Macro & \bfseries Symbol & + \bfseries Macro & \bfseries Symbol \\ + \midrule + \showsymbol{normalbar} & \showsymbol{leftrepeat} \\ + \showsymbol{rightrepeat} & \showsymbol{leftrightrepeat} \\ + \showsymbol{doublebar} & \showsymbol{stopbar} \\ + \bottomrule + \end{tabular} + \label{tab:bar-symbols} +\end{table} + +There are three macros that can be redefined to adjust the appearance of those +bars: +\begin{commands} + \command{normalbarwidth}\Default{.02em} + The thickness of a bar rule as used in \cs{normalbar}. + \command{thickbarwidth}\Default{.15em} + The thickness of the thick bar rules as used for example in + \cs{leftrepeat} or \cs{stopbar}. + \command{interbarwidth}\Default{.1em} + The distance between two bar rules as in \cs{doublebar} or \cs{stopbar}. +\end{commands} + +Finally \musicsymbols{} provides a macro for adding an abitrary meter: +\begin{commands} + \command{meter}[\marg{numerator}\marg{denominator}] + \sinceversion{0.5}For example \verbcode+\meter{6}{8}+: \meter{6}{8} +\end{commands} + +\clearpage +\part{The \library*{chords} Library (and the \library*{musejazz} + Library)}\label{part:chords-library} +\dictum[Wes Montgomery]{% + I never practice my guitar -- from time to time I just open the case and + throw in a piece of raw meat.% +} + +\begin{figure} + \centering + \includegraphics[scale=.5,trim=0 22cm 10cm 2cm,clip]{ring-of-fire.pdf} + \caption{One possible layout for \leadsheets{} mimicking the typewriter + style.} + \label{fig:leadsheet} +\end{figure} + +\section{The \cs*{writechord} Command} + +\chords{} provides the command \cs{writechord}\marg{chord} for convenient +typesetting of chords: + +\begin{example}[side-by-side] + \writechord{Bb7(#9)} \writechord{Bbb6} + \writechord{C#7(b9)} \writechord{C##13} +\end{example} + +\begin{commands} + \command{chordname}[\marg{chord}] + Typesetting chords. Inside the argument every \code{\#} will be replaced + by $\sharp$ and every \code{b} is replaced with $\flat$. Numerals and + parentheses are typeset as superscripts. Everything between parentheses + is always a superscript: \verbcode+\writechord{F#7(#11)}+ + \writechord{F#7(#11)}. + \command{writechord}[\marg{chord}] + This command can and actually \emph{should} be used for placing chords + inline. It transforms the chords according to the options knows the + options \option{input-notation} and \option{output-notation}. This + command also transforms the chord according to the options inside of the + \env{song} environment \option{transpose} and \option{enharmonic} before + printing it, see also page~\pageref{cs:writechord}. +\end{commands} + +There are several token lists that are treated specially inside \cs{writechord}: +\begin{labeling}[--]{xxxxx} + \item[\code{\^{}}] This token is replaced by \cs*{textsuperscript}. + \item[\code{ma}] The symbol for major chords. Per default this is + empty. \verbcode+\writechord{Gma}+ \writechord{Gma}. + \item[\code{mi}] The symbol for minor chords. Per default this is + \code{m}. \verbcode+\writechord{Gmi}+ \writechord{Gmi}. + \item[\code{o}] The symbol for diminished chords. Per default this is + \code{\cs*{textsuperscript}\Marg{o}}. \verbcode+\writechord{Go}+ + \writechord{Go}. + \item[\code{+}] The symbol for augmented chords. Per default this is + \code{\cs*{textsuperscript}\Marg{+}}. \verbcode!\writechord{G+}! + \writechord{G+}. + \item[\code{/o}] The symbol for half diminished chords. Per default + this is \code{\cs*{textsuperscript}\Marg{\cs*{o}\Marg{}}}. + \verbcode+\writechord{G/o}+ \writechord{G/o}. + \item[\code{\#}] The \enquote{sharp} symbol. Per default this is + \cs{sharp}. \verbcode+\writechord{F#}+ \writechord{F#}. + \item[\code{\#\#}] The \enquote{double sharp} symbol. Per default this is + \cs{doublesharp}. \verbcode+\writechord{F##}+ \writechord{F##}. + \item[\code{b}] The \enquote{flat} symbol. Per default this is + \cs{flat}. \verbcode+\writechord{Eb}+ \writechord{Eb}. + \item[\code{bb}] The \enquote{double flat} symbol. Per default this is + \cs{doubleflat}. \verbcode+\writechord{Ebb}+ \writechord{Ebb}. + \item[\code{b\#}] Cancelling flat/sharp combination: this is removed. + \item[\code{\#b}] Cancelling sharp/flat combination: this is removed. + \item[\code{add}] This is superscripted: \verbcode+\writechord{Gadd9}+ + \writechord{Gadd9}. + \item[\code{sus}] This is superscripted: \verbcode+\writechord{Gsus4}+ + \writechord{Gsus4}. + \item[\code{dim}] This is superscripted: \verbcode+\writechord{Gdim5}+ + \writechord{Gdim5}. + \item[\code{maj7}] This is superscripted: \verbcode+\writechord{Gmaj7}+ + \writechord{Gmaj7}. + \item[\code{maj9}] This is superscripted: \verbcode+\writechord{Gmaj9}+ + \writechord{Gmaj9}. +\end{labeling} + +How these token lists are treated depends on optional settings: + +\begin{example} + \setchords{ + major-seven = $\Delta$ , + major-nine = $\Delta$\textsuperscript{9} + } + \writechord{Gmaj7} \writechord{Gmaj9} + \writechord{G^6} \writechord{G6} + \writechord{G7^#5} +\end{example} + +If you want to use the library standalone then you can say: +\begin{sourcecode} + \usepackage[minimal]{leadsheets} + \useleadsheetslibraries{chords} +\end{sourcecode} +This also loads the \musicsymbols{} library. + +\section{Options} + +Options are set with the command +\begin{commands} + \command{setchords}[\marg{options}] + where \meta{options} is a comma separated list of keyval options. +\end{commands} +Actually there's a second possibility: options can also be set with the +command \cs{setleadsheets} (see section~\ref{sec:options}) if they're preceded +by \code{chords/} (including the slash). + +The options allow detailed customization of how chords are printed. It +doesn't change the input syntax. + +\begin{options} + \keyval{format}{code}\Default + Code inserted before a chord within the same group. Can be used for + special formatting of the chords, with \cs*{sffamily}, say. + \keyval{sharp}{code}\Default{\cs{sharp}} + The sharp symbol. + \keyval{flat}{code}\Default{\cs{flat}} + The flat symbol. + \keyval{double-sharp}{code}\Default{\cs{doublesharp}} + The double sharp symbol. + \keyval{double-flat}{code}\Default{\cs{doubleflat}} + The double flat symbol. + \keyval{aug}{code}\Default{+} + The augmented symbol. + \keyval{half-dim}{code}\Default{\cs*{o}\Marg{}} + The half-diminished symbol. + \keyval{full-dim}{code}\Default{o} + The diminished symbol. + \keyval{dim}{code}\Default{\cs*{textsuperscript}\Marg{dim}} + The token list \code{dim}. + \keyval{add}{code}\Default{\cs*{textsuperscript}\Marg{add}} + The token list \code{add}. + \keyval{sus}{code}\Default{\cs*{textsuperscript}\Marg{sus}} + The token list \code{sus}. + \keyval{major}{code}\Default + The token list \code{ma}. + \keyval{minor}{code}\Default{m} + The token list \code{mi}. This option knows a special value. If you set + \keyis{minor}{lowercase} then minor chords are converted to lowercase + letters. This means an input \code{Dmi} becomes \code{d}. + \keyval{major-seven}{code}\Default{\cs*{textsuperscript}\Marg{maj7}} + The token list \code{maj7}. + \keyval{major-nine}{code}\Default{\cs*{textsuperscript}\Marg{maj9}} + The token list \code{maj9}. +\end{options} + +There are further options which concern the different notations of the pitches +\writechord{B} and \writechord{Bb} in German (and a few other European +countries) and English. +\begin{options} + \keychoice{input-notation}{german,english}\Default{english} + If\changedversion{0.2} set to \code{german} B should be input as \code{H} + and B~flat as \code{B}. If set to \code{english} B should be input as + \code{B} and B~flat as \code{Bb}. + \keychoice{output-notation}{german,english}\Default{english} + \setchords{output-notation=german}If\changedversion{0.2} set to + \code{german} B is output as \writechord{B} and B-flat as \writechord{Bb}. + \keyval{german-B}{code}\Default{B} + Customize\sinceversion{0.2} the output of B~flat when + \keyis{output-notation}{german}. + \keyval{german-H}{code}\Default{H} + Customize\sinceversion{0.2} the output of B when + \keyis{output-notation}{german}. +\end{options} + +Let's see a few examples for the \option{input-notation} and +\option{output-notation} options. + +\begin{example} + input and output English:\par + \writechord{Bb} \writechord{B} \writechord{B#}\par + \writechord{B} \writechord{H} \writechord{H#}\par + \medskip + + \setchords{input-notation=german} + input German and output English:\par + \writechord{Bb} \writechord{B} \writechord{B#}\par + \writechord{B} \writechord{H} \writechord{H#}\par + \medskip + + \setchords{output-notation=german} + input and output German:\par + \writechord{Bb} \writechord{B} \writechord{B#}\par + \writechord{B} \writechord{H} \writechord{H#}\par + + \medskip + \setchords{input-notation=english} + input English and output German:\par + \writechord{Bb} \writechord{B} \writechord{B#}\par + \writechord{B} \writechord{H} \writechord{H#} +\end{example} + +\section{The \library*{musejazz} Library}\label{sec:musejazz-libr} + +The \musejazz\ library extends the \chords\ library to use +MuseScore's\footnote{\url{http://musescore.com/}} font \enquote{MuseJazz} for +the chord symbols. The library contains the two lines which explains why it +requires \LuaLaTeX\ or \XeLaTeX. Well, and the font, obviously. + +\begin{sourcecode} + \RequirePackage{fontspec} + \newfontfamily\musejazz{MuseJazz} +\end{sourcecode} + +Here is a small example of it's usage and the outcome: + +\begin{example}[compile,program=xelatex,max-pages=1,add-frame=false] + % compile with LuaLaTeX or XeLaTeX + \documentclass[margin=4mm]{standalone} + \usepackage{leadsheets} + \useleadsheetslibrary{musejazz} + \begin{document} + \Huge\writechord{Bb7(#9)}\space\writechord{F##9} + \end{document} +\end{example} + +\clearpage +\part{The \library*{songs} Library}\label{part:leadsheets-songs-library} +\dictum[Jeff Beck]{% + I don't care about the rules. If I don't break the rules at least ten + times every song then I'm not doing my job.% +} + +\section{Background} + +The \leadsheets{} package allows for easy creation of leadsheets but it also +can be used to create complete songbooks. The basic idea is that songs are +typeset in the \env{song} environment. Each song gets a number of properties +(see section~\ref{sec:song-properties}) that determine how the title of the +song is typeset. For the typesetting of the titles a template mechanism is +used (see section~\ref{sec:title-templates}). Songs can also be tagged. The +tags then allow to typeset only songs matching a list of tags that is +specified via an option. + +\begin{figure} + \centering + \includegraphics[width=.9\linewidth]{liederbuechlein.jpg} + \caption{Even before officially publishing this bundle I used it for + typesetting a small songbook!} + \label{fig:liederbuch} +\end{figure} + +\section{The \env*{song} Environment} + +\begin{environments} + \environment{song}[\oarg{options}\marg{properties}] + The main environment used to typeset songs. It has a mandatory argument + where the song's properties are set + (\cf\ section~\ref{sec:song-properties}). It also has an optional + argument for setting options specific to the song. +\end{environments} + +\subsection{A First Example} +First let's take a look at an example: + +\begin{example}[ + compile, + graphics={trim={2cm 18cm 2cm 2cm},clip}, + add-sourcecode-options={literate=}] + \documentclass{article} + \usepackage{leadsheets} + \begin{document} + + \begin{song}{title={Mary Had A Little Lamb}, music={Stevie Ray Vaughan}, + lyrics={traditional}, tags={srv,blues}} + \begin{verse} + Mary had a little lamb \\ + Its fleece was white as snow, yea \\ + Everywhere the child went \\ + The little lamb was sure to go, yea + \end{verse} + \begin{verse} + He followed her to school one day \\ + And broke the teacher's rule \\ + What a time did they have \\ + That day at school + \end{verse} + \end{song} + + \end{document} +\end{example} + +Per default the songtitle simply is a \cs{section}\sarg{} without any other +additions. This is the songtitle template \titletemplate{minimal}, see +section~\ref{sec:title-templates} for more details on those templates and how +to create your own. + +\subsection{Using the \env*{song} Environment} + +Inside the \env{song} environment a number of additional environments are used +to specify the different parts of a song. They all are basically the same +kind of environment, namely an \env*{itemize} environment internally where the +only \cs*{item} has the name of the environment as option. The \env{verse} +environment is a little bit different since verses can be numbered. If they +are then each usage of \env{verse} inside \env{song} will step a vers number +and print it (as option to the internal \cs*{item}). + +\begin{environments} + \environment{verse}[\oarg{options}] + An environment for specifying the verses of a song. + \environment{chorus}[\oarg{options}] + An environment for specifying the chorus of a song.\\ + This is the same as \beginenv*\Marg{verse}\Oarg{type=chorus,\meta{options}}. + \environment{intro}[\oarg{options}] + An environment for specifying the intro of a song.\\ + This is the same as \beginenv*\Marg{verse}\Oarg{type=intro,\meta{options}}. + \environment{interlude}[\oarg{options}] + An environment for specifying an interlude of a song.\\ + This is the same as \beginenv*\Marg{verse}\Oarg{type=interlude,\meta{options}}. + \environment{bridge}[\oarg{bridge}] + An environment for specifying a bridge of a song.\\ + This is the same as \beginenv*\Marg{verse}\Oarg{type=bridge,\meta{options}}. +\end{environments} + +These environments and their options are described in more detail in +sections~\ref{sec:envverse-environment} and~\ref{sec:other-envverse-like}. + +\subsection{Options}\label{sec:options} + +The options to the \env{song} environment are the same as the general options +of \leadsheets. This means you can set the following options either local to +a song or global for the whole document with this command: + +\begin{commands} + \command{setleadsheets}[\marg{options}] + Setup command for \leadsheets. +\end{commands} + +Although I used the word \enquote{global} above \emph{all options are local to + the current scope}! + +\begin{options} + \keyval{title-template}{template name}\Default{minimal} + The songtitle template, see section~\ref{sec:title-templates} for + details. + \keyval{chord-cs}{cs}\Default{\cs*{chordname}} + The command that is used to parse the chords. See + section~\ref{sec:placing-chords} for details. \meta{cs} needs to be a + command that takes a mandatory argument. + \keyval{song-format}{code}\Default + \meta{code} is inserted \emph{before} the song title at the + beginning of the \env{song} environment. + \keyval{text-format}{code}\Default + \meta{code} is inserted \emph{after} the song title at the + beginning of the \env{song} environment. + \keyval{before-song}{code}\Default + \meta{code}\sinceversion{0.3} is inserted at the beginning of a song + \emph{before} the title! + \keyval{after-song}{code}\Default + \meta{code}\sinceversion{0.3} is inserted after the whole song. + \keyval{after-title}{code}\Default + \meta{code}\sinceversion{0.3} is inserted after the title of the song but + before the body of the environment. + % \keybool{numbered}\Default{false} + % Determines wether verses are numbered or not. + \keyval{print-tags}{list of tags} + A comma separated list of tags. When specified a song will only be printed + if it is tagged with at least one of the tags in \meta{list of tags}. + \keyval{add-to-reset}{list of counters} + A\sinceversion{0.3} comma separated list of counters which should be + reset for each song. + \keybool{obey-lines}\Default{false} + An experimental option. Use at your own risk! If set to \code{true} then + inside the \env{verse} like environments end-of-lines will be obeyed and + start a new line. This comes with a price when using chords, see + section~\ref{sec:placing-chords:caveat}. + \keybool{bar-shortcuts}\Default{false} + Makes the characters \shortcut{:} and \shortcut{\barsymbol} active inside + the \env{song} environment. See sections~\ref{sec:special-characters} + and~\ref{sec:typesetting-bars} for more details. + \keybool{disable-measuring}\Default{false} + \sinceversion{0.4}This option turns of the song height measuring. This + makes song title template definitions easier (see section~\ref{sec:title-templates} for + details). \emph{The song property \property{height} will be set to 0pt then!} +\end{options} + +\subsection{Song Properties}\label{sec:song-properties} + +Songs can have a number of properties which basically are used in songtitle +templates (see section~\ref{sec:title-templates}). One specific property, +\property{tags}, plays a different role, though. + +\begin{properties} + \prop{title}{title} + This is the main title of the song. + \prop{subtitle}{subtitle} + A subtitle. + \prop{short-title}{short song title} + A short title (may be useful in a template that writes the titles in + \cs*{section}s for a version to be used in the table of contents). + \prop{sort-title}{song title} + If not set explicitly this property holds the same value as + \property{title}. + \prop{sort-short-title}{short song title} + If not set explicitly this property holds the same value as + \property{short-title}. + \prop{composer}{composer} + The composer of the song. As of now this accepts an arbitrary entry but + maybe this will not be supported any more when indexing will be + implemented. No promises. + \prop{sort-composer}{composer} + If not set explicitly this property holds the same value as + \property{composer}. + \prop{lyrics}{writer} + Whoever wrote the lyrics if different from the composer. As of now this + accepts an arbitrary entry but maybe this will not be supported any more + when indexing will be implemented. No promises. + \prop{sort-lyrics}{writer} + If not set explicitly this property holds the same value as + \property{writer}. + \prop{arr}{arranger} + Whoever arranged the song. As of now this accepts an arbitrary entry but + maybe this will not be supported any more when indexing will be + implemented. No promises. + \prop{sort-arr}{arranger} + If not set explicitly this property holds the same value as + \property{arr}. + \prop{band}{band} + The band who plays or played the song. + \prop{sort-band}{band} + If not set explicitly this property holds the same value as + \property{band}. + \prop{interpret}{interpret} + The interpret of the song. As of now this accepts an arbitrary entry but + maybe this will not be supported any more when indexing will be + implemented. No promises. + \prop{sort-interpret}{interpret} + If not set explicitly this property holds the same value as + \property{interpret}. + \prop{genre}{genre} + The genre of the song. + \prop{key}{key} + The key of the song. This property is used for transposing and must have + a specific format then, see section~\ref{sec:transposing}. + \prop{capo}{fret} + This property is used for transposing and for the \cs{capo} macro, see + sections~\ref{sec:capo-information} and~\ref{sec:transposing} . + \prop{tempo}{tempo} + The tempo of the song. + \prop{tags}{tags} + A comma separated list of tags. Those tags play a role for the option + \option{print-tags}. When that option is used a song is only printed if + it has at least one of the tags specified in the option. +\end{properties} + +There are three more properties, \property{counter}, \property{ID} and +\property{height} that cannot be set but are set automatically for each song. +The \property{counter} simply holds the number of the current song starting +from \code{1} for the first song. The \property{ID} currently always is +\code{song\meta{counter}} where \meta{counter} is the current +\property{counter} value. The property \property{height} holds the height of +the typeset song in pt. The height is determined by placing the body of the +respective \env{song} environment in a vertical box and measuring the height +and depth of the box. This is done in a measuring phase that can and should +be tested in a songtitle template definition, see +section~\ref{sec:title-templates} for details. \emph{This is important since + the property \property{height} is not available in the measuring phase but + only afterwards!} If the option \option{disable-measuring} has been set the +property \property{height} will have the value~0pt! + +In principle all properties can get list of entries where items are separated +with \code{\visualizespaces{ and }}. Of course this doesn't make sense for +each property -- a song does only have one title. But a song can very well +have more than one composer: think of the Beatles where most songs were +written by Paul McCartney and John Lennon\footnote{This is not quite true: + most songs were mostly written either by Paul or John but legally usually + both are the composers.}. + +It is possibly to define further such properties. For details see +section~\ref{sec:own-templates}. + +\subsection{Special Characters}\label{sec:special-characters} +Inside the \env{song} environment several characters don't have their usual +catecory codes: +\begin{labeling}[--]{xxxxx} + \item[\shortcut{\textasciicircum}] category code 13 (active). It is a + shortcut for the \cs{chord} command. + \item[\shortcut{\_}] category code 13 (active). It is a shortcut for the + \cs{writechord} command. + \item[\shortcut{\barsymbol}] category code 13 (active). Used for + typesetting bars. + \item[\shortcut{:}] category code 13 (active). Used for typesetting bars. + \item[\code{\#}] category code 12 (other). Used for chord names. +\end{labeling} + +Actually the characters \shortcut{\barsymbol} and \shortcut{:} are \emph{not} +changed per default. In order to do that you have to use the option +\option{bar-shortcuts}. + +For details on the usage of the characters \shortcut{\barsymbol} and +\shortcut{:} see section~\ref{sec:typesetting-bars}. The usage of chords is +explained in section~\ref{sec:placing-chords}. + +\subsection{Capo Information}\label{sec:capo-information} +When you set the \property{capo} property the macro \cs{capo} writes +\begin{center} + \GetTranslation{leadsheets/capo}: IV.~\GetTranslation{leadsheets/fret} +\end{center} +What it writes \emph{exactly} depends on a few settings: the \property{capo} +property obviously, which determines the number that is printed. The +translations for the \enquote{capo} and \enquote{fret} strings (see +section~\ref{sec:internationalization} for details) and the setting of the +following option: +\begin{options} + \keychoice{capo-nr-format}{arabic,roman,Roman}\Default{Roman} + The format of the number printed by the \cs{capo} macro. + \keyval{capo-nr}{code}\Default{\#1.} + The code to print the number. In the code refer to the number with + \code{\#1}. +\end{options} + +\section{The \env*{verse} Environment}\label{sec:envverse-environment} + +\begin{environments} + \environment{verse}[\oarg{options}] + An environment for specifying the verses of a song. + \environment{verse*}[\oarg{options}] + The same as the \env{verse} environment but will always be unnumbered + regardless of any option settings. +\end{environments} + +\begin{example}[ + compile, + graphics={trim={2cm 18cm 2cm 2cm},clip}, + add-sourcecode-options={literate=}] + \documentclass{article} + \usepackage{leadsheets} + \setleadsheets{verse/numbered=true} + \begin{document} + + \begin{song}{title=Foo} + \begin{verse} + Lorem ipsum dolor sit amet, consetetur sadipscing elitr,\\ + sed diam nonumy eirmod tempor invidunt ut labore et dolore\\ + magna aliquyam erat, sed diam voluptua. + \end{verse} + \begin{verse*} + Lorem ipsum dolor sit amet, consetetur sadipscing elitr,\\ + sed diam nonumy eirmod tempor invidunt ut labore et dolore\\ + magna aliquyam erat, sed diam voluptua. + \end{verse*} + \begin{verse} + Lorem ipsum dolor sit amet, consetetur sadipscing elitr,\\ + sed diam nonumy eirmod tempor invidunt ut labore et dolore\\ + magna aliquyam erat, sed diam voluptua. + \end{verse} + \end{song} + + \end{document} +\end{example} + +\subsection{Options}\label{sec:verses-options} + +The \env{verse} environment and all related environments have the following +options: + +\begin{options} + \keyval{format}{code}\Default + \meta{code} is inserted at the beginning of the environment and can thus + be used to add formatting, \eg, \keyis{format}{\cs*{itshape}}. + \keyval{label-format}{code}\Default + The same for the environment labels. + \keyval{class}{class-name}\Default{default} + The\sinceversion{0.2} \env{verse} environment and all related environments + all belong to a class, the default class is called \code{default}. This + is of interest when using the \option{remember-chords} and + \option{recall-chords} options.\label{option:class} +\end{options} + +This can be used either locally, \ie, as option to the corresponding +environment, or for all environments of the same type using the setup command +using the following syntax: + +\begin{center} + \cs{setleadsheets}\Marg{\meta{env name}/format = \meta{code}} +\end{center} + +\begin{example} + \begin{verse}[format=\itshape] + Lorem ipsum dolor sit amet, consetetur sadipscing elitr,\\ + sed diam nonumy eirmod tempor invidunt ut labore et dolore\\ + magna aliquyam erat, sed diam voluptua. + \end{verse} +\end{example} + +It is also possible so set the formatting for all related environments at +once: +\begin{options} + \keyval{verses-format}{code}\Default + Sets the format for all \env{verse} like environments. + \keyval{verses-label-format}{code}\Default + Sets the label format for all \env{verse} like environments. +\end{options} +Both options are overwritten if the options for a specific environment are +set. That is, if you want all environments to have italic shape except for +choruses, then you could do +\begin{sourcecode} + \setleadsheets{ + verses-format = \itshape , + chorus/format = + } +\end{sourcecode} + +\section{Placing Chords}\label{sec:placing-chords} + +\subsection{The Commands} +Inside the \env{song} environment the characters \shortcut{\textasciicircum} +and \code{\_} are active characters\footnote{There are more characters with a + special function, see + section~\ref{sec:special-characters}}. \shortcut{\textasciicircum} is a +shortcut for the command \cs{chord}, \shortcut{\_} is a shortcut for +\cs{writechord}. Those commands have the following functions: + +\begin{commands} + \command{chord}[\sarg\symarg{-}\marg{chord}\meta{text}\visiblespace] + Places \meta{chord} centered above \meta{text}. The starred version + gobbles the trailing space while the unstarred version does not. Like the + star the dash is optional. It sets the option \option{smash-next-chord} + to \code{true}. \meta{text} may be empty but the trailing space + \emph{must} be there. If \meta{text} is empty then the chord is place + above some horizontal space which can be set with the option + \option{empty-chord-dim}. + \command{writechord}[\marg{chord}] + This command transforms the chord according to the options + \option{transpose} and \option{enharmonic} before printing it. This + command can/should be used for placing chords inline or for typesetting + the \property{key} property in a template. The command is used by + \cs{chord} for the actual printing. The command also transforms the + chords according to the options \option{input-notation} and + \option{output-notation}.\label{cs:writechord} +\end{commands} + +\begin{example}[side-by-side] + Text \chord{E7}text \chord*{B7}lon ger text +\end{example} + +\subsection{Usage} +Note that per default the width of a chord is not ignored: +\begin{example}[side-by-side] + text \chord{Gbmi7(b5)}text text +\end{example} +However, there is an option which sets the width of a chord to zero: +\begin{options} + \keybool{smash-chords}\Default{false} + If set to true the width of the chords set with \cs{chord} is set to + zero. + \keybool{smash-next-chord}\Default{false} + If set to true the width of the next chord set with \cs{chord} is set to + zero. +\end{options} +\begin{example}[side-by-side] + \setleadsheets{smash-next-chord=true} + text \chord{Gbmi7(b5)}text text \par + text \chord{Gbmi7(b5)}text text \par + \setleadsheets{smash-chords=true} + text \chord{Gbmi7(b5)}text text \par + text \chord{Gbmi7(b5)}text text +\end{example} + +Before we forget -- there are more options: +\begin{options} + \keyval{empty-chord-dim}{dim}\Default{1em} + The horizontal space that is inserted if the \meta{text} argument of + \cs{chord} is empty. + \keyval{align-chords}{col}\Default{c} + Determines how a chord is aligned with respect to the word it is placed + above of. Valid input is any valid \env*{tabular} column identifier. + \keybool{print-chords}\Default{true} + If set to false \cs{chord} won't print the chord but will do nothing + instead. This options does not affect \cs{writechord}. +\end{options} + +While \cs{chord} is available in the whole document the +\code{\textasciicircum} syntax is -- as mentioned before -- only available +inside of the \env{song} environment. + +\begin{example}[ + compile, + graphics={trim={2cm 16cm 2cm 4cm},clip}, + add-sourcecode-options={literate=}] + \documentclass{article} + \usepackage{leadsheets} + \begin{document} + + \begin{song}{title={Mary Had A Little Lamb}, music={Stevie Ray Vaughan}, + lyrics={traditional}, tags={srv,blues}} + \begin{verse} + ^{E7} Mary had a little lamb ^{A7} \\ + Its fleece was white as ^{E7}snow, yea \\ + Everywhere the child ^{B7}went ^{A7} \\ + The little lamb was sure to ^{E7}go, yea + \end{verse} + \begin{verse} + ^{E7} He followed her to school one day ^{A7} \\ + And broke the teacher's ^{E7}rule \\ + What a time did they ^{B7}have ^{A7} \\ + That day at ^{E7}school + \end{verse} + \end{song} + + \end{document} +\end{example} + +You've probably noticed: chords are printed with \cs{chordname} in the default +setting. You can change this with the option \option{chord-cs}. If you do +then keep in mind that the input syntax will also change. + +\subsection{Caveat}\label{sec:placing-chords:caveat} + +If you use \keyis{obey-lines}{true} you have to be careful when you place +chords. If you place a chord over the last word in a line +\begin{sourcecode} + ^{F#mi} You've been ^*{B}run nin', ^*{E}hid in' much too ^{A}long. +\end{sourcecode} +then the end of line that is used as the mandatory space argument for +\cs{chord} may not be recognized as an end of line. Even worse: at the end of +a \env{verse} like environment this may cause non-obvious errors. So if +you're getting in trouble in these cases you should always insert an explicit +space, \eg. by one of the following methods: +\begin{sourcecode} + ^{F#mi} You've been ^*{B}run nin', ^*{E}hid in' much too ^{A}long. {} + ^{F#mi} You've been ^*{B}run nin', ^*{E}hid in' much too ^{A}long. \empty + ^{F#mi} You've been ^*{B}run nin', ^*{E}hid in' much too ^{A}long. \relax +\end{sourcecode} + +\subsection{Remembering Chords}\label{sec:remembering-chords} +\leadsheets{} has the option +\begin{options} + \keybool{remember-chords}\Default{false} + If set to \code{true} the chords in the \emph{first} appearance of a + \env{verse} like environment are remembered. In the next appearances of + said environment the shortcut \shortcut{\textasciicircum} has changed its + meaning and inserts a chord automatically. +\end{options} + +Let's take at look at an example to see what this means: +\begin{example} + \definesongtitletemplate{empty}{} + \begin{song}[verse/numbered,remember-chords,title-template=empty]{title=foobar} + \begin{verse} + ^{G}Lorem ipsum ^{C}dolor sit ^{E7}amet, consetetur ^{Bb7(b5)}sadipscing + \end{verse} + \begin{verse} + ^Lorem ipsum ^dolor sit ^amet, consetetur ^sadipscing + \end{verse} + \end{song} +\end{example} +In this example the chords used in the first \env{verse} environment have been +remembered and in the second \env{verse} environment the +\shortcut{\textasciicircum} shortcut inserted the corresponding chords in the +order they had been specified the first time. It is important when using this +that you don't use the \shortcut{\textasciicircum} shortcut in subsequent +environments more often than the first time. It will produce an error +otherwise. You can use it less, of course. + +The \shortcut{\textasciicircum} shortcut still has the \emph{the same} syntax +as \cs{chord} with one exception: it lacks the mandatory argument +\meta{chord} (since it's obviously not needed). It has the optional \sarg{} +and \code{-}, though, as well as the mandatory space (\visiblespace)! + +\emph{Please note that \shortcut{\textasciicircum} \emph{can't} be the last + token in a line! It then should be followed by a space an an empty group -- + similar to the caveat in section~\ref{sec:placing-chords:caveat}.} + +Each \env{verse} like environment (see section~\ref{sec:other-envverse-like} +for more information) is treated uniquely by this mechanism: + +\begin{example} + \definesongtitletemplate{empty}{} + \begin{song}[verse/numbered,remember-chords,title-template=empty]{title=foobar} + \begin{verse} + ^{G}Lorem ipsum ^{C}dolor sit ^{E7}amet, consetetur ^{Bb7(b5)}sadipscing + \end{verse} + \begin{chorus} + ^{F}Lorem ipsum ^{Gmi}dolor sit amet, consetetur ^{C7}sadipscing + \end{chorus} + \begin{verse} + ^Lorem ipsum ^dolor sit ^amet, consetetur ^sadipscing + \end{verse} + \begin{chorus} + ^Lorem ipsum ^dolor sit amet, consetetur ^sadipscing + \end{chorus} + \end{song} +\end{example} + +This is important: \env{verse} and \env{verse*} are treated as two different +environments, the same holds for all starred \env{verse} like environments! +If you want to recall the chords of a different type of environment, then you +can use the option \option{recall-chords}: + +\begin{example} + \definesongtitletemplate{empty}{} + \begin{song}[verse/numbered,remember-chords,title-template=empty]{title=foobar} + \begin{verse} + ^{G}Lorem ipsum ^{C}dolor sit ^{E7}amet, consetetur ^{Bb7(b5)}sadipscing + \end{verse} + \begin{chorus} + ^{F}Lorem ipsum ^{Gmi}dolor sit amet, consetetur ^{C7}sadipscing + \end{chorus} + \begin{verse} + ^Lorem ipsum ^dolor sit ^amet, consetetur ^sadipscing + \end{verse} + \begin{chorus}[recall-chords=verse-default] + ^Lorem ipsum ^dolor sit amet, consetetur ^sadipscing + \end{chorus} + \end{song} +\end{example} + +\section{Transposing}\label{sec:transposing} +Provided a song has the property \property{key} \emph{and} the key is given as +one of the twelve \enquote{usual} keys, \ie, one of the keys given in +table~\ref{tab:key-signatures}, the chords of a song can be transposed. + +\begin{options} + \keyval{transpose}{number} + Transposes the chords of a song by \meta{number} of semitones. + \meta{number} can be a negative number, then the chords are transposed + down. + \keychoice{enharmonic}{sharp,flat} + Suppose you transpose a song in the key of \writechord{E} down a semitone. + \leadsheets{} will then transpose to the key of \writechord{Eb}. It always + chooses the key whose signature has less accidentals. You can force a + variant, though, by using this option. With \keyis{enharmonic}{sharp} + \leadsheets{} would have chosen \writechord{D#} instead of \writechord{Eb}. + \keybool{transpose-capo} + When this is set to true chords are transposed down on semitone per capo + fret. +\end{options} + +The transposing mechanism relies on the \chords{} input syntax which means +that if you change \option{chord-cs} horrible things may happen. \emph{So + don't change \option{chord-cs} and use \option{transpose} at the same time!} + +\begin{table}[htbp] + \centering + \catcode`\#=12 + \catcode`\!=6 + \def\showsignature!1{\writechord{!1}&\code{!1}}% + \caption{Allowed keys for the \property{key} property.} + \begin{tabular}{*{12}{l}} + \toprule + \bfseries Key & \bfseries Input & + \bfseries Key & \bfseries Input & + \bfseries Key & \bfseries Input & + \bfseries Key & \bfseries Input & + \bfseries Key & \bfseries Input & + \bfseries Key & \bfseries Input \\ + \midrule + \showsignature{C} && & + \showsignature{Cma} && & + \showsignature{Ami} \\ + \cmidrule(lr){1-4} \cmidrule(lr){5-8} \cmidrule(lr){9-12} + \showsignature{G} & \showsignature{F} & + \showsignature{Gma} & \showsignature{Fma} & + \showsignature{Emi} & \showsignature{Dmi} \\ + \showsignature{D} & \showsignature{Bb} & + \showsignature{Dma} & \showsignature{Bbma} & + \showsignature{Bmi} & \showsignature{Gmi} \\ + \showsignature{A} & \showsignature{Eb} & + \showsignature{Ama} & \showsignature{Ebma} & + \showsignature{F#mi} & \showsignature{Cmi} \\ + \showsignature{E} & \showsignature{Ab} & + \showsignature{Ema} & \showsignature{Abma} & + \showsignature{C#mi} & \showsignature{Fmi} \\ + \showsignature{B} & \showsignature{Db} & + \showsignature{Bma} & \showsignature{Dbma} & + \showsignature{G#mi} & \showsignature{Fbmi} \\ + \showsignature{F#} & \showsignature{Gb} & + \showsignature{F#ma} & \showsignature{Gbma} & + \showsignature{D#mi} & \showsignature{Ebmi} \\ + \bottomrule + \end{tabular} + \label{tab:key-signatures} +\end{table} + +\begin{example}[ + compile, + graphics={trim={2cm 16cm 2cm 4cm},clip}, + add-sourcecode-options={literate=}] + \documentclass{article} + \usepackage{leadsheets} + \begin{document} + + \begin{song}[transpose=2]{title={Mary Had A Little Lamb}, music={Stevie Ray + Vaughan}, lyrics={traditional}, tags={srv,blues},key=E} + \begin{verse} + ^{E7} Mary had a little lamb ^{A7} \\ + Its fleece was white as ^{E7}snow, yea \\ + Everywhere the child ^{B7}went ^{A7} \\ + The little lamb was sure to ^{E7}go, yea + \end{verse} + \begin{verse} + ^{E7} He followed her to school one day ^{A7} \\ + And broke the teacher's ^{E7}rule \\ + What a time did they ^{B7}have ^{A7} \\ + That day at ^{E7}school + \end{verse} + \end{song} + + \end{document} +\end{example} + +\section{Other \env*{verse}-like Environments}\label{sec:other-envverse-like} +Songs can have lots of different kinds of parts: verses, choruses, bridges, +intros, outros, and so on. Typographically they're all more or less the same, +at least for the purpose of this package. This means we'd ideally have +environments for all of these parts with a distinct name in order to get a +clean source. At the same time these environments should all behave basically +the same. This is what the environments described in the following sections +are for. + +\subsection{Available Environments}\label{sec:avail-envir} + +\begin{environments} + \environment{chorus}[\oarg{options}] + An environment for specifying the chorus of a song. + \environment{chorus*}[\oarg{options}] + The same as \env{chorus} but does not display the label. + \environment{intro}[\oarg{options}] + An environment for specifying the intro of a song. + \environment{intro*}[\oarg{options}] + The same as \env{intro} but does not display the label. + \environment{interlude}[\oarg{options}] + An environment for specifying an interlude of a song. + \environment{bridge}[\oarg{bridge}] + An environment for specifying a bridge of a song. + \environment{info}[\oarg{options}] + An environment for specifying arbitrary information. This environment has + no label. + \environment{solo}[\oarg{options}] + An environment for specifying a solo to a song. + \environment{solo*}[\oarg{options}] + The same as \env{solo} but does not display the label. +\end{environments} + +\subsection{Own \env*{verse}-like Environments} +All environments mentioned in the previous section were defined with this +command: +\begin{commands} + \command{newversetype}[\sarg\marg{environment name}\oarg{default options}] + This defines an environment \meta{environment name}. This environment + uses the verse-type template \versetemplate{itemize} (see + section~\ref{sec:verse-type-templates}) unless specified differently in + the \meta{default options}. The starred version defines an environment + which hides the displayed name. More precisely: the macro \cs{verselabel} + that is used in verse-type template definitions prints nothing in an + environment defined with \cs{newversetype}\sarg. + + This also defines a translation string (see + section~\ref{sec:internationalization}) \code{leadsheets/\meta{environment + name}} with both an empty translation fallback and English translation + unless specified differently with the \option{name} option. + + At last this defines a new counter \meta{environment name} and sets + \cs*{the\meta{environment name}} to \code{\cs*{arabic}\Marg{environment + name}.}. +\end{commands} + +As mentioned before in section~\ref{sec:verses-options} all environments +defined this way have the options \option{format} and \option{label-format}. +They have more options. Here's a complete list: +\begin{options} + \keyval{format}{code}\Default + \meta{code} is inserted at the beginning of the environment and can thus + be used to add formatting, \eg, \keyis{format}{\cs*{itshape}}. + \keyval{label-format}{code}\Default + The same for the environment labels. + \keyval{after-label}{code}\Default{:} + \meta{code} is inserted in the label after the label text. + \keyval{name}{name}\Default + The translation fallback and English translation of the environment. This + should only be used with \cs{newversetype}. Later changes should be made + with \cs{DeclareTranslation} (see section~\ref{sec:internationalization}). + \keyval{template}{template}\Default{itemize} + The verse-type template used for the environment, see + section~\ref{sec:verse-type-templates} for details. + \keybool{numbered}\Default{false} + If set to \code{true} \cs{verselabel} (used in verse-type template + definitions, see section~\ref{sec:verse-type-templates}) adds a number + after the name. + \keybool{named}\Default{true} + If set to \code{true} \cs{verselabel} (used in verse-type template + definitions, see section~\ref{sec:verse-type-templates}) prints the name + of the current environment (as determined by the translation of the + corresponding string, see also section~\ref{sec:internationalization}). + \keylit{recall-chords}{\meta{environment}-\meta{class}} + An option to be used with the \option{remember-chords} mechanism, see + section~\ref{sec:remembering-chords} for an example. If you're not using + different classes then \meta{class} needs to be \code{default}, see also + page~\pageref{option:class}. The \option{class} to a \env{verse}-like + environment allows for example to have verses with different chords which + are still counted reguarly together with the \option{remember-chords} + option. +\end{options} + +There are also a number of general options for setting the defaults of some +options for all environments: +\begin{options} + \keyval{verses-format}{code}\Default + Sets the format for all \env{verse} like environments. + \keyval{verses-label-format}{code}\Default + Sets the label format for all \env{verse} like environments. + \keyval{verses-after-label}{code}\Default{:} + Defeault \meta{code} that is inserted in the label after the label text of + \env{verse} like environments. +\end{options} +This options only determine the formatting of an environment if the +corresponding options of the environment hasn't been set. + +Let's summarize: the label text of these environments is built of three items +in the following order: +\begin{enumerate} + \item The \meta{code} set with the corresponding \option{label-format} option. + \item The label text as defined as second argument to \cs{newversetype} or + as declared through the corresponding translation. + \item The \meta{code} set with the corresponding \option{after-label} option. +\end{enumerate} + +\begin{example} + \newversetype{foo}{Foo} + \setleadsheets{ + foo/label-format = \bfseries , + foo/after-label = ~$\Rightarrow$ + } + \begin{foo} + Lorem ipsum dolor sit amet, consetetur sadipscing elitr,\\ + sed diam nonumy eirmod tempor invidunt ut labore et dolore\\ + magna aliquyam erat, sed diam voluptua. + \end{foo} +\end{example} + +And just to give you some more examples here is how some of the existing +environments are defined: +\begin{sourcecode} + \newversetype{verse}[ name=Verse, named=false, after-label= ] + \newversetype*{verse*} + \newversetype{chorus}[ name=Chorus ] + \newversetype*{chorus*} +\end{sourcecode} + +\section{Typesetting Bars}\label{sec:typesetting-bars} + +Sometimes it can be useful to typeset the chord scheme of a song. Then one +should be able to indicate start and beginnings of bars, maybe indicate +repeats and so on. While this is obviously possible with the macros provided +by the \musicsymbols{} package listed in table~\ref{tab:bar-symbols} it may be +more convenient to have a shorter syntax. This is why inside the \env{song} +environment some characters can be made (or are) active (see +section~\ref{sec:special-characters}). For the typesetting of bars this are +the characters \shortcut{:} nor \shortcut{\barsymbol}. Per default they are +not active, though. If you want to use the shortcut syntax you have to use +the option \option{bar-shortcuts}. Here's a short example that emulates the +behaviour by setting the characters active explicitly: + +\begin{example}[add-sourcecode-options={literate=}] + \catcode`|=\active + \catcode`:=\active + |: repeat | this :|: and | this :| \par + | this | part | ends | here || \par + | the | song | is over | now ||| +\end{example} + +All possibly combinations that have a special definition are shown in the +example above. The replacements that are done internally are these: +\begin{labeling}[--]{xxxxx} + \item[\shortcut{\barsymbol}] \cs{normalbar}\cs*{space} (the space is there + because otherwise it eats following spaces which would be annoying) + \item[\code{|:}] \cs{leftrepeat} + \item[\code{:|}] \cs{rightrepeat} + \item[\code{:|:}] \cs{leftrightrepeat} + \item[\code{||}] \cs{doublebar} + \item[\code{|||}] \cs{stopbar} +\end{labeling} + +\section{Templates}\label{sec:templates} +\subsection{Title Templates}\label{sec:title-templates} + +\subsubsection{Background} +The titles of songs set with the \env{song} environment are displayed +according to the chosen title template. It is chosen through the option +\option{title-template} which can be set with \cs{setleadsheets} or as option +to a specific \env{song} environment. \leadsheets{} provides few predefined +templates and an easy mechanism to define own templates. + +\subsubsection{Existing Templates} + +Currently \leadsheets{} provides two templates: +\begin{description} + \item[\titletemplate{minimal}] This only typesettes the song title in a + \cs{section}\sarg. + \item[\titletemplate{tabular}] This typesets the song title in a + \cs{section} and prints some song properties in a \env*{tabular} below it. + This template needs the \pkg{array}~\cite{pkg:array} package loaded. +\end{description} + +\subsubsection{Own Templates}\label{sec:own-templates} +The principle is pretty straight forward: templates are defined with the +following command: +\begin{commands} + \command{definesongtitletemplate}[\marg{name}\marg{code}] + This defines the template \meta{name}. +\end{commands} +Inside of \meta{code} any code can be used. The idea is that you use the +commands presented below to insert song properties where you want them. + +First there are two commands related to defining new properties: +\begin{commands} + \command{definesongproperty}[\marg{property}] + Defines a new property \meta{property}. All existing properties have been + defined this way. The command can only be used in the preamble. + \command{copysongproperty}[\marg{from}\marg{to}] + Copies the values of property \meta{from} to property \meta{to} if + property \meta{to} has not been set but property \meta{from} has been. + For example all \code{sort-\meta{property}} properties have been treated + this way so they have the \meta{property} value as fallback. + The command can only be used in the preamble. +\end{commands} + +Then there are a number of commands related to retrieving and using the values +of properties. All these commands only make sense inside a title template +definition (see section~\ref{sec:title-templates}). Some of the commands are +expandable which means they can be used in an \cs*{edef} like context, \ie, +they are also suitable for writing the property values to the table of +contents or other auxiliary files. +\begin{commands} + \expandable\command{songproperty}[\marg{property}] + Retrieves property \meta{property}. + \command{printsongpropertylist}[\oarg{code}\marg{property}\marg{between + two}\marg{between more}\marg{between last two}]\Default{\cs*{@firstofone}} + Prints a property list \meta{property} separated with \meta{between two} + if the list contains only two items and separated with \meta{between more} + and \meta{between last two} if the list contains more than two items. + \meta{code} is placed directly in front of each item and items are + surrounded with braces which means that the last token in \meta{code} may + be a macro with a mandatory argument. + \command{usesongpropertylist}[\oarg{code}\marg{property}\marg{between}]% + \Default{\cs*{@firstofone}} + Like \cs{printsongpropertylist} but separates items with \meta{between} + regardless of the length of the list. + \expandable\command{forsongpropertylist}[\marg{property}\marg{code}] + Places all items of the property list \meta{property} in the input stream, + each item preceded with \meta{code}. Items are surrounded with braces + which means that the last token in \meta{code} may be a macro with a + mandatory argument. + \expandable\command{ifsongproperty}[\marg{property}\marg{true}\marg{false}] + Checks if property \meta{property} has been set. + \command{ifanysongproperty}[\Marg{csv list of properties}\marg{true}\marg{false}] + \sinceversion{0.4}Checks if any of the properties in \meta{csv list of + properties} has been set. + \command{ifallsongproperties}[\Marg{csv list of properties}\marg{true}\marg{false}] + \sinceversion{0.4}Checks if all of the properties in \meta{csv list of + properties} have been set. + \command{ifsongpropertiesequal}[\marg{property 1}\marg{property + 2}\marg{true}\marg{false}] + Checks if properties \meta{property 1} and \meta{property 2} have been set + to the same value. + \expandable\command{ifsongmeasuring}[\marg{true}\marg{false}] + \leadsheets{} measures the height of a song body before it typesets it and + it can often be necessary in a template to know if the measuring phase is + active or not. For example the song property \property{height} should + only be used if \emph{not} in the measuring phase: it's value get's + determined there and is not yet available. + \command{expandcode}[\marg{code}] + Exhaustively expands \meta{code}. Experienced users won't need this. It + is essentially + + \cs*{begingroup}\cs*{edef}\cs*{x}\Marg{\cs*{endgroup}\meta{code}}\cs*{x}. + + (More precisely it is a wrapper for the expl3 function \cs*{use:x}.) This + means that any \code{\#} needs to doubled. Inside the argument of this + commands non-robust macros that should not be expanded need to be prefixed + with \cs*{noexpand}. +\end{commands} + +With the right template definition you can index composers, interprets, song +titles, \ldots{} You can write tables of contents for properties such as song +titles, and so on, and so on. \leadsheets{} does not do this for you and it +may require some experience to create templates which do all this. + +\subsubsection{Examples} +In order to give you an idea on how to use songtitle templates I'll show you +how the existing ones are defined and one new definition. + +\paragraph{The \titletemplate*{minimal} template} +This is quite short and self-explaining. + +\begin{sourcecode} + \definesongtitletemplate{minimal}{\section*{\songproperty{title}}} +\end{sourcecode} + +\paragraph{A custom template} +Now let's see an example for a newly defined template. It's nearly as simple +as the \titletemplate{minimal} template. + +\begin{example}[ + compile, + graphics={trim={2cm 18cm 2cm 2cm},clip}, + add-sourcecode-options={literate=}] + \documentclass{article} + \usepackage{leadsheets} + \definesongtitletemplate{custom}{ + \ifsongmeasuring + {\section*} + {\section}{% + \songproperty{title}% + \ifsongproperty{music} + { (music by \printsongpropertylist{music}{ \& }{, }{ \& })} + {}% + } + } + \setleadsheets{title-template = custom} + \begin{document} + + \begin{song}{title={Mary Had A Little Lamb}, music={Stevie Ray Vaughan}, + lyrics={traditional}, tags={srv,blues}} + \begin{verse} + Mary had a little lamb \\ + Its fleece was white as snow, yea \\ + Everywhere the child went \\ + The little lamb was sure to go, yea + \end{verse} + \begin{verse} + He followed her to school one day \\ + And broke the teacher's rule \\ + What a time did they have \\ + That day at school + \end{verse} + \end{song} + + \end{document} +\end{example} + +\paragraph{The \titletemplate*{tabular} template} +This one is a lot more advanced and demonstrates various of the available +commands. + +\begin{sourcecode} + \definesongtitletemplate{tabular}{ + \ifsongmeasuring + {\section*} + {\section}% + {\songproperty{title}} + \begingroup\footnotesize + \begin{tabular}{ + @{} + >{\raggedright\arraybackslash}p{.5\linewidth} + @{} + >{\raggedleft\arraybackslash}p{.5\linewidth} + @{} + } + \ifsongproperty{interpret} + {\GetTranslation{leadsheets/interpret}} + {}% + \ifsongproperty{composer} + {% + & + \GetTranslation{leadsheets/composer}: % + \printsongpropertylist{composer}{ \& }{, }{ \& } + \ifsongproperty{lyrics} + { + \\ & + \GetTranslation{leadsheets/lyrics}: % + \printsongpropertylist{lyrics}{ \& }{, }{ \& } + } + {}% + } + {}% + \ifsongproperty{interpret}{\\}{\ifsongproperty{composer}{\\}{}}% + \ifsongproperty{genre} + {& Genre: \songproperty{genre} \\} + {}% + \ifsongproperty{tempo} + {& Tempo: \songproperty{tempo} \\} + {}% + \ifsongproperty{key} + {% + & \setchords{ + major = -\GetTranslation{leadsheets/major} , + minor = -\GetTranslation{leadsheets/minor} + }% + \GetTranslation{leadsheets/key}: % + \expandcode{\writechord{\songproperty{key}}} \\% + } + {}% + \end{tabular} + \par\endgroup + } +\end{sourcecode} + +A song using the \titletemplate{tabular} template: + +\begin{example}[ + compile, + graphics={trim={2cm 18cm 2cm 2cm},clip}, + add-sourcecode-options={literate=}] + \documentclass{article} + \usepackage{leadsheets} + \usepackage{array} + \setleadsheets{title-template = tabular} + \begin{document} + + \begin{song}{title={Mary Had A Little Lamb}, interpret={Stevie Ray Vaughan}, + genre={blues}, tags={srv,blues},key=E} + \begin{verse} + ^{E7} Mary had a little lamb ^{A7} \\ + Its fleece was white as ^{E7}snow, yea \\ + Everywhere the child ^{B7}went ^{A7} \\ + The little lamb was sure to ^{E7}go, yea + \end{verse} + \begin{verse} + ^{E7} He followed her to school one day ^{A7} \\ + And broke the teacher's ^{E7}rule \\ + What a time did they ^{B7}have ^{A7} \\ + That day at ^{E7}school + \end{verse} + \end{song} + + \end{document} +\end{example} + +\subsection{Verse-type Templates}\label{sec:verse-type-templates} +\subsubsection{Background} +Similar to the songtitles also the \env{verse} like environments are typeset +using templates. Defining them is just as easy as for the song titles. + +\subsubsection{Existing Templates} +Currently \leadsheets{} provides only one template: +\begin{description} + \item[\versetemplate{itemize}] Uses an \env*{itemize} environment for + typesetting the corresponding environment. +\end{description} + +\subsubsection{Own Templates} +Own templates can be defined using these commands: +\begin{commands} + \command{defineversetypetemplate}[\marg{name}\marg{begin code}\marg{end code}] + This defines the template \meta{name}. + \command{verselabel} + Used inside \cs{defineversetypetemplate}. This determines where the label + of the environment using the template will be displayed. + \command{verselabelformat} + Used inside \cs{defineversetypetemplate}. The format of the current + environment as set with the corresponding \option{format} option. + \command{verseafterlabel} + Used inside \cs{defineversetypetemplate}. The format of the current + environment as set with the corresponding \option{after-label} option. + \command{versename} + Used inside \cs{defineversetypetemplate}. This prints the name of the + current environment. + \command{versenumber} + Used inside \cs{defineversetypetemplate}. Expands to the + \cs*{the\meta{environment}} command for the current environment. + \command{ifversestarred}[\marg{true}\marg{false}] + Can be used inside \cs{defineversetypetemplate} for checking if the + current environment was defined by the starred version of + \cs{newversetype}. + \command{ifversenumbered}[\marg{true}\marg{false}] + Can be used inside \cs{defineversetypetemplate} for checking if for the + current environment the option \option{numbered} is true or false. + \command{ifversenamed}[\marg{true}\marg{false}] + Can be used inside \cs{defineversetypetemplate} for checking if for the + current environment the option \option{named} is true or false. + \command{ifobeylines}[\marg{true}\marg{false}] + Checks if for the current song the option \option{obey-lines} is true or + false. +\end{commands} +Since with \cs{defineversetypetemplate} you define a template for an +environment it has two argument for code: one for code at the beginning of the +environment and one for code at the end. The command \cs{verselabel} +internally uses the conditionals. Its definition is equivalent to the +following: + +\begin{sourcecode} + \newcommand*\verselabel{% + \ifversestarred + {} + {% + \verselabelformat + \ifversenamed + {% + \versename + \ifversenumbered{ }{}% + } + {}% + \ifversenumbered + {\versenumber} + {}% + \verseafterlabel + }% + } +\end{sourcecode} + +\subsubsection{Examples} +In order to give you an idea on how to use verse-type templates I'll show you +how the existing ones are defined and a few new definitions. + +\paragraph{The \versetemplate*{itemize} template} +This is how the \versetemplate{itemize} is defined. +\begin{sourcecode} + \makeatletter + \defineversetypetemplate{itemize} + {% + \itemize + \@itemdepth=0 + \ifobeylines + {% + \setlength{\parskip}{0pt}% + \setleadsheets{ obey-lines-parskip = \parsep }% + } + {}% + \item[{\verselabel}]% + } + {\enditemize} + \makeatother +\end{sourcecode} +The most interesting part is probably the \cs{ifobeylines} part. When the +option \option{obey-lines} is set to true an end of a line inserts a \cs*{par} +token. So in order not to get a vertical skip after every line the template +sets \cs*{parskip} to zero. With \keyis{obey-lines}{true} an empty line also +inserts a \cs*{par} token but it also inserts a vertical space according to +the value set with \option{obey-lines-parskip}. This option can only be set +in a verse-type template definition (which is why it isn't documented +elsewhere). All \env{verse} like environments initialize the length to the +current value of \cs*{parskip} \emph{before} the template code is inserted. + +\paragraph{A \versetemplate*{flushleft} template} +An example for a template \versetemplate*{flushleft} that typesets the label +in the margin: +\begin{example} + \defineversetypetemplate{flushleft} + {% + \noindent\llap{\verselabel\space}% + \flushleft + \unskip + \vspace*{-\baselineskip} + \ifobeylines + {% + \setlength\parskip{0pt} + \setleadsheets{ obey-lines-parskip = .5\baselineskip } + } + {% + \setlength\parskip{.5\baselineskip} + \vspace*{-\parskip} + }% + } + {\endflushleft} + \begin{chorus}[template=flushleft] + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, \\ + sed diam nonumy eirmod tempor invidunt ut labore et dolore \\ + magna aliquyam erat, sed diam voluptua. + + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, \\ + sed diam nonumy eirmod tempor invidunt ut labore et dolore \\ + magna aliquyam erat, sed diam voluptua. + \end{chorus} +\end{example} + +\paragraph{A \versetemplate*{flushright} template} +An example for a template \versetemplate*{flushright} that typesets the label +in the margin: +\begin{example} + \defineversetypetemplate{flushright} + {% + \noindent\llap{\verselabel\space}% + \flushright + \unskip + \vspace*{-\baselineskip} + \ifobeylines + {% + \setlength\parskip{0pt} + \setleadsheets{ obey-lines-parskip = .5\baselineskip } + } + {% + \setlength\parskip{.5\baselineskip} + \vspace*{-\parskip} + }% + } + {\endflushright} + \begin{chorus}[template=flushright] + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, \\ + sed diam nonumy eirmod tempor invidunt ut labore et dolore \\ + magna aliquyam erat, sed diam voluptua. + + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, \\ + sed diam nonumy eirmod tempor invidunt ut labore et dolore \\ + magna aliquyam erat, sed diam voluptua. + \end{chorus} +\end{example} + +As you can see it's not entirely easy to define a template that suits both +songs with and without \keyis{obey-lines}{true}. Personally I would forget +about that option and not care about it at all in my templates. + +\paragraph{A \versetemplate*{framed} template} +Last but not least an example using the \pkg{mdframed} +package~\cite{pkg:mdframed} -- just to show you that everything is possible. +The example adapts one of the examples of \pkg{mdframed}'s manual. +\begin{example} + \defineversetypetemplate{framed} + {% + \expandcode{% + \noexpand\mdframed[ + \ifversestarred{}{% + frametitle={% + \noexpand\tikz[baseline=(current bounding box.east),outer sep=0pt] + \noexpand\node[anchor=east,rectangle,fill=blue!20,rounded corners=2pt] + {\noexpand\strut\noexpand\verselabel}; + }% + }, + roundcorner = 5pt , + linecolor = blue!20 , + linewidth = 2pt, + topline = true, + frametitleaboveskip = \dimexpr-\ht\strutbox\relax , + ]% + }% + \setlength\parindent{0pt} + \setlength\parskip{\parsep} + \ifobeylines + {\setleadsheets{ obey-lines-parskip=\parskip }\setlength\parskip{0pt}} + {\vspace*{-\parskip}}% + } + {% + \endmdframed + \addvspace{\baselineskip}% + } + \begin{chorus}[template=framed] + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, \\ + sed diam nonumy eirmod tempor invidunt ut labore et dolore \\ + magna aliquyam erat, sed diam voluptua. + + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, \\ + sed diam nonumy eirmod tempor invidunt ut labore et dolore \\ + magna aliquyam erat, sed diam voluptua. + \end{chorus} +\end{example} + +\section{Internationalization}\label{sec:internationalization} + +Th environments described in sections~\ref{sec:envverse-environment} +and~\ref{sec:other-envverse-like} as well as a few other words used in +\leadsheets{} are translated with the help of the \pkg{translations} +package~\cite{pkg:translations}. All predefined and available translation +strings are listed in table~\ref{tab:translations}. You can change those +translations or add translations for other languages with this command: +\begin{commands} + \command*{DeclareTranslation}[\marg{language}\marg{string}\marg{translation}] + The command provided by the \pkg{translations} package for translating + strings. +\end{commands} +Those translations can be used for example in song title templates (see +section~\ref{sec:title-templates}). One of the strings listed in +table~\ref{tab:translations} is a little different: the string +\code{leadsheets/interpret} is declared as +\begin{sourcecode} + \DeclareTranslation{English}{leadsheets/interpret} + {as interpreted by \printsongpropertylist{interpret}{ \& }{, }{ \& }} + \DeclareTranslation{German}{leadsheets/interpret} + {wie von \printsongpropertylist{interpret}{ \& }{, }{ \& } interpretiert} +\end{sourcecode} +which means it uses the song property \property{interpret}. As a consequence +it only really can be used inside a \env{song} environment. In other cases as +for example in table~\ref{tab:translations} the property part expands to +nothing (but the spaces around it are of course there). Also keep in mind +that \cs{printsongpropertylist} is not expandable. + +\begin{table}[htbp] + \centering + \caption{Predefined translation strings.} + \newcommand*\showtranslation[1]{% + \texttt{leadsheets/#1} & + \GetTranslationFor{English}{leadsheets/#1} & + \GetTranslationFor{German}{leadsheets/#1} + } + \begin{tabular}{lll} + \toprule + \bfseries String & \bfseries English & \bfseries German \\ + \midrule + \showtranslation{major} \\ + \showtranslation{minor} \\ + \showtranslation{chorus} \\ + \showtranslation{verse} \\ + \showtranslation{composer} \\ + \showtranslation{lyrics} \\ + \showtranslation{key} \\ + \showtranslation{capo} \\ + \showtranslation{fret} \\ + \showtranslation{interpret} \\ + \showtranslation{intro} \\ + \showtranslation{interlude} \\ + \showtranslation{bridge} \\ + \showtranslation{solo} \\ + \bottomrule + \end{tabular} + \label{tab:translations} +\end{table} + +\clearpage +\part{The \library*{external} Library and the \cls*{leadsheet} + Class}\label{part:external-leadsheet} +\dictum[Thelonious Monk]{% + Talking about music is like dancing about architecture.% +} + +\section{The Idea} + +For\sinceversion{0.5} some users -- like myself -- it may be desirable to +create leadsheets that can be reused in another document as a compilation of +songs. The usual way would be to +\begin{itemize} + \item either solve this manually by copying the \env{song} environment from + one document to the other. This is not ideal, of course. + \item place the \env{song} in a file of its own and \cs*{input} it in the + different documents. This is easy and safe but requires a total of three + files for two documents. That's not really a problem, though, so it is a + valid way. +\end{itemize} + +\leadsheets{} now provides a third way. You write the single leadsheet using +the \cls{leadsheet} class that comes with this package. Let's call this file +\code{single.tex} for the following discussion: +\begin{sourcecode} + \documentclass{leadsheet} + \usepackage[T1]{fontenc} + \usepackage[utf8]{inputenc} + + \begin{document} + + \begin{song}{ ... } + ... + \end{song} + + \end{document} +\end{sourcecode} + +You can now include this document as is in another file -- let's call it +\code{multiple.tex}: +\begin{sourcecode} + \documentclass{scrartcl} + \usepackage{leadsheets} + \useleadsheetslibraries{external} + + \begin{document} + + \includeleadsheet{single.tex} + + \end{document} +\end{sourcecode} + +Depending on the settings this removes the complete preamble from +\code{single.tex} and only includes the document body of the file. + +\section{The \cls*{leadsheet} Class}\label{sec:leadsheet-class} + +The \cls{leadsheet} class is a class file built upon the \cls{scrartcl} +class. It defines a song title template \titletemplate{leadsheet}, makes a +few setup choices +\begin{sourcecode} + \setleadsheets{ + title-template = leadsheet , + bar-shortcuts , + verse/numbered , + verses-format = , + verses-label-format = \bfseries , + info/format = \itshape , + chorus/format = \itshape + } +\end{sourcecode} +and sets the header and the footer of the leadsheet pages. + +\begin{example}[ + compile, + graphics={trim={2cm 18cm 2cm 2cm},clip}, + add-sourcecode-options={literate=}] + \documentclass{leadsheet} + \usepackage[T1]{fontenc} + \usepackage[utf8]{inputenc} + \usepackage[ngerman]{babel} + + \begin{document} + + \begin{song}{title={Mary Had A Little Lamb}, music={Stevie Ray Vaughan}, + interpret={Stevie Ray Vaughan}, lyrics={traditional}, tags={srv,blues}} + \begin{verse} + Mary had a little lamb \\ + Its fleece was white as snow, yea \\ + Everywhere the child went \\ + The little lamb was sure to go, yea + \end{verse} + \begin{verse} + He followed her to school one day \\ + And broke the teacher's rule \\ + What a time did they have \\ + That day at school + \end{verse} + \end{song} + + \end{document} +\end{example} + +The header contains \enquote{\meta{song title} (\meta{interpret})} if the +leadsheet has more than one page in total. Otherwise it is empty. + +The footer contains \enquote{\meta{page} of \meta{pages}} if the leadsheet has +more than one page in total. Otherwise it is empty. + +The class provides the verse type \env{prechorus}: +\begin{environments} + \environment{prechorus}[\oarg{options}] + Environment for marking the pre-chorus of a song. +\end{environments} + +\begin{commands} + \command{instruction}[\marg{text}] + Short macro to add instructional text. + \command{mkinstruction}[\marg{text}] + The formatting macro used by \cs{instruction}. You can redefine it in + order to change the appearance. The default definition is: \\ + \verbcode+\newcommand*\mkinstruction[1]{\emph{#1}}+ + \command{choir}[\marg{text}] + Short macro to add (background) choir text. + \command{mkchoir}[\marg{text}] + The formatting macro used by \cs{choir}. You can redefine it in + order to change the appearance. The default definition is: \\ + \verbcode+\newcommand*\mkchoir[1]{\instruction{\leadsheetstranslate{choir}: #1}}+ + \command{lsenparen}[\marg{text}] + Short macro to add parentheses around text. Used internally by + \cs{instruction}. + \command{mklsenparens} + The parentheses setting macro used by \cs{lsenparen}. You can redefine it + in order to change the parentheses. The default definition is: \\ + \verbcode+\newcommand*\mklsenparens{[]}+ \\ + \emph{The definition needs to be expandable and to expand to exactly two + tokens or braced groups, one for the opening parenthesis and the second + for the closing parenthesis!} + \command{mklsenparen}[\marg{openen parenthesis}\marg{closing + parenthesis}\marg{text}] + The formatting macro used by \cs{lsenparen}. You can redefine it in + order to change the appearance. The default definition is: \\ + \verbcode+\newcommand*\mklsenparen[3]{\textup{#1}#3\textup{#2}}+ +\end{commands} + +Here is an example that demonstrates \cs{choir} and \cs{instruction}. (The +code of the example code has been saved in a file called +\code{single-leadsheet.tex}. It is used later on again.)\label{single-leadsheet} +\begin{example}[compile,graphics={trim={2cm 18cm 2cm 2cm},clip}, + add-sourcecode-options={literate=}] + \documentclass{leadsheet} + \usepackage[T1]{fontenc} + \usepackage[utf8]{inputenc} + + \begin{document} + + \begin{song}{title=foobar} + \begin{verse} + \instruction{keyboard only} \\ + Lorem ipsum dolor sit amet, consetetur sadipscing \\ + \choir{sed diam nonumy eirmod tempor invidunt ut labore et dolore} + \end{verse} + \begin{prechorus} + \instruction{+ band} \\ + Lorem ipsum dolor sit amet, consetetur sadipscing + \end{prechorus} + \end{song} + + \end{document} +\end{example} + +\section{The \library*{external} Library} + +Loading the \library{external} library allows to include complete leadsheet +documents (\ie, with preamble) into a main document. This requires the +included leadsheet to use the \cls{leadsheet} class (see +section~\ref{sec:leadsheet-class}). When the file is included the whole +preamble of said file will be discarded. This can be changed with an option +but then \cs*{usepackage} and \cs*{RequirePackage} will still be disabled and +simply do nothing in the included file. + +\begin{commands} + \command{includeleadsheet}[\sarg\oarg{options}\marg{file name}] + Include the leadsheet \meta{file name}. \meta{options} apply locally for + the included file. The file \meta{file name} may include a complete + document preamble. +\end{commands} + +\begin{filecontents*}{single-leadsheet.tex} +\documentclass{leadsheet} +\usepackage[T1]{fontenc} +\usepackage[utf8]{inputenc} + +\begin{document} + +\begin{song}{title=foobar} +\begin{verse} + \instruction{keyboard only} \\ + Lorem ipsum dolor sit amet, consetetur sadipscing \\ + \choir{sed diam nonumy eirmod tempor invidunt ut labore et dolore} +\end{verse} +\begin{prechorus} + \instruction{+ band} \\ + Lorem ipsum dolor sit amet, consetetur sadipscing +\end{prechorus} +\end{song} + +\end{document} +\end{filecontents*} +The next example shows the basic usage by inputting the example file mentioned +on page~\pageref{single-leadsheet}. \emph{Notice that the formatting setup by + the \cls{leadsheets} is not used}. Also the title template +\titletemplate{leadsheet} is not defined in this process. +\begin{example}[compile,graphics={trim={2cm 18cm 2cm 2cm},clip}, + add-sourcecode-options={literate=}] + \documentclass{scrartcl} + \usepackage{leadsheets} + \useleadsheetslibraries{external} + + \begin{document} + + \includeleadsheet{single-leadsheet} + + \end{document} +\end{example} +Also notice that the \env{prechorus} environment and the \cs{instruction} and +\cs{choir} macros \emph{are} available! \emph{All new macros defined in the + \cls{leadsheet} class and described in section~\ref{sec:leadsheet-class} are + defined}. If you do not want this then you can use the starred version of +\cs{includeleadsheet}. In this process the preamble of the included file is +gobbled. It may be desirable not to have the preamble gobbled, though -- +because of custom macro definitions for example. +\begin{options} + \keybool{gobble-preamble}\Default{true} + If set to \code{false} \cs{includeleadsheet} will not gobble the preamble + of the file it inputs. Using this is dangerous: for it to work + \cs*{usepackage} and \cs*{RequirePackage} have to be disabled while the + file is included. So including the preamble may lead to more problems + than it solves. +\end{options} + +The included leadsheets do not have to be a complete document -- a standard +tex file only consisting of the \env{song} environments will work just as +nicely. Files that are complete documents but are using another class than +\cls{leadsheet} will lead to errors, though. + +\clearpage +\part{Appendix} +\dictum[Thelonious Monk]{Wrong is right.} +\appendix + +\end{document} + |