X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=scm%2Fdefine-context-properties.scm;h=c041e85cfeceb9bcf98f8534450e3ab9bb1222dd;hb=6a6969bee0b27f71175f2764a03398102fb67a2b;hp=23389f9cbfeeee77cbfc7ae789706128960a19a5;hpb=a092cdafdcd520e03795f2086f324aaa73c52247;p=lilypond.git diff --git a/scm/define-context-properties.scm b/scm/define-context-properties.scm index 23389f9cbf..c041e85cfe 100644 --- a/scm/define-context-properties.scm +++ b/scm/define-context-properties.scm @@ -26,23 +26,61 @@ (lambda (x) (apply translator-property-description x)) `( - (aDueText ,string? "text for begin of a due") + (aDueText ,string? "Text to print at a unisono passage.") (alignBassFigureAccidentals ,boolean? "If true, then the accidentals are aligned in bass figure context.") - (allowBeamBreak ,boolean? "If true allow line breaks during beams.") + (allowBeamBreak ,boolean? "If true allow line breaks for beams over bar lines.") (associatedVoice ,string? "Name of the -Voice that has the melody for this Lyrics.") +@code{Voice} that has the melody for this @code{Lyrics} line.") (autoBeamSettings ,list? "Specifies when automatically generated beams should begin and end. -See the notation manual for more information. ") +See @usermanref{Setting automatic beam behavior} for more information. +") (autoAccidentals ,list? "List of -different ways to typeset an accidental. See the notation manual for more information on setting this.") - (autoBeaming ,boolean? "If set to true -then beams are generated automatically.") +different ways to typeset an accidental. + +For determining when to print an accidental, several different rules +are tried. The rule that gives the highest number of accidentals is +used. Each rule consists of + +@table @var + +@item context: + In which context is the rule applied. For example, if +@var{context} is @internalsref{Score} then all staves share +accidentals, and if @var{context} is @internalsref{Staff} then all +voices in the same staff share accidentals, but staves do not. + +@item octavation: + Whether the accidental changes all octaves or only the current + octave. Valid choices are + + @table @samp + @item same-octave: + This is the default algorithm. Accidentals are typeset if the note changes + the accidental of that note in that octave. Accidentals lasts to the end of the measure + and then as many measures as specified in the value. I.e. 1 means to the end + of next measure, -1 means to the end of previous measure (that is: no duration at all), etc. #t means forever. + @item any-octave: + Accidentals are typeset if the note is different from + the previous note on the same pitch in any octave. The value has same meaning as in + same-octave. + @end table + +@item laziness + +Over how many bar lines the accidental lasts. +If @var{laziness} is @code{-1} then the accidental is forget +immediately, and if @var{laziness} is @code{#t} then the accidental +lasts forever. +@end table +") + (autoBeaming ,boolean? "If set to true then beams are generated +automatically.") (autoCautionaries ,list? "List similar to -autoAccidentals, but it controls cautionary accidentals rather than +@code{autoAccidentals}, but it controls cautionary accidentals rather than normal ones. Both lists are tried, and the one giving the most accidentals wins. In case of draw, a normal accidental is typeset. ") @@ -56,36 +94,24 @@ if this property is unset. (barAlways ,boolean? "If set to true a bar line is drawn after each note.") - (barCheckSynchronize ,boolean? "If true then reset measurePosition + (barCheckSynchronize ,boolean? "If true then reset @code{measurePosition} when finding a barcheck.") (barNumberVisibility ,procedure? "Procedure that takes an int and returns whether the corresponding bar number should be printed") - (bassFigureFormatFunction ,procedure? "DOCME") + (bassFigureFormatFunction ,procedure? "Procedure that is called +to produce the formatting for a @code{BassFigure} grob. It takes a +list of @code{BassFigureEvent}s, a context, and the grob to format.") (beatLength ,ly:moment? "The length of one beat in this time signature.") (beatGrouping ,list? - "List of beatgroups. Eg. in 5/8 time #(list 2 3).") + "List of beatgroups, e.g., in 5/8 time @code{'(2 +3)}.") - (breakAlignOrder ,list? "Defines the order in which -prefatory matter (clefs, key signatures) appears, eg. this puts the -key signatures after the bar lines: - -@example - \\property Score.breakAlignOrder = #'( - span-bar - breathing-sign - clef - staff-bar - key - time-signature - ) -@end example -") - (centralCPosition ,number? "Place of the central C, measured in half -staffspaces. Usually determined by looking at clefPosition and -clefGlyph.") + (middleCPosition ,number? "Place of the middle C, measured in half +staffspaces. Usually determined by looking at @code{clefPosition} and +@code{clefGlyph}.") (chordNameFunction ,procedure? "The function that converts lists of pitches to chord names.") @@ -94,85 +120,87 @@ clefGlyph.") (chordRootNamer ,procedure? "Function that converts from a pitch object to a text markup. Used for chords.") (chordNameExceptions ,list? - "Alist of chord exceptions. Contains (CHORD . MARKUP) entries.") + "Alist of chord exceptions. +Contains (@var{chord} . @var{markup}) entries.") (chordNameExceptionsFull ,list? - "Alist of chord exceptions. Contains (CHORD . (MARKUP)) entries.") - (chordNameExceptionsPartial ,list? - "Alist of partial chord exceptions. Contains (CHORD . (PREFIX-MARKUP SUFFIX-MARKUP)) entries.") + "Alist of chord exceptions. +Contains (@var{chord} . @var{markup}) entries.") + (chordNameExceptionsPartial + ,list? + "Alist of partial chord exceptions. Contains (@var{chord} . (@var{prefix-markup} @var{suffix-markup})) entries.") + (chordNameSeparator ,markup? - "The markup object used to separate parts of a chord name.") - + "The markup object used to separate + parts of a chord name.") (chordChanges ,boolean? "Only show changes in chords scheme?") - (clefGlyph ,string? "Name of the symbol within the music font") + (clefGlyph ,string? "Name of the symbol within the music font.") (clefOctavation ,integer? "Add this much extra octavation. Values of 7 and -7 are common.") - (clefPosition ,number? "Where should the center of the clef symbol go? -The unit of this distance is the half staff space, and 0 represents the vertical center.") + (clefPosition ,number? "Where should the center of the clef +symbol go, measured in half staff spaces from the center of the staff.") - (connectArpeggios ,boolean? " If set, connect all arpeggios that are -found. In this way, you can make arpeggios that cross staves. ") + (connectArpeggios ,boolean? " If set, connect arpeggios across +piano staff.") (createKeyOnClefChange ,boolean? "Print a key signature whenever the clef is changed.") - (crescendoText ,markup? "Text to print at start of non-hairpin crecscendo, ie: @samp{cresc.}") + (crescendoText ,markup? "Text to print at start of non-hairpin crescendo, i.e.: @samp{cresc.}") (crescendoSpanner ,symbol? "Type of spanner to be used for crescendi. One of: @samp{hairpin}, @samp{line}, @samp{dashed-line}, @samp{dotted-line}. If unset, hairpin type is used.") - (decrescendoText ,markup? "Text to print at start of non-hairpin decrecscendo, ie: @samp{dim.}") + (decrescendoText ,markup? "Text to print at start of non-hairpin decrescendo, i.e.: @samp{dim.}") (drumPitchTable ,hash-table? "A table mapping percussion instruments (symbols) to pitches.") (drumStyleTable ,hash-table? "A hash table containing mapping -drums to layout settings. Predefined values: @code{drums-style}, -@code{timbales-style}, @code{congas-style}, @code{bongos-style} and -@code{percussion-style}. +drums to layout settings. Predefined values: @samp{drums-style}, +@samp{timbales-style}, @samp{congas-style}, @samp{bongos-style} and +@samp{percussion-style}. -The layout style is a hash table, containing the drum-pitches (eg. the -symbol @code{hihat}) as key, and a list (@var{notehead-style} +The layout style is a hash table, containing the drum-pitches (e.g. the +symbol @samp{hihat}) as key, and a list (@var{notehead-style} @var{script} @var{vertical-position}) as values. ") (currentBarNumber ,integer? "Contains the current barnumber. This property is incremented at -every barline. +every bar line. ") (defaultBarType ,string? "Sets the default type of bar line. -Available bar types: [FIXME]; +See @code{whichBar} for information on available bar types. -This variable is typically read by Timing_engraver at Score level, so -overriding Staff.defaultBarType will have no effect. +This variable is read by @internalsref{Timing_engraver} at +@internalsref{Score} level. ") - (decrescendoSpanner ,symbol? "Type of spanner to be used for -decrescendi. One of: @samp{hairpin}, @samp{line}, @samp{dashed-line}, -@samp{dotted-line}. If unset, hairpin type is used.") + (decrescendoSpanner ,symbol? "See @code{crescendoSpanner}.") - (explicitClefVisibility ,procedure? "break-visibility function for clef changes.") + (explicitClefVisibility ,procedure? "@samp{break-visibility} function for clef changes.") - (explicitKeySignatureVisibility ,procedure? "break-visibility -function for explicit Key changes; \\override of #'break-visibility -will set the visibility for normal (ie. at the start of the line) key -signatures.") + (explicitKeySignatureVisibility ,procedure? +"@samp{break-visibility} function for explicit key +changes. @samp{\\override} of @samp{#'break-visibility} will set the +visibility for normal (i.e. at the start of the line) key signatures.") (extraNatural ,boolean? "Whether to typeset an extra natural sign before accidentals changing from a non-natural to another non-natural.") (extraVerticalExtent ,number-pair? - "extra vertical extent, same format as MinimumVerticalExtent") + "extra vertical extent, same format as @var{minimumVerticalExtent}") (followVoice ,boolean? "if set, note heads are tracked across staff switches by a thin line") (fontSize ,number? - "The relative size of all grobs in a context. This is -done using the @code{Font_size_engraver}.") + "The relative size of all grobs in a context. ") (fingeringOrientations ,list? - "List of symbols, containing left, right, up and/or down. This list + "List of symbols, containing +@samp{left}, @samp{right}, @samp{up} and/or @samp{down}. This list determines where fingerings are put relative to the chord being fingered.") - (forceClef ,boolean? "Show clef symbol, even if it hasn't + (forceClef ,boolean? "Show clef symbol, even if it has not changed. Only active for the first clef after the property is set, not for the full staff.") @@ -180,35 +208,36 @@ for the full staff.") highest pitch on the instrument. This used by the automatic string selector for tab notation.") - (ignoreMelismata ,boolean? "Ignore melismata for this @internalsref{Lyrics}.") - (instr ,markup? "see @code{instrument}") + (ignoreMelismata ,boolean? "Ignore melismata for this @internalsref{Lyrics} line.") + (instr ,markup? "See @code{instrument}") (instrument ,markup? "The name to print left of a staff. The @code{instrument} property labels the staff in the first system, and the @code{instr} property labels following lines.") - (instrumentEqualizer ,procedure? "[DOCUMENT-ME]") + (instrumentEqualizer ,procedure? " +Function taking a string (instrument name), and returning a (@var{min} . @var{max}) pair of numbers for the loudness range of the instrument. +") + (instrumentTransposition ,ly:pitch? "Define the transposition of the instrument. This is used to transpose the MIDI output, and @code{\\quote}s.") - (instrumentSupport ,list? "list of grobs to attach instrument name -to.") - (keyAccidentalOrder ,list? " -Alist that defines in what order alterations should be printed. -The format is (NAME . ALTER), where NAME is from 0 .. 6 and ALTER from -1, 1. + (keyAccidentalOrder ,list? " Alist that defines in what order +alterations should be printed. The format is (@var{name} +. @var{alter}), where @var{name} is from 0 .. 6 and @var{alter} from -1, 1. ") (keySignature ,list? "The current key signature. This is an alist -containing (NAME . ALTER) or ((OCTAVE . NAME) . ALTER). - where NAME is from 0.. 6 and -ALTER from -4 (double flat) to 4 (double sharp). +containing (@var{name} . @var{alter}) or ((@var{octave} . @var{name}) . @var{alter}). + where @var{name} is from 0.. 6 and +@var{alter} from -4 (double flat) to 4 (double sharp). ") (majorSevenSymbol ,markup? "How should -the major7 be formatted in a chord name?") +the major 7th be formatted in a chord name?") (markFormatter ,procedure? "Procedure taking as arguments context and rehearsal mark. It should return the formatted mark as a markup object.") (measureLength ,ly:moment? "Length of one -measure in the current time signature last?") +measure in the current time signature.") (measurePosition ,ly:moment? "How much of the current measure have we had. This can be set manually to create incomplete @@ -226,31 +255,36 @@ manual beams are considered. Possible values include (metronomeMarkFormatter ,procedure? "How to produce a metronome markup. Called with 2 arguments, event and context.") (midiInstrument ,string? "Name of the MIDI instrument to use ") - (midiMinimumVolume ,number? "[DOCUMENT-ME]") - (midiMaximumVolume ,number? "[DOCUMENT-ME]") + (midiMinimumVolume ,number? "Sets the minimum loudness for MIDI. Ranges from 0 to 1.") + (midiMaximumVolume ,number? "Analogous to @code{midiMinimumVolume}.") (minimumFret ,number? "The tablature auto string-selecting mechanism -selects the highest string with a fret not less than minimumFret") +selects the highest string with a fret at least @var{minimumFret}") (minimumVerticalExtent ,number-pair? "minimum vertical extent, same -format as VerticalExtent") - (recordEventSequence ,procedure? "Upon termination of this context, -this function is called with current context and a list of music -objects. The list of contains entries with start times, music objects -and whether they're processed in this context.") - (ottavation ,string? "If set, the text for an 8va spanner. Changing -this implies a new text spanner. ") +format as @var{verticalExtent}") + (ottavation ,string? "If set, the text for an ottava spanner. Changing +this creates a new text spanner. ") (pedalSustainStrings ,list? "List of string to print for -sustain-pedal. Format is (UP UPDOWN DOWN), where each of the three is -the string to print when this is done with the pedal.") - (pedalUnaCordaStrings ,list? "see pedalSustainStrings.") - (pedalSostenutoStrings ,list? "see pedalSustainStrings.") +sustain-pedal. Format is (@var{up} @var{updown} @var{down}), where +each of the three is the string to print when this is done with the +pedal.") + (pedalUnaCordaStrings ,list? "See @code{pedalSustainStrings}.") + (pedalSostenutoStrings ,list? "See @code{pedalSustainStrings}.") (pedalSustainStyle ,symbol? "A symbol that indicates how to print -sustain pedals: text, bracket or mixed (both).") - (pedalUnaCordaStyle ,symbol? "see pedalSustainStyle.") - (pedalSostenutoStyle ,symbol? "see pedalSustainStyle.") +sustain pedals: @code{text}, @code{bracket} or @code{mixed} (both).") + (pedalUnaCordaStyle ,symbol? "see @code{pedalSustainStyle}.") + (pedalSostenutoStyle ,symbol? "see @code{pedalSustainStyle}.") + (printKeyCancellation ,boolean? "Print restoration alterations before a key signature change. ") (printOctaveNames ,boolean? "Print octave marks for the NoteNames context.") - (rehearsalMark ,integer? "The last rehearsal mark printed.") - (repeatCommands ,list? "This property is read to find any command of the form (volta . X), where X is a string or #f") + (recordEventSequence ,procedure? "When +@internalsref{Recording_group_engraver} is in this context, then upon +termination of the context, this function is called with current +context and a list of music objects. The list of contains entries +with start times, music objects and whether they are processed in this +context.") + + (rehearsalMark ,integer? "The last rehearsal mark printed.") + (repeatCommands ,list? "This property is read to find any command of the form @code{(volta . @var{x})}, where @var{x} is a string or @code{#f}") (restNumberThreshold ,number? "If a multimeasure rest takes less than this number of measures, no number is printed. ") @@ -270,15 +304,13 @@ r1 r1*3 R1*3 \\\\property Score.skipBars= ##t r1*3 R1*3 @end example ") (skipTypesetting ,boolean? - "When true, all no typesetting is done at this -moment, causing the interpretation phase to go a lot faster. This can -help with debugging large scores.") + "When true, all no typesetting is done, speeding +up the interpretation phase. This speeds up debugging large scores.") (soloADue ,boolean? "set Solo/A due texts in the part combiner?") (soloIIText ,string? "text for begin of solo for voice ``two'' when part-combining.") (soloText ,string? "text for begin of solo when part-combining.") - (sparseTies ,boolean? "only create one tie per chord.") (squashedPosition ,integer? " Vertical position of -squashing for Pitch_squash_engraver.") +squashing for @internalsref{Pitch_squash_engraver}.") (stringOneTopmost ,boolean? "Whether the 1st string is printed on the top line of the tablature.") @@ -288,36 +320,36 @@ verse. Use in Lyrics context.") (stemLeftBeamCount ,integer? " Specify the number of beams to draw on the left side of the next note. Overrides automatic beaming. The -value is only used once, and then it is erased. [JUNKME.]") +value is only used once, and then it is erased.") - (stemRightBeamCount ,integer? "idem, for the right side. [JUNKME]") + (stemRightBeamCount ,integer? "See @code{stemLeftBeamCount}.") - (stringTunings ,list? "The tablature strings tuning. Must be a list of -the different semitons pitch of each string (starting by the lower + (stringTunings ,list? "The tablature strings tuning. It is a list +of the pitch (in semitones) of each string (starting with the lower one).") (subdivideBeams ,boolean? "If set, multiple beams will be subdivided -at beat positions - by only drawing one beam over the beat.") +at beat positions by only drawing one beam over the beat.") (systemStartDelimiter ,symbol? "Which grob to make for the start of the system/staff? Set to @code{SystemStartBrace}, @code{SystemStartBracket} or @code{SystemStartBar}.") - (tablatureFormat ,procedure? "Function formatting a tab notehead; it + (tablatureFormat ,procedure? "Function formatting a tab note head; it takes a string number, a list of string tunings and Pitch object. It returns the text as a string.") (timeSignatureFraction ,number-pair? - "pair of numbers, signifying the time signature. For example #'(4 . 4) -is a 4/4 time signature.") + "pair of numbers, signifying the time +signature. For example @code{#'(4 . 4)} is a 4/4 time signature.") (timing ,boolean? " Keep administration of measure length, position, bar number, etc? Switch off for cadenzas.") (tonic ,ly:pitch? "The tonic of the current scale") - (transposing ,integer? "Transpose the MIDI output. Set this property to the number of half-steps to transpose by.") - (tremoloFlags ,integer? "Number of tremolo flags to add if none is specified.") + (tremoloFlags ,integer? "Number of tremolo flags to add if no +number is specified.") (tupletNumberFormatFunction ,procedure? @@ -338,15 +370,15 @@ context Voice \\times 2/3 @{ @@end lilypond @end example .") - (verticalAlignmentChildCallback ,procedure? "what callback to add to children of a vertical alignment. -It determines what alignment procedure is used on the alignment -itself. .") - (verticalExtent ,number-pair? "hard coded vertical extent. The format + (verticalAlignmentChildCallback ,procedure? "What callback to add +to children of a vertical alignment. It determines what +procedure is used on the alignment itself.") + (verticalExtent ,number-pair? "Hard coded vertical extent. The format is a pair of dimensions, for example, this sets the sizes of a staff to 10 (5+5) staffspaces high. @example -property Staff.verticalExtent = #'(-5.0 . 5.0) +\\set Staff.verticalExtent = #'(-5.0 . 5.0) @end example @@ -357,9 +389,9 @@ vertical group.") (vocNam ,markup? "Name of a vocal line, short version.") (voltaOnThisStaff ,boolean? - "Normally, volta brackets are put only on the topmost staff. Setting -this variable to true, will force a bracket to be on this staff as -well.") + "Normally, volta brackets are put only on the +topmost staff. Setting this variable will create a bracket on +this staff as well.") (voltaSpannerDuration ,ly:moment? "This specifies the maximum duration to use for the brackets printed for @code{\\alternative}. This can be @@ -368,11 +400,11 @@ alternative is very large.") (whichBar ,string? - "This property is read to determine what type of barline to create. + "This property is read to determine what type of bar line to create. Example: @example -\\property Staff.whichBar = \"|:\" +\\set Staff.whichBar = \"|:\" @end example This will create a start-repeat bar in this staff only. @@ -391,7 +423,7 @@ Valid values are described in @internalsref{bar-line-interface}. `((slurMelismaBusy ,boolean? "Signal if a slur is present.") (originalCentralCPosition ,integer? - "Used for temporary overriding central C in octavation brackets. ") + "Used for temporary overriding middle C in octavation brackets. ") (melismaBusy ,boolean? "Signifies whether a melisma is active. This can be used to signal melismas on top of those automatically detected. ") @@ -417,9 +449,9 @@ pairs. It is reset at every bar line." ) (finalizations ,list? "List of expressions to evaluate before proceeding to next time step. Internal variable.") (busyGrobs ,list? "a queue of (@var{end-moment} . @var{GROB}) conses. This is for internal (C++) use only. This property contains -the grobs which are still busy (eg. noteheads, spanners, etc.) +the grobs which are still busy (e.g. note heads, spanners, etc.) ") - (barCheckLastFail ,ly:moment? "Where in the measurze did the last barcheck fail?") + (barCheckLastFail ,ly:moment? "Where in the measure did the last barcheck fail?") (associatedVoiceContext ,ly:context? "The context object of the Voice that has the melody for this Lyrics.") (acceptHashTable ,vector? "Internal variable: store table with MusicName to Engraver entries.") @@ -437,7 +469,10 @@ signature change.") Script_engraver for typesetting note-super/subscripts. See @file{scm/script.scm} for more information ") + (quotes ,hash-table? "Hash table, mapping names to music-event vectors.") (stavesFound ,grob-list? "list of all staff-symbols found.") + (instrumentSupport ,grob-list? "list of grobs to attach instrument name +to.") (tieMelismaBusy ,boolean? "Signal whether a tie is present.") ) ))