4 @c * more details about running lilypond; error messages,
5 @c compiling/viewing (emacs?)
6 @c * where to go from First steps+More basics?
12 <!--- @@WEB-TITLE@@=Tutorial --->
16 * First steps:: Music language of LilyPond
17 * Running LilyPond:: Printing music
21 * Listening to output::
23 * Single staff polyphony ::
26 * Fine tuning layout::
27 * Organizing larger pieces::
28 * An orchestral part::
29 * Integrating text and music:: Integrating text and music
32 Operating is done through text files: To print a piece of music, you
33 enter the music in a file. When LilyPond is run (normally using the
34 program @code{ly2dvi}) on that file, another file containing formatted
35 sheet music, is produced. That file may be printed or viewed.
37 This tutorial starts with a small introduction to the LilyPond music
38 language. After this first contact, we will show which commands to
39 run to produce printed output, so you should then be able to create
40 your first sheets of music. When starting out, it will be convenient
45 @ref{Cheat sheet}, which is a table listing all commands for
53 We start off by showing how very simple music is entered in LilyPond:
54 you get a note simply by typing its @htmlref{note name}, from @samp{a}
55 through @samp{g}. So if you enter
62 then the result looks like this:
65 @c \transpose c c' { c d e f g a b }
67 @c \property Score.timing = ##f
68 @lilypond[notime, relative=2]
72 We will continue with this format: First we show a snippet of input,
73 then the resulting output.
75 The length of a note is specified by adding a number, @samp{1} for a
76 @rglos{whole note}, @samp{2} for a @rglos{half note}, and so on:
83 \property Score.timing = ##f
84 \property Staff.autoBeaming = ##f
85 \transpose c c' { a1 a2 a4 a16 a32 s16_" " }
88 If you do not specify a @rglos{duration}, the previous one is used:
95 \property Score.timing = ##f
96 \transpose c c' { a a a2 a s16_" " }
99 A @rglos{sharp} (@texisharp{}) is made by adding @samp{is}, a
100 @rglos{flat} (@texiflat{}) by adding @samp{es}. As you might expect,
101 a @rglos{double sharp} or @rglos{double flat} is made by adding
102 @samp{isis} or @samp{eses}:@footnote{This syntax derived from note
103 naming conventions in Nordic and Germanic languages, like German and
111 \property Score.timing = ##f
112 \transpose c c' { cis1 ees fisis aeses s16_" " }
115 Add a dot @samp{.} after the duration to get a @rglos{dotted note}:
122 \property Score.timing = ##f
123 \transpose c c' { a2. a4 a8. a16 s16_" " }
126 Entering pitches and durations is fully explained in @ref{Pitches} and
130 The @rglos{meter} (or @rglos{time signature}) can be set with the
131 @code{\time} command:
139 @c a clef here may lead to confusion
141 \property Staff.Clef \set #'transparent = ##t
150 Time signatures and other timing commands are described in @ref{Time
154 The @rglos{clef} can be set using the @code{\clef} command:
156 @c what is more common name treble or violin?
157 @c in Dutch, its violin.
158 @c in English its definitely treble.
167 \property Score.timing = ##f
178 Clefs are fully explained in @ref{Clef}.
181 When you enter these commands in a file, you must to enclose them in
182 @code{\notes @{@dots{}@}}. This lets LilyPond know that music (as
183 opposed to @rglos{lyrics}) follows:
193 Now the piece of music is almost ready to be printed. The final step is to
194 combine the music with a printing command.
196 The printing command is the so-called @code{\paper} block. Later on
197 you will see that the @code{\paper} block is used to customize
198 printing specifics. The music and the @code{\paper} block are combined by
199 enclosing them in @code{\score @{ ... @}}. This is what a full source file looks like:
222 linewidth = 55 * \staffspace
228 @node Running LilyPond
229 @section Running LilyPond
231 In the last section we explained what kind of things you could enter
232 in a LilyPond file. In this section we explain what commands to run
233 and how to view or print the output. If you have not used LilyPond
234 before, want to test your setup, or want to run an example file
235 yourself, read this section. The instructions that follow are for
236 Unix-like systems. Some additional instructions for Microsoft Windows are given
237 at the end of this section.
239 Begin by opening a terminal window and starting a text editor.
240 For example, you could open an xterm and execute @code{joe}. In your
241 text editor, enter the following input and save the file as
247 \notes @{ c'4 e' g' @}
254 @c now this is weird, running ly2dvi to run LilyPond
255 @c (therefore name change proposal)
257 LilyPond is the program that computes the sheet music. All other
258 things, such as adding titles, page breaking and other page layout,
259 are done by a small wrapper program called
260 @code{ly2dvi}. @code{ly2dvi} calls LilyPond to render the music, and
261 then adds the titling and page layout instructions. To process
262 @file{test.ly} with @code{ly2dvi}, proceed as follows:
270 You will see the following on your screen:
275 Now processing: `/home/fred/ly/test.ly'
277 Interpreting music...[1]
278 @emph{ ... more interesting stuff ... }
279 PDF output to `test.pdf'...
280 DVI output to `test.dvi'...
284 @cindex Viewing music
287 The results of the ly2dvi run are two files, @file{test.dvi} and
288 @file{test.pdf}. The PDF file (@file{test.pdf}) is the one you can
289 print or view. For example, viewing PDF can be done with ghostview.
290 If a version of ghostview is installed on your system, one of these
291 commands will produce a window with some music notation on your
304 If the music on your screen looks good, you can print it by clicking
305 File/Print inside ghostview.
307 The DVI file (@file{test.dvi}) contains the same sheet music in a
308 different format. DVI files are more easily processed by the computer,
309 so viewing them usually is quicker. You can run @code{xdvi test.dvi}
310 @c KDVI doesn't grok the PS specials.
312 @c @code{kdvi test.dvi}
314 to view the DVI file. In Xdvi, the mouse buttons
315 activate magnifying glasses. Unfortunately, variable symbols (such as
316 beams and slurs) are not displayed in the magnifying glasses.
321 @cindex Printing output
325 If you are familiar with @TeX{}, be warned: do not use other DVI
326 drivers like @code{dvilj}. LilyPond DVI use embedded PostScript code
327 and will not render correctly with other DVI drivers besides
335 Various commands for formatting and printing music are detailed in
336 @ref{Invoking LilyPond}.
339 @unnumberedsubsec Windows users
341 On Windows, the terminal is started by clicking on the LilyPond or
342 Cygwin icon. Any text editor (such as NotePad, Emacs or Vim) may be
343 used to edit the LilyPond file. When Cygwin's @code{XFree86} X11
344 window system is installed along with @code{tetex-x11} and
345 @code{ghostscript-x11} packages, then the @code{dvi} output may be
346 viewed with @code{xdvi test.dvi} as described above. If you have
347 installed a PostScript/PDF viewer, such as @code{GSView} from
348 @uref{http://www.cs.wisc.edu/~ghost}, viewing the PDF file can be done
352 @code{gsview32 test.pdf}
355 Printing may be done by executing
358 @code{gsview32 /s test.pdf}
366 We continue with the introduction of more musical constructs. Normal
367 rests are entered just like notes with the name ``@code{r}'':
375 \property Score.timing = ##f
376 \property Staff.Clef = \turnOff
377 \property Staff.TimeSignature = \turnOff
384 Rests are described in full detail in @ref{Rests}.
387 @c Tim wants to move this quotes example just before the: quotes-do not-work
388 @c score, but we'd need to remove quotes from the other two (key and
391 @c better to have this just before the `octaves are bad' snipped
392 @c but we'd need to remove the ', from \key and tie
393 To raise a note by an octave, add a high quote @code{'} (apostrophe) to
394 the note name, to lower a note one octave, add a ``low quote'' @code{,}
395 (a comma). Middle C is @code{c'}:
399 c'4 c'' c''' \clef bass c c,
403 \property Score.timing = ##f
404 \property Staff.TimeSignature = \turnOff
405 c'4 c'' c''' \clef bass c c,
410 A tie is created by adding a tilde ``@code{~}'' to the first note
413 @lilypond[fragment,verbatim]
418 A tie is different from a slur. A tie simply makes the first note
419 sound longer, and can only be used on pairs of notes with the same
420 pitch. Slurs indicate the articulations of notes, and can be used on
421 larger groups of notes. Slurs and ties are also nested in practice:
422 @lilypond[fragment, relative=1]
423 c2-~-( c8 fis fis4 ~ fis2 g2-)
426 The notation manual discusses ties in @ref{Ties}.
428 The key signature is set with the command ``@code{\key}'', followed by
429 a pitch and @code{\major} or @code{\minor}:
439 \property Staff.TimeSignature = \turnOff
449 @c bit on the long/complex/scary taste
450 @c cheating a bit: two lines makes for a friendlier look
451 This example shows notes, ties, octave marks, and rests in action.
460 r4 r8 d''8 cis''4 e''
462 cis''4 cis''8 cis'' bis'4 d''8 cis''-~
475 r4 r8 d''8 cis''4 e''
477 cis''4 cis''8 cis'' bis'4 d''8 cis''-~
480 \paper { linewidth = 50*\staffspace }
486 There are some interesting points to note in this example.
487 Accidentals (sharps and flats) do not have to be marked explicitly:
488 you just enter the note name, and an accidental is printed
489 automatically, only when necessary. Bar lines and beams are drawn
490 automatically. Line breaks are calculated automatically; it does not
491 matter where the lines breaks are in the source file. Finally, the
492 order of time, key and clef changes is not relevant: in the printout,
493 these are ordered using standard notation conventions.
495 The example also indicates that a piece of music written in a high
496 register needs lots of quotes. This makes the input less readable,
497 and is also a potential source of errors.
499 The solution is to use ``relative octave'' mode. In practice, this is
500 the most convenient way to copy existing music. To use relative mode,
501 add @code{\relative} before the piece of music. You must also give a
502 note from which relative starts, in this case @code{c''}. If you do
503 not use octavation quotes (i.e. do not add ' or , after a note),
504 relative mode chooses the note that is closest to the previous one.
505 @c do not use commas or quotes in this sentence
506 For example: @code{c f} goes up; @code{c g} goes down:
516 \property Score.timing = ##f
517 \property Staff.TimeSignature = \turnOff
526 Since most music has small intervals, in relative mode pieces can be
527 written almost without using octavation quotes.
529 @c needed better, maybe even redundant explanation
530 @c added another example below.
531 @c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
532 @c in eerste instantie drong het `relative' niet door zonder extra uitleg.
533 Larger intervals are made by adding octavation quotes. Quotes or
534 commas do not determine the absolute height of a note; the height of a
535 note is relative to the previous one.
536 @c do not use commas or quotes in this sentence
537 For example: @code{c f,} goes down; @code{f, f} are both the same;
538 @code{c' c} are the same; and @code{c g'} goes up:
548 \property Score.timing = ##f
549 \property Staff.TimeSignature = \turnOff
558 Here is an example of the difference between relative mode and
559 ``normal'' (non-relative) mode:
570 \property Score.timing = ##f
571 \property Staff.TimeSignature = \turnOff
587 \property Score.timing = ##f
588 \property Staff.TimeSignature = \turnOff
595 A slur is drawn across many notes, and indicates bound articulation
596 (legato). The starting note and ending note are marked with a
597 ``@code{(}'' and a ``@code{)}'' respectively:
600 @lilypond[fragment,relative 1, verbatim]
601 d4-( c16-)-( cis d e c cis d e-)-( d4-)
606 If you need two slurs at the same time (one for articulation, one for
607 phrasing), you can also make a phrasing slur with @code{\(} and
612 @c fragment of 1st hrn in Adams' The Chairman Dances, with creative
613 @c chromatic thing pasted in front. (admittedly the original does not
614 @c have a phrasing slur. The problem is that we do not want the slur
615 @c and the Phrasing slur to collide. We are trying to make a good
619 @lilypond[fragment,relative 1, verbatim]
620 a8-(-\( ais b c-) cis2 b'2 a4 cis, c-\)
625 Beams are drawn automatically, but if you do not like where they are
626 put, they can be entered by hand. Mark the first note to be beamed
627 with @code{[} and the last one with @code{]}:
629 @lilypond[fragment,relative 1, verbatim]
630 a8-[ ais-] d-[ es r d-]
635 To print more than one staff, each piece of music that makes up a staff
636 is marked by adding @code{\context Staff} before it. These
637 @code{Staff}'s are then grouped inside @code{\simultaneous @{} and @code{@}}, as is
641 @lilypond[fragment,verbatim]
643 \context Staff = staffA { \clef violin c'' }
644 \context Staff = staffB { \clef bass c }
649 In this example, @code{staffA} and @code{staffB} are names that are
650 given to the staves. It does not matter what names you give, as long
651 as each staff has a different name. If you give them the same name,
652 they are assumed to belong on the same staff, and will be printed like
653 that. @code{\simultaneous } indicates that both fragments happen at
654 the same time, and must be printed stacked vertically. The notation
655 @code{< .. >} can also be used as a shorthand for @code{\simultaneous
660 We can now typeset a melody with two staves:
663 @lilypond[verbatim,singleline]
666 < \context Staff = staffA {
670 e2-( d4 c2 b4 a8-[ a-]
671 b-[ b-] g-[ g-] a2.-) }
673 \context Staff = staffB {
684 The time signature is specified in one melody staff only
685 (the top staff), but is printed on both, since common practice
686 dictates that all staves have the same time signature.
690 Common accents can be added to a note using @code{-.}, @code{--}, @code{->}:
692 @lilypond[verbatim,relative 1]
698 Similarly, fingering indications can be added to a note using @code{-}
699 and the digit to be printed.
700 @lilypond[verbatim,relative 1]
708 Dynamic signs are made by adding the markings to the note:
710 @lilypond[verbatim,relative 1]
716 Crescendi and decrescendi are started with the commands @code{\<} and
717 @code{\>}. The command @code{\!} finishes a crescendo on the note it
720 @lilypond[verbatim,relative 1]
721 c2-\< c2-\!-\ff c2-\> c2-\!
726 Chords can be made by
727 surrounding pitches with @code{<<} and @code{>}>:
729 @lilypond[relative 0, fragment,verbatim]
730 r4 <<c e g>>4 <<c f a>>8
736 You can combine beams and ties with chords. Beam and tie markings
737 must be placed outside the chord markers:
739 @lilypond[relative 0, fragment,verbatim]
740 r4 <<c e g>>8-[ <<c f a>>-]-~ <<c f a>>
746 r4 <<c e g>>8-\>-( <<c e g>> <<c e g>> <<c f a>>8-\!-)
748 @lilypond[relative 0, fragment]
750 r4 <<c e g>>8-\>-( <<c e g>> <<c e g>> <<c f a>>8-\!-)
756 A pickup (or upstep) is entered with the keyword @code{\partial}. It
757 is followed by a duration: @code{\partial 4} is a quarter note upstep
758 and @code{\partial 8} an eighth note.
759 @lilypond[relative 1,verbatim,fragment]
764 Tuplets are made with the @code{\times} keyword. It takes two
765 arguments: a fraction and a piece of music. The duration of the piece
766 of music is multiplied by the fraction. Triplets make notes occupy
767 2/3 of their notated duration, so a triplet has 2/3 as its fraction.
769 @lilypond[relative 0,verbatim,fragment]
770 \times 2/3 { f8 g a }
774 Grace notes are also made by prefixing a note, or a set of notes with
775 a keyword. In this case, the keyword is @code{\grace}.
776 @lilypond[relative 1, verbatim,fragment]
778 \grace { d16-( e } d4-)
782 More information on the use of grace notes is in @ref{Grace notes}.
785 Comments are pieces of the input that are ignored. There are two
786 types of comments. A line comments are introduced by @code{%}: after
787 that, the rest of that line is ignored. Block comments span larger
788 sections of input. Anything that is enclosed in @code{%@{} and
789 @code{%@}} is ignored too. The following fragment shows possible uses
793 % notes for twinkle twinkle follow:
798 This line, and the notes below
799 are ignored, since they are in a
809 @node Printing lyrics
810 @section Printing lyrics
813 Lyrics are entered by separating each syllable with a space, and
814 surrounding them with @code{\lyrics @{ @dots{} @}}, for example
816 \lyrics @{ I want to break free @}
819 Like notes, lyrics are also a form of music, but they must not be
820 printed on a staff, which is the default way to print music. To print
821 them as lyrics, they must be marked with @code{ \context Lyrics}:
823 \context Lyrics \lyrics @{ I want to break free @}
825 The melody for this song is as follows
827 @lilypond[fragment,relative=1]
830 \times 2/3 { f4 g g } \times 2/3 { g4-( a2-) }
833 The lyrics can be set to these notes, combining both with the
834 @code{\addlyrics} keyword:
838 \context Lyrics @dots{}
842 @lilypond[singleline,verbatim]
849 \times 2/3 { f g g } \times 2/3 { g4-( a2-) }
851 \context Lyrics \lyrics { I want to break free }
857 This melody ends on a @rglos{melisma}, a single syllable (``free'')
858 sung to more than one note. This is indicated with a @emph{extender
859 line}. It is entered as two underscores, i.e.,
861 \lyrics @{ I want to break free __ @}
870 \times 2/3 { f g g } \times 2/3 { g4-( a2-) }
872 %% ugh, this is to deal with bugs in the extender implementation
876 \context Lyrics \lyrics { I want to break free __ }
878 \paper{ linewidth = 9.0 \cm }
882 Similarly, hyphens between words can be entered as two dashes,
883 resulting in a centered hyphen between two syllables.
885 Twin -- kle twin -- kle
887 @lilypond[singleline]
889 \addlyrics \notes \relative f' { \time 2/4
891 \context Lyrics \lyrics { Twin -- kle twin -- kle
893 \paper { linewidth = 6.0 \cm }
898 More options, like putting multiple lines of lyrics below a melody are
899 discussed in @ref{Vocal music}.
903 TODO: discuss contexts.
907 @section A lead sheet
909 In popular music, it is common to denote accompaniment as chord-names.
910 Using them in LilyPond has two parts, just like lyrics: entering the
911 chords (with @code{\chords}), and printing them (with @code{\context
914 Chord names are entered by starting chords mode (with @code{\chords}).
915 In chords mode, you can enter chords with a letter (indicating the
916 root of the chord), and a durations following that.
919 \chords { c2 f4. g8 }
923 The result of @code{\chords} is a list of chords, and is equivalent
924 to entering chords with @code{<<@dots{}>>}.
926 Other chords can be created by adding modifiers, after a colon. The
927 following example shows a few common modifiers
930 \chords { c2 f4:m g4:maj7 gis1:dim7 }
933 Printing chords is done by adding @code{\context ChordNames}
934 before the chords thus entered:
937 \context ChordNames \chords \chords { c2 f4.:m g4.:maj7 gis8:dim7 }
940 A complete list of modifiers, and other options for layout are in the
941 reference manual section @ref{Chords}.
944 When put together, chord names, lyrics and a melody form
945 a lead sheet, for example,
950 \context ChordNames \chords @{ @emph{chords} @}
952 \notes @emph{the melody}
953 \context Lyrics \lyrics @{ @emph{the text} @}
961 \context ChordNames \chords { r8 c2:sus4 f }
963 \notes \relative c' {
966 \times 2/3 { f g g } \times 2/3 { g4-( a2-) } }
967 \context Lyrics \lyrics { I want to break free __ }
969 \paper{ raggedright = ##t }
974 @node Listening to output
975 @section Listening to output
977 MIDI (Musical Instrument Digital Interface) is a standard for
978 connecting and recording digital instruments. A MIDI file is like a
979 tape recording of a MIDI instrument. The @code{\midi} block makes the
980 music go to a MIDI file, so you can listen to the music you entered.
981 It is great for checking the music: octaves that are off, or
982 accidentals that were mistyped, stand out very much when listening to
983 the musical transcription.
985 @code{\midi} can be used in similarly to @code{\paper @{ @}}, for
990 \midi @{ \tempo 4=72 @}
995 Here, the tempo is specified using the @code{\tempo} command. In this
996 case the tempo of quarter notes is set to 72 beats per minute. More
997 information on auditory output is in the @ref{Sound} section in the
1004 Bibliographic information is entered in a separate block, the
1005 @code{\header} block. The name of the piece, its composer, etc. are
1006 entered as assignment within @code{\header @{ @dots{} @}}. For
1010 title = "Eight miniatures"
1011 composer = "Igor Stravinsky"
1012 tagline = "small is beautiful"
1015 \score @{ @dots{} @}
1018 @cindex bibliographic information
1024 When the file is processed by @code{ly2dvi}, the title and composer
1025 specified are printed above the music. The `tagline' is a short line
1026 printed at bottom of the last page, which normally says ``Lily was
1027 here, version @dots{}''. In the example above, it is replaced by the
1028 line ``small is beautiful.''
1030 Normally, the @code{\header} is put at the top of the file. However,
1031 for a document that contains multiple pieces (e.g. a etude book, or
1032 part with multiple movements), then the header can be put into the
1033 @code{\score} block as follows In this case, the name of each piece
1034 will be printed before each movement.
1037 @cindex Lily was here
1038 @cindex signature line
1043 title = "Eight miniatures"
1044 composer = "Igor Stravinsky"
1045 tagline = "small is beautiful"
1049 \header @{ piece = "Adagio" @}
1052 \header @{ piece = "Menuetto" @}
1056 More information on titling can be found in @ref{Invoking ly2dvi}.
1059 @node Single staff polyphony
1060 @section Single staff polyphony
1062 When different melodic lines are combined on a single staff, these are
1063 printed as polyphonic voices: each voice has its own stems, slurs
1064 and beams, and the top voice has the stems up, while the bottom voice
1067 Entering such parts is done by entering each voice as a sequence (with
1068 @code{@{ .. @}}), and combing those simultaneously, separating the
1069 voices with @code{\\}:
1072 < @{ a4 g2 f4-~ f4 @} \\
1075 @lilypond[relative=1]
1076 \context Staff < { a4 g2 f4-~ f4 } \\
1080 For polyphonic typesetting spacer rests can also be convenient: these
1081 are rests that do not print. It is useful for filling up voices that
1082 temporarily do not play:
1084 < @{ a4 g2 f4-~ f4 @} \\
1088 \context Staff < { a4 g2 f4-~ f4 } \\
1092 More features of polyphonic typesetting are in the notation manual
1096 @section Piano staffs
1098 @cindex staff switch, manual
1099 @cindex cross staff voice, manual
1100 @cindex @code{\translator}
1102 Piano music is always typeset in two staffs connected by a brace.
1103 Printing such a staff is done similar to the polyphonic example in
1106 < \context Staff = up @{ @dots{} @}
1107 \context Staff = down @{ @dots{} @}
1110 but now this entire expression must be interpreted as a
1113 \context PianoStaff < \context Staff @dots{} >
1116 Here is a full-fledged example:
1118 @lilypond[relative 0,fragment]
1120 < \context Staff = up {
1122 \context Staff = down {
1123 \clef bass c, c' e c }
1127 More information on formatting piano music is in @ref{Piano music}.
1129 @node Setting variables
1130 @section Setting variables
1132 When the music is converted from notes to print, it is interpreted
1133 from left-to-right order, similar to what happens when we read
1134 music. During this step, context-sensitive information, such as the
1135 accidentals to print, and where barlines must be placed, are stored in
1136 variables. These variables are called @emph{translation properties}.
1137 The properties can also be manipulated from input files: for example,
1139 \property Staff.autoBeaming = ##f
1141 sets the property named @code{autoBeaming} in the current staff to
1142 @code{##f} which means `false'. This property controls whether beams
1143 are printed automatically:
1144 @lilypond[relative 1,fragment,verbatim]
1146 \property Staff.autoBeaming = ##f
1151 LilyPond includes a built-in programming language, namely, a dialect
1152 of Scheme. The argument to @code{\property}, @code{##f}, is an
1153 expression in that language. The first hash-mark signals that a piece
1154 of Scheme code follows. The second hash character is part of the
1155 boolean value true (@code{#t}). Values of other types may be
1158 @item a string, enclosed in double quotes, for example
1160 \property Staff.instrument = #"French Horn"
1162 @item a boolean: either @code{#t} or @code{#f}, for true and false
1165 \property Voice.autoBeaming = ##f
1166 \property Score.skipBars = ##t
1171 \property Score.currentBarNumber = #20
1174 @item a symbol, which is introduced by a quote character,
1176 \property Staff.crescendoSpanner = #'dashed-line
1179 @item a pair, which is also introduced by a quote character.
1180 The following statements set properties to the pairs (-7.5, 6) and
1181 (3, 4) respectively.
1184 \property Staff.minimumVerticalExtent = #'(-7.5 . 6)
1185 \property Staff.timeSignatureFraction = #'(3 . 4)
1191 There are many different properties, and not all of them are listed in
1192 this manual. However, the internal documentation lists them all in the
1193 @internalsref{All translation properties}, and almost all properties
1194 are demonstrated in one of the
1196 @uref{../../../input/test/out-www/collated-files.html,tips-and-tricks}
1204 @node Fine tuning layout
1205 @section Fine tuning layout
1207 Sometimes it is necessary to change music layout by hand. When music
1208 is formatted, layout objects are created for each symbol. For
1209 example, every clef and every note head is represented by a layout
1210 object. These layout objects also carry variables, which we call
1211 @emph{layout properties}. By changing these variables from their
1212 values, we can alter the look of a formatted score.
1214 @lilypond[verbatim,relative 0]
1216 \property Voice.Stem \override #'thickness = #3.0
1221 In the example shown here, the layout property @code{thickness} (a
1222 symbol) is set to 3 in the @code{Stem} layout objects of the current
1223 Voice. As a result, the notes following @code{\property} have thicker
1226 In most cases of manual overrides, only a single object must be
1227 changed. This can be achieved by prefix @code{\once} to the
1228 @code{\property} statement, i.e.,
1231 \once \property Voice.Stem \set #'thickness = #3.0
1234 @lilypond[relative 0]
1236 \once \property Voice.Stem \set #'thickness = #3.0
1241 Some overrides are so common that predefined commands are provided as
1242 a short cut. For example, @code{\slurUp} and @code{\stemDown}. These
1243 commands are described in the @ref{Notation manual}, under the
1244 sections for slurs and stems respectively.
1246 The exact tuning possibilities for each type of layout object are
1247 documented in the internal documentation of the respective
1248 object. However, many layout objects share properties, which can be
1249 used to apply generic tweaks. We mention a couple of these:
1252 @cindex @code{extra-offset}
1253 @item The @code{extra-offset} property
1254 moves around objects in the printout. The unit of these offsets are
1255 staff-spaces. The first number controls left-right movement; a
1256 positive number will move the object to the right. The second number
1257 controls up-down movement; a positive number will move it higher. The
1258 @code{extra-offset} is a low-level feature: the formatting engine is
1259 completely oblivious to these offsets.
1261 In the following example example, the second fingering is moved a
1262 little to the left, and 1.8 staff space downwards.
1264 @cindex setting object properties
1266 @lilypond[relative=2,verbatim]
1269 \once \property Voice.Fingering
1270 \set #'extra-offset = #'(-0.3 . -1.8)
1275 Setting the @code{transparent} property will make an object be
1276 printed in `invisible ink': the object is not printed, but all its
1277 other behavior is retained. The object still takes space, takes part
1278 in collisions, and slurs, ties and beams can be attached to it.
1280 @cindex transparent objects
1281 @cindex removing objects
1282 @cindex invisible objects
1283 The following example demonstrates how to connect different voices
1284 using ties. Normally ties only happen between notes of the same
1285 voice. By introducing a tie in a different voice, and blanking a stem
1286 in that voice, the tie appears to cross voices.
1288 @lilypond[fragment,relative=1]
1290 \once \property Voice.Stem \set #'transparent = ##t
1298 The @code{padding} property for objects with
1299 @code{side-position-interface} can be set to increase distance between
1300 symbols that are printed above or below notes. An example of the use
1301 of padding is in @ref{Constructing a tweak}.
1304 More specific overrides are also possible. The notation manual
1305 discusses in depth how to figure out these statements for yourself, in
1306 @ref{Tuning output}.
1308 @node Organizing larger pieces
1309 @section Organizing larger pieces
1311 TODO: discuss identifiers, include files, \version.
1315 @node An orchestral part
1316 @section An orchestral part
1320 \markup, mmrest, transposing, cue notes
1328 Lilypond and its language are still under development, and
1329 occasionally details of the syntax are changed. The @code{version}
1330 fragment indicates which LilyPond version the input file was written
1331 for. When you compile this file, the version number will be
1332 checked. When the file is too old, a warning is issued. The version
1333 number is also used by the @code{convert-ly} program (See
1334 @ref{Invoking convert-ly}), which updates the file to the latest
1335 version automatically.
1337 @node Integrating text and music
1338 @section Integrating text and music
1341 @cindex La@TeX{}, music in
1342 @cindex HTML, music in
1343 @cindex Texinfo, music in
1345 Sometimes you might want to use music examples in a text that you are
1346 writing (for example a musicological treatise, a songbook, or (like us)
1347 the LilyPond manual). You can make such texts by hand, simply by
1348 importing a PostScript figure into your word processor. However,
1349 there is an automated procedure to reduce the amount of work.
1351 If you use HTML, La@TeX{}, or Texinfo, you can mix text and LilyPond
1352 code. A script called @code{lilypond-book} will extract the music
1353 fragments, run LilyPond on them, and put back the resulting notation.
1354 This program is fully described in @ref{lilypond-book manual}. Here
1355 we show a small example. Since the example also contains explanatory
1356 text, we will not comment it further.
1359 \documentclass[a4paper]@{article@}
1362 In a lilypond-book document, you can freely mix music and text. For
1365 \score @{ \notes \relative c' @{
1366 c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
1370 Notice that the music line length matches the margin settings of the
1373 If you have no \verb+\score+ block in the fragment,
1374 \texttt@{lilypond-book@} will supply one:
1380 In the example you see here, two things happened: a
1381 \verb+\score+ block was added, and the line width was set to natural
1382 length. You can specify many more options using \LaTeX style options
1385 \begin[verbatim,11pt,singleline,
1386 fragment,relative,intertext="hi there!"]@{lilypond@}
1390 The option \texttt@{verbatim@} prints the LilyPond code in addition to
1391 the graphical score, \texttt@{11pt@} selects the default music size,
1392 \texttt@{fragment@} adds a score block, \texttt@{relative@} uses
1393 relative mode for the fragment, and \texttt@{intertext@} specifies
1394 what to print between the \texttt@{verbatim@} code and the music.
1396 If you want to include large examples into the text, it may be more
1397 convenient to put the example in a separate file:
1399 \lilypondfile[printfilename]@{screech-boink.ly@}
1401 The \texttt@{printfilename@} option adds the file name to the output.
1406 Under Unix, you can view the results as follows.
1410 $ lilypond-book --outdir=out/ lilbook.tex
1411 lilypond-book (GNU LilyPond) 1.7.23
1412 Reading `input/tutorial/lilbook.tex'
1413 Reading `input/screech-boink6.ly'
1414 @var{lots of stuff deleted}
1415 Writing `out/lilbook.latex'
1417 $ latex lilbook.latex
1418 @var{lots of stuff deleted}
1422 Running lilypond-book and running latex creates a lot of temporary
1423 files, and you would not want those to clutter up your working
1424 directory. The @code{outdir} option to lilypond-book creates the
1425 temporary files in a separate subdirectory @file{out}.
1427 The result looks more or less like this:
1431 In a lilypond-book document, you can freely mix music and text. For
1435 \notes \relative c' {
1436 c2 g'2 \times 2/3 { f8 e d } c'2 g4
1444 Notice that the music line length matches the margin settings of the
1447 If you have no @code{\score} block in the fragment,
1448 @code{lilypond-book} will supply one:
1454 In the example you see here, a number of things happened: a
1455 @code{\score} block was added, and the line width was set to natural
1456 length. You can specify many more options using La@TeX{} style options
1459 @lilypond[verbatim,11pt,singleline,
1460 fragment,relative,intertext="hi there!"]
1464 The option @code{verbatim} also shows the LilyPond code, @code{11pt} selects
1465 the default music size, @code{fragment} adds a score block,
1466 @code{relative} uses relative mode for the fragment, and
1467 @code{intertext} specifies what to print between the
1468 @code{verbatim} code and the music.
1470 If you include large examples into the text, it may be more convenient
1471 to put the example in a separate file:
1473 @lilypondfile[printfilename]{screech-boink.ly}
1475 The @code{printfilename} option adds the file name to the output.