summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/leadsheets
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2015-01-11 22:50:01 +0000
committerKarl Berry <karl@freefriends.org>2015-01-11 22:50:01 +0000
commit9a32a7a9d63c685e263389fb8d77f6fc7fce616a (patch)
tree83e223e01c5b8503036efe14dfc1ea471c91b75e /Master/texmf-dist/doc/latex/leadsheets
parent343b8c08bc86c86208e49112681665dd68e4e9a2 (diff)
leadsheets (11jan15)
git-svn-id: svn://tug.org/texlive/trunk@36029 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/leadsheets')
-rw-r--r--Master/texmf-dist/doc/latex/leadsheets/README43
-rw-r--r--Master/texmf-dist/doc/latex/leadsheets/leadsheets_en.pdfbin0 -> 823201 bytes
-rw-r--r--Master/texmf-dist/doc/latex/leadsheets/leadsheets_en.tex1897
3 files changed, 1940 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/leadsheets/README b/Master/texmf-dist/doc/latex/leadsheets/README
new file mode 100644
index 00000000000..458f562b3e8
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/leadsheets/README
@@ -0,0 +1,43 @@
+--------------------------------------------------------------------------
+the LEADSHEETS package v0.1 2015/01/11
+
+ typesetting leadsheets and songbooks
+
+--------------------------------------------------------------------------
+Clemens Niederberger
+Web: https://github.com/cgnieder/leadsheets/
+E-Mail: contact@mychemistry.eu
+--------------------------------------------------------------------------
+Copyright 2014-2015 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.
+--------------------------------------------------------------------------
+The leadsheets bundle consists of the following files
+ - leadsheets.sty
+ - libraries -- they all follow the naming scheme
+ leadsheets.library.<name>.code.tex:
+ * chordnames
+ * chords
+ * musejazz
+ * musicsymbols
+ * properties
+ * songs
+ * templates
+ * translations
+ * transposing
+ - leadsheets_en.tex
+ - leadsheets_en.pdf
+--------------------------------------------------------------------------
+If you have any ideas, questions, suggestions or bugs to report, please
+feel free to contact me.
+--------------------------------------------------------------------------
diff --git a/Master/texmf-dist/doc/latex/leadsheets/leadsheets_en.pdf b/Master/texmf-dist/doc/latex/leadsheets/leadsheets_en.pdf
new file mode 100644
index 00000000000..69af371ca47
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/leadsheets/leadsheets_en.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/leadsheets/leadsheets_en.tex b/Master/texmf-dist/doc/latex/leadsheets/leadsheets_en.tex
new file mode 100644
index 00000000000..118320aa61e
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/leadsheets/leadsheets_en.tex
@@ -0,0 +1,1897 @@
+% !arara: pdflatex: { shell: on }
+% !arara: biber
+% arara: pdflatex
+% arara: pdflatex
+\documentclass[load-preamble+]{cnltx-doc}
+\usepackage{leadsheets}
+\setcnltx{
+ package = leadsheets ,
+ info = Typesetting leadsheets and songbooks ,
+ authors = Clemens Niederberger ,
+ email = contact@mychemistry.eu ,
+ url = https://github.com/cgnieder/leadsheets/ ,
+ add-cmds = {
+ chord , chordname ,
+ definesongtitletemplate ,
+ defineversetypetemplate ,
+ expandcode ,
+ ifobeylines ,
+ ifsongmeasuring ,
+ ifsongpropertiesequal ,
+ ifsongproperty ,
+ ifversenamed ,
+ ifversenumbered ,
+ ifversestarred ,
+ newversetype ,
+ printsongpropertylist ,
+ setchordnames ,
+ setleadsheets ,
+ songproperty ,
+ useleadsheetslibraries ,
+ useleadsheetslibrary ,
+ verseafterlabel ,
+ verselabel ,
+ verselabelformat ,
+ versename ,
+ versenumber ,
+ writechord
+ } ,
+ add-silent-cmds = {
+ @itemdepth ,
+ endmdframed ,
+ mdframed ,
+ newfontfamily,
+ musejazz
+ } ,
+ add-envs = {
+ arraybackslash ,
+ bridge ,
+ chorus , chorus* ,
+ flushleft ,
+ flushright ,
+ info ,
+ interlude ,
+ intro , intro* ,
+ outro , outro *
+ 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*\chordnames{\library{chordnames}}
+\newrobustcmd*\musejazz{\library{musejazz}}
+
+\setchordnames{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}
+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{chordnames}] \packageoption{chordnames}This library defines a
+ few macros for typesetting of chord symbols. It is described in
+ part~\ref{part:chordnames-library}. It also loads the
+ \library{musicsymbols}library.
+ \item[\library{musejazz}] \packageoption{musejazz}extends the \chordnames\
+ library to use MuseScore's \enquote{MuseJazz} font, see
+ section~\ref{sec:musejazz-libr}. It loads the \library{chordnames}
+ library.
+ \item[\library{songs}] \packageoption{songs}This is the 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. This library is described in
+ part~\ref{part:leadsheets-library}.
+\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{chordnames} 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{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{chords}] This is an auxiliary library not meant to be loaded
+ directly by users. It defines the necessary macros for printing the
+ chords in songs as well as the mechanism of remembering and recalling
+ chord sequences of verses.
+ \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} \\
+ \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}
+
+\clearpage
+\part{The \library*{chordnames} Library (and the \library*{musejazz} Library)}\label{part:chordnames-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.%
+}
+
+\section{The \cs*{chordname} Command}
+
+\chordnames{} provides the command \cs{chordname}\marg{chord} for convenient
+typesetting of chords:
+
+\begin{example}[side-by-side]
+ \chordname{Bb7(#9)} \chordname{Bbb6}
+ \chordname{C#7(b9)} \chordname{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+\chordname{F#7(#11)}+
+ \chordname{F#7(#11)}.
+\end{commands}
+
+There are several token lists that are treated specially inside \cs{chordname}:
+\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+\chordname{Gma}+ \chordname{Gma}.
+ \item[\code{mi}] The symbol for minor chords. Per default this is
+ \code{m}. \verbcode+\chordname{Gmi}+ \chordname{Gmi}.
+ \item[\code{o}] The symbol for diminished chords. Per default this is
+ \code{\cs*{textsuperscript}\Marg{o}}. \verbcode+\chordname{Go}+
+ \chordname{Go}.
+ \item[\code{+}] The symbol for augmented chords. Per default this is
+ \code{\cs*{textsuperscript}\Marg{+}}. \verbcode!\chordname{G+}!
+ \chordname{G+}.
+ \item[\code{/o}] The symbol for half diminished chords. Per default
+ this is \code{\cs*{textsuperscript}\Marg{\cs*{o}\Marg{}}}.
+ \verbcode+\chordname{G/o}+ \chordname{G/o}.
+ \item[\code{\#}] The \enquote{sharp} symbol. Per default this is
+ \cs{sharp}. \verbcode+\chordname{F#}+ \chordname{F#}.
+ \item[\code{\#\#}] The \enquote{double sharp} symbol. Per default this is
+ \cs{doublesharp}. \verbcode+\chordname{F##}+ \chordname{F##}.
+ \item[\code{b}] The \enquote{flat} symbol. Per default this is
+ \cs{flat}. \verbcode+\chordname{Eb}+ \chordname{Eb}.
+ \item[\code{bb}] The \enquote{double flat} symbol. Per default this is
+ \cs{doubleflat}. \verbcode+\chordname{Ebb}+ \chordname{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+\chordname{Gadd9}+
+ \chordname{Gadd9}.
+ \item[\code{sus}] This is superscripted: \verbcode+\chordname{Gsus4}+
+ \chordname{Gsus4}.
+ \item[\code{dim}] This is superscripted: \verbcode+\chordname{Gdim5}+
+ \chordname{Gdim5}.
+ \item[\code{maj7}] This is superscripted: \verbcode+\chordname{Gmaj7}+
+ \chordname{Gmaj7}.
+ \item[\code{maj9}] This is superscripted: \verbcode+\chordname{Gmaj9}+
+ \chordname{Gmaj9}.
+\end{labeling}
+
+How these token lists are treated depends on optional settings:
+
+\begin{example}
+ \setchordnames{
+ major-seven = $\Delta$ ,
+ major-nine = $\Delta$\textsuperscript{9}
+ }
+ \chordname{Gmaj7} \chordname{Gmaj9}
+ \chordname{G^6} \chordname{G6}
+ \chordname{G7^#5}
+\end{example}
+
+If you want to use the library standalone then you can say:
+\begin{sourcecode}
+ \usepackage[minimal]{leadsheets}
+ \useleadsheetslibraries{chordnames}
+\end{sourcecode}
+This also loads the \musicsymbols{} library.
+
+\section{Options}
+
+Options are set with the command
+\begin{commands}
+ \command{setchordnames}[\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{chordnames/} (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}.
+ \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 two further options which concern the different notations of the
+pitches \chordname{B} and \chordname{Bb} in German (and a few other European
+countries) and English.
+\begin{options}
+ \keychoice{input-notation}{literal,german,english}\Default{literal}
+ If set to \code{german} B should be input as \code{H} and B~flat as
+ \code{B}. If set to \code{american} B should be input as \code{B} and
+ B~flat as \code{Bb}.
+ \keychoice{output-notation}{literal,german,english}\Default{literal}
+ \setchordnames{output-notation=german}If set to \code{german} B is output
+ as \chordname{B} and B-flat as \chordname{Bb}.
+\end{options}
+Setting one option to a value other than \code{literal} implicitly sets the
+other one to \code{english} except the other option already has been set.
+This is shown in the example below. Setting on option to \code{literal} again
+also sets the other option to \code{literal}. This also resets the options.
+Earlier settings are forgotten. What does that mean? Here is an exercise:
+which options are active at each step and at the end?
+\begin{sourcecode}
+ 1. \setchordnames{ input-notation = german }
+ 2. \setchordnames{ output-notation = german , input-notation = english }
+ 3. \setchordnames{ input-notation = german }
+ 4. \setchordnames{ output-notation = english , input-notation = literal }
+ 5. \setchordnames{ output-notation = german }
+\end{sourcecode}
+Here's the solution:
+\begin{enumerate}
+ \item \keyis{input-notation}{german} and \keyis{output-notation}{english}
+ \item \keyis{input-notation}{english} and \keyis{output-notation}{german}
+ \item \keyis{input-notation}{german} and \keyis{output-notation}{german}
+ \item \keyis{input-notation}{literal} and \keyis{output-notation}{literal}
+ \item \keyis{input-notation}{german} and \keyis{output-notation}{english}
+\end{enumerate}
+
+The following example shows the effects of different input and output
+notations.
+\begin{example}
+ input and output literal:\par
+ \chordname{Bb} \chordname{B} \chordname{B#}\par
+ \chordname{B} \chordname{H} \chordname{H#}\par
+ \medskip
+
+ \setchordnames{input-notation=german}
+ input German and output English:\par
+ \chordname{Bb} \chordname{B} \chordname{B#}\par
+ \chordname{B} \chordname{H} \chordname{H#}\par
+ \medskip
+
+ \setchordnames{output-notation=german}
+ input and output German:\par
+ \chordname{Bb} \chordname{B} \chordname{B#}\par
+ \chordname{B} \chordname{H} \chordname{H#}\par
+
+ \medskip
+ \setchordnames{input-notation=english}
+ input English and output German:\par
+ \chordname{Bb} \chordname{B} \chordname{B#}\par
+ \chordname{B} \chordname{H} \chordname{H#}\par
+\end{example}
+
+\section{The \library*{musejazz} Library}\label{sec:musejazz-libr}
+
+The \musejazz\ library extends the \chordnames\ 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=lualatex,max-pages=1,add-frame=false]
+ % compile with LuaLaTeX or XeLaTeX
+ \documentclass[margin=4mm]{standalone}
+ \usepackage{leadsheets}
+ \useleadsheetslibrary{musejazz}
+ \begin{document}
+ \Huge\chordname{Bb7(#9)}\space\chordname{F##9}
+ \end{document}
+\end{example}
+
+\clearpage
+\part{The \library*{songs} Library}\label{part:leadsheets-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 mechansim 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}{\TeX{} code}\Default
+ \meta{\TeX{} code} is inserted \emph{before} the song title at the
+ beginning of the \env{song} environment.
+ \keyval{text-format}{\TeX{} code}\Default
+ \meta{\TeX{} code} is inserted \emph{after} the song title at the
+ beginning of the \env{song} 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}.
+ \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.
+\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 ia
+\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 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!}
+
+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
+option:
+
+\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.
+\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.
+\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)!
+
+Each \env{verse} like environment (see section~\ref{sec:other-envverse-like}
+for more information) is treated uniquely by this mechansim:
+
+\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]
+ ^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 \chordname{E} down a semitone.
+ \leadsheets{} will then transpose to the key of \chordname{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 \chordname{D#} instead of \chordname{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 \chordnames{} 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{\chordname{!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}).
+ \keyval{recall-chords}{environment}
+ An option to be used with the \option{remember-chords} mechanism, see
+ section~\ref{sec:remembering-chords} for an example.
+\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 mechansim 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{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 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}
+ {%
+ & \setchordnames{
+ 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}}{\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}}{\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]
+ {\noexpand\strut\noexpand\verselabel};
+ }%
+ },
+ roundcorner = 5pt ,
+ linecolor = blue!20 ,
+ linewidth = 2pt,
+ topline = true,
+ frametitleaboveskip = \dimexpr-\ht\strutbox\relax ,
+ ]%
+ }%
+ \ifobeylines{\setlength\parskip{0pt}}{}%
+ }
+ {%
+ \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{Appendix}
+\dictum[Thelonious Monk]{%
+ Talking about music is like dancing about architecture.%
+}
+\appendix
+
+\end{document}