@chapter Reference Manual
This document describes GNU LilyPond and its input format. The last
-revision of this document was made for LilyPond 1.3.145.
+revision of this document was made for LilyPond 1.3.145. It supposes a
+passing familiarity with how LilyPond input works. New users are
+encouraged to study the tutorial first.
@menu
can be forced by adding an exclamation mark @code{!} after the pitch. A
cautionary accidental,
@cindex cautionary accidental
+@cindex parenthesized accidental
i.e., an accidental within parentheses can be obtained by adding the
question mark `@code{?}' after the pitch.
@cindex @code{\key}
-Changing the key signature is done with the @code{\key} command.
+Setting or changing the key signature is done with the @code{\key}
+command.
@example
@code{\key} @var{pitch} @var{type}
@end example
This command sets the context property @code{Staff.keySignature}.
Non-standard key signatures can be specified by setting this property
-directly, see the generated documentation.
+directly, see the generated documentation for @rgrob{KeySignature}.
The printed signature is a @code{KeySignature} grob.
@node Clef
@subsection Clef
@cindex @code{\clef}
+
+The clef can be set or changed with the @code{\clef} command.
@example
- \clef @var{clefname} @code{;}
+ \clef @var{clefname}
@end example
Shortcut for
@cindex meter
@cindex @code{\time}
-The time signature is changed by the @code{\time} command. Syntax:
+The time signature is set or changed by the @code{\time}
+command. Syntax:
@example
- \time @var{numerator}@code{/}@var{denominator}
+ \time @var{n}@code{/}@var{d}
@end example
Internally, this is a shortcut for doing
@example
- \property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator})
+\property Score.timeSignatureFraction = #'(@var{n} . @var{d})
+\property Score.beatLength = #(make-moment 1 @var{d})
+\property Score.measureLength = #(make-moment @var{n} @var{d})
@end example
-The property @code{timeSignatureFraction} is used to determine where bar
-lines should be inserted, and how automatic beams should be generated.
+These properties @code{timeSignatureFraction} determine where bar lines
+should be inserted, and how automatic beams should be
+generated.
+
+Changing the value of @code{timeSignatureFraction} also causes a
+fraction to be printed. This grob is @code{TimeSignature}.
+
+The actual symbol that's printed can be customised with the style
+property.
+@lilypond[fragment, verbatim, singleline]
+\time 3/4 s2
+\property Staff.TimeSignature \override #'style = #'C
+\time 4/4 s2
+\property Staff.TimeSignature \override #'style = #'()
+\time 4/4 s2
+\property Staff.TimeSignature \override #'style = #'C
+\time 2/2 s2
+@end lilypond
+
+There are many more options for the layout of this grob. They are
+selected through the @code{style} grob property.
-The grob is @code{TimeSignature}. There are many options for the layout
-of this grob. They are selected through the @code{style} grob
-property. See @file{input/test/time.ly} for examples.
+@c FIXME: this isn't documented except in example?
+See
+@file{input/test/time.ly} for examples.
@c . {Partial}
@subsection Partial
\tempo @var{duration} = @var{perminute}
@end example
-For example, @code{\tempo 4 = 76;} requests output with 76 quarter notes
+For example, @code{\tempo 4 = 76} requests output with 76 quarter notes
per minute.
@refbugs
Ending a staff or score with grace notes may also generate a run-time
error, since there will be no main note to attach the grace notes to.
-
The present implementation of grace notes is not robust and generally
kludgey. We expect it to change after LilyPond 1.4. Syntax changes might
also be implemented.
-
-
@menu
* Glissando ::
* Dynamics::
is to be expected that more functionality -- especially for the MIDI
backend -- will be implemented at some point in the future.
+Volta repeats are printed over all staffs in a score. You must turn them
+off explicitly, for example by doing
+@example
+ \property Staff.VoltaBracket = \turnOff
+@end example
+
@node Manual repeat commands
@subsection Manual repeat commands
@example
\translator Staff = @var{staffname} @var{music}
@end example
-The string @var{staffname} is the name of the staff. Typically it is
-@code{"up"} or @code{"down"}.
-
-Formally, this construct is a music expression indicating that the
-context which is a direct child of the context of type
-@var{contexttype} should be shifted to a context of type
-@var{contexttype} and the specified name.
+The string @var{staffname} is the name of the staff. It switches the
+current voice from its current staff to the Staff called
+@var{staffname}. Typically @var{staffname} is @code{"up"} or
+@code{"down"}.
+The formal definition of this construct is obtuse, but for the sake of
+completeness we give it here.
@cindex @code{\translator}
@example
\translator @var{contexttype} = @var{name}
@end example
+Formally, this construct is a music expression indicating
+that the context which is a direct child of the context of type
+@var{contexttype} should be shifted to a context of type
+@var{contexttype} and the specified name.
@c . {Pedals}
The symbols that are printed can be modified by setting
@code{pedal@var{X}Strings}, where @var{X} is one of the pedal
-types. Refer to the generated documentation for more information.
+types. Refer to the generated documentation of @rgrob{PianoPedal} for
+more information.
@refbugs
\score { \notes {
\property Staff.instrument = #`((kern . 0.5) (lines
- "2 Clarinetti" (rows " (B" ,text-flat ")")))
+ "2 Clarinetti" (columns " (B" ,text-flat ")")))
c'' 4 }
}
@end lilypond
There are a number of other properties that you can use to tweak the
behavior of part combining, refer to the automatically generated
-documentation. Look at the documentation of the responsible engravers,
-@code{Thread_devnull_engraver}, @code{Voice_devnull_engraver} and
-@code{A2_engraver}.
+documentation of @reng{Thread_devnull_engraver} and
+@reng{Voice_devnull_engraver}. Look at the documentation of the
+responsible engravers, @code{Thread_devnull_engraver},
+@code{Voice_devnull_engraver} and @code{A2_engraver}.
@refbugs
head: markup | (markup+)
markup-item: property | abbrev
property: (@var{key} . @var{value})
-abbrev: @code{rows lines roman music bold italic named super sub text}
+abbrev: @code{columns lines roman music bold italic named super sub
+overstrike text}
@code{finger volta timesig mmrest mark script large Large dynamic}
@end example
The markup is broken down and converted into a list of grob properties,
which are prepended to the property list. The @var{key}-@var{value}
pair is a grob property. A list of properties available is included in
-the generated documentation for @code{text-interface}
+the generated documentation for @rint{Text_interface}.
The following abbreviations are currently defined:
@table @code
-@item rows
-horizontal mode: set all text on one line (default)
+@item columns
+ horizontal mode: set all text on one line (default)
@item lines
vertical mode: set every text on a new line
@item roman
superscript
@item sub
subscript
+@item overstrike
+ the next text or character overstrikes this one
@item finger
select fingering number fontstyle
@item volta
marking:
@lilypond[verbatim]
-#(define note '(rows
+#(define note '(columns
(music "noteheads-2" ((kern . -0.1) "flags-stem"))))
-#(define eight-note `(rows ,note ((kern . -0.1)
+#(define eight-note `(columns ,note ((kern . -0.1)
(music ((raise . 3.5) "flags-u3")))))
#(define dotted-eight-note
- `(rows ,eight-note (music "dots-dot")))
+ `(columns ,eight-note (music "dots-dot")))
\score {
\notes\relative c'' {
- a1^#`((rows (font-relative-size . -1)) ,dotted-eight-note " = 64")
+ a1^#`((columns (font-relative-size . -1)) ,dotted-eight-note " = 64")
}
\paper {
linewidth = -1.
music notation. The syntax is
@example
- @code{\paper @{} @var{[paperidentifier]} @var{items} @code{@}}
+ @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
@end example
where each of the items is one of
@cindex page breaks
@cindex breaking pages
-
Page breaks are normally computed by @TeX{}, so they are not under
direct control of LilyPond. However, you can insert a commands into the
-@file{.tex} output to instruct @TeX{} where to break pages. For more
-details, see the example file @file{input/test/between-systems.ly}
+@file{.tex} output to instruct @TeX{} where to break pages, by inserting
+the command @code{\newpage}
+@cindex @code{\newpage}
+
+@example
+ \newpage
+@end example
+@c why do so difficult?
+@c maybe should explain contents of between-system.ly,
+@c but not now, we're talking about page breaks here.
+@c For more
+@c details, see the example file @file{input/test/between-systems.ly}
@c . {Output scaling}
is used to generate PostScript. Alternatively, @file{ly2dvi} can be
used to generate the .dvi for you.
+@refbugs
+
+Titling is not generated.
+
@node PostScript output
@subsection PostScript output
necessary .pfa files to LilyPond's .ps output, or upload them to the
printer before printing.
-Titling is not generated.
+The line height calculation is broken, you must set @var{lineheight} in
+the paperblock if you have more than one staff in your score, e.g.
+
+@example
+ ...
+ \paper @{
+ % Set line height to 40 staff spaces
+ lineheight = 40
+ @}
+@end example
@node Scheme output
@subsection Scheme output
If you want to build a context from scratch, you must also supply the
following extra information:
@itemize @bullet
- @item A name, specified by @code{\name @var{contextname};}.
+ @item A name, specified by @code{\name @var{contextname}}.
@item A cooperation module. This is specified by @code{\type
-@var{typename};}.
+@var{typename}}.
@end itemize
This is an example: