X-Git-Url: https://git.lyx.org/gitweb/?a=blobdiff_plain;f=lib%2Fexamples%2Flilypond.lyx;h=aa2f62dba74c538125006eca1c62fc3a3640dff4;hb=a860d18b5a722606c68fb1a4ec22ffe3e99792e6;hp=847bd394b717b452ea76b83255469bfeb22d34b2;hpb=bda8ae6a8cacb1e384d930b5cbbd23d0626c0098;p=lyx.git diff --git a/lib/examples/lilypond.lyx b/lib/examples/lilypond.lyx index 847bd394b7..aa2f62dba7 100644 --- a/lib/examples/lilypond.lyx +++ b/lib/examples/lilypond.lyx @@ -1,29 +1,27 @@ -#LyX 2.0.0svn created this file. For more info see http://www.lyx.org/ -\lyxformat 404 +#LyX 2.1 created this file. For more info see http://www.lyx.org/ +\lyxformat 474 \begin_document \begin_header \textclass article -\begin_preamble -\date{} -\end_preamble \use_default_options true \begin_modules lilypond \end_modules \maintain_unincluded_children false \language english +\language_package default \inputencoding auto \fontencoding global -\font_roman default -\font_sans default -\font_typewriter default +\font_roman lmodern +\font_sans lmss +\font_typewriter lmtt +\font_math auto \font_default_family default -\use_xetex false +\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 @@ -31,18 +29,39 @@ lilypond \index_command default \paperfontsize default \spacing single -\use_hyperref false +\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_amsmath 1 -\use_esint 1 -\use_mhchem 1 -\use_mathdots 1 +\use_package amsmath 1 +\use_package amssymb 1 +\use_package cancel 0 +\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 default +\biblio_style plain \use_bibtopic false \use_indices false \paperorientation portrait -\suppress_date false +\suppress_date true +\justification true \use_refstyle 0 \index Index \shortcut idx @@ -54,8 +73,8 @@ lilypond \bottommargin 2cm \secnumdepth 3 \tocdepth 3 -\paragraph_separation skip -\defskip smallskip +\paragraph_separation indent +\paragraph_indentation default \quotes_language english \papercolumns 1 \papersides 1 @@ -63,50 +82,115 @@ lilypond \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 + LyX +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 is an example file demonstrating the use of LilyPond music notation - with LyX. +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 -Using LilyPond code within LyX +Introduction \end_layout \begin_layout Standard -Support for LilyPond constructs (LilyPond code) within LyX is enabled by - adding the LilyPond module to your document. - This is done from the menu Document \SpecialChar \menuseparator - Settings..., 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 LaTeX code through - LilyPond-book for you. - LilyPond-book can also handle DocBook documents but LilyPond-DocBook support - in LyX is missing at the moment. +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 Subsection -Requirements +\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 a 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 Itemize -LilyPond-book version 2.13 +\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 Paragraph -Notes: +\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 @@ -120,17 +204,29 @@ LilyPond-book supports LaTeX output since version 2.1. 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 Insert - \SpecialChar \menuseparator - Custom Insets. +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's try a simple scale: + First, let us try a simple scale: \end_layout \begin_layout Standard @@ -139,6 +235,20 @@ 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'' { @@ -160,13 +270,18 @@ relative c'' { \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} +begin{lilypond}[staffsize=28] +\end_layout + +\begin_layout LyX-Code + \end_layout \begin_layout LyX-Code @@ -190,24 +305,54 @@ end{lilypond} \end_layout \begin_layout Standard -This code is not, in fact, processed by LaTeX, but is preprocessed by LilyPond-b -ook, which creates the graphics files and include them in the LaTeX document - by replacing the above with +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 toolchain is as follow: LyX\SpecialChar \menuseparator +Thus, the conversion process is as follow: +\family sans +LyX\SpecialChar \menuseparator LilyPond-book\SpecialChar \menuseparator -LaTeX. - Every step of the toolchain obeys your spacing, so whether you put the - musical extract inline or in its own paragraph, centered or left-aligned, +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 @@ -215,7 +360,16 @@ 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 @@ -239,8 +393,12 @@ Previews 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 Insert \SpecialChar \menuseparator - Preview. + from the menu +\family sans +Insert\SpecialChar \menuseparator +Preview +\family default +. This only affects the display within LyX, not the output: \end_layout @@ -249,7 +407,7 @@ It is possible to have a direct feedback of what the music notation looks \begin_layout Standard \begin_inset Flex LilyPond -status open +status collapsed \begin_layout Plain Layout @@ -282,12 +440,116 @@ relative c'' { 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 @@ -348,7 +610,7 @@ With surrounding braces, all is well: \begin_layout Standard \begin_inset Flex LilyPond -status open +status collapsed \begin_layout Plain Layout @@ -368,7 +630,18 @@ score given \end_layout \begin_layout Standard -Another gotcha is with subsequent lilypond snippets with +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 @@ -424,10 +697,55 @@ end{lilypond} \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 @@ -438,8 +756,9 @@ reference "sub:Editorial-headword" \end_inset - shows a complex example using many LilyPond constructs; some inline scheme - code has been removed to be able to run in safe mode. + 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 @@ -967,6 +1286,7 @@ staccato \end_layout \begin_layout Standard +\noindent [from \begin_inset Flex URL status collapsed @@ -978,7 +1298,7 @@ http://lsr.dsi.unimi.it/LSR/Item?id=627 \end_inset -; inline scheme code removed, centering applied through the paragraph settings] +; scheme code removed, centering applied through the paragraph settings] \end_layout \begin_layout Subsection @@ -1145,6 +1465,7 @@ lower } \end_layout \begin_layout Standard +\noindent [from \begin_inset Flex URL status collapsed