Guide, node Updating translation committishes..
@end ignore
-@c \version "2.16.0"
+@c \version "2.17.6"
@node General input and output
@chapter General input and output
circumstances to avoid errors:
@itemize
+
@item Around every opening and closing curly bracket.
+
@item After every command or variable, i.e. every item that
begins with a @code{\} sign.
+
@item After every item that is to be interpreted as a Scheme
expression, i.e. every item that begins with a @code{#}@tie{}sign.
+
@item To separate all elements of a Scheme expression.
-@item In @code{lyricmode} to separate all the terms in both
-@code{\override} and @code{\set} commands. In particular, spaces
-must be used around the dot and the equals sign in commands like
-@code{\override Score . LyricText #'font-size = #5} and before and
-after the entire command.
+
+@item In @code{lyricmode} before and after @code{\set} and
+@code{\override} commands.
@end itemize
@table @emph
@item Event-based footnotes
-are attached to a particular event. Examples
-for such events are single notes, notes inside a chord, articulations
-(like beams, slurs, fingering indications, accents, dynamics) and
-lyrics.
-
-@item Time-based footnotes
-are bound to a particular point of time in a
-musical context. Some commands like @code{\time} and @code{\clef}
-don't actually use events for creating objects like time signatures
-and clefs. Neither does a chord create an event of its own: its
-stem or flag is created at the end of a time step (nominally through
-one of the note events inside). A time-based footnote allows
-annotating such layout objects without referring to an event.
+are attached to a particular event. Examples for such events are
+single notes, articulations (like fingering indications, accents,
+dynamics), and post-events (like slurs and manual beams). The
+general form for event-based footnotes is as follows:
-@end table
+@example
+[@var{direction}] \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
+@end example
-The full form of a footnote command for both Event- and Time-based
-footnotes is
+@item Time-based footnotes
+are bound to a particular point of time in a musical context. Some
+commands like @code{\time} and @code{\clef} don't actually use events
+for creating objects like time signatures and clefs. Neither does a
+chord create an event of its own: its stem or flag is created at the
+end of a time step (nominally through one of the note events inside).
+Exactly which of a chord's multiple note events will be deemed the
+root cause of a stem or flag is undefined. So for annotating those,
+time-based footnotes are preferable as well.
+
+A time-based footnote allows such layout objects to be annotated
+without referring to an event. The general form for Time-based
+footnotes is:
@example
-[@var{direction}] \footnote [@var{mark}] @var{offset} [@var{grob-name}] @var{footnote} @var{music}
+\footnote [@var{mark}] @var{offset} @var{footnote} [@var{Context}].@var{GrobName}
@end example
-The elements are:
+@end table
+
+The elements for both forms are:
@table @var
offsets are taken from the right/top edge, negative values from the
left/bottom edge and zero implies the mark is centered on the edge.
-@item grob-name
-specifies a type of grob to mark (like @samp{#'Flag}). If it is
-given, a grob of that type associated with the referenced @var{music}
-will be used as the reference point. It can be omitted (or replaced
-with @code{\default}) if the footnote mark is to be attached to the
-directly created grob in @var{music}.
+@item Context
+is the context in which the grob being footnoted is created. It
+may be omitted if the grob is in a bottom context, e.g. a
+@code{Voice} context.
+
+@item GrobName
+specifies a type of grob to mark (like @samp{Flag}). If it is
+specified, the footnote is not attached to a music expression in
+particular, but rather to all grobs of the type specified which
+occur at that moment of musical time.
@item footnote
is the markup or string specifying the footnote text to use at the
bottom of the page.
@item music
-is the music event or chord constituent or post-event that is being
-annotated. While it cannot be omitted, it can be replaced by
-@code{\default} in which case the footnote is not attached to a music
-expression in particular, but rather to a moment of time. It is
-mandatory in this case to use the @var{grob-name} argument for
-selecting an affected grob type, like @samp{#'TimeSignature}.
+is the music event or post-event or articulation
+that is being annotated.
@end table
@cindex footnotes, event-based
-The simplest form of event-based footnotes is just
+A footnote may be attached to a layout object directly caused
+by the event corresponding to @var{music} with the syntax:
@example
-\footnote @var{offset} @var{footnote} @var{music}
+\footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
@end example
-This kind of footnote is attached to a layout object directly caused
-by the event corresponding to @var{music}.
-
@lilypond[quote,verbatim,papersize=a8landscape]
\book {
\header { tagline = ##f }
@end lilypond
If the footnote is to be attached to a post-event or articulation
-the @code{\footnote} command must be preceded by a direction
+the @code{\footnote} command @emph{must} be preceded by a direction
indicator, @code{-, _, ^}, and followed by the post-event or
articulation to be annotated as the @var{music} argument. In this
form the @code{\footnote} can be considered to be simply a copy of
-its last argument with a footnote mark attached to it.
+its last argument with a footnote mark attached to it. The syntax
+is:
+
+@example
+@var{direction} \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
+@end example
@lilypond[quote,verbatim,papersize=a8landscape]
\book {
}
@end lilypond
-Custom marks can be used as alternatives to numerical marks, and the
-annotation line joining the marked object to the mark can be
-suppressed:
+@subsubsubheading Time-based footnotes
+
+@cindex footnotes, time-based
+
+If the layout object being footmarked is @emph{indirectly} caused by
+an event (like an @code{Accidental} or @code{Stem} caused by a
+@code{NoteHead} event), the @var{GrobName} of the layout object
+is required after the footnote text instead of @var{music}:
@lilypond[quote,verbatim,papersize=a8landscape]
\book {
\header { tagline = ##f }
- \relative c' {
- \footnote "*" #'(0.5 . -2) \markup { \italic "* The first note" }
- a'4 b8
- \footnote \markup { \super "$" } #'(0.5 . 1)
- \markup { \super "$" \italic " The second note" }
- e c4
- \once \override Score.FootnoteItem #'annotation-line = ##f
- b-\footnote \markup \tiny "+" #'(0.1 . 0.1)
- \markup { \super "+" \italic " Editorial" } \p
+ \relative c'' {
+ \footnote #'(-1 . -3) "A flat" Accidental
+ aes4 c
+ \footnote #'(-1 . 0.5) "Another flat" Accidental
+ ees
+ \footnote #'(1 . -2) "A stem" Stem
+ aes
}
}
@end lilypond
-More examples of custom marks are shown in
-@ref{Footnotes in stand-alone text}.
+Note, however, that when a GrobName is specified, a footnote
+will be attached to all grobs of that type at the current time step:
-Marking an entire chord in this manner is not possible since a
-chord does not produce an event separate from that of its chord
-constituents, but the constituents themselves can be marked.
+@lilypond[quote,verbatim,papersize=a8landscape]
+\book {
+ \header { tagline = ##f }
+ \relative c' {
+ \footnote #'(-1 . 3) "A flat" Accidental
+ <ees ges bes>4
+ \footnote #'(2 . 0.5) "Articulation" Script
+ c'->-.
+ }
+}
+@end lilypond
-If the layout object being footmarked is @emph{indirectly} caused by
-an event (like an @code{Accidental} or @code{Stem} caused by a
-@code{NoteHead}), an additional symbol argument, the @var{grob-name},
-is required before the footnote text:
+A chord constituent can be given an individual footnote. A
+@code{NoteHead} is the (only) grob directly caused from a chord
+constituent, so an Event-based footnote command should be used to
+add a footnote to a @code{NoteHead} within a chord. All other
+grobs within a chord are indirectly caused and should be footnoted
+with a Time-based footnote command, prefixed with @code{\single}:
@lilypond[quote,verbatim,papersize=a8landscape]
\book {
\header { tagline = ##f }
\relative c'' {
- % footnotes may be added to chord constituents
- < \footnote #'(-1 . -3) #'Accidental "Another flat" aes
- c
- \footnote #'(-1 . 0.5) #'Accidental "A flat" ees
+ < \footnote #'(1 . -2) "An A" a
+ \single \footnote #'(-1 . -1) "A sharp" Accidental
+ cis
+ \single \footnote #'(0.5 . 0.5) "A flat" Accidental
+ ees fis
>2
- \footnote #'(-1 . 2) #'Stem "A stem" ees2
}
}
@end lilypond
@warning {When footnotes are attached to several musical elements at
-the same musical moment, the footnotes are numbered from the higher
-to the lower elements as they appear in the printed output, not in
-the order in which they are written in the input stream.}
-
-@subsubsubheading Time-based footnotes
-
-@cindex footnotes, time-based
+the same musical moment, as they are in the example above, the
+footnotes are numbered from the higher to the lower elements as they
+appear in the printed output, not in the order in which they are
+written in the input stream.}
-Layout objects like clefs and key change signatures are mostly caused
+Layout objects like clefs and key-change signatures are mostly caused
as a consequence of changed properties rather than actual events.
Others, like bar lines and bar numbers, are a direct consequence of
timing. For this reason, footnotes on such objects have to be based
such per-chord features are nominally assigned to @emph{one} event
inside the chord, relying on a particular choice would be imprudent.
-A time-based footnote is written in the same manner as an event-based
-footnote, except that @code{\default} is used in place of music
-indicating an event. The layout object in question should always be
-explicitly specified for time-based footnotes to avoid getting marks
-on unexpected objects.
+The layout object in question must always be explicitly specified
+for time-based footnotes, and the appropriate context must be
+specified if the grob is created in a context other than the bottom
+context.
@lilypond[quote,verbatim,papersize=a8landscape]
\book {
\header { tagline = ##f }
\relative c'' {
r1 |
- \footnote #'(-0.5 . -1) #'TimeSignature "Meter change" \default
+ \footnote #'(-0.5 . -1) "Meter change" Staff.TimeSignature
\time 3/4
- \footnote #'(1 . -1) #'Stem "Chord stem" \default
+ \footnote #'(1 . -1) "Chord stem" Stem
<c e g>4 q q
- \footnote #'(-0.5 . 1) #'BarLine "Bar line" \default
+ \footnote #'(-0.5 . 1) "Bar line" Staff.BarLine
q q
- \footnote #'(0.5 . -1) #'KeySignature "Key change" \default
+ \footnote #'(0.5 . -1) "Key change" Staff.KeySignature
\key c\minor
q
}
}
@end lilypond
+Custom marks can be used as alternatives to numerical marks, and the
+annotation line joining the marked object to the mark can be
+suppressed:
+
+@lilypond[quote,verbatim,papersize=a8landscape]
+\book {
+ \header { tagline = ##f }
+ \relative c' {
+ \footnote "*" #'(0.5 . -2) \markup { \italic "* The first note" } a'4
+ b8
+ \footnote \markup { \super "$" } #'(0.5 . 1)
+ \markup { \super "$" \italic " The second note" } e
+ c4
+ \once \override Score.FootnoteItem.annotation-line = ##f
+ b-\footnote \markup \tiny "+" #'(0.1 . 0.1)
+ \markup { \super "+" \italic " Editorial" } \p
+ }
+}
+@end lilypond
+
+More examples of custom marks are shown in
+@ref{Footnotes in stand-alone text}.
+
@node Footnotes in stand-alone text
@unnumberedsubsubsec Footnotes in stand-alone text
@rinternals{Footnote_engraver}.
@knownissues
-Multiple footnotes for the same page can only be stacked, one on top
-of the other; they cannot be printed on the same line.
+Multiple footnotes for the same page can only be stacked, one above
+the other; they cannot be printed on the same line.
Footnotes cannot be attached to @code{MultiMeasureRests} or
-automatic beams and footnote marks may collide with staves,
-@code{\markup} objects, other footnote marks and annotation lines.
+automatic beams or lyrics.
+
+Footnote marks may collide with staves, @code{\markup} objects, other
+footnote marks and annotation lines.
@node Reference to page numbers
@menu
* Creating MIDI files::
+* MIDI Instruments::
* MIDI block::
* What goes into the MIDI output?::
* Repeats in MIDI::
@end example
-@unnumberedsubsubsec Instrument names
-
-@cindex instrument names
-@funindex Staff.midiInstrument
-
-The MIDI instrument to be used is specified by setting the
-@code{Staff.midiInstrument} property to the instrument name.
-The name should be chosen from the list in @ref{MIDI instruments}.
-
-@example
-\new Staff @{
- \set Staff.midiInstrument = #"glockenspiel"
- @var{...notes...}
-@}
-@end example
-
-@example
-\new Staff \with @{midiInstrument = #"cello"@} @{
- @var{...notes...}
-@}
-@end example
-
-If the selected instrument does not exactly match an instrument from
-the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
-instrument is used.
-
-
@snippets
@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
output. Players that are known to work include MS Windows Media
Player and @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
+@node MIDI Instruments
+@subsection MIDI Instruments
+
+@cindex instrument names
+@cindex MIDI, instruments
+@funindex Staff.midiInstrument
+
+The MIDI instrument to be used is specified by setting the
+@code{Staff.midiInstrument} property to the instrument name.
+The name should be chosen from the list in @ref{MIDI instruments}.
+
+@example
+\new Staff @{
+ \set Staff.midiInstrument = #"glockenspiel"
+ @var{...notes...}
+@}
+@end example
+
+@example
+\new Staff \with @{midiInstrument = #"cello"@} @{
+ @var{...notes...}
+@}
+@end example
+
+If the selected instrument does not exactly match an instrument from
+the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
+instrument is used.
+
@node MIDI block
@subsection MIDI block
@cindex MIDI block
@c TODO Check grace notes - timing is suspect?
+@menu
+* Supported in MIDI::
+* Unsupported in MIDI::
+@end menu
+
+@node Supported in MIDI
@unnumberedsubsubsec Supported in MIDI
@cindex Pitches in MIDI
@end itemize
+@node Unsupported in MIDI
@unnumberedsubsubsec Unsupported in MIDI
@c TODO index as above
overall MIDI volume, the relative volume of dynamic markings and
the relative volume of different instruments.
+@menu
+* Dynamic marks::
+* Overall MIDI volume::
+* Equalizing different instruments (i)::
+* Equalizing different instruments (ii)::
+@end menu
+
+@node Dynamic marks
@unnumberedsubsubsec Dynamic marks
Dynamic marks are translated to a fixed fraction of the available
@file{../scm/midi.scm} and the associated table as a model.
The final example in this section shows how this might be done.
+@node Overall MIDI volume
@unnumberedsubsubsec Overall MIDI volume
The minimum and maximum overall volume of MIDI dynamic markings is
}
@end lilypond
+@node Equalizing different instruments (i)
@unnumberedsubsubsec Equalizing different instruments (i)
If the minimum and maximum MIDI volume properties are set in
}
@end lilypond
+
+@node Equalizing different instruments (ii)
@unnumberedsubsubsec Equalizing different instruments (ii)
If the MIDI minimum and maximum volume properties are not set