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
@headitem Procedure name @tab Condition tested
@item print-page-number-check-first @tab should this page number be printed?
-@item create-page-number-stencil @tab 'print-page-numbers true?
-@item print-all-headers @tab 'print-all-headers true?
+@item create-page-number-stencil @tab print-page-numbers true?
+@item print-all-headers @tab print-all-headers true?
@item first-page @tab first page in the book?
@item (on-page nmbr) @tab page number = nmbr?
@item last-page @tab last page in the book?
@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.
+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:
-@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.
-
-@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
+Marking a @emph{whole} chord with an event-based footnote is not
+possible: a chord, even one containing just a single note, does
+not produce an actual event of its own. However, individual
+notes @emph{inside} of the chord can be marked:
+
+@lilypond[quote,verbatim,papersize=a8landscape]
+\book {
+ \header { tagline = ##f }
+ \relative c'' {
+ \footnote #'(2 . 3) "Does not work" <a-3>2
+ <\footnote #'(-2 . -3) "Does work" a-3>4
+ <a-3 \footnote #'(3 . 1/2) "Also works" c-5>4
+ }
+}
+@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 note inside of a chord can be given an individual (event-based)
+footnote. A @samp{NoteHead} is the only grob directly caused
+from a chord note, so an event-based footnote command is
+@emph{only} suitable for adding a footnote to the @samp{NoteHead}
+within a chord. All other chord note grobs are indirectly caused.
+The @code{\footnote} command itself offers no syntax for
+specifying @emph{both} a particular grob type @emph{as well as} a
+particular event to attach to. However, one can use a time-based
+@code{\footnote} command for specifying the grob type, and then
+prefix this command with @code{\single} in order to have it
+applied to just the following event:
@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
been brought into the main file, so the file names they specify
must all be relative to the directory containing the main file,
not the directory containing the included file. However,
-this behavior can be changed by passing the option
+this behavior can be changed globally by passing the option
@option{-drelative-includes} option at the command line
(or by adding @code{#(ly:set-option 'relative-includes #t)}
-at the top of the main input file). With @code{relative-includes}
-set, the path for each @code{\include} command will be taken
-relative to the file containing that command. This behavior is
-recommended and it will become the default behavior in a future
-version of lilypond.
+at the top of the main input file).
+
+When @code{relative-includes} is set to @code{#t}, the path for each
+@code{\include} command will be taken relative to the file containing
+that command. This behavior is recommended and it will become the
+default behavior in a future version of lilypond.
+
+Files relative to the main directory and files relative to some other
+directory may both be @code{\include}d by setting
+@code{relative-includes} to @code{#t} or @code{#f} at appropriate
+places in the files. For example, if a general library, libA, has
+been created which itself uses sub-files which are @code{\include}d
+by the entry file of that library, those @code{\include} statements
+will need to be preceded by
+@code{#(ly:set-option #relative-includes #t)} so they are interpreted
+correctly when brought into the main @code{.ly} file, like this:
+
+@example
+libA/
+ libA.ly
+ A1.ly
+ A2.ly
+ ...
+@end example
+
+@noindent
+then the entry file, @code{libA.ly}, will contain
+
+@example
+#(ly:set-option 'relative-includes #t)
+\include "A1.ly"
+\include "A2.ly"
+...
+% return to default setting
+#(ly:set-option 'relative-includes #f)
+@end example
+
+Any @file{.ly} file can then include the entire library simply with
+
+@example
+\include "~/libA/libA.ly"
+@end example
+
+More complex file structures may be devised by switching at
+appropriate places.
Files can also be included from a directory in a search path
specified as an option when invoking LilyPond from the command
@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
projects / lilypond.git / blobdiff