+@node Integrating text and music
+@section Integrating text and music
+
+Sometimes, you might want to use music examples in a text that you are
+writing. For example, if you are writing a musicological treatise, a
+songbook, or (like us) the LilyPond manual. You can make such texts by
+hand, simply by importing a PostScript figure into your wordprocessor.
+However, there is a also an automated procedure:
+
+If you use La@TeX{} or texinfo, you can mix text and lilypond code. A
+script called @code{lilypond-book} will extract the music fragments, run
+lilypond on them, and put back the resulting notation. lilypond-book is
+described fully in @ref{lilypond-book}, but here we show a small
+example. Since the example also contains explanatory text, we won't
+comment on the contents.
+
+@example
+\documentclass[a4paper]@{article@}
+\begin@{document@}
+
+In a lilypond-book document, you can freely mix music and text. For
+example:
+\begin@{lilypond@}
+ \score @{ \notes \relative c' @{
+ c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
+ @} @}
+\end@{lilypond@}
+Notice that the music line length matches the margin settings of the
+document.
+
+If you have no \verb+\score+ block in the fragment,
+\texttt@{lilypond-book@} will supply one:
+
+\begin@{lilypond@}
+ c'4
+\end@{lilypond@}
+
+In the example you see here, a number of things happened: a
+\verb+\score+ block was added, and the line width was set to natural
+length. You can specify many more options using \LaTeX style options
+in brackets:
+
+\begin[verbatim,11pt,singleline,
+ fragment,relative,intertext="hi there!"]@{lilypond@}
+ c'4 f bes es
+\end@{lilypond@}
+
+\texttt@{verbatim@} also shows the lilypond code, \texttt@{11pt@} selects
+the default music size, \texttt@{fragment@} adds a score block,
+\texttt@{relative@} uses relative mode for the fragment, and
+\texttt@{intertext@} specifies what to print between the
+\texttt@{verbatim@} code and the music.
+
+If you include large examples into the text, it may be more convenient
+to put the example in a separate file:
+
+\lilypondfile[printfilename]@{sammartini.ly@}
+
+The \texttt@{printfilename@} option adds the file name to the output.
+
+\end@{document@}
+@end example
+
+Under Unix, you can view the results as follows.
+@example
+$ cd input/tutorial
+$ lilypond-book --outdir=out/ lilbook.tex
+lilypond-book (GNU LilyPond) 1.3.146
+Reading `/home/hanwen/usr/src/lilypond-1.3.146/input/tutorial/lilbook.tex'
+Reading
+`/home/hanwen/usr/src/lilypond-1.3.146/input/tutorial/sammartini.ly'
+@var{lots of stuff deleted}
+Writing `out/lilbook.latex'
+$ cd out
+$ latex lilbook.latex
+@var{lots of stuff deleted}
+$ xdvi lilbook
+@end example
+
+Notice the @code{outdir} option to lilypond-book. Running lilypond-book
+and running latex creates a lot of temporary files, and you wouldn't
+those to clutter up your working directory. Hence, we have them created
+in a separate subdirectory.
+
+The result more or less looks like this:
+
+@separate
+
+In a lilypond-book document, you can freely mix music and text. For
+example:
+@lilypond
+ \score { \notes \relative c' {
+ c2 g'2 \times 2/3 { f8 e d } c'2 g4
+ } }
+@end lilypond
+Notice that the music line length matches the margin settings of the
+document.
+
+If you have no @code{\score} block in the fragment,
+@code{lilypond-book} will supply one:
+
+@lilypond
+ c'4
+@end lilypond
+
+In the example you see here, a number of things happened: a
+@code{\score} block was added, and the line width was set to natural
+length. You can specify many more options using La@TeX{} style options
+in brackets:
+
+@lilypond[verbatim,11pt,singleline,
+ fragment,relative,intertext="hi there!"]
+ c'4 f bes es
+@end lilypond
+
+@code{verbatim} also shows the lilypond code, @code{11pt} selects
+the default music size, @code{fragment} adds a score block,
+@code{relative} uses relative mode for the fragment, and
+@code{intertext} specifies what to print between the
+@code{verbatim} code and the music.
+
+If you include large examples into the text, it may be more convenient
+to put the example in a separate file:
+
+@lilypondfile[printfilename]{sammartini.ly}
+
+The @code{printfilename} option adds the file name to the output.
+@node end of tutorial
+@section The end
+
+That's all folks. From here, you can either try fiddling with input
+files, or you can read the reference manual. You can find more example
+files in @file{input} and @file{input/test}. You can also look at some
+real music. Have a look at the @uref{Mutopia project,
+http://www.mutopiaproject.org}.
+
+
+
+@ignore
+
+[TODO
+
+this should be on mutopia website.
+
+]
+
+
+@c waar deze info? is uiteindelijk wel handig, schat ik.
+[TODO: cut blabla]
+
+If you have a big music project, or just a lot of LilyPond input files,
+all generated output from LilyPond, @TeX{} and metafont will clutter
+your working directory. LilyPond comes with a one-size-fits-all
+pre-cooked makefile that helps you manage producing output. It will
+produce all output in the directory @file{out} , generate and track
+dependencies. Also, it helps in preparing your submission to @ref{Mutopia
+project}.
+
+@file{make/ly.make}
+@example
+mkdir my-project
+cd my-project
+cp /usr/share/lilypond/make/ly.make GNUmakefile
+cp /usr/share/doc/lilypond/examples/input/tutorial/menuet.ly .
+make menuet
+[..]
+Generated out/menuet.ps for target menuet.
+@end example
+
+Type @samp{make help} to see possible targets.
+
+[TODO]
+@file{/usr/share/lilypond/doc/lilypond/examples/input/mutopia-header.ly}
+
+
+
projects / lilypond.git / blobdiff