* Orchestral music::
* Contemporary notation::
* Educational use::
+* Other stuff::
@end menu
* Text scripts::
* Text spanners::
* Analysis brackets::
-* Articulations::
@end menu
Examples: @inputfileref{input/@/regression,note@/-group@/-bracket@/.ly}.
-@node Articulations
-@subsection Articulations
-@cindex Articulations
-
-@cindex articulations
-@cindex scripts
-@cindex ornaments
-
-A variety of symbols can appear above and below notes to indicate
-different characteristics of the performance. They are added to a note
-by adding a dash and the character signifying the
-articulation. They are demonstrated here
-
-@lilypondfile[quote,raggedright]{script-abbreviations.ly}
-
-The meanings of these shorthands can be changed. See
-@file{ly/@/script@/-init@/.ly} for examples.
-
-
-The script is automatically placed, but the direction can be forced as
-well. Like other pieces of LilyPond code, @code{_} will place them
-below the staff, and @code{^} will place them above.
-
-
-@lilypond[quote,raggedright,fragment,verbatim]
-c''4^^ c''4_^
-@end lilypond
-
-Other symbols can be added using the syntax
-@var{note}@code{\}@var{name}. Again, they
-can be forced up or down using @code{^} and @code{_},
-e.g.,
-
-@lilypond[quote,raggedright,verbatim,fragment,relative=2]
-c\fermata c^\fermata c_\fermata
-@end lilypond
-
-
-
-@cindex accent
-@cindex marcato
-@cindex staccatissimo
-@cindex espressivo
-@cindex fermata
-@cindex stopped
-@cindex staccato
-@cindex portato
-@cindex tenuto
-@cindex upbow
-@cindex downbow
-@cindex foot marks
-@cindex organ pedal marks
-@cindex turn
-@cindex open
-@cindex flageolet
-@cindex reverseturn
-@cindex trill
-@cindex prall
-@cindex mordent
-@cindex prallprall
-@cindex prallmordent
-@cindex prall, up
-@cindex prall, down
-@cindex mordent
-@cindex thumb marking
-@cindex segno
-@cindex coda
-@cindex varcoda
-
-Here is a chart showing all scripts available,
-
-@lilypondfile[raggedright,quote]{script-chart.ly}
-
-
-The vertical ordering of scripts is controlled with the
-@code{script-priority} property. The lower this number, the closer it
-will be put to the note. In this example, the
-@internalsref{TextScript} (the sharp symbol) first has the lowest
-priority, so it is put lowest in the first example. In the second, the
-prall trill (the @internalsref{Script}) has the lowest, so it is on the
-inside. When two objects have the same priority, the order in which
-they are entered decides which one comes first.
-
-
-@lilypond[verbatim,relative=3,raggedright,fragment,quote]
-\once \override TextScript #'script-priority = #-100
-a4^\prall^\markup { \sharp }
-
-\once \override Script #'script-priority = #-100
-a4^\prall^\markup { \sharp }
-@end lilypond
-
-
-
-
-@seealso
-
-Program reference: @internalsref{ScriptEvent}, and @internalsref{Script}.
-
-@refbugs
-
-These signs appear in the printed output but have no effect on the
-MIDI rendering of the music.
-
-
-
-
@code{\setEasyHeads}
+@node Other stuff
+@section Other stuff
+
+This is a temporary placeholder for stuff that's being moved to Advanced.
+It's just here so that somebody doesn't build the docs and then email me
+to complain that I've lost some doc sections. :)
+
+@menu
+* Aligning to cadenzas::
+* Stems::
+* Transpose::
+* Ottava brackets::
+* Time administration::
+* Controlling formatting of prefatory matter::
+* Setting automatic beam behavior::
+* Beam formatting::
+@end menu
+
+
+@node Aligning to cadenzas
+@subsection Aligning to cadenzas
+
+
+In an orchestral context, cadenzas present a special problem:
+when constructing a score that includes a cadenza, all other
+instruments should skip just as many notes as the length of the
+cadenza, otherwise they will start too soon or too late.
+
+A solution to this problem are the functions @code{mmrest-of-length}
+and @code{skip-of-length}. These Scheme functions take a piece of music
+as argument, and generate a @code{\skip} or multi-rest, exactly as
+long as the piece. The use of @code{mmrest-of-length} is demonstrated
+in the following example.
+
+@lilypond[verbatim,raggedright,quote]
+cadenza = \relative c' {
+ c4 d8 << { e f g } \\ { d4. } >>
+ g4 f2 g4 g
+}
+
+\new GrandStaff <<
+ \new Staff { \cadenza c'4 }
+ \new Staff {
+ #(ly:export (mmrest-of-length cadenza))
+ c'4
+ }
+>>
+@end lilypond
+
+
+@node Stems
+@subsection Stems
+
+Whenever a note is found, a @internalsref{Stem} object is created
+automatically. For whole notes and rests, they are also created but
+made invisible.
+
+@refcommands
+
+@cindex @code{\stemUp}
+@code{\stemUp},
+@cindex @code{\stemDown}
+@code{\stemDown},
+@cindex @code{\stemNeutral}
+@code{\stemNeutral}.
+
+
+@node Transpose
+@subsection Transpose
+@cindex Transpose
+@cindex transposition of pitches
+@cindex @code{\transpose}
+
+A music expression can be transposed with @code{\transpose}. The
+syntax is
+@example
+\transpose @var{from} @var{to} @var{musicexpr}
+@end example
+
+This means that @var{musicexpr} is transposed by the interval between
+the pitches @var{from} and @var{to}: any note with pitch @code{from}
+is changed to @code{to}.
+
+
+For example, consider a piece written in the key of D-major. If
+this piece is a little too low for its performer, it can be
+transposed up to E-major with
+@example
+\transpose d e @dots{}
+@end example
+
+Consider a part written for violin (a C instrument). If
+this part is to be played on the A clarinet, the following
+transposition will produce the appropriate part
+
+@example
+\transpose a c @dots{}
+@end example
+
+@code{\transpose} distinguishes between enharmonic pitches: both
+@code{\transpose c cis} or @code{\transpose c des} will transpose up
+half a tone. The first version will print sharps and the second
+version will print flats
+
+@lilypond[quote,raggedright,verbatim]
+mus = { \key d \major cis d fis g }
+\context Staff {
+ \clef "F" \mus
+ \clef "G"
+ \transpose c g' \mus
+ \transpose c f' \mus
+}
+@end lilypond
+
+@code{\transpose} may also be used to input written notes for a
+transposing instrument. Pitches are normally entered into LilyPond
+in C (or ``concert pitch''), but they may be entered in another
+key. For example, when entering music for a B-flat trumpet which
+begins on concert D, one would write
+
+@example
+\transpose c bes @{ e4 @dots{} @}
+@end example
+
+To print this music in B-flat again (ie producing a trumpet part,
+instead of a concert pitch conductor's score) you would wrap the
+existing music with another @code{transpose}
+
+@example
+\transpose bes c @{ \transpose c bes @{ e4 @dots{} @} @}
+@end example
+
+
+@seealso
+
+Program reference: @internalsref{TransposedMusic}, and
+@internalsref{UntransposableMusic}.
+
+@refbugs
+
+If you want to use both @code{\transpose} and @code{\relative},
+you must put @code{\transpose} outside of @code{\relative}, since
+@code{\relative} will have no effect music that appears inside a
+@code{\transpose}.
+
+
+@node Ottava brackets
+@subsection Ottava brackets
+
+`Ottava' brackets introduce an extra transposition of an octave for
+the staff. They are created by invoking the function
+@code{set-octavation}
+
+@cindex ottava
+@cindex 15ma
+@cindex octavation
+
+@lilypond[quote,raggedright,verbatim,fragment]
+\relative c''' {
+ a2 b
+ #(set-octavation 1)
+ a b
+ #(set-octavation 0)
+ a b
+}
+@end lilypond
+
+The @code{set-octavation} function also takes -1 (for 8va bassa) and 2
+(for 15ma) as arguments. Internally the function sets the properties
+@code{ottavation} (e.g., to @code{"8va"}) and
+@code{centralCPosition}. For overriding the text of the bracket, set
+@code{ottavation} after invoking @code{set-octavation}, i.e.,
+
+@lilypond[quote,raggedright,verbatim]
+{
+ #(set-octavation 1)
+ \set Staff.ottavation = #"8"
+ c'''
+}
+@end lilypond
+
+@seealso
+
+Program reference: @internalsref{OttavaBracket}.
+
+Examples: @inputfileref{input/@/regression,ottava@/.ly},
+@inputfileref{input/@/regression,ottava@/-broken@/.ly}.
+
+@refbugs
+
+@code{set-octavation} will get confused when clef changes happen
+during an octavation bracket.
+
+
+@node Time administration
+@subsection Time administration
+
+Time is administered by the @internalsref{Time_signature_engraver},
+which usually lives in the @internalsref{Score} context.
+The bookkeeping deals with the following variables
+
+@table @code
+@item currentBarNumber
+The measure number.
+
+@item measureLength
+The length of the measures in the current time signature. For a 4/4
+time this is@tie{}1, and for 6/8 it is 3/4.
+
+@item measurePosition
+The point within the measure where we currently are. This quantity
+is reset to@tie{}0 whenever it exceeds @code{measureLength}. When that
+happens, @code{currentBarNumber} is incremented.
+
+@item timing
+If set to true, the above variables are updated for every time
+step. When set to false, the engraver stays in the current measure
+indefinitely.
+@end table
+
+Timing can be changed by setting any of these variables explicitly.
+In the next example, the 4/4 time signature is printed, but
+@code{measureLength} is set to 5/4. After a while, the measure is
+shortened by 1/8, by setting @code{measurePosition} to 7/8 at 2/4
+in the measure, so the next bar line will fall at 2/4 + 3/8. The
+3/8 arises because 5/4 normally has 10/8, but we have manually
+set the measure position to be 7/8 and 10/8 - 7/8 = 3/8.
+
+@lilypond[quote,raggedright,verbatim,relative,fragment]
+\set Score.measureLength = #(ly:make-moment 5 4)
+c1 c4
+c1 c4
+c4 c4
+\set Score.measurePosition = #(ly:make-moment 7 8)
+b8 b b
+c4 c1
+@end lilypond
+
+
+@node Controlling formatting of prefatory matter
+@subsection Controlling formatting of prefatory matter
+
+@c This section will be moved to somewhere else soon. -gp
+This example demonstrates how to place prefatory matter
+(such as the clef and key signature) at the end of a line.
+
+@lilypond[quote,verbatim]
+\transpose c c' {
+ \override Staff.Clef
+ #'break-visibility = #end-of-line-visible
+ \override Staff.KeySignature
+ #'break-visibility = #end-of-line-visible
+ \set Staff.explicitClefVisibility = #end-of-line-visible
+ \set Staff.explicitKeySignatureVisibility = #end-of-line-visible
+
+ % We want the time sig to take space, otherwise there is not
+ % enough white at the start of the line.
+
+ \override Staff.TimeSignature #'transparent = ##t
+ \set Score.defaultBarType = #"empty"
+
+ c1 d e f g a b c
+ \key d \major
+ \break
+
+ % see above.
+ \time 4/4
+
+ d e fis g a b cis d
+ \key g \major
+ \break
+ \time 4/4
+}
+@end lilypond
+
+
+@node Setting automatic beam behavior
+@subsection Setting automatic beam behavior
+
+@cindex @code{autoBeamSettings}
+@cindex @code{(end * * * *)}
+@cindex @code{(begin * * * *)}
+@cindex automatic beams, tuning
+@cindex tuning automatic beaming
+
+@c [TODO: use \applycontext]
+
+In normal time signatures, automatic beams can start on any note but can
+only end in a few positions within the measure: beams can end on a beat,
+or at durations specified by the properties in
+@code{autoBeamSettings}. The defaults for @code{autoBeamSettings}
+are defined in @file{scm/@/auto@/-beam@/.scm}.
+
+The value of @code{autoBeamSettings} is changed with three functions,
+@example
+#(override-auto-beam-setting
+ '(@var{be} @var{p} @var{q} @var{n} @var{m}) @var{a} @var{b}
+ [@var{context}])
+#(score-override-auto-beam-setting
+ '(@var{be} @var{p} @var{q} @var{n} @var{m}) @var{a} @var{b})
+#(revert-auto-beam-setting '(@var{be} @var{p} @var{q} @var{n} @var{m})
+ [@var{context}])
+@end example
+Here, @var{be} is the symbol @code{begin} or @code{end}, and
+@var{context} is an optional context (default: @code{'Voice}). It
+determines whether the rule applies to begin or end-points. The
+quantity @var{p}/@var{q} refers to the length of the beamed notes (and
+`@code{* *}' designates notes of any length), @var{n}/@var{M} refers
+to a time signature (wildcards `@code{* *}' may be entered to
+designate all time signatures), @var{a}/@var{b} is a duration. By
+default, this command changes settings for the current voice. It is
+also possible to adjust settings at higher contexts, by adding a
+@var{context} argument. @code{score-override-auto-beam-setting} is
+equal to @code{override-auto-beam-setting} with the argument
+@var{context} set to @code{'Score}.
+
+For example, if automatic beams should end on every quarter note, use
+the following
+@example
+#(override-auto-beam-setting '(end * * * *) 1 4 'Staff)
+@end example
+Since the duration of a quarter note is 1/4 of a whole note, it is
+entered as @code{(ly:make-moment 1 4)}.
+
+The same syntax can be used to specify beam starting points. In this
+example, automatic beams can only end on a dotted quarter note
+@example
+#(override-auto-beam-setting '(end * * * *) 3 8)
+@end example
+In 4/4 time signature, this means that automatic beams could end only on
+3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
+3/8, has passed within the measure).
+
+Rules can also be restricted to specific time signatures. A rule that
+should only be applied in @var{N}/@var{M} time signature is formed by
+replacing the second asterisks by @var{N} and @var{M}. For example, a
+rule for 6/8 time exclusively looks like
+@example
+#(override-auto-beam-setting '(begin * * 6 8) @dots{})
+@end example
+
+If a rule should be to applied only to certain types of beams, use the
+first pair of asterisks. Beams are classified according to the
+shortest note they contain. For a beam ending rule that only applies
+to beams with 32nd notes (and no shorter notes), use @code{(end 1 32 *
+*)}.
+
+@cindex automatic beam generation
+@cindex autobeam
+@cindex @code{autoBeaming}
+@cindex lyrics
+
+If beams are used to indicate melismata in songs, then automatic
+beaming should be switched off. This is done by setting
+@code{autoBeaming} to @code{#f}.
+
+@refcommands
+
+@cindex @code{\autoBeamOff}
+@code{\autoBeamOff},
+@cindex @code{\autoBeamOn}
+@code{\autoBeamOn}.
+
+
+@refbugs
+
+If a score ends while an automatic beam has not been ended and is
+still accepting notes, this last beam will not be typeset at all. The
+same holds polyphonic voices, entered with @code{<< @dots{} \\ @dots{}
+>>}. If a polyphonic voice ends while an automatic beam is still
+accepting notes, it is not typeset.
+
+The rules for ending a beam depend on the shortest note in a beam.
+So, while it is possible to have different ending rules for eight
+beams and sixteenth beams, a beam that contains both eight and
+sixteenth notes will use the rules for the sixteenth beam.
+
+In the example below, the autobeamer makes eighth beams and sixteenth
+end at three eighths. The third beam can only be corrected by
+specifying manual beaming.
+
+@lilypond[quote,raggedright,fragment,relative=1]
+#(override-auto-beam-setting '(end * * * *) 3 8)
+% rather show case where it goes wrong
+%\time 12/8 c'8 c c c16 c c c c c c[ c c c] c8[ c] c4
+\time 12/8 c'8 c c c16 c c c c c c c c c c8 c c4
+@end lilypond
+It is not possible to specify beaming parameters that act differently in
+different parts of a measure. This means that it is not possible to use
+automatic beaming in irregular meters such as @code{5/8}.
+
+@node Beam formatting
+@subsection Beam formatting
+
+
+When a beam falls in the middle of the staff, the beams point normally
+down. However, this behaviour can be altered with the
+@code{neutral-direction} property.
+
+
+@lilypond[quote,raggedright,relative=2,fragment,verbatim]
+{
+ b8[ b]
+ \override Beam #'neutral-direction = #-1
+ b[ b]
+ \override Beam #'neutral-direction = #1
+ b[ b]
+}
+@end lilypond
+
projects / lilypond.git / commitdiff