summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/leadsheets/leadsheets_en.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /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.tex2256
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}
+