3 @c ugh: because of @include, we need to fill in these nodes?
8 * Introduction:: Introduction
9 * The first tune:: The first tune
10 * Lyrics and chords:: Lyrics and chords
11 * Piano music:: Piano music
12 * end of tutorial:: The end
19 LilyPond prints music from a specification that you, the user, supply.
20 You have to give that specification using a @emph{language}. This
21 document is a gentle introduction to that language, which is called
22 Lilypond, an acronym of Music Definition Language.
24 This tutorial will demonstrate how to use Lilypond by presenting
25 examples of input along with resulting output. We will use English
26 terms for notation. In case you are not familiar with those, you may
27 consult the glossary that is distributed with LilyPond.
29 The examples discussed are included in the distribution, in the
30 subdirectory @file{input/tutorial/}. It is recommended that you
31 experiment with writing Lilypond input yourself, to get a feel for
35 @section The first tune
38 To demonstrate what LilyPond input looks like, we start off with a
39 full fledged, yet simple example. It is a convoluted version
40 of the famous menuet in J. S. Bach's @emph{Klavierbuechlein}.
43 % lines preceded by a percent are comments which
44 % are ignored by Lilypond.
48 \relative c'' \sequential{
53 d4 g,8 a b c d4 g, g |
54 e'4 c8 d e fis g4 g, g |
55 c4 d8()c b a( )b4 c8 b a g |
56 a4 [b8 a] [g fis] g2. |
61 g4 e8 fis g d cis4 b8 cis a4 |
62 a8-. b-. cis-. d-. e-. fis-.
69 % standard settings are too wide for a book
75 Enter it (or copy it, the filename is @file{menuet.ly}), compile it
76 with LilyPond and view the output. Details of this procedure may vary
77 from system to system. To create the output, one would issue the
78 command `@code{ly2dvi menuet}'. @file{ly2dvi} is a program that does
79 the job of running LilyPond and @TeX{}, handling of titles and
80 adjusting of page margins.
82 If all goes well, the file @file{menuet.dvi} will be created.
83 To view this output, issue the command `@code{xdvi menuet}'.
85 Now that we are familiar with the procedure of producing output, we
86 will analyse the input, line by line.
88 Let's try to redo this
91 % lines preceded by a percent are comments which
92 % are ignored by Lilypond.
96 The percent sign, `@code{%}', introduces a line comment. If you want to
97 make larger comments, you can use block comments. These are delimited
98 by `@code{%@{}' and `@code{%@}}'
100 @multitable @columnfractions .60 .39
103 @c @example urg: no tt font
104 @c @exdent % lines preceded by a percent are comments.
105 @exdent @code{% lines preceded by a percent are comments.}
108 The percent sign, `@code{%}', introduces a line comment. If you
109 want to make larger comments, you can use block comments. These
110 are delimited by `@code{%@{}' and `@code{%@}}'
117 By default, LilyPond will use definitions for a 20
118 point@footnote{A point is the standard measure of length for
119 printing. One point is 1/72.27 inch.} high staff. We want smaller
120 output (16 point staff height), so we must import the settings for
121 that size, which is done.
127 A lilypond file combines music with directions for outputting that
128 music. The music is combined with the output directions by putting
129 them into a @code{\score} block.
135 This makes LilyPond ready for accepting notes.
141 As we will see, pitches are combinations of octave, note name and
142 chromatic alteration. In this scheme, the octave is indicated by
143 using raised quotes (`@code{'}') and ``lowered'' quotes (commas:
144 `@code{,}'). The central C is denoted by @code{c'}. The C one octave
145 higher is @code{c''}. One and two octaves below the central C is
146 denoted by @code{c} and @code{c,} respectively.
148 For pitches in a long piece you might have to type many quotes. To
149 remedy this, LilyPond has a ``relative'' octave entry mode. In this
150 mode, octaves of notes without quotes are chosen such that a note is
151 as close as possible (graphically, on the staff) to the the preceding
152 note. If you add a high-quote an extra octave is added. The lowered
153 quote (a comma) will subtract an extra octave. Because the first note
154 has no predecessor, you have to give the (absolute) pitch of the note
161 What follows is sequential music, i.e.,
162 notes that are to be played and printed after each other.
168 This command changes the time signature of the current piece: a 3/4
169 sign is printed. This command is also used to generate bar lines in
176 This command changes the current key to G-major. Although this
177 command comes after the @code{\time} command, in the output, the key
178 signature comes before the time signature: LilyPond knows about music
179 typesetting conventions.
185 This command tells LilyPond that the following piece of music must
186 be played twice; @code{"volta"} means that volta brackets should be used
187 for alternatives---if there were any.
193 The subject of the repeat is again sequential music. Since
194 @code{\sequential} is such a common construct, a shorthand is provided:
195 just leave off @code{\sequential}, and the result is the same.
201 This is a note with pitch @code{d} (determined up to octaves). The
202 relative music was started with a @code{c''}, so the real pitch of this
203 note is @code{d''}. The @code{4} designates the duration of the note
204 (it is a quarter note).
210 These are notes with pitch @code{a} and @code{b}. Because their
211 duration is the same as the @code{g}, there is no need to enter the
212 duration (You may enter it anyway, e.g. @code{a4 b4})
218 Three more notes. The `@code{|}' character is a `bar check'. When
219 processing the music, LilyPond will verify that bar checks are found at
220 the start of a measure. This can help you track down errors.
222 So far, no notes were chromatically altered. Here is the first one
223 that is: @code{fis}. Lilypond by default uses Dutch note names, and
224 ``Fis'' is the Dutch note name for ``F sharp''. However, there is no
225 sharp sign in the output. The program keeps track of key signatures,
226 and will only print accidentals if they are needed.
232 LilyPond guesses were beams can be added to eighth and shorter notes.
233 In this case, a beam over 4 eighths is added.
236 c4 d8( )c b a( )b4 c8 b a g |
239 The next line shows how to make a slur:
240 the beginning and ending note of the slur is marked with an opening and
241 closing parenthesis respectively. In the line shown above, this is
242 done for two slurs. Slur markers (parentheses) are put between
249 Automatic beaming can be overridden by inserting beam marks
250 (brackets). Brackets are put around the notes you want beamed.
256 A duration with augmentation dot is notated
257 with the duration number followed by a period.
263 This ends the sequential music to be repeated. LilyPond will typeset
270 This line shows that Lily will print an accidental if that is
271 needed: the first C sharp of the bar will be printed with an accidental,
272 the second one without.
275 a8-. b-. cis-. d-. e-. fis-.
278 You can enter articulation signs either in a verbose form using a
279 shorthand. Here we demonstrate the shorthand: it is formed by a dash
280 and the character for the articulation to use, e.g. `@code{-.}' for
281 staccato as shown above.
288 Rests are denoted by the special notename `@code{r}'. You can also enter
289 an invisible rest by using the special notename `@code{s}'.
295 All articulations have a verbose form, like @code{\fermata}. The
296 command `@code{\fermata}' is not part of the core of the language (most
297 of the other discussed elements are), but it is a shorthand for a more
298 complicated description of a fermata. @code{\fermata} names that
299 description and is therefore called an @emph{identifier}.
314 This specifies a conversion from music to notation output. Most of
315 the details of this conversions (font sizes, dimensions, etc.) have
316 been taken care of, but to fit the output in this document, it has
317 to be smaller. We do this by setting the line width to 14 centimeters
318 (approximately 6 inches).
324 The last brace ends the @code{\score} block.
326 There are two things to note here. The format contains musical
327 concepts like pitches and durations, instead of symbols and positions:
328 the input format tries to capture the meaning of @emph{music}, and not
329 notation. Therefore Second, the format tries to be @emph{context-free}:
330 a note will sound the same regardless of the current time signature,
333 The purpose of LilyPond is explained informally by the term `music
334 typesetter'. This is not a fully correct name: not only does the
335 program print musical symbols, it also makes esthetic decisions. All
336 symbols and their placement is @emph{generated} from a high-level musical
337 description. In other words, LilyPond would be best
338 described by `music compiler' or `music to notation compiler'.
340 @node Lyrics and chords
341 @section Lyrics and chords
343 In this section we show how to typeset a song of unknown
344 origin.@footnote{The author would welcome information about the origin
349 title = "The river is flowing";
350 composer = "Traditional (?)";
352 \include "paper16.ly"
353 melody = \notes \relative c' @{
357 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
358 c4 c8 d [es () d] c4 | d4 es8 d c4.
363 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
364 ri -- ver is flo -- wing down to the sea.
367 accompaniment =\chords @{
369 c2:3- f:3-.7 d:min es4 c8:min r8
370 c2:min f:min7 g:7^3.5 c:min @}
375 \context ChordNames \accompaniment
378 \context Staff = mel @{
379 \property Staff.noAutoBeaming = ##t
380 \property Staff.automaticMelismata = ##t
383 \context Lyrics \text
385 \midi @{ \tempo 4=72;@}
386 \paper @{ linewidth = 10.0\cm; @}
391 The result would look this@footnote{The titling and font size shown
392 may differ, since the titling in this document is not generated by
395 @center @strong{The river is flowing}
400 title = "The river is flowing";
401 composer = "Traditional (?)";
403 \include "paper16.ly"
404 melody = \notes \relative c' {
408 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
409 c4 c8 d [es () d] c4 | d4 es8 d c4.
414 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
415 ri -- ver is flo -- wing down to the sea.
418 accompaniment =\chords {
420 c2:3- f:3-.7 d:min es4 c8:min r8
421 c2:min f:min7 g:7^3.5 c:min }
426 \context ChordNames \accompaniment
429 \context Staff = mel {
430 \property Staff.noAutoBeaming = ##t
431 \property Staff.automaticMelismata = ##t
434 \context Lyrics \text
436 \midi { \tempo 4=72;}
437 \paper { linewidth = 10.0\cm; }
441 Again, we will dissect the file line by line.
447 Information about the music you are about to typeset goes into a
448 @code{\header} block. The information in this block is not used by
449 LilyPond, but it is included in the output. @file{ly2dvi} uses this
450 information to print titles above the music.
453 title = "The river is flowing";
454 composer = "Traditional (?)";
456 the @code{\header} block contains assignments. An assignment starts
457 with a string. (which is unquoted, in this case). Then comes the
458 equal sign `@code{=}'. After the equal sign comes the expression you
459 want to store. In this case, you want to put in strings. The
460 information has to be quoted here, because it contains spaces. Each
461 assignment is finished with a semicolon.
464 \include "paper16.ly"
467 Smaller size for inclusion in a book.
470 melody = \notes \relative c' @{
473 The structure of the file will be the same as the previous one, a
474 @code{\score} block with music in it. To keep things readable, we will
475 give names to the different parts of music, and use the names to
476 construct the music within the score block.
482 The piece starts with an anacrusis of one eighth.
486 The key is C minor: we have three flats.
490 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
491 c4 c8 d [es () d] c4 | d4 es8 d c4.
496 We use explicit beaming. Since this is a song, we will turn automatic
497 beams off, and use explicit beaming where needed.
503 This ends the definition of @code{melody}. Note that there are no
504 semicolons after assignments at top level.
510 Another identifier assignment. This one is for the lyrics.
511 Lyrics are formed by syllables that have duration, and not by
512 notes. To make LilyPond parse words as syllables, switch it into
513 lyrics mode with @code{\lyrics}. Again, the brace after @code{\lyrics}
514 is a shorthand for @code{\sequential @{}.
517 The4 ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
518 ri- ver is flo- __ wing down to the sea.
522 The syllables themselves are separated by spaces. You can get syllable
523 extenders by entering `@code{__}', and centered hyphens with
524 `@code{-}@code{-}'. We enter the syllables as if they are all quarter notes
525 in length (hence the @code{4}), and use a feature to align the
526 syllables to the music (which obviously isn't all quarter notes.)
529 accompaniment =\chords @{
532 We'll put chords over the music. There is a special mode (analogous
533 to @code{\lyrics} and @code{\notes} mode) where you can give the names
534 of the chords you want, instead of the notes comprising the chord.
540 There is no accompaniment during the anacrusis.
546 A chord is started by the tonic of the chord. The
547 first one lasts a half note. An unadorned note creates a major
548 triad, while a minor triad is wanted. @code{3-} modifies the third to
549 be small. @code{7} modifies (adds) a seventh, which is small by default
550 to create the @code{f a c es} chord. Multiple modifiers must be
557 Some modifiers have predefined names, eg. @code{min} is the same as
558 @code{3-}, so @code{d-min} is a minor @code{d} chord.
561 c2:min f:min7 g:7^3.5 c:min @}
564 A named modifier @code{min} and a normal modifier @code{7} do not have
565 to be separated by a dot. Tones from a chord are removed with chord
566 subtractions. Subtractions are started with a caret, and they are
567 also separated by dots. In this example, @code{g:7^3.5} produces a
568 minor seventh. The brace ends the sequential music.
575 We assemble the music in the @code{\score} block. Melody, lyrics and
576 accompaniment have to sound at the same time, so they should be
577 @code{\simultaneous}.
583 Chord mode generates notes grouped in @code{\simultaneous} music. If
584 you remove the comment sign, you can see the chords in normal
585 notation: they will be printed as note heads on a separate
589 \context ChordNames \accompaniment
592 Normally, the notes that you enter are transformed into note heads.
593 The note heads alone make no sense, they need surrounding information:
594 a key signature, a clef, staff lines, etc. They need @emph{context}. In
595 LilyPond, these symbols are created by objects called `interpretation
596 contexts'. Interpretation contexts only exist during a run of
597 LilyPond. Interpretation contexts that are for printing music (as
598 opposed to playing music) are called `notation contexts'.
600 By default, LilyPond will create a Staff context for you. If you
601 removed the @code{%} sign in the previous line, you would see that
604 We don't want default contexts here, because we want chord names, not
605 note heads. An interpretation context can also created upon explicit
606 request. The keyword for such a request is @code{\context}. It takes
607 two arguments. The first is the name of an interpretation context.
608 The name is a string, it can be quoted with double quotes). The
609 second argument is the music that should be interpreted in this
610 context. For the previous line, we could have written @code{\context
611 Staff \accompaniment}, and get the same effect.
617 The lyrics need to be aligned with the melody. This is done by
618 combining both with @code{\addlyrics}. @code{\addlyrics} takes two
619 pieces of music (usually a melody and lyrics, in that order) and
620 aligns the syllables of the second piece under the notes of the
621 first piece. If you would reverse the order, the notes would be
622 aligned on the lyrics, which is not very useful. (Besides, it looks
626 \context Staff = mel @{
629 This is the argument of @code{\addlyrics}. We instantiate a
630 @code{Staff} context explicitly: should you chose to remove the comment
631 before the ``note heads'' version of the accompaniment, the
632 accompaniment will be on a nameless staff. The melody has to be on a
633 different staff as the accompaniment. This is accomplished by giving
634 the melody staff a different name.
637 \property Staff.noAutoBeaming = ##t
640 An interpretation context has variables that tune its behaviour. One
641 of the variables is @code{noAutoBeaming}. If set and non-zero (i.e.,
642 true) LilyPond will not try to put automatic beaming on the current
646 \property Staff.automaticMelismata = ##t
649 Similarly, we don't want to print a syllable when there is
650 a slur. This sets up the Staff context to signal slurs while
651 @code{\addlyrics} is processed.
658 Finally, we put the melody on the current staff. Note that the
659 @code{\property} directives and @code{\melody} are grouped in sequential
660 music, so the property settings are done before the melody is
664 \context Lyrics \text
667 The second argument of @code{\addlyrics} is the text. The text also
668 should not land on a Staff, but on a interpretation context for
669 syllables, extenders, hyphens etc. This context is called
676 This ends @code{\simultaneous}.
679 \midi @{ \tempo 4=72;@}
682 This makes the music go to a MIDI file. MIDI is great for
683 checking music you enter. You listen to the MIDI file: if you hear
684 something unexpected, it's probably a typing error. @code{\midi} is an
685 `output definition', a declaration that specifies how to output music
686 analogous to @code{\paper @{ @}}. You can specify the tempo using the
687 @code{\tempo} command, in this case the tempo of quarter notes is set
688 to 72 beats per minute.
691 \paper @{ linewidth = 10.0\cm; @}
694 We also want notation output. The linewidth is short so the piece
695 will be set in two lines.
706 Our third subject is a piece of piano music. The fragment in the input
707 file is a piano reduction of the G major Sinfonia by Giovanni Battista
708 Sammartini. It was composed around 1740.
713 \include "paper16.ly";
715 viola = \notes \relative c' \context Voice = viola {
722 oboes = \notes \relative c'' \context Voice = oboe {
723 \stemUp s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
724 \grace <e8( g> <d4 f> <c2 e> \times 2/3 { <d8 \< f> <e g> <f a> }
726 { \times 2/3 { a8 g c } \! c2 }
727 \context Voice = oboeTwo {
730 \property Grace.Stem \override #'direction = #-1
735 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
736 [<d ( f> < )f8. a>] <)b,8 d> r [<d16( f> <f8. )a>] <b,8 d> r |
737 [<c16( e> < )e8. g>] <c8 e,>
740 hoomPah = \notes \transpose c' {
741 c8 \translator Staff = top \stemDown
742 c'8 \translator Staff = bottom \stemUp }
744 hoomPahHoomPah = { [\hoomPah \hoomPah] }
746 bassvoices = \notes \relative c' {
748 \repeat unfold 4 {\hoomPahHoomPah}
749 \stemDown [c8 c'8] r4
751 < {\stemUp r2 <e4 c'> <c8 g'> }
752 \context Voice = reallyLow {\stemDown g2 ~ | g4 c8 } >
756 \context PianoStaff \notes <
757 \context Staff = top < \time 2/2;
761 \context Staff = bottom < \time 2/2; \clef bass;
768 linewidth = 15.0 \cm; }
772 If it looks like incomprehensible gibberish to you@dots{} Then you are
773 right. The author has doctored this example to have as many quirks in
774 one system as possible.
778 Lilypond and the Lilypond language is still under development, therefore
779 it is useful to indicate the Lilypond version of the file. Lilypond
780 will check the version number and warn you when the syntax has
781 changed. Also, the @code{convert-ly} program will be able to
782 update most of the syntax changes automatically.
784 viola = \notes \relative c' \context Voice = viola @{
786 In this example, you can see multiple parts on a staff. Each part is
787 associated with one notation context. This notation context handles
788 stems and dynamics (among others). The name of this context is
789 @code{Voice}. For each part we have to make sure that there is
790 precisely one Voice context.
794 @code{<} and @code{>} are short hands for @code{\simultaneous @{} and
795 @code{@}}. So the expression enclosed in @code{<} and @code{>} is a
796 chord. @code{\f} places a forte symbol under the chord.
800 \property Voice.verticalDirection = \down
802 @code{verticalDirection} is a property of the voice context. It
803 controls the directions of stems, articulations marks and other
806 If @code{verticalDirection} is set to @code{\down}
807 (identifier for the integer -1) the stems go down,
808 @code{\up} (identifier for the integer 1) makes the stems go up.
812 Relative octaves work a little differently with chords. The starting
813 point for the note following a chord is the first note of the chord. So
814 the @code{g} gets an octave up quote: it is a fifth above the starting
815 note of the previous chord (the central C).
820 @code{s} is a `spacer' rest. It does not print anything, but it does
821 have the duration of a rest.
823 oboes = \notes \relative c'' \context Voice = oboe @{
825 Now comes a part for two oboes. They play homophonically, so we
826 print the notes as one voice that makes chords. Again, we insure that
827 these notes are indeed processed by precisely one context with
830 \stemUp s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
832 @code{\stemUp} is an identifier reference. It is shorthand for
833 @code{\property Voice.verticalDirection = \up}. If possible, you
834 should use predefined identifiers like these for setting properties.
835 Your input will be less dependent upon the implementation of LilyPond.
837 \grace <e8( g> < )d4 f> <c2 e>
839 @code{\grace} introduces grace notes. It takes one argument, in this
840 case a chord. The slur started on the @code{e} of the chord
841 will be attached to the next note.@footnote{LilyPond will squirm
842 about unended Slurs. In this case, you can ignore the warning}.
846 Tuplets are made with the @code{\times} keyword. It takes two
847 arguments: a fraction and a piece of music. The duration of the
848 second argument is multiplied by the first argument. Triplets make
849 notes occupy 2/3 of their notated duration, so in this case the
852 @{ <d8 \< f> <e g> <f a> @}
854 The piece of music to be `tripletted' is sequential music containing
855 three notes. On the first chord (the @code{d}), a crescendo is started
860 At this point, the homophonic music splits into two rhythmically
861 different parts. We can't use a sequence of chords to enter this, so
862 we make a `chord' of sequences to do it. We start with the upper
863 voice, which continues with upward stems:
865 @{ \times 2/3 @{ a8 g c @} \! c2 @}
867 The crescendo is ended at the half note by the escaped exclamation
870 \context Voice = oboeTwo @{
873 We can't share stems with the other voice, so we have to create a new
874 @code{Voice} context. We give it the name @code{oboeTwo} to distinguish
875 it from the other context. Stems go down in this voice.
879 When a grace section is processed, a @code{Grace} context is
880 created. This context acts like a miniature score of its own. It has
881 its own time bookkeeping, and you can make notes, beams, slurs
882 etc. Here we fiddle with a property and make a beam. The argument of
883 @code{\grace} is sequential music.
886 \property Grace.verticalDirection = \down
890 Normally, grace notes are always stem up, but in this case, the upper
891 voice interferes. We set the stems down here.
893 As far as relative mode is concerned, the previous note is the
894 @code{c'''2} of the upper voice, so we have to go an octave down for
901 This ends the two-part section.
904 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
906 @code{\stemBoth} ends the forced stem directions. From here, stems are
907 positioned as if it were single part music.
909 The bass has a little hoom-pah melody to demonstrate parts switching
910 between staffs. Since it is repetitive, we use identifiers:
912 hoomPah = \notes \transpose c' @{
914 Transposing can be done with @code{\transpose}. It takes two
915 arguments; the first specifies what central C should be transposed to.
916 The second is the to-be-transposed music. As you can see, in this
917 case, the transposition is a no-op. Central C is transposed to
920 The purpose of this no-op is circumventing relative mode. Relative
921 mode can not be used in conjunction with transposition, so relative
922 mode will leave the contents of @code{\hoomPah} alone. We can use it
923 without having to worry about getting the motive in a wrong
924 octave@footnote{@code{hoomPah = \relative @dots{}} would be more
925 intuitive to use, but that would not let me plug @code{\transpose}
928 c8 \translator Staff = top \stemDown
930 We assume that the first note will be put in the lower staff. After
931 that note we switch to the upper staff with @code{\translator}. To be
932 precise, this @code{\translator} entry switches the current voice to a
933 @code{Staff} named @code{top}. So we have to name the upper staff
934 `@code{top}'. Stem directions are set to avoid interfering with the
937 c'8 \translator Staff = bottom \stemUp @}
939 Then a note is put on the upper staff, and we switch again. We have
940 to name the lower staff `@code{bottom}'.
942 hoomPahHoomPah = @{ [\hoomPah \hoomPah] @}
944 Put two of these fragments in sequence, and beam them.@example
945 bassvoices = \notes \relative c' @{
947 \repeat unfold 4 @{\hoomPahHoomPah @}
949 Entering the bass part is easy: the hoomPahHoomPah variable is
950 repeated four times; @code{unfold} means that all four repetitions
951 should be written out.
953 \context Voice = reallyLow @{\stemDown g2 ~ | g4 c8 @} >
955 After skipping some lines, we see @code{~}. This mark makes ties.
959 For piano music, a special context is needed to get cross staff
960 beaming right. It is called @code{PianoStaff}.
962 \context Staff = bottom < \time 2/2; \clef bass;
964 The bottom staff must have a different clef.
968 To make some more room on the line, the first (in this case the only)
969 line is not indented. The line still looks very cramped, but that is due
970 to the format of this tutorial.
972 This example shows a lot of features, but the organisation isn't
973 perfect. For example, it would be less confusing to use a chord
974 containing sequential music than a sequence of chords for the oboe
977 [TODO: demonstrate Hara-Kiri with scores and part extraction.]
979 @node end of tutorial
982 That's all folks. From here, you can either try fiddling with input
983 files, or you can read the reference manual.