diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/leadsheets')
| -rw-r--r-- | Master/texmf-dist/doc/latex/leadsheets/README | 4 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/leadsheets/leadsheets_en.pdf | bin | 836428 -> 913056 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/leadsheets/leadsheets_en.tex | 340 |
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 Binary files differindex 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} + |