path: root/Master/texmf-dist/doc/latex/leadsheets/leadsheets_en.tex

% arara: pdflatex: { shell: on , action: nonstopmode }
% !arara: biber
% !arara: pdflatex
% !arara: pdflatex
\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)!

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}