X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Finput.itely;h=2debffd3364d722d3066f6613314378d25949344;hb=ee0ef98a35634718033d505deb8a355e05513d6a;hp=a8f12215ef963a056cae75466cdf8ec9b4927ed6;hpb=80ac25965335ba51ace93fe478ce7f7907e4df91;p=lilypond.git diff --git a/Documentation/notation/input.itely b/Documentation/notation/input.itely index a8f12215ef..2debffd336 100644 --- a/Documentation/notation/input.itely +++ b/Documentation/notation/input.itely @@ -8,7 +8,7 @@ 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 @@ -288,17 +288,17 @@ and @file{eightminiatures-Nocturne.pdf} by adding a \book @{ \bookOutputSuffix "Romanze" \score @{ @dots{} @} -  \layout @{ @dots{} @} + \paper @{ @dots{} @} @} \book @{ \bookOutputSuffix "Menuetto" \score @{ @dots{} @} -  \layout @{ @dots{} @} + \paper @{ @dots{} @} @} \book @{ \bookOutputSuffix "Nocturne" \score @{ @dots{} @} -  \layout @{ @dots{} @} + \paper @{ @dots{} @} @} @end example @@ -309,17 +309,17 @@ by using @code{\bookOutputName} declarations \book @{ \bookOutputName "Romanze" \score @{ @dots{} @} -  \layout @{ @dots{} @} + \paper @{ @dots{} @} @} \book @{ \bookOutputName "Menuetto" \score @{ @dots{} @} -  \layout @{ @dots{} @} + \paper @{ @dots{} @} @} \book @{ \bookOutputName "Nocturne" \score @{ @dots{} @} -  \layout @{ @dots{} @} + \paper @{ @dots{} @} @} @end example @@ -493,17 +493,19 @@ However, whitespace should always be used in the following 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 @@ -1129,8 +1131,8 @@ provided: @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? @@ -1220,30 +1222,36 @@ Footnotes in music expressions fall into two categories: @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 @@ -1268,24 +1276,24 @@ object where the mark should be placed. Positive values of the 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 @@ -1293,15 +1301,13 @@ selecting an affected grob type, like @samp{#'TimeSignature}. @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 } @@ -1314,12 +1320,33 @@ by the event corresponding to @var{music}. } @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" 2 + <\footnote #'(-2 . -3) "Does work" a-3>4 + 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 { @@ -1334,62 +1361,77 @@ its last argument with a footnote mark attached to it. } @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 + 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.} +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.} -@subsubsubheading Time-based footnotes - -@cindex footnotes, time-based - -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 @@ -1398,30 +1440,52 @@ when marking features like stems and beams on @emph{chords}: while 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 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 @@ -1564,12 +1628,14 @@ Internals Reference: @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 @@ -2019,13 +2085,16 @@ to tagged music is as follows: @headitem Filter @tab Result @item -Tagged music preceded by @code{\keepWithTag #'@var{name}} - @tab Untagged music and music tagged with @var{name} is included; - music tagged with any other tag name is excluded. +Tagged music preceded by @code{\keepWithTag #'@var{name}} or + @code{\keepWithTag #'(@var{name1} @var{name2}@dots{})} +@tab Untagged music and music tagged with any of the given tag + names is included; + music tagged with any other tag name is excluded. @item -Tagged music preceded by @code{\removeWithTag #'@var{name}} -@tab Untagged music and music tagged with any tag name other than - @var{name} is included; music tagged with @var{name} is +Tagged music preceded by @code{\removeWithTag #'@var{name}} or + @code{\removeWithTag #'(@var{name1} @var{name2}@dots{})} +@tab Untagged music and music not tagged with any of the given tag names + is included; music tagged with any of the given tag names is excluded. @item Tagged music not preceded by either @code{\keepWithTag} or @@ -2096,12 +2165,13 @@ c1-\tag #'warn ^"Watch!" @end example Multiple tags may be placed on expressions with multiple -@code{\tag} entries: +@code{\tag} entries, or by combining multiple tags into one symbol +list: @lilypond[quote,verbatim] music = \relative c'' { \tag #'a \tag #'both { a4 a a a } - \tag #'b \tag #'both { b4 b b b } + \tag #'(b both) { b4 b b b } } << \keepWithTag #'a \music @@ -2111,7 +2181,9 @@ music = \relative c'' { @end lilypond Multiple @code{\removeWithTag} filters may be applied to a single -music expression to remove several differently named tagged sections: +music expression to remove several differently named tagged +sections. Alternatively, you can use a single +@code{\removeWithTag} with a list of tags. @lilypond[verbatim,quote] music = \relative c'' { @@ -2124,6 +2196,8 @@ music = \relative c'' { \removeWithTag #'B \removeWithTag #'C \music +\removeWithTag #'(B C) +\music } @end lilypond @@ -2131,6 +2205,9 @@ Two or more @code{\keepWithTag} filters applied to a single music expression will cause @emph{all} tagged sections to be removed, as the first filter will remove all tagged sections except the one named, and the second filter will remove even that tagged section. +Usually you would rather want to use a single @code{\keepWithTag} +command with a list of multiple tags: this will only remove tagged +sections not given in @emph{any} of the tags. Sometimes you want to splice some music at a particular place in an existing music expression. You can use @code{\pushToTag} and @@ -2165,16 +2242,14 @@ Notation Reference: @ref{Automatic part combining}, @ref{Including LilyPond files}. -@ignore -@c This warning is more general than this placement implies. -@c Rests are not merged whether or not they come from tagged sections. -@c Should be deleted? -td - @knownissues -Multiple rests are not merged if you create a score with more -than one tagged section at the same place. - -@end ignore +Calling @code{\relative} on a music expression obtained by filtering +music through @code{\keepWithTag} or @code{\removeWithTag} might cause +the octave relations to change, as only the pitches actually +remaining in the filtered expression will be considered. Applying +@code{\relative} first, before @code{\keepWithTag} or +@code{\removeWithTag}, avoids this danger as @code{\relative} then +acts on all the pitches as-input. @node Using global settings @@ -2567,6 +2642,7 @@ score contains more than 15 staves, MIDI channels will be reused. @menu * Creating MIDI files:: +* MIDI Instruments:: * MIDI block:: * What goes into the MIDI output?:: * Repeats in MIDI:: @@ -2637,33 +2713,6 @@ lilypond … -dmidi-extension=midi lilyFile.ly @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] @@ -2700,6 +2749,34 @@ Not all midi players correctly handle tempo changes in the midi 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 @@ -2763,6 +2840,12 @@ within a score block defined with a @code{\score} command. @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 @@ -2810,6 +2893,7 @@ above list: @end itemize +@node Unsupported in MIDI @unnumberedsubsubsec Unsupported in MIDI @c TODO index as above @@ -2881,6 +2965,14 @@ by default in the Voice context. It is possible to control the 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 @@ -2930,6 +3022,7 @@ redefined, it would be better to use the @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 @@ -2982,6 +3075,7 @@ volume is limited to the range 0.2 - 0.5. } @end lilypond +@node Equalizing different instruments (i) @unnumberedsubsubsec Equalizing different instruments (i) If the minimum and maximum MIDI volume properties are set in @@ -3029,6 +3123,8 @@ correctly. } @end lilypond + +@node Equalizing different instruments (ii) @unnumberedsubsubsec Equalizing different instruments (ii) If the MIDI minimum and maximum volume properties are not set