summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/lyluatex/lyluatex.tex
blob: d3617d0cfe526f1aaa17906995bc572c4f403795 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
\documentclass[]{article}
\usepackage{lmodern}
\usepackage{amssymb,amsmath}
\usepackage{ifxetex,ifluatex}
\usepackage{fixltx2e} % provides \textsubscript
\ifnum 0\ifxetex 1\fi\ifluatex 1\fi=0 % if pdftex
  \usepackage[T1]{fontenc}
  \usepackage[utf8]{inputenc}
\else % if luatex or xelatex
  \ifxetex
    \usepackage{mathspec}
  \else
    \usepackage{fontspec}
  \fi
  \defaultfontfeatures{Ligatures=TeX,Scale=MatchLowercase}
\fi
% 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
}{}
\PassOptionsToPackage{hyphens}{url} % url is loaded by hyperref
\usepackage[unicode=true]{hyperref}
\hypersetup{
            pdfborder={0 0 0},
            breaklinks=true}
\urlstyle{same}  % don't use monospace font for urls
\IfFileExists{parskip.sty}{%
\usepackage{parskip}
}{% else
\setlength{\parindent}{0pt}
\setlength{\parskip}{6pt plus 2pt minus 1pt}
}
\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{}}
\fi

% set default figure placement to htbp
\makeatletter
\def\fps@figure{htbp}
\makeatother


\date{}

\begin{document}

\section{Lyluatex}\label{lyluatex}

\subsection{Usage}\label{usage}

In the preable of your document, include the package \texttt{lyluatex}:

\begin{verbatim}
\usepackage{lyluatex}
\end{verbatim}

The \texttt{program} option permits the definition of an alternative
path to \texttt{lilypond}, for example:

\begin{verbatim}
\usepackage[program=/opt/lilypond-dev/lilypond]{lyluatex}
\end{verbatim}

Thereafter, you can include a lilypond file with the command:

\begin{verbatim}
\includely[staffsize=17]{PATH/TO/THE/FILE}
\end{verbatim}

The argument \texttt{staffsize}, which is optional, changes the size of
the score. You can change the size for all the subsequent scores in a
document by placing the following command before your first include
statement to be so affected:

\begin{verbatim}
\def\staffsize{24}
\end{verbatim}

Next, you simply need to compile the document normally with the command
\texttt{lualatex\ -shell-escape}~:

\begin{verbatim}
lualatex -shell-escape DOCUMENT.TEX
\end{verbatim}

Another ``more secure'' option is to add \texttt{lilypond} to default
allowed commands~:

\begin{verbatim}
shell_escape_commands=$(kpsewhich -expand-var '$shell_escape_commands'),lilypond lualatex DOCUMENT.TEX
\end{verbatim}

On systems with low RAM, when working on big documents, you could
encounter \emph{buffer overflows} in \texttt{lilypond} calls. In that
case, first compile with option \texttt{-draftmode}, then compile again
without this option.

You can also input music directly into your docoment with the
\texttt{ly} environment. This is only recommended for relatively short
snippets. For example:

\begin{verbatim}
\begin{ly}
\relative c' { c d e f g a b c }
\end{ly}
\end{verbatim}

Finally, for truly short snippets, there is also the
\texttt{\textbackslash{}lily} command. Example:

\begin{verbatim}
\lily[staffsize=12]{c' d' g'}
\end{verbatim}

\textbf{Nota bene:} The \texttt{\textbackslash{}lily} command \emph{does
not} support blocks of LilyPond code with explicit
\texttt{\textbackslash{}score} blocks. Such code must be included with
the \texttt{ly} environment or as a separate file.

\subsection{\texorpdfstring{Migration from
\texttt{lilypond-book}}{Migration from lilypond-book}}\label{migration-from-lilypond-book}

In order to facilitate the migration from \texttt{lilypond-book},
\texttt{lyluatex} defines the command
\texttt{\textbackslash{}lilypondfile} with the same arguments as
\texttt{\textbackslash{}includely}. There is also the environment
\texttt{lilypond} which is the same as \texttt{ly}, and the command
\texttt{\textbackslash{}lilypond} should work as with
\texttt{lilypond-book}.

In this manner, documents typeset with \texttt{lilypond-book} can be
adapted to use \texttt{lyluatex} without much difficulty. Just keep in
mind that apart from the \texttt{staffsize} parameter, the optional
parameters that \texttt{lilypond-book} supports are not supported by
\texttt{lyluatex} (at least for now).

\end{document}