lyx_mirror/lib/examples/lilypond.lyx

#LyX 2.1 created this file. For more info see http://www.lyx.org/
\lyxformat 459
\begin_document
\begin_header
\textclass article
\use_default_options true
\begin_modules
lilypond
\end_modules
\maintain_unincluded_children false
\language english
\language_package default
\inputencoding auto
\fontencoding global
\font_roman lmodern
\font_sans lmss
\font_typewriter lmtt
\font_math auto
\font_default_family default
\use_non_tex_fonts false
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100
\graphics default
\default_output_format default
\output_sync 0
\bibtex_command default
\index_command default
\paperfontsize default
\spacing single
\use_hyperref true
\pdf_title "LilyPond-book and LyX"
\pdf_author "The LyX Team"
\pdf_bookmarks true
\pdf_bookmarksnumbered true
\pdf_bookmarksopen true
\pdf_bookmarksopenlevel 1
\pdf_breaklinks false
\pdf_pdfborder false
\pdf_colorlinks true
\pdf_backref false
\pdf_pdfusetitle false
\pdf_quoted_options "linkcolor=blue,urlcolor=blue,pdfstartview=XYZ"
\papersize default
\use_geometry true
\use_package amsmath 1
\use_package amssymb 1
\use_package esint 1
\use_package mathdots 1
\use_package mathtools 0
\use_package mhchem 1
\use_package stackrel 0
\use_package stmaryrd 0
\use_package undertilde 0
\cite_engine basic
\cite_engine_type numerical
\biblio_style plain
\use_bibtopic false
\use_indices false
\paperorientation portrait
\suppress_date true
\justification true
\use_refstyle 0
\index Index
\shortcut idx
\color #008000
\end_index
\leftmargin 2cm
\topmargin 2cm
\rightmargin 2cm
\bottommargin 2cm
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\paragraph_indentation default
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\tracking_changes false
\output_changes false
\html_math_output 0
\html_css_as_file 0
\html_be_strict true
\end_header

\begin_body

\begin_layout Title
LilyPond-book and LyX
\end_layout

\begin_layout Author
The LyX Team
\end_layout

\begin_layout Date
Version 2.1.x
\end_layout

\begin_layout Abstract
This document explains and demonstrates the inclusion of musical snippets
 in a LyX document, using the LilyPond syntax for music notation and the
 LilyPond-book utility for processing.
\end_layout

\begin_layout Section
Introduction
\end_layout

\begin_layout Standard
LilyPond is an open-source project that renders possible the creation of
 beautiful computer-generated musical scores.
 The project consists of a text-based music notation language, and a program
 to process this notation into musical scores.
\end_layout

\begin_layout Standard
While LilyPond itself supports the display of title, author information,
 footnotes, endnotes, etc., its primary focus is on music typesetting.
 For text typesetting, other programs are generally better suited.
 LilyPond-book is an utility provided by the LilyPond project that helps
 incorporate musical scores using the LilyPond notation into LaTeX documents,
 among other formats.
\end_layout

\begin_layout Standard
This document describes the use of the LilyPond music notation within LyX
 documents that use a LaTeX-based layout, thus combining the beauty and
 quality of the typesetting achieved by both LaTeX and LilyPond.
 While a basic understanding of the LilyPond syntax for music notation is
 in order, knowledge of LaTeX is not necessary when using LyX.
\end_layout

\begin_layout Standard
Section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sec:Using-LilyPond-code"

\end_inset

 explains the requirements, usage instructions, and shortcomings of LilyPond
 music notation within LyX.
 Section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sec:LilyPond-examples"

\end_inset

 demonstrates the beauty and quality of the typesetting with a few examples.
\end_layout

\begin_layout Section
Using LilyPond code within LyX
\begin_inset CommandInset label
LatexCommand label
name "sec:Using-LilyPond-code"

\end_inset


\end_layout

\begin_layout Standard
Support for LilyPond music notation (LilyPond code) within LyX is enabled
 by adding the LilyPond module to your document.
 This is done from the menu 
\family sans
Document\SpecialChar \menuseparator
Settings
\family default
, then selecting LilyPond in the list of modules.
 You can use any LaTeX-based LyX layout and use the regular preview and
 export mechanism; LyX will take care of processing the mixed LaTeX/LilyPond
 code through LilyPond-book for you.
 LilyPond-book can also handle DocBook and HTML documents, but the integration
 of these document types with LilyPond-book and LyX is missing at the moment.
\end_layout

\begin_layout Subsection
Requirements
\end_layout

\begin_layout Standard
LilyPond-book version 2.13 or newer.
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
LilyPond-book supports LaTeX output since version 2.1.
 However, some features used by LyX are available only in recent versions:
 PDFLaTeX support (version 2.9), the 
\family typewriter
--lily-output-dir
\family default
 flag (version 2.11) and especially the 
\family typewriter
--safe
\family default
 flag (version 2.13).
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Integration
\end_layout

\begin_layout Standard
The module provides a LilyPond inset which you insert from the menu 
\family sans
Insert\SpecialChar \menuseparator
Custom
\begin_inset space ~
\end_inset

Insets
\family default
.
 This inset is for typing the LilyPond code which will be typeset into your
 musical notes.
 First, let us try a simple scale:
\end_layout

\begin_layout Standard
\begin_inset Flex LilyPond
status open

\begin_layout Plain Layout

\begin_inset Argument 1
status open

\begin_layout Plain Layout
staffsize=28
\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout


\backslash
relative c'' {
\end_layout

\begin_layout Plain Layout

  g a b c
\end_layout

\begin_layout Plain Layout

}
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\noindent
The previous LyX inset produces the following LaTeX-lookalike code:
\end_layout

\begin_layout LyX-Code

\backslash
begin{lilypond}[staffsize=28]
\end_layout

\begin_layout LyX-Code

\end_layout

\begin_layout LyX-Code

\backslash
relative c'' {
\end_layout

\begin_layout LyX-Code
  g a b c
\end_layout

\begin_layout LyX-Code
}
\end_layout

\begin_layout LyX-Code

\backslash
end{lilypond}
\end_layout

\begin_layout Standard
What appear first inside square brackets are options to pass to LilyPond-book.
 This is inserted in LyX from the 
\family sans
Insert
\family default
 menu, in the same way that the LilyPond inset itself is inserted.
 Here, we set the dimension of the staff to 28
\begin_inset space \thinspace{}
\end_inset

pt.
 Other options can be added by separating them by a comma, for example:
 
\family typewriter
[staffsize=28,verbatim]
\family default
.
 A list of music fragment options is available in the LilyPond documentation.
 This whole block can be omitted when the default settings are desired.
\end_layout

\begin_layout Standard
What follows after the options block is the textual representation in LilyPond
 syntax of a musical fragment.
 This code is not, in fact, processed by LaTeX, but is preprocessed by LilyPond-
book, which creates the graphics files and includes them in the LaTeX document
 by replacing the above with a 
\family typewriter

\backslash
includegraphics{\SpecialChar \ldots{}
}
\family default
 command.
\end_layout

\begin_layout Standard
Thus, the conversion process is as follow: 
\family sans
LyX\SpecialChar \menuseparator
LilyPond-book\SpecialChar \menuseparator
LaTeX
\family default
.
 LyX creates a .lytex file, LilyPond-book creates a .tex files and the accompanyin
g image files, and LaTeX creates the final document.
 Every step of the tool chain obeys your spacing, so whether you put the
 musical extract inline, or in its own paragraph, centered, left-aligned,
 etc., what you see in the LyX window should be respected in the final format.
 An example of inline use may be to display a chord name, such as
\begin_inset Flex LilyPond
status open

\begin_layout Plain Layout

\begin_inset Argument 1
status open

\begin_layout Plain Layout

staffsize=12
\end_layout

\end_inset

 
\backslash
markup { 
\backslash
concat {B 
\backslash
super 
\backslash
flat } }
\end_layout

\end_inset

, or perhaps a very short snippet.
\end_layout

\begin_layout Subsection
Previews
\end_layout

\begin_layout Standard
It is possible to have a direct feedback of what the music notation looks
 like from within LyX.
 To do this, wrap a LilyPond inset inside a Preview inset, which you find
 from the menu 
\family sans
Insert\SpecialChar \menuseparator
Preview
\family default
.
 This only affects the display within LyX, not the output:
\end_layout

\begin_layout Standard
\begin_inset Preview

\begin_layout Standard
\begin_inset Flex LilyPond
status collapsed

\begin_layout Plain Layout


\backslash
relative c'' {
\end_layout

\begin_layout Plain Layout

  ais a g ges
\end_layout

\begin_layout Plain Layout

}
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
Unfortunately, you might find that the preview isn't exactly instantaneous.
 You need to move the cursor out of the Preview inset to start compilation,
 and processing time can take a few seconds.
 Nevertheless, the direct feedback is often worthwhile during editing, and
 renders the navigation through the document much easier.
\end_layout

\begin_layout Subsection
Gotchas
\end_layout

\begin_layout Standard
A few gotchas that have been experienced with the integration of LilyPond-book
 and LyX are reported here.
\end_layout

\begin_layout Subsubsection
Child documents
\end_layout

\begin_layout Standard
A LyX document using the LilyPond module cannot have child documents using
 the 
\begin_inset Quotes eld
\end_inset

Input
\begin_inset Quotes erd
\end_inset

 method.
 If you select 
\begin_inset Quotes eld
\end_inset

Input
\begin_inset Quotes erd
\end_inset

 as the 
\begin_inset Quotes eld
\end_inset

Include Type
\begin_inset Quotes erd
\end_inset

 under 
\family sans
Insert\SpecialChar \menuseparator
File\SpecialChar \menuseparator
Child
\begin_inset space ~
\end_inset

Document
\family default
, you will get an error when producing output.
 This is due to the way LilyPond-book automatically processes these input
 files recursively.
 Since there is currently no command-line option to turn off this behavior
 of LilyPond-book, it is suggested to use the 
\begin_inset Quotes eld
\end_inset

Include
\begin_inset Quotes erd
\end_inset

 method instead.
\end_layout

\begin_layout Standard
Note that it is possible to insert child documents which make use of the
 LilyPond module, using either the 
\begin_inset Quotes eld
\end_inset

Input
\begin_inset Quotes erd
\end_inset

 or 
\begin_inset Quotes eld
\end_inset

Include
\begin_inset Quotes erd
\end_inset

 method, in a master document which does not make use of the LilyPond module.
 For this to work you might have to add the line
\end_layout

\begin_layout LyX-Code

\backslash
usepackage{graphicx}
\end_layout

\begin_layout Standard
to your master document's preamble under 
\family sans
Document\SpecialChar \menuseparator
Settings
\family default
.
\end_layout

\begin_layout Subsubsection
Surrounding braces
\end_layout

\begin_layout Standard
LilyPond-book searches for a 
\family typewriter

\backslash
score
\family default
 or 
\family typewriter

\backslash
relative
\family default
 command when it decides if the code is only a fragment.
 It is possible to include no LilyPond command at all, but in that case
 {surrounding braces} are required.
 Thus, in the following code,
\end_layout

\begin_layout LyX-Code

\backslash
begin{lilypond}
\end_layout

\begin_layout LyX-Code
  ais' f'' g' e'' % no 
\backslash
score given
\end_layout

\begin_layout LyX-Code

\backslash
end{lilypond}
\end_layout

\begin_layout Standard
LilyPond-book gets confused:
\end_layout

\begin_layout LyX-Code
error: syntax error, unexpected NOTENAME_PITCH
\end_layout

\begin_layout LyX-Code
ais' f'' g' e'' % no 
\backslash
score given
\end_layout

\begin_layout Standard
With surrounding braces, all is well:
\end_layout

\begin_layout Standard
\begin_inset Preview

\begin_layout Standard
\begin_inset Flex LilyPond
status collapsed

\begin_layout Plain Layout

{ais' f'' g' e''} % no 
\backslash
score given
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
Writing the notes directly within braces without using any LilyPond command
 is convenient when writing short snippets.
 Advanced users will probably want to enter their musical content using
 LilyPond variables and commands, which is of course supported.
\end_layout

\begin_layout Subsubsection
Fret diagrams
\end_layout

\begin_layout Standard
Another gotcha is with subsequent LilyPond snippets with 
\family typewriter

\backslash
fret-diagram
\family default
 markup commands:
\end_layout

\begin_layout LyX-Code

\backslash
begin{lilypond}
\end_layout

\begin_layout LyX-Code
  
\backslash
markup{ 
\backslash
fret-diagram-terse #"x;3;2;o;1;o;" }
\end_layout

\begin_layout LyX-Code

\backslash
end{lilypond}
\end_layout

\begin_layout LyX-Code

\end_layout

\begin_layout LyX-Code

\backslash
begin{lilypond}
\end_layout

\begin_layout LyX-Code
  
\backslash
markup{ 
\backslash
fret-diagram-terse #"x;x;o;2;3;2;" }
\end_layout

\begin_layout LyX-Code

\backslash
end{lilypond}
\end_layout

\begin_layout Standard
For some reason LilyPond-book version 2.13 barks on this when run in safe
 mode (which you always should use, unless you know what you are doing).
 This has been corrected as of version 2.15 (was LilyPond issue #1900).
\end_layout

\begin_layout Subsubsection
The 
\family typewriter

\backslash
lilypondfile
\family default
 command
\end_layout

\begin_layout Standard
LilyPond-book supports including LilyPond code that resides in external
 files with the 
\family typewriter

\backslash
lilypondfile
\family default
 command.
 With this command, the LilyPond code is processed as if it was typed inside
 the document and the output score follows the typesetting determined by
 LaTeX with respect to line width, page breaks, and so on.
 This is in contrast to the long-standing LyX feature to include LilyPond
 scores as external material, which calls LilyPond on the external file
 to produce a rigid figure, and includes this figure in the document, leaving
 the typesetting decisions to LilyPond.
 Unfortunately, support for the 
\family typewriter

\backslash
lilypondfile
\family default
 command in LyX is not implemented yet, but it is possible to use it inside
 a TeX-Code block, provided that one writes the complete, absolute path
 to the desired file.
\end_layout

\begin_layout Section
LilyPond examples
\begin_inset CommandInset label
LatexCommand label
name "sec:LilyPond-examples"

\end_inset


\end_layout

\begin_layout Standard
Example 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:Editorial-headword"

\end_inset

 shows a complex score using many LilyPond constructs; some scheme code
 has been removed from the original source of this snippet, to be able to
 run in safe mode.
 Example 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:Tablatures-template"

\end_inset

 shows another LilyPond output which should be interesting to guitarists.
\end_layout

\begin_layout Subsection
Editorial headword
\begin_inset CommandInset label
LatexCommand label
name "sub:Editorial-headword"

\end_inset


\end_layout

\begin_layout Standard
NR 1.7 Editorial annotations Beethoven, Op.
 31, No.
 3 Piano sonata 18, Movt II, Scherzo Measures 9--14.
\end_layout

\begin_layout Standard
\noindent
\align center
\begin_inset Preview

\begin_layout Standard
\begin_inset Flex LilyPond
status collapsed

\begin_layout Plain Layout


\backslash
new PianoStaff <<
\end_layout

\begin_layout Plain Layout

  
\end_layout

\begin_layout Plain Layout

  % RH Staff
\end_layout

\begin_layout Plain Layout

  
\backslash
new Staff {
\end_layout

\begin_layout Plain Layout

    
\backslash
clef treble
\end_layout

\begin_layout Plain Layout

    
\backslash
key aes 
\backslash
major
\end_layout

\begin_layout Plain Layout

    
\backslash
time 2/4
\end_layout

\begin_layout Plain Layout

    %
\backslash
set Staff.fingeringOrientations = #'(up)
\end_layout

\begin_layout Plain Layout

    %
\backslash
set Score.currentBarNumber = #9
\end_layout

\begin_layout Plain Layout

    
\backslash
partial 8
\end_layout

\begin_layout Plain Layout

    <aes''-4 c''>8
\backslash
staccato
\end_layout

\begin_layout Plain Layout

    |
\end_layout

\begin_layout Plain Layout

    %
\backslash
set doubleSlurs = ##t
\end_layout

\begin_layout Plain Layout

    <bes''-5 des''-2>4(
\end_layout

\begin_layout Plain Layout

    <aes''-4 c''>8
\backslash
staccato)
\end_layout

\begin_layout Plain Layout

    
\backslash
noBeam
\end_layout

\begin_layout Plain Layout

    c''8-5
\backslash
staccato
\backslash
pp
\end_layout

\begin_layout Plain Layout

    |
\end_layout

\begin_layout Plain Layout

    
\backslash
unset doubleSlurs
\end_layout

\begin_layout Plain Layout

    bes'8..(
\end_layout

\begin_layout Plain Layout

    aes'32
\end_layout

\begin_layout Plain Layout

    g'8)
\backslash
staccato
\end_layout

\begin_layout Plain Layout

    f'8
\backslash
staccato
\end_layout

\begin_layout Plain Layout

    |
\end_layout

\begin_layout Plain Layout

    e'4-2
\end_layout

\begin_layout Plain Layout

    r8
\end_layout

\begin_layout Plain Layout

    %
\backslash
once 
\backslash
override Script #'script-priority = #-100
\end_layout

\begin_layout Plain Layout

    
\backslash
afterGrace
\end_layout

\begin_layout Plain Layout

    f'8(
\backslash
trill^
\backslash
markup { 
\backslash
finger "3-2" }
\end_layout

\begin_layout Plain Layout

    { e'16[ f'16] }
\end_layout

\begin_layout Plain Layout

    |
\end_layout

\begin_layout Plain Layout

    g'8..-3
\end_layout

\begin_layout Plain Layout

    f'32
\end_layout

\begin_layout Plain Layout

    e'8-1)
\backslash
staccato
\end_layout

\begin_layout Plain Layout

    d'8-2
\backslash
staccato
\end_layout

\begin_layout Plain Layout

    |
\end_layout

\begin_layout Plain Layout

    c'4
\end_layout

\begin_layout Plain Layout

    r4
\end_layout

\begin_layout Plain Layout

  }
\end_layout

\begin_layout Plain Layout

  
\end_layout

\begin_layout Plain Layout

  % LH Staff
\end_layout

\begin_layout Plain Layout

  
\backslash
new Staff {
\end_layout

\begin_layout Plain Layout

    
\backslash
key aes 
\backslash
major
\end_layout

\begin_layout Plain Layout

    
\backslash
clef treble
\end_layout

\begin_layout Plain Layout

    %
\backslash
override Fingering #'direction = #down
\end_layout

\begin_layout Plain Layout

    %
\backslash
set Staff.fingeringOrientations = #'(down)
\end_layout

\begin_layout Plain Layout

    
\backslash
partial 8
\end_layout

\begin_layout Plain Layout

    <aes' aes>8
\backslash
staccato
\end_layout

\begin_layout Plain Layout

    %
\backslash
set doubleSlurs = ##t
\end_layout

\begin_layout Plain Layout

    <g'-2 ees'-3>4(
\end_layout

\begin_layout Plain Layout

    <aes' aes>8)
\backslash
staccato
\end_layout

\begin_layout Plain Layout

    
\backslash
noBeam
\end_layout

\begin_layout Plain Layout

    
\backslash
clef bass
\end_layout

\begin_layout Plain Layout

    c'8-1
\backslash
staccato
\end_layout

\begin_layout Plain Layout

    |
\end_layout

\begin_layout Plain Layout

    %
\backslash
set doubleSlurs = ##f
\end_layout

\begin_layout Plain Layout

    bes8..(
\end_layout

\begin_layout Plain Layout

    aes32
\end_layout

\begin_layout Plain Layout

    g8-1)
\backslash
staccato
\end_layout

\begin_layout Plain Layout

    f8
\backslash
staccato
\end_layout

\begin_layout Plain Layout

    |
\end_layout

\begin_layout Plain Layout

    e4
\end_layout

\begin_layout Plain Layout

    r8
\end_layout

\begin_layout Plain Layout

    
\backslash
afterGrace
\end_layout

\begin_layout Plain Layout

    f8(
\backslash
trill_
\backslash
markup { 
\backslash
finger "2-1" }
\end_layout

\begin_layout Plain Layout

    { e16[ f16] }
\end_layout

\begin_layout Plain Layout

    |
\end_layout

\begin_layout Plain Layout

    g8..-1
\end_layout

\begin_layout Plain Layout

    f32
\end_layout

\begin_layout Plain Layout

    e8)
\backslash
staccato
\end_layout

\begin_layout Plain Layout

    d8
\backslash
staccato
\end_layout

\begin_layout Plain Layout

    |
\end_layout

\begin_layout Plain Layout

    c4
\end_layout

\begin_layout Plain Layout

    r4
\end_layout

\begin_layout Plain Layout

  }
\end_layout

\begin_layout Plain Layout

>>
\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
\noindent
[from 
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

http://lsr.dsi.unimi.it/LSR/Item?id=627
\end_layout

\end_inset

; scheme code removed, centering applied through the paragraph settings]
\end_layout

\begin_layout Subsection
Tablatures template
\begin_inset CommandInset label
LatexCommand label
name "sub:Tablatures-template"

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Preview

\begin_layout Standard
\begin_inset Flex LilyPond
status collapsed

\begin_layout Plain Layout

upper=  
\backslash
relative c' {
\end_layout

\begin_layout Plain Layout

  c4.
  g4  g  c
\end_layout

\begin_layout Plain Layout

}
\end_layout

\begin_layout Plain Layout

lower=  
\backslash
relative c {
\end_layout

\begin_layout Plain Layout

  c4  e  g,  e'
\end_layout

\begin_layout Plain Layout

}
\end_layout

\begin_layout Plain Layout


\backslash
score {
\end_layout

\begin_layout Plain Layout

  
\backslash
new StaffGroup <<
\end_layout

\begin_layout Plain Layout

    
\backslash
new Staff = "guitar" <<
\end_layout

\begin_layout Plain Layout

      
\backslash
context Voice = "upper guitar" { 
\backslash
clef "G_8" 
\backslash
voiceOne  
\backslash
upper }
\end_layout

\begin_layout Plain Layout

      
\backslash
context Voice = "lower guitar" { 
\backslash
clef "G_8" 
\backslash
voiceTwo  
\backslash
lower }
\end_layout

\begin_layout Plain Layout

    >>
\end_layout

\begin_layout Plain Layout

    
\backslash
new TabStaff = "tab" <<
\end_layout

\begin_layout Plain Layout

      
\backslash
context TabVoice = "upper tab" { 
\backslash
clef "tab" 
\backslash
voiceOne 
\backslash
upper }
\end_layout

\begin_layout Plain Layout

      
\backslash
context TabVoice = "lower tab" { 
\backslash
clef "tab" 
\backslash
voiceTwo 
\backslash
lower }
\end_layout

\begin_layout Plain Layout

    >>
\end_layout

\begin_layout Plain Layout

  >>
\end_layout

\begin_layout Plain Layout

}
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
\noindent
[from 
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

http://lsr.dsi.unimi.it/LSR/Item?id=634
\end_layout

\end_inset

]
\end_layout

\end_body
\end_document