LilyPond The music typesetter Usage The LilyPond development team ☛ ✟ This file explains how to execute the programs distributed with LilyPond version 2.21.82. In addition, it suggests some “best practices” for efficient usage. ✡ ✠ ☛ ✟ For more information about how this manual fits with the other documentation, or to read this manual in other formats, see Section “Manuals” in General Information. If you are missing any manuals, the complete documentation can be found at http://lilypond.org/. ✡ ✠ Copyright ⃝c 1999–2020 by the authors. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections. A copy of the license is included in the section entitled “GNU Free Documentation License”. For LilyPond version 2.21.82 i Table of Contents 1 Running lilypond .............................................. 1 1.1 Normal usage ................................................... ................... 1 1.2 Command-line usage ................................................... ............ 1 Invoking lilypond ................................................... ................ 1 Using LilyPond with standard shell features ....................................... 1 Basic command line options for LilyPond............................................. 2 Advanced command line options for LilyPond ........................................ 5 Environment variables ................................................... ........... 11 Relocation ................................................... ....................... 11 Relocation files ................................................... ............... 12 Relocation algorithm ................................................... ......... 12 LilyPond in chroot jail ................................................... ........... 13 1.3 Error messages ................................................... ................ 14 1.4 Common errors ................................................... ................ 15 Music runs off the page ................................................... .......... 15 An extra staff appears ................................................... ........... 16 Error message Unbound variable % ................................................. 16 Error message FT Get Glyph Name ................................................ 16 Warning staff affinities should only decrease ......................................... 17 Error message unexpected \new ................................................... .. 17 Warning this voice needs a \voiceXx or \shiftXx setting ........................... 18 2 Updating files with convert-ly ............................... 19 2.1 Why does the syntax change? ................................................... .. 19 2.2 Invoking convert-ly ................................................... .......... 19 2.3 Command line options for convert-ly ............................................ 20 2.4 Problems running convert-ly ................................................... 21 2.5 Manual conversions ................................................... ............ 22 2.6 Writing code to support multiple versions ......................................... 23 3 Running lilypond-book ....................................... 24 3.1 An example of a musicological document .......................................... 24 3.2 Integrating music and text ................................................... ..... 28 A 3.2.1 LTEX................................................... ..................... 28 3.2.2 Texinfo ................................................... ................... 30 3.2.3 HTML................................................... .................... 31 3.2.4 DocBook ................................................... ................. 31 3.3 Music fragment options ................................................... ........ 32 3.4 Invoking lilypond-book................................................... ....... 35 3.5 Filename extensions ................................................... ........... 38 3.6 lilypond-book templates ................................................... ....... 38 3.6.1 LaTeX ................................................... .................... 38 3.6.2 Texinfo ................................................... ................... 39 3.6.3 html ................................................... ...................... 39 3.6.4 xelatex ................................................... ................... 40 3.7 Sharing the table of contents ................................................... ... 41 3.8 Alternative methods of mixing text and music ..................................... 42 ii 4 External programs ............................................ 43 4.1 Point and click ................................................... ................ 43 4.1.1 Configuring the system................................................... .... 43 Using Xpdf ................................................... ................... 43 Using GNOME 2 ................................................... ............. 44 Using GNOME 3 ................................................... ............. 44 Extra configuration for Evince ................................................... 44 Enabling point and click ................................................... ......... 44 Selective point-and-click ................................................... ......... 45 4.2 Text editor support ................................................... ............ 45 Emacs mode ................................................... ..................... 46 Vim mode ................................................... ....................... 46 Other editors ................................................... .................... 46 4.3 Converting from other formats ................................................... 46 4.3.1 Invoking midi2ly ................................................... ......... 46 4.3.2 Invoking musicxml2ly ................................................... .... 48 4.3.3 Invoking abc2ly ................................................... .......... 49 4.3.4 Invoking etf2ly ................................................... .......... 50 4.3.5 Other formats ................................................... ............ 50 4.4 LilyPond output in other programs................................................ 50 4.4.1 LuaTex ................................................... ................... 50 4.4.2 OpenOffice and LibreOffice................................................... 50 4.4.3 Other programs ................................................... ........... 51 4.5 Independent includes ................................................... ......... 51 4.5.1 MIDI articulation ................................................... ......... 51 5 Suggestions for writing files .................................. 52 5.1 General suggestions ................................................... ............ 52 5.2 Typesetting existing music ................................................... ..... 53 5.3 Large projects ................................................... ................. 53 5.4 Troubleshooting ................................................... ............... 54 5.5 Make and Makefiles ................................................... ............ 55 Appendix A GNU Free Documentation License .............. 62 Appendix B LilyPond index .................................... 69 1 1 Running lilypond This chapter details the technicalities of running LilyPond. 1.1 Normal usage Most users run LilyPond through a GUI; if you have not done so already, please read the Section “Tutorial” in Learning Manual. If you use an alternate editor to write LilyPond files, see the documentation for that program. 1.2 Command-line usage This section contains extra information about using LilyPond on the command-line. This may be desirable to pass extra options to the program. In addition, there are certain extra ‘helper’ programs (such as midi2ly) which are only available on the command-line. By ‘command-line’, we mean the command line in the operating system. Windows users might be more familiar with the terms ‘DOS shell’ or ‘command shell’. MacOS X users might be more familiar with the terms ‘terminal’ or ‘console’. Some additional setup is required for MacOS X users; please see Section “MacOS X” in General Information. Describing how to use this part of an operating system is outside the scope of this manual; please consult other documentation on this topic if you are unfamiliar with the command-line. Invoking lilypond The lilypond executable may be called as follows from the command line. lilypond [option]... file... When invoked with a filename that has no extension, the .ly extension is tried first. To read input from stdin, use a dash (-) for file. When filename.ly is processed it produces filename.pdf as output by default. Several files can be specified; they are each processed independently.1 If filename.ly contains more than one \book block, the rest of the scores is output in numbered files, starting with filename-1.pdf. In addition, the value of output-suffix is inserted between the basename and the number. For example, if filename.ly contains #(define output-suffix "violin") \score { ... } #(define output-suffix "cello") \score { ... } LilyPond outputs filename-violin.pdf and filename-cello-1.pdf.