From c7892fe1a11367872de6f3ee0fa074b39824e59c Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 31 Oct 2022 03:04:01 +0000 Subject: CTAN sync 202210310303 --- support/lyluatex/lyluatex.tex | 301 +++++++++++++++++++++++++++++++++--------- 1 file changed, 236 insertions(+), 65 deletions(-) (limited to 'support/lyluatex/lyluatex.tex') diff --git a/support/lyluatex/lyluatex.tex b/support/lyluatex/lyluatex.tex index aaa95d7848..a804663555 100644 --- a/support/lyluatex/lyluatex.tex +++ b/support/lyluatex/lyluatex.tex @@ -1,38 +1,45 @@ -\PassOptionsToPackage{unicode=true}{hyperref} % options for packages loaded elsewhere +% Options for packages loaded elsewhere +\PassOptionsToPackage{unicode}{hyperref} \PassOptionsToPackage{hyphens}{url} % -\documentclass[]{lyluatexmanual} +\documentclass[ +]{lyluatexmanual} +\usepackage{amsmath,amssymb} \usepackage[]{libertine} -\usepackage{amssymb,amsmath} -\usepackage{ifxetex,ifluatex} -\usepackage{fixltx2e} % provides \textsubscript -\ifnum 0\ifxetex 1\fi\ifluatex 1\fi=0 % if pdftex +\usepackage{iftex} +\ifPDFTeX \usepackage[T1]{fontenc} \usepackage[utf8]{inputenc} - \usepackage{textcomp} % provides euro and other symbols -\else % if luatex or xelatex + \usepackage{textcomp} % provide euro and other symbols +\else % if luatex or xetex \usepackage{unicode-math} - \defaultfontfeatures{Ligatures=TeX,Scale=MatchLowercase} + \defaultfontfeatures{Scale=MatchLowercase} + \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1} \fi -% use upquote if available, for straight quotes in verbatim environments +% Use upquote if available, for straight quotes in verbatim environments \IfFileExists{upquote.sty}{\usepackage{upquote}}{} -% use microtype if available -\IfFileExists{microtype.sty}{% -\usepackage[]{microtype} -\UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts +\IfFileExists{microtype.sty}{% use microtype if available + \usepackage[]{microtype} + \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts }{} -\IfFileExists{parskip.sty}{% -\usepackage{parskip} -}{% else -\setlength{\parindent}{0pt} -\setlength{\parskip}{6pt plus 2pt minus 1pt} -} -\usepackage{hyperref} +\makeatletter +\@ifundefined{KOMAClassName}{% if non-KOMA class + \IfFileExists{parskip.sty}{% + \usepackage{parskip} + }{% else + \setlength{\parindent}{0pt} + \setlength{\parskip}{6pt plus 2pt minus 1pt}} +}{% if KOMA class + \KOMAoptions{parskip=half}} +\makeatother +\usepackage{xcolor} +\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available +\IfFileExists{bookmark.sty}{\usepackage{bookmark}}{\usepackage{hyperref}} \hypersetup{ - pdfauthor={Fr. Jacques Peron; Urs Liska; Br. Samuel Springuel}, - pdfborder={0 0 0}, - breaklinks=true} -\urlstyle{same} % don't use monospace font for urls + pdfauthor={Fr.~Jacques Peron; Urs Liska; Br. Samuel Springuel}, + hidelinks, + pdfcreator={LaTeX via pandoc}} +\urlstyle{same} % disable monospaced font for URLs \usepackage{color} \usepackage{fancyvrb} \newcommand{\VerbBar}{|} @@ -44,7 +51,7 @@ \newcommand{\AnnotationTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}} \newcommand{\AttributeTok}[1]{\textcolor[rgb]{0.49,0.56,0.16}{#1}} \newcommand{\BaseNTok}[1]{\textcolor[rgb]{0.25,0.63,0.44}{#1}} -\newcommand{\BuiltInTok}[1]{#1} +\newcommand{\BuiltInTok}[1]{\textcolor[rgb]{0.00,0.50,0.00}{#1}} \newcommand{\CharTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}} \newcommand{\CommentTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textit{#1}}} \newcommand{\CommentVarTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}} @@ -57,7 +64,7 @@ \newcommand{\ExtensionTok}[1]{#1} \newcommand{\FloatTok}[1]{\textcolor[rgb]{0.25,0.63,0.44}{#1}} \newcommand{\FunctionTok}[1]{\textcolor[rgb]{0.02,0.16,0.49}{#1}} -\newcommand{\ImportTok}[1]{#1} +\newcommand{\ImportTok}[1]{\textcolor[rgb]{0.00,0.50,0.00}{\textbf{#1}}} \newcommand{\InformationTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}} \newcommand{\KeywordTok}[1]{\textcolor[rgb]{0.00,0.44,0.13}{\textbf{#1}}} \newcommand{\NormalTok}[1]{#1} @@ -71,30 +78,23 @@ \newcommand{\VariableTok}[1]{\textcolor[rgb]{0.10,0.09,0.49}{#1}} \newcommand{\VerbatimStringTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}} \newcommand{\WarningTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}} -\setlength{\emergencystretch}{3em} % prevent overfull lines +\setlength{\emergencystretch}{3em} % prevent overfull lines \providecommand{\tightlist}{% \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}} -\setcounter{secnumdepth}{0} -% Redefines (sub)paragraphs to behave more like sections -\ifx\paragraph\undefined\else -\let\oldparagraph\paragraph -\renewcommand{\paragraph}[1]{\oldparagraph{#1}\mbox{}} -\fi -\ifx\subparagraph\undefined\else -\let\oldsubparagraph\subparagraph -\renewcommand{\subparagraph}[1]{\oldsubparagraph{#1}\mbox{}} +\setcounter{secnumdepth}{-\maxdimen} % remove section numbering +\ifLuaTeX + \usepackage{selnolig} % disable illegal ligatures \fi -% set default figure placement to htbp +\title{\lyluatex} +\usepackage{etoolbox} \makeatletter -\def\fps@figure{htbp} +\providecommand{\subtitle}[1]{% add subtitle to \maketitle + \apptocmd{\@title}{\par {\large #1 \par}}{}{} +} \makeatother - - -\title{\lyluatex} -\providecommand{\subtitle}[1]{} -\subtitle{1.0f} -\author{Fr. Jacques Peron \and Urs Liska \and Br. Samuel Springuel} +\subtitle{1.1} +\author{Fr.~Jacques Peron \and Urs Liska \and Br. Samuel Springuel} \date{\lyluatexmanualdate} \begin{document} @@ -317,8 +317,8 @@ Linux with TeXLive: \begin{Shaded} \begin{Highlighting}[] -\ExtensionTok{%}\NormalTok{ export shell_escape_commands=}\VariableTok{$(}\ExtensionTok{kpsewhich}\NormalTok{ -expand-var }\StringTok{'$shell_escape_commands'}\VariableTok{)}\NormalTok{,lilypond,gs} -\ExtensionTok{%}\NormalTok{ lualatex --shell-restricted DOCUMENT.tex} +\ExtensionTok{\%}\NormalTok{ export shell\_escape\_commands=}\VariableTok{$(}\ExtensionTok{kpsewhich} \AttributeTok{{-}expand{-}var} \StringTok{\textquotesingle{}$shell\_escape\_commands\textquotesingle{}}\VariableTok{)}\NormalTok{,lilypond,gs} +\ExtensionTok{\%}\NormalTok{ lualatex }\AttributeTok{{-}{-}shell{-}restricted}\NormalTok{ DOCUMENT.tex} \end{Highlighting} \end{Shaded} @@ -347,13 +347,13 @@ The basic mode of inserting scores into text documents is the \KeywordTok{\textbackslash{}score} \KeywordTok{\{} \KeywordTok{\textbackslash{}new} \DataTypeTok{ChoirStaff}\NormalTok{ \textbackslash{}with}\KeywordTok{ \{} \DataTypeTok{instrumentName}\NormalTok{ = "}\StringTok{2 Fl."} - \KeywordTok{\}} \KeywordTok{<<} - \KeywordTok{\textbackslash{}new} \DataTypeTok{Staff} \FunctionTok{\textbackslash{}transpose c c'} \FunctionTok{\textbackslash{}music} + \KeywordTok{\}} \KeywordTok{\textless{}\textless{}} + \KeywordTok{\textbackslash{}new} \DataTypeTok{Staff} \FunctionTok{\textbackslash{}transpose c c\textquotesingle{}} \FunctionTok{\textbackslash{}music} \KeywordTok{\textbackslash{}new} \DataTypeTok{Staff} \KeywordTok{\{} \FunctionTok{\textbackslash{}clef bass} \FunctionTok{\textbackslash{}music} \KeywordTok{\}} - \KeywordTok{>>} + \KeywordTok{\textgreater{}\textgreater{}} \KeywordTok{\}} \FunctionTok{\textbackslash{}end}\KeywordTok{\{}\NormalTok{lilypond}\KeywordTok{\}} \end{Highlighting} @@ -510,23 +510,23 @@ arguments to the individual command or environments: \begin{Highlighting}[] \FunctionTok{\textbackslash{}lilypondfile}\NormalTok{[key1=value1]\{path/to/file.ly\}} -\FunctionTok{\textbackslash{}lilypond}\NormalTok{[key1=value1]\{ c' d' e' \}} +\FunctionTok{\textbackslash{}lilypond}\NormalTok{[key1=value1]\{ c\textquotesingle{} d\textquotesingle{} e\textquotesingle{} \}} \KeywordTok{\textbackslash{}begin}\NormalTok{\{}\ExtensionTok{lilypond}\NormalTok{\}[key1=value1]} \NormalTok{\{} -\NormalTok{ c' d' e'} +\NormalTok{ c\textquotesingle{} d\textquotesingle{} e\textquotesingle{}} \NormalTok{\}} \KeywordTok{\textbackslash{}end}\NormalTok{\{}\ExtensionTok{lilypond}\NormalTok{\}} \end{Highlighting} \end{Shaded} -\lyCmd{lysetoption} +\lyCmd{setluaoption{ly}} At any place in the document the value of an option can be changed using \begin{Shaded} \begin{Highlighting}[] -\FunctionTok{\textbackslash{}lysetoption}\NormalTok{\{key\}\{new-value\}} +\FunctionTok{\textbackslash{}setluaoption}\NormalTok{\{ly\}\{key\}\{new{-}value\}} \end{Highlighting} \end{Shaded} @@ -756,7 +756,7 @@ detail. If not stated otherwise dimensions can be given in arbitrary \TeX~units, e.g. \texttt{200pt}, \texttt{1ex} or \texttt{3cm} or as \TeX~lengths, -e.g. \texttt{0.4\textbackslash{}textwidth}. +e.g.~\texttt{0.4\textbackslash{}textwidth}. \hypertarget{general}{% \paragraph{General}\label{general}} @@ -1169,7 +1169,7 @@ example: \begin{Shaded} \begin{Highlighting}[] -\FunctionTok{\textbackslash{}lilypond}\NormalTok{\{a' b' c'\}} +\FunctionTok{\textbackslash{}lilypond}\NormalTok{\{a\textquotesingle{} b\textquotesingle{} c\textquotesingle{}\}} \end{Highlighting} \end{Shaded} @@ -1372,8 +1372,8 @@ monospace: \begin{Shaded} \begin{Highlighting}[] -\FunctionTok{\textbackslash{}renewcommand}\NormalTok{\{}\ExtensionTok{\textbackslash{}lyFilename}\NormalTok{\}[1]\{}\CommentTok{%} -\FunctionTok{\textbackslash{}noindent} \FunctionTok{\textbackslash{}texttt}\NormalTok{\{#1\}}\FunctionTok{\textbackslash{}par\textbackslash{}bigskip}\CommentTok{%} +\FunctionTok{\textbackslash{}renewcommand}\NormalTok{\{}\ExtensionTok{\textbackslash{}lyFilename}\NormalTok{\}[1]\{}\CommentTok{\%} +\FunctionTok{\textbackslash{}noindent} \FunctionTok{\textbackslash{}texttt}\NormalTok{\{\#1\}}\FunctionTok{\textbackslash{}par\textbackslash{}bigskip}\CommentTok{\%} \NormalTok{\}} \end{Highlighting} \end{Shaded} @@ -1425,8 +1425,8 @@ indent and prints the text blue: \begin{Shaded} \begin{Highlighting}[] -\FunctionTok{\textbackslash{}renewcommand}\NormalTok{\{}\ExtensionTok{\textbackslash{}lyIntertext}\NormalTok{\}[1]\{}\CommentTok{%} -\FunctionTok{\textbackslash{}noindent} \FunctionTok{\textbackslash{}textcolor}\NormalTok{\{blue\}\{#1\}}\FunctionTok{\textbackslash{}par\textbackslash{}bigskip}\CommentTok{%} +\FunctionTok{\textbackslash{}renewcommand}\NormalTok{\{}\ExtensionTok{\textbackslash{}lyIntertext}\NormalTok{\}[1]\{}\CommentTok{\%} +\FunctionTok{\textbackslash{}noindent} \FunctionTok{\textbackslash{}textcolor}\NormalTok{\{blue\}\{\#1\}}\FunctionTok{\textbackslash{}par\textbackslash{}bigskip}\CommentTok{\%} \NormalTok{\}} \end{Highlighting} \end{Shaded} @@ -1452,11 +1452,11 @@ match today is to use the \texttt{TeX} highlighting of the \begin{Shaded} \begin{Highlighting}[] -\CommentTok{% In the document header:} +\CommentTok{\% In the document header:} \BuiltInTok{\textbackslash{}usepackage}\NormalTok{\{}\ExtensionTok{minted}\NormalTok{\}} -\CommentTok{% anywhere in the header or the body:} -\FunctionTok{\textbackslash{}lysetverbenv}\NormalTok{\{}\KeywordTok{\textbackslash{}begin}\NormalTok{\{}\ExtensionTok{minted}\NormalTok{\}\{TeX\}\}\{\textbackslash{}end\{minted\}\}} +\CommentTok{\% anywhere in the header or the body:} +\FunctionTok{\textbackslash{}lysetverbenv}\NormalTok{\{}\KeywordTok{\textbackslash{}begin}\NormalTok{\{}\ExtensionTok{minted}\NormalTok{\}\{TeX\}}\VerbatimStringTok{\}\{}\KeywordTok{\textbackslash{}end}\NormalTok{\{}\ExtensionTok{minted}\NormalTok{\}\}} \end{Highlighting} \end{Shaded} @@ -1505,9 +1505,9 @@ absolute paths in that process. \begin{Shaded} \begin{Highlighting}[] -\FunctionTok{\textbackslash{}lysetoption}\NormalTok{\{includepaths\}\{}\FunctionTok{\textbackslash{}string}\NormalTok{~/lilypond-lib\}} +\FunctionTok{\textbackslash{}setluaoption}\NormalTok{\{ly\}\{includepaths\}\{}\FunctionTok{\textbackslash{}string}\NormalTok{\textasciitilde{}/lilypond{-}lib\}} -\FunctionTok{\textbackslash{}lilypondfile}\NormalTok{[includepaths=\{}\FunctionTok{\textbackslash{}string}\NormalTok{~/lilypond-lib,/home/johndoe/project-lib\}]} +\FunctionTok{\textbackslash{}lilypondfile}\NormalTok{[includepaths=\{}\FunctionTok{\textbackslash{}string}\NormalTok{\textasciitilde{}/lilypond{-}lib,/home/johndoe/project{-}lib\}]} \end{Highlighting} \end{Shaded} @@ -1774,22 +1774,31 @@ Those examples and others may be found in \addcontentsline{toc}{subsection}{Insert Systems} \hypertarget{insert-systems}{} + \section*{Insert System-by-System} + By default scores defined by the \option{lilypond} environment or the \cmd{lilypondfile} command are inserted as a sequence of systems. + \lyluatex\ determines the vertical space between the systems as a flexible length calculated from the \emph{staff size} of the score (as opposed to from the font size) to produce an regular-looking vertical spacing: + \begin{lilypond}[] { \repeat unfold 30 { c' d' e' d' } } \end{lilypond} + The following score has a significantly smaller staff size, and consequently the inter-system space is reduced: + \begin{lilypond}[staffsize=12] { \repeat unfold 36 { c' d' e' d' } } \end{lilypond} + \subsection*{Before and After the Score} + \cmd{preLilyPondExample} and \cmd{postLilyPondExample} allow some code to be printed before and after the score. This may for example be used to wrap the resulting score in an environment. In the following example rules are printed: + \def\preLilyPondExample{% \par\bigskip \noindent Before the score: @@ -1798,35 +1807,43 @@ The following score has a significantly smaller staff size, and consequently the \par\bigskip \hrule\par\medskip\noindent After the score \par\bigskip} + \begin{verbatim} \newcommand{\preLilyPondExample}{% \par\bigskip \noindent Before the score: \par\medskip\hrule\par\medskip} + \newcommand{\postLilyPondExample}{% \par\bigskip \hrule\par\medskip\noindent After the score \par\bigskip} \end{verbatim} + \begin{lilypond}[] { \repeat unfold 30 { c' d' e' d' } } \end{lilypond} + \subsection*{Configuring the Inter-System Content} + \let\preLilyPondExample\undefined \let\postLilyPondExample\undefined + Using \cmd{betweenLilyPondSystem} it is possible to define a macro that is expanded between each system pair. It is given the index of the previous system as an argument to work with. The following example simply prints that index between the systems, but with some programming more complicated and useful things could be done, for example printing a rule after every third system or conditionally insert a page break. + \def\betweenLilyPondSystem#1{% \begin{center} System #1 \end{center} } + \begin{verbatim} \newcommand{\betweenLilyPondSystem}[1]{% \begin{center} @@ -1834,42 +1851,53 @@ System #1 \end{center} } \end{verbatim} + \bigskip + \begin{lilypond}[] { \repeat unfold 30 { c' d' e' d' } } \end{lilypond} + \let\betweenLilyPondSystem\undefined + \addcontentsline{toc}{subsection}{Insert Inline} \hypertarget{insert-inline}{} + \section*{Insert Scores Inline} + With the \option{insert=inline} option it is simple to insert arbitrary notational fragments in the \lilypond{ e'8 d'16 e' } continuous text of a document. By default the staffsize is scaled to be 2/3 of the staffsize a regular score would have at this point. This means if the \option{staffsize} option is modified globally or locally then the staffsize of the inline score is changed too. + In order to make the size of inline scores independent from the regular staffsize the option \option{inline-staffsize} can be used the same way as \option{staffsize}. \lilypond[inline-staffsize=8]{ e'8 d'16 e' } has the inline staffsize manually set to \texttt{8}. + \paragraph{Alignment and padding} By default inline scores are vertically centered to a line 1/2em above the text's baseline. \lilypond[valign=top]{ e'8 d'16 e' } but the score can also be aligned \lilypond[valign=bottom]{ e'8 d'16 e' } to the top or the baseline of the text. + Unfortunately this can only consider the borders of the \emph{image} and not those of the \emph{score} or the staff lines. To alleviate this situation a specific vertical offset can be given with \option{voffset=-3pt} (or any other \TeX\ lengths). This offset is calculated after the alignment. \lilypond[valign=bottom,voffset=-6pt]{ e'8 d'16 e' } is inserted with \option{valign=bottom,voffset=-4pt}. + Horizontally inline scores are padded by \option{hpadding=0.75ex} -- except if they happen to appear at the beginning or end of a line, as can be seen in the last score in the previous paragraph. \lilypond[hpadding=2em]{ e'8 d'16 e' } Increasing the \option{hpadding} will ensure more space around the score. + \paragraph{Bare Inline scores} \option{insert=bare-inline} will remove all the staff elements (staff symbol, time signature, clef) by implicitly applying \option{nostaff}, which is most useful for including notational symbols like @@ -1885,121 +1913,165 @@ possibility of inserting arbitrary LilyPond material without having to prepare precompiled PDF images. + \addcontentsline{toc}{subsection}{Choosing Systems} \hypertarget{print-only}{} + \def\postLilyPondExample{\par\bigskip\hrule\par\bigskip} + \section*{Print only Selected Systems or Pages} + The \texttt{print-only} and \texttt{do-not-print} options allow to limit the printed systems or pages from a score. A typical use case is to print a score interspersed with comments. The advantage of this approach is that the score is compiled only once while the individual systems are simply reused by \LaTeX. + Throughout this document we'll demonstrate the different options to select systems from the following score: + \lilypondfile[verbatim]{eight-systems.ly} + The simplest selection is a single system: \texttt{print-only=4} + \lilypondfile[print-only=4]{eight-systems.ly} + Ranges are also possible: \texttt{print-only=3-5}, with the special form of \texttt{print-only=6-} which prints from the given system throughout the end of the score. Negative ranges can be given with \texttt{print-only=7-5} + \lilypondfile[print-only=3-5]{eight-systems.ly} + \lilypondfile[print-only=6-]{eight-systems.ly} + \lilypondfile[print-only=7-5]{eight-systems.ly} + With a comma-separated list an arbitrary sequence of systems can be specified. The list has to be enclosed in curly brackets: \texttt{print-only={4,1,2}} + \lilypondfile[print-only={4,1,2}]{eight-systems.ly} + Each element of the list can include any of the forms described above:\\ \texttt{print-only={3,5-7,4,7-}} + \lilypondfile[print-only={3,5-7,4,7-}]{eight-systems.ly} + \texttt{do-not-print} does the opposite: it prevents the list of systems from being printed. It might be used alone, or in combination with \texttt{print-only}:\\ \texttt{print-only=3-,do-not-print=6} + \lilypondfile[print-only=3-,do-not-print=6]{eight-systems.ly} + The functionality is identical with fullpage scores where the selection applies to \emph{pages} instead. This can for example be used when the “score” file contains a number of individual pieces (e.g. songs for a song book), and individual selections are to be printed. + Systems have some specific behaviour with regard to \emph{indent}, but this is demonstrated in its own file \texttt{dynamic-indent.tex}. + \let\postLilyPondExample\undefined + \addcontentsline{toc}{subsection}{Dynamic Indent Handling} \hypertarget{dynamic-indent}{} + \def\postLilyPondExample{\par\bigskip\hrule\par\bigskip} + \section*{Dynamic Indent} + This document demonstrates the use of \texttt{indent} and \texttt{autoindent}, partially in combination with \texttt{print-only}. + \texttt{indent=1cm} indents the first line, but if the resulting score contains only one system this indent is suppressed (issuing a warning on the console): + \begin{lilypond}[indent=1cm] \set Staff.instrumentName = "Violin" \repeat unfold 12 { c' d' e' d' } \end{lilypond} + \begin{lilypond}[indent=1cm] { \set Staff.instrumentName = "Violin" c' d' e' d' } \end{lilypond} + If the output of a score which contains more than one system is limited to the first system using \texttt{print-only=1} then the indent is removed but the score is recompiled to ensure a full-length system. The following score shows the two-system score from above (with \texttt{indent=1cm}), limited to its first system: + \begin{lilypond}[indent=1cm,print-only=1] \set Staff.instrumentName = "Violin" \repeat unfold 12 { c' d' e' d' } \end{lilypond} + Note that this behaviour also applies when \texttt{print-only} causes the first system to be printed at another position, e.g. with \texttt{print-only={3,1,2}}. In this case the indent of the first system is suppressed in order to avoid a “hole”. Of course this is a corner case, but might be useful when a score consists of separate entities (examples, exercises) per system. + \begin{lilypond}[indent=1cm,print-only={3,1,2},max-protrusion=0.5cm] \repeat unfold 25 { c' d' e' d' } \end{lilypond} + If a protrusion limit has been set with \texttt{max-protrusion=0.5cm} and the score exceeds that limit in spite of \texttt{indent=1cm} then the whole score will appropriately be narrowed: + \begin{lilypond}[indent=1cm,max-protrusion=0.5cm] \set Staff.instrumentName = "Violin I. and II." \repeat unfold 11 { c' d' e' d' } \end{lilypond} + + This doesn't really look good because the indentation of the second system wouldn't have been necessary since only the first system exceeds the protrusion limit. The solution to this situation is the option \texttt{autoindent} which handles the indentation \emph{automatically} and set the indent to a value that will make the \emph{first} system fit into the protrusion limit and leave the remaining systems unchanged: + \begin{lilypond}[autoindent=true,max-protrusion=0.5cm] \set Staff.instrumentName = "Violin I. and II." \repeat unfold 11 { c' d' e' d' } \end{lilypond} + + However, if the protrusion limit is not only exceeded by the \emph{first} system (which should be the typical case due to the instrument name) \texttt{lyluatex} will deal with the situation by narrowing the \emph{whole} score by the appropriate amount and adjusting the indent of the first system so all systems will just fit into the protrusion limit: + \begin{lilypond}[autoindent=true,max-protrusion=0.5cm] \set Staff.instrumentName = "Violin I. and II." \set Staff.shortInstrumentName = "Violin I/II" \repeat unfold 11 { c' d' e' d' } \end{lilypond} + There is one special case to be mentioned. As described above the indent is deactivated if the first system of a score is printed at a later position. However, if this score will exceed the left protrusion limit \texttt{autoindent} will be automatically activated to avoid having the \emph{whole} score narrowed: + \begin{lilypond}[indent=1cm,print-only={3,1,2},max-protrusion=0.5cm] \set Staff.instrumentName = "Violin" \repeat unfold 25 { c' d' e' d' } \end{lilypond} + \paragraph{Right protrusion} The dynamic handling of (automatic) indent also works correctly when there is protrusion handling to the right. The following score has the ties manually shaped to exceed the staff symbol by 10, and 7 staff spaces, and \texttt{max-protrusion=1cm} . + \begin{lilypond}[nofragment,max-protrusion=1cm,] { \set Staff.instrumentName = "Violin 1 & 2" @@ -2011,42 +2083,57 @@ shaped to exceed the staff symbol by 10, and 7 staff spaces, and c' } \end{lilypond} + + \paragraph{Performance considerations} The handling of indent suppression may require up to four compilations of the score, but these are handled automatically, and the resulting intermediate stages of the score are cached just like the scores actually used in the document. + The \texttt{autoindent} option is active by default but will be deactivated if \texttt{indent} is set explicitly. It has to be noted that this option will add more LilyPond compilations and therefore compilation time. But it will only apply and be executed if the score exceeds the protrusion limit, so it can only occur in circumstances where multiple LilyPond runs are expected anyway. + \let\postLilyPondExample\undefined + \addcontentsline{toc}{subsection}{Font Handling} \hypertarget{fonts}{} + \defaultfontfeatures{Ligatures=TeX,Numbers=OldStyle,Scale=MatchLowercase} \setmainfont{Linux Libertine O} \setsansfont[BoldFont={Linux Biolinum O Bold}]{Linux Biolinum O} \setmonofont{Inconsolata} + \section*{Font Handling} + To demonstrate the font handling features of \lyluatex\ we will repeatedly include the following score from an external file. It includes roman (lyrics, instrument name), sans (rehearsal mark), and mono (tempo) text, first using LilyPond's built-in default fonts. + \lilypondfile[verbatim]{fonts} + \bigskip The current document uses \option{fontspec} to set roman font to \emph{Linux Libertine O}, sans font to \emph{Linux Biolinum O}, and mono font to \emph{Inconsolata}. So if you compile this document yourself and don't have these fonts installed you will receive unexpected results. + \subsection*{Passing Document Fonts to Score} + With \option{pass-fonts} the currently active font families for roman, sans, and mono fonts are passed to LilyPond in order to achieve the most coherent appearance between text and music. + \bigskip + \lilypondfile[pass-fonts]{fonts} + \bigskip Note that LilyPond loads fonts differently than \LaTeX\ and can only make use of fonts installed as system fonts, fonts that are only installed through a \LaTeX\ @@ -2054,11 +2141,14 @@ distribution are not accessible to it. That means that if the document fonts are not installed system-wide (e.\,g. the default fonts) LilyPond will use rather ugly fallback fonts. This can't be demonstrated here but the section about explicitly setting font families will include an example. + The inherent problem of fallback fonts, especially with \LaTeX's default settings, is the reason \option{pass-fonts} is inactive by default. But the general recommendation is to set \option{pass-fonts} as package option if the text document uses fonts that are available to LilyPond. + \bigskip + \sffamily \option{current-font-as-main} will use the font that is \emph{currently} used for typesetting as LilyPond's main (roman) font. This can make sure that the score's main font (and roman is usually the font used most in @@ -2069,9 +2159,12 @@ is one of the two others. Additionally this \emph{may} introduce an inconsistency not between the score and the surrounding text but between different scores in a document. For all these reasons the option is by default set to \texttt{false}. + \bigskip \lilypondfile[pass-fonts,current-font-as-main]{fonts} + \subsection*{Setting Score Fonts Explicitly} + With \option{rmfamily}, \option{sffamily}, and \option{ttfamily} specific families can be set to arbitrary fonts, independently from the text document. For the following score \option{ttfamily=\{TeXGyre Adventor\}} is @@ -2079,24 +2172,31 @@ used.\footnote{Note that this font (which is included in TeXLive) has to be installed if you want to successfully compile this document.} Note that this implicitly sets \option{pass-fonts=true}, and \emph{Linux Libertine O} and \emph{Linux Biolinum O} are used from the text document. + \bigskip \lilypondfile[ttfamily={TeXGyre Adventor}]{fonts} + \highlight{NOTE:} when \option{rmfamily} is set explicitly \option{current-font-as-main} is forced to \texttt{false} to ensure that the roman font is actually used. The next score sets \option{rmfamily=\{TeXGyre Adventor\}} and \option{current-font-as-main}, and despite the current font still being \cmd{sffamily} \emph{Adventor} is used as the score's main font: + \bigskip \lilypondfile[current-font-as-main,rmfamily={TeXGyre Adventor}]{fonts} + \subsection*{LilyPond's Font Fallback} + If unavailable fonts are set in a LilyPond document they will \emph{silently} be replaced with fallback fonts that tend to cause ugly results. This will be shown by setting \option{rmfamily=FantasyFontOne}, \option{sffamily=FantasyFontTwo}, and \option{tfamily=FantasyFontThree}: + \bigskip \lilypondfile[rmfamily=FantasyFontOne,% sffamily=FantasyFontTwo,% ttfamily=FantasyFontThree]{fonts} + This can happen in several contexts: apart from compiling the document on a different computer where the used fonts are missing it is most likely to occur with the \option{pass-fonts} option, when the text document uses internal @@ -2104,6 +2204,7 @@ with the \option{pass-fonts} option, when the text document uses internal family is specified explicitly with an option and the other families are passed from the text document. + \defaultfontfeatures{Ligatures=TeX,Numbers=OldStyle,Scale=MatchLowercase} \setmainfont{Linux Libertine O} \setsansfont[BoldFont={Linux Biolinum O Bold}]{Linux Biolinum O} @@ -2111,18 +2212,29 @@ from the text document. \addcontentsline{toc}{subsection}{Wrapping Commands} \hypertarget{wrappingcommands}{} + \VerbatimFootnotes + \section*{Wrapping Commands} + \subsection*{Command within commands} + \cmd{lily} can be wrapped within another command as usual: + \begin{verbatim} \newcommand\mylily[2][1]{\lily[inline-staffsize=10, #1]{#2}} + This is \mylily[voffset=10pt]{a' b' c''} an example. \end{verbatim} + \newcommand\mylily[2][1]{\lily[inline-staffsize=10, #1]{#2}} + This is \mylily[voffset=10pt]{a' b' c''} an example.\par + \subsection*{Environment within environments} + \emph{It isn't possible to wrap \highlight{ly} environment within a command.}\par + It's possible to wrap \highlight{ly} within and environment, but there are several drawbacks\footnote{% Those drawbacks are: @@ -2140,8 +2252,10 @@ Those drawbacks are: \end{itemize} \end{itemize}% }. + To avoid those drawbacks, \lyluatex\ defines a special command, \verb`\lynewenvironment`, that behaves as you'd expect from \verb`\newenvironment`. + \begin{verbatim} \lynewenvironment{myly}{% This is \emph{my} lilypond environment. @@ -2149,19 +2263,23 @@ that behaves as you'd expect from \verb`\newenvironment`. }{% \end{ly} } + \begin{myly} a b c \end{myly} \end{verbatim} + \newenvironment{myly}{% This is \emph{my} lilypond environment. \begin{ly}% }{% \end{ly} } + \begin{myly} a b c \end{myly} + \begin{verbatim} \lynewenvironment{lyfigure}[2][]{% \edef\mycaption{#2} @@ -2174,11 +2292,13 @@ that behaves as you'd expect from \verb`\newenvironment`. \end{center} \end{figure} } + \begin{lyfigure}{This is a caption} a' b' c d' e' f \end{lyfigure} \end{verbatim} + \lynewenvironment{lyfigure}[2][]{% \edef\mycaption{#2} \begin{figure} @@ -2190,10 +2310,12 @@ d' e' f \end{center} \end{figure} } + \begin{lyfigure}{This is a caption} a' b' c d' e' f \end{lyfigure} + \begin{verbatim} \lynewenvironment{lyotherfigure}[1][]{% \edef\option{#1} @@ -2206,11 +2328,13 @@ d' e' f \endcenter \endfigure } + \begin{lyotherfigure} d' e' f a' b' c \end{lyotherfigure} \end{verbatim} + \lynewenvironment{lyotherfigure}[1][]{% \edef\option{#1} \figure @@ -2222,23 +2346,28 @@ a' b' c \endcenter \endfigure } + \begin{lyotherfigure} d' e' f a' b' c \end{lyotherfigure} + \begin{verbatim} \begin{lyotherfigure}[This time with a caption] d' e' f a' b' c \end{lyotherfigure} \end{verbatim} + \begin{lyotherfigure}[This time with a caption] d' e' f a' b' c \end{lyotherfigure} + \textbf{Important note:} \verb`\lynewenvironment` is intended to insert \LaTeX\ code before and after the scores; due to the special behavior of \verb`ly` environment, it isn't possible to insert \emph{LilyPond} code that way. So this won't work: + \begin{verbatim} \lynewenvironment{myly}{% \begin{ly} @@ -2247,26 +2376,33 @@ to insert \emph{LilyPond} code that way. So this won't work: \end{ly} } \end{verbatim} + To do such a thing, \lyluatex\ defines a command and four options: \begin{itemize} \item \verb`\lysavefrag` lets one save a LilyPond fragment to be re-used afterward; \item \verb`include_header`, \verb`include_footer`, \verb`include_before_body` and \verb`include_after_body` options let one insert such fragments at designed places within inserted score. \end{itemize} + So this works: + \begin{verbatim} \begin{lysavefrag}{head} a b c \end{lysavefrag} + \begin{lysavefrag}{foot} g a' b \end{lysavefrag} + \begin{lysavefrag}{mymark} \mark \default \end{lysavefrag} + \begin{lysavefrag}{mymark} \mark \default \end{lysavefrag} + begin{ly}[ include_before_body={head,mymark,head}, include_after_body=foot, @@ -2274,17 +2410,22 @@ begin{ly}[ d e f \end{ly} \end{verbatim} + It's also possible to use \verb`\lynewenvironment` to wrap such a command: + \begin{verbatim} \begin{lysavefrag}{head} a b c \end{lysavefrag} + \begin{lysavefrag}{foot} g a' b \end{lysavefrag} + \begin{lysavefrag}{mymark} \mark \default \end{lysavefrag} + \lynewenvironment{yourly}[1][]{% {\centering test \par} \begin{ly}[ @@ -2294,19 +2435,24 @@ g a' b }{ \end{ly} } + \begin{yourly} d e f \end{yourly} \end{verbatim} + \begin{lysavefrag}{head} a b c \end{lysavefrag} + \begin{lysavefrag}{foot} g a' b \end{lysavefrag} + \begin{lysavefrag}{mymark} \mark \default \end{lysavefrag} + \lynewenvironment{yourly}[1][]{% {\centering test \par} \begin{ly}[ @@ -2316,27 +2462,34 @@ g a' b }{ \end{ly} } + \begin{yourly} d e f \end{yourly} + \addcontentsline{toc}{subsection}{Wrapping Raw PDF Filenames} \hypertarget{insert-raw-pdf}{} + \section*{Wrapping Raw PDF Filenames} + With the \option{raw-pdf} option it is possible to create wrapping commands that circumvent \lyluatex's layout considerations by working with the raw PDF filename of the generated score. This is especially useful for developing packages or personal class and style files. For this scores generated with \option{raw-pdf} define a command \cmd{lyscore} that can be used in the wrapping commands or environments. + All examples in this document could also be realized using “default” \lyluatex\ without \option{raw-pdf}, but they are intended to show how this low-level access can be used to retrieve the information from the generated score in order to build custom versions of commands that don't have to adhere to \lyluatex's pre-built strategies of including the score in the document + The easiest way to use a “raw” score is to simply access \cmd{lyscore} in a command and pass it to an \cmd{includegraphics} macro: + \begin{verbatim} \newcommand\lilyinline[2][]{% \lily[raw-pdf,% @@ -2348,27 +2501,33 @@ command and pass it to an \cmd{includegraphics} macro: \includegraphics{\lyscore{}}% } \end{verbatim} + \newcommand\lilyinline[2][]{% \lily[raw-pdf,insert=bare-inline,inline-staffsize=8,hpadding=0.25ex,#1]{ \omit Stem #2}% \includegraphics{\lyscore{}}% } + This basically is a way to provide pre-configured commands. In this case \lilyinline{ c'8 d' c' d'} it is used to pre-configure an inline type, entered as \verb+\lilyinline{ c'8 d' c' d'}+. + + \bigskip \cmd{lyscore} takes one mandatory argument which can be empty -- as in the example above --, receive a number, one of the keywords \texttt{nsystems} and \texttt{hoffset}, or any of the score's options. If passed a number it will return the filename of the N-th system. With \texttt{nsystems} the number of systems in the generated score will be returned, while \texttt{hoffset} generates the code that shifts the score to the left to accommodate protrusion. + The following example takes an optional argument with options that are passed to \lyluatex, and one mandatory argument which expects the system to be used. It prints the given system centered in a figure and uses the file name as the caption and makes use of the score's \texttt{label}. Figure \ref{centered} shows the centering of a short fragment, figure \ref{fifth} the selection of the fifth system from a larger score. + \begin{verbatim} \newenvironment{centeredlilypondsystem}[2][]{% \def\usesystem{#2} @@ -2383,13 +2542,16 @@ system from a larger score. \end{center} \end{figure} } + \begin{centeredlilypondsystem}[label=centered]{1} c'1 d' e' \end{centeredlilypondsystem} + \begin{centeredlilypondsystem}[label=fifth]{5} \repeat unfold 8 { c'1 \break } \end{centeredlilypondsystem} \end{verbatim} + \newenvironment{centeredlilypondsystem}[2][]{% \def\usesystem{#2} \begin{figure} @@ -2403,17 +2565,22 @@ system from a larger score. \end{center} \end{figure} } + \begin{centeredlilypondsystem}[label=centered]{1} c'1 d' e' \end{centeredlilypondsystem} + \begin{centeredlilypondsystem}[label=fifth]{5} \repeat unfold 8 { c'1 \break } \end{centeredlilypondsystem} + + Finally there's an example showing how to iterate over the systems of a score using \cmd{foreach} from the \option{pgffor} package. It iterates over all the systems in the given score, prints them using the protrusion adjustment seen before, and if the system is the third it prints this information, otherwise just a line break: + \begin{verbatim} \newcommand\myforlily[2][]{% \lily[insert=systems,raw-pdf,#1]{#2}% @@ -2422,10 +2589,12 @@ just a line break: \ifthenelse{\equal{\n}{3}}{\par Third system\par}{\\} }% } + \myforlily[staffsize=24]{ \set Staff.instrumentName = "Vl. " \repeat unfold 4 { c'1 \break } } \end{verbatim} + \newcommand\myforlily[2][]{% \lily[insert=systems,raw-pdf,#1]{#2}% \foreach \n in {1,...,\lyscore{nsystems}}% @@ -2433,9 +2602,11 @@ just a line break: \ifthenelse{\equal{\n}{3}}{\par\bigskip Third system\par\bigskip}{\\} }% } + \myforlily[staffsize=24]{ \set Staff.instrumentName = "Vl. " \repeat unfold 4 { c'1 \break } } + \end{document} -- cgit v1.2.3