leadsheets (19aug16)

git-svn-id: svn://tug.org/texlive/trunk@41890 c570f23f-e606-0410-a88d-b1316a301751

3 files changed, 316 insertions, 28 deletions

diff --git a/Master/texmf-dist/doc/latex/leadsheets/README b/Master/texmf-dist/doc/latex/leadsheets/README
index 955c3c8222d..b9aa292acc4 100644
--- a/Master/texmf-dist/doc/latex/leadsheets/README
+++ b/Master/texmf-dist/doc/latex/leadsheets/README
@@ -1,5 +1,5 @@
 --------------------------------------------------------------------------
-the LEADSHEETS package v0.3a 2016/02/02
+the LEADSHEETS package v0.5 2016/08/18
  
   typesetting leadsheets and songbooks
 
@@ -28,9 +28,11 @@ The leadsheets bundle consists of the following files
    leadsheets.library.<name>.code.tex:
     * chordnames
     * chords
+    * external
     * musejazz
     * musicsymbols
     * properties
+    * shorthands
     * songs
     * templates
     * translations
diff --git a/Master/texmf-dist/doc/latex/leadsheets/leadsheets_en.pdf b/Master/texmf-dist/doc/latex/leadsheets/leadsheets_en.pdf
index 8bed560bd85..1bbdd730d63 100644
--- a/Master/texmf-dist/doc/latex/leadsheets/leadsheets_en.pdf
+++ b/Master/texmf-dist/doc/latex/leadsheets/leadsheets_en.pdf
diff --git a/Master/texmf-dist/doc/latex/leadsheets/leadsheets_en.tex b/Master/texmf-dist/doc/latex/leadsheets/leadsheets_en.tex
index 2c1e3acbbb4..4ac2ee677f5 100644
--- a/Master/texmf-dist/doc/latex/leadsheets/leadsheets_en.tex
+++ b/Master/texmf-dist/doc/latex/leadsheets/leadsheets_en.tex
@@ -1,20 +1,22 @@
-% !arara: pdflatex: { shell: on }
-% arara: biber
-% arara: pdflatex
-% arara: pdflatex
+% arara: pdflatex: { shell: on , action: nonstopmode }
+% !arara: biber
+% !arara: pdflatex
+% !arara: pdflatex
 \documentclass[load-preamble+]{cnltx-doc}
-\usepackage{leadsheets}
+\usepackage{leadsheets,bookmark}
 \setcnltx{
   package = leadsheets ,
   info    = Typesetting leadsheets and songbooks ,
   authors = Clemens Niederberger ,
   email   = contact@mychemistry.eu ,
-  url     = http://www.mychemistry.eu/forums/forum/leadsheets/ ,
+  url     = https://github.com/cgnieder/leadsheets/ ,
   add-cmds = {
-    chord , chordname ,
+    choir , chord , chordname ,
     definesongtitletemplate ,
     defineversetypetemplate , 
     expandcode ,
+    ifallsongproperties ,
+    ifanysongproperty ,
     ifobeylines ,
     ifsongmeasuring ,
     ifsongpropertiesequal ,
@@ -22,6 +24,14 @@
     ifversenamed ,
     ifversenumbered ,
     ifversestarred ,
+    includeleadsheet ,
+    instruction ,
+    leadsheetstranslate ,
+    lsenparen ,
+    mkchoir ,
+    mkinstruction ,
+    mklsenparen ,
+    mklsenparens ,
     newversetype ,
     printsongpropertylist ,
     setchords ,
@@ -42,6 +52,7 @@
     endmdframed ,
     mdframed ,
     newfontfamily ,
+    newrobustcmd ,
     musejazz
   } ,
   add-envs = {
@@ -52,7 +63,8 @@
     info ,
     interlude ,
     intro , intro* ,
-    outro , outro *
+    outro , outro * ,
+    prechorus , prechorus* ,
     solo , solo* ,
     song ,
     verse
@@ -227,11 +239,14 @@ The user-libraries are the following ones:
     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
+  \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-library}.
+    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}
@@ -254,6 +269,9 @@ the following list gives hints to where some of the concepts are explained:
     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.
@@ -315,6 +333,8 @@ they're not explained here.
       \showsymbol{wholerest}   & \showsymbol{halfrest} \\
       \showsymbol{quarterrest} & \showsymbol{eighthrest} \\
       \showsymbol{sixteenthrest} \\
+    \midrule
+      \showsymbol{Break} \\
     \bottomrule
   \end{tabular}
   \label{tab:musicsymbols}
@@ -352,8 +372,15 @@ bars:
     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}
+\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.%
@@ -491,7 +518,9 @@ doesn't change the input syntax.
   \keyval{major}{code}\Default
     The token list \code{ma}.
   \keyval{minor}{code}\Default{m}
-    The token list \code{mi}.
+    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}}
@@ -558,7 +587,7 @@ requires \LuaLaTeX\ or \XeLaTeX.  Well, and the font, obviously.
 
 Here is a small example of it's usage and the outcome:
 
-\begin{example}[compile,program=lualatex,max-pages=1,add-frame=false]
+\begin{example}[compile,program=xelatex,max-pages=1,add-frame=false]
   % compile with LuaLaTeX or XeLaTeX
   \documentclass[margin=4mm]{standalone}
   \usepackage{leadsheets}
@@ -569,7 +598,7 @@ Here is a small example of it's usage and the outcome:
 \end{example}
 
 \clearpage
-\part{The \library*{songs} Library}\label{part:leadsheets-library}
+\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.%
@@ -581,7 +610,7 @@ 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
+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.
@@ -722,6 +751,10 @@ Although I used the word \enquote{global} above \emph{all options are local to
     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}
@@ -796,15 +829,17 @@ templates (see section~\ref{sec:title-templates}).  One specific property,
 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
+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 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!}
+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
@@ -1107,7 +1142,7 @@ as \cs{chord} with one exception: it lacks the mandatory argument
 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:
+for more information) is treated uniquely by this mechanism:
 
 \begin{example}
   \definesongtitletemplate{empty}{}
@@ -1424,7 +1459,7 @@ 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.
+templates and an easy mechanism to define own templates.
 
 \subsubsection{Existing Templates}
 
@@ -1488,16 +1523,22 @@ contents or other auxiliary files.
     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 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.
+    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
@@ -1934,10 +1975,255 @@ that \cs{printsongpropertylist} is not expandable.
 \end{table}
 
 \clearpage
-\part{Appendix}
+\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}
+