X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=scm%2Fdefine-context-properties.scm;h=9509adc9b67739380961e39665d2b3391d7e4b79;hb=b715af1d7ae27aa1c3cdca6b18cf17873ecdb6ba;hp=357a3e02f4239aca187a74f55f2a3bdde71576f7;hpb=2885f759ba07d814656c040ed3b3f6f9c81f1b2e;p=lilypond.git diff --git a/scm/define-context-properties.scm b/scm/define-context-properties.scm index 357a3e02f4..9509adc9b6 100644 --- a/scm/define-context-properties.scm +++ b/scm/define-context-properties.scm @@ -1,8 +1,8 @@ ;;;; define-context-properties.scm -- part of backend documentation ;;;; ;;;; source file of the GNU LilyPond music typesetter -;;;; -;;;; (c) 1998--2007 Han-Wen Nienhuys +;;;; +;;;; (c) 1998--2009 Han-Wen Nienhuys ;;;; Jan Nieuwenhuizen @@ -14,11 +14,11 @@ (procedure? type?) (string? description))) (throw 'init-format-error)) - - + + (if (not (equal? #f (object-property symbol 'translation-doc))) (ly:error (_ "symbol ~S redefined" symbol))) - + (set-object-property! symbol 'translation-type? type?) (set-object-property! symbol 'translation-doc description) (set! all-translation-properties (cons symbol all-translation-properties)) @@ -32,14 +32,14 @@ `( ;; TODO FIXME - - (aDueText ,string? "Text to print at a unisono passage.") - (alignBelowContext ,string? "Where to insert newly created context in -vertiical alignment.") + + (aDueText ,markup? "Text to print at a unisono passage.") (alignAboveContext ,string? "Where to insert newly created context in -vertiical alignment.") +vertical alignment.") (alignBassFigureAccidentals ,boolean? "If true, then the accidentals are aligned in bass figure context.") + (alignBelowContext ,string? "Where to insert newly created context in +vertical alignment.") (associatedVoice ,string? "Name of the @code{Voice} that has the melody for this @code{Lyrics} line.") (autoAccidentals ,list? "List of different ways to typeset an @@ -47,63 +47,62 @@ 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 +used. + +Each entry in the list is either a symbol or a procedure. @table @var -@item context -In which context is the rule applied. For example, if @var{context} -is @rinternals{Score} then all staves share accidentals, and if -@var{context} is @rinternals{Staff} then all voices in the same staff -share accidentals, but staves do not. +@item symbol +The symbol is the name of the context in which the following rules are to be +applied. For example, if @var{context} is @rinternals{Score} then all +staves share accidentals, and if @var{context} is @rinternals{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 +@item procedure +The procedure represents an accidental rule to be applied to the previously +specified context. + +The procedure takes the following arguments: @table @code -@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. This is, @code{1}@tie{}means to the end of next measure, -@code{-1}@tie{}means to the end of previous measure (that is: no -duration at all), etc. @code{#t} means forever. +@item context +The current context to which the rule should be applied. + +@item pitch +The pitch of the note to be evaluated. + +@item barnum +The current bar number. -@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 -@code{same-octave}. +@item measurepos +The current measure position. @end table -@item laziness -Over how many bar lines the accidental lasts. If @var{laziness} is -@code{-1} then the accidental is forgotten immediately, and if -@var{laziness} is @code{#t} then the accidental lasts forever. +The procedure returns a pair of booleans. The first states whether an extra +natural should be added. The second states whether an accidental should be +printed. @code{(#t . #f)} does not make sense. @end table") (autoBeamCheck ,procedure? "A procedure taking three arguments, @var{context}, @var{dir} [start/stop (-1 or 1)], and @var{test} [shortest note in the beam]. A non-@code{#f} return value starts or stops the auto beam.") - (autoBeamSettings ,list? "Specifies when automatically generated -beams should begin and end. See @ruser{Setting automatic beam -behavior} for more information.") (autoBeaming ,boolean? "If set to true then beams are generated automatically.") (autoCautionaries ,list? "List similar to @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.") - (automaticBars ,boolean? "If set to true then bar lines will not + (automaticBars ,boolean? "If set to false then bar lines will not be printed automatically; they must be explicitly created with a -@code{\\bar} command. Unlike the @code{\\cadenza} keyword, measures -are still counted. Bar generation will resume according to that count -if this property is unset.") +@code{\\bar} command. Unlike the @code{\\cadenzaOn} keyword, measures +are still counted. Bar line generation will resume according to that +count 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 @@ -118,15 +117,15 @@ format.") (bassStaffProperties ,list? "An alist of property settings to apply for the down staff of @code{PianoStaff}. Used by @code{\\autochange}.") + (beamSettings ,list? "Specifies when automatically generated +beams should begin and end, as well as beam subdivision behavior. +See @ruser{Setting automatic beam +behavior} for more information.") (beatLength ,ly:moment? "The length of one beat in this time signature.") - (beatGrouping ,list? "A list of beatgroups, e.g., in 5/8 time -@code{'(2 3)}.") (chordChanges ,boolean? "Only show changes in chords scheme?") - (chordNameFunction ,procedure? "The function that converts lists -of pitches to chord names.") (chordNameExceptions ,list? "An alist of chord exceptions. Contains @code{(@var{chord} . @var{markup})} entries.") (chordNameExceptionsFull ,list? "An alist of full chord @@ -134,6 +133,8 @@ exceptions. Contains @code{(@var{chord} . @var{markup})} entries.") (chordNameExceptionsPartial ,list? "An alist of partial chord exceptions. Contains @code{(@var{chord} . (@var{prefix-markup} @var{suffix-markup}))} entries.") + (chordNameFunction ,procedure? "The function that converts lists +of pitches to chord names.") (chordNameSeparator ,markup? "The markup object used to separate parts of a chord name.") (chordNoteNamer ,procedure? "A function that converts from a pitch @@ -157,17 +158,18 @@ percent repeats.") the clef is changed.") (createSpacing ,boolean? "Create @code{StaffSpacing} objects? Should be set for staves.") + (crescendoSpanner ,symbol? "The type of spanner to be used for +crescendi. Available values are @samp{hairpin} and @samp{text}. If unset, +a hairpin crescendo is used.") (crescendoText ,markup? "The text to print at start of non-hairpin crescendo, i.e., @samp{cresc.}.") - (crescendoSpanner ,symbol? "The type of spanner to be used for -crescendi. Available values are @samp{hairpin}, @samp{line}, -@samp{dashed-line}, @samp{dotted-line}. If unset, a hairpin crescendo -is used.") (currentBarNumber ,integer? "Contains the current barnumber. This property is incremented at every bar line.") - (decrescendoSpanner ,symbol? "See @code{crescendoSpanner}.") + (decrescendoSpanner ,symbol? "The type of spanner to be used for +decrescendi. Available values are @samp{hairpin} and @samp{text}. If +unset, a hairpin decrescendo is used.") (decrescendoText ,markup? "The text to print at start of non-hairpin decrescendo, i.e., @samp{dim.}.") (defaultBarType ,string? "Set the default type of bar line. See @@ -175,6 +177,8 @@ non-hairpin decrescendo, i.e., @samp{dim.}.") This variable is read by @rinternals{Timing_translator} at @rinternals{Score} level.") + (doubleRepeatType ,string? "Set the default bar line for double +repeats.") (doubleSlurs ,boolean? "If set, two slurs are created for every slurred note, one above and one below the chord.") (drumPitchTable ,hash-table? "A table mapping percussion @@ -234,6 +238,8 @@ for the full staff.") (harmonicAccidentals ,boolean? "If set, harmonic notes in chords get accidentals.") + (harmonicDots ,boolean? "If set, harmonic notes in dotted chords get +dots.") (highStringOne ,boolean? "Whether the first string is the string with highest pitch on the instrument. This used by the automatic string selector for tablature notation.") @@ -249,12 +255,12 @@ printed as numbers, but only as extender lines.") the default time signature.") (instrumentCueName ,markup? "The name to print if another instrument is to be taken.") - (instrumentName ,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? "A function taking a string (instrument name), and returning a @code{(@var{min} . @var{max})} pair of numbers for the loudness range of the instrument.") + (instrumentName ,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.") ;; the definition is reversed wrt traditional transposition ;; otherwise \transpose { \transposition .. } won't work (instrumentTransposition ,ly:pitch? "Define the transposition of @@ -263,11 +269,11 @@ This is used to transpose the MIDI output, and @code{\\quote}s.") (internalBarNumber ,integer? "Contains the current barnumber. This property is used for internal timekeeping, among others by the @code{Accidental_engraver}.") - + (keepAliveInterfaces ,list? "A list of symbols, signifying grob interfaces that are worth keeping a staff with @code{remove-empty} set -around for.") +around for.") (keyAlterationOrder ,list? "An alist that defines in what order alterations should be printed. The format is @code{(@var{step} . @var{alter})}, where @var{step} is a number from 0 to@tie{}6 and @@ -301,12 +307,7 @@ manual beams are considered. Possible values include @code{melismaBusy}, @code{slurMelismaBusy}, @code{tieMelismaBusy}, and @code{beamMelismaBusy}.") (metronomeMarkFormatter ,procedure? "How to produce a metronome -markup. Called with two arguments, event and context.") - (midiInstrument ,string? "Name of the MIDI instrument to use.") - (midiMaximumVolume ,number? "Analogous to -@code{midiMinimumVolume}.") - (midiMinimumVolume ,number? "Set the minimum loudness for MIDI. -Ranges from 0 to@tie{}1.") +markup. Called with four arguments: text, duration, count and context.") (middleCClefPosition ,number? "The position of the middle C, as determined only by the clef. This can be calculated by looking at @code{clefPosition} and @code{clefGlyph}.") @@ -316,6 +317,11 @@ is used for ottava brackets.") (middleCPosition ,number? "The place of the middle C, measured in half staff-spaces. Usually determined by looking at @code{middleCClefPosition} and @code{middleCOffset}.") + (midiInstrument ,string? "Name of the MIDI instrument to use.") + (midiMaximumVolume ,number? "Analogous to +@code{midiMinimumVolume}.") + (midiMinimumVolume ,number? "Set the minimum loudness for MIDI. +Ranges from 0 to@tie{}1.") (minimumFret ,number? "The tablature auto string-selecting mechanism selects the highest string with a fret at least @code{minimumFret}.") @@ -325,11 +331,13 @@ page turn to be allowed.") repeated section for a page turn to be allowed within that section.") + (noChordSymbol ,markup? "Markup to be displayed for rests in a +ChordNames context.") (noteToFretFunction ,procedure? "How to produce a fret diagram. Parameters: A list of note events and a list of tabstring events.") - (ottavation ,string? "If set, the text for an ottava spanner. + (ottavation ,markup? "If set, the text for an ottava spanner. Changing this creates a new text spanner.") (output ,ly:music-output? "The output produced by a score-level translator during music interpretation.") @@ -345,6 +353,8 @@ the pedal.") sustain pedals: @code{text}, @code{bracket} or @code{mixed} (both).") (pedalUnaCordaStrings ,list? "See @code{pedalSustainStrings}.") (pedalUnaCordaStyle ,symbol? "See @code{pedalSustainStyle}.") + (predefinedDiagramTable ,hash-table? "The hash table of predefined +fret diagrams to use in FretBoards.") (printKeyCancellation ,boolean? "Print restoration alterations before a key signature change.") (printOctaveNames ,boolean? "Print octave marks for the @@ -363,9 +373,13 @@ 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}.") + (repeatCommands ,list? "This property is a list of commands +of the form @code{(list 'volta @var{x})}, where @var{x} is a string or +@code{#f}. @code{'end-repeat} is also accepted as a command.") + (repeatCountVisibility ,procedure? "A procedure taking as +arguments an integer and context, returning whether the corresponding +percent repeat number should be printed when @code{countPercentRepeats} +is set.") (restNumberThreshold ,number? "If a multimeasure rest has more measures than this, a number is printed.") @@ -391,9 +405,9 @@ voices is preserved. (skipTypesetting ,boolean? "If true, no typesetting is done, speeding up the interpretation phase. Useful for debugging large scores.") - (soloIIText ,string? "The text for the start of a solo for + (soloIIText ,markup? "The text for the start of a solo for voice @q{two} when part-combining.") - (soloText ,string? "The text for the start of a solo when + (soloText ,markup? "The text for the start of a solo when part-combining.") (squashedPosition ,integer? "Vertical position of squashing for @rinternals{Pitch_squash_engraver}.") @@ -422,16 +436,18 @@ cautionary suggestions over the note.") of the system/staff? Set to @code{SystemStartBrace}, @code{SystemStartBracket} or @code{SystemStartBar}.") (systemStartDelimiterHierarchy ,pair? "A nested list, indicating -the nesting of a start delimiters.") +the nesting of a start delimiters.") (tablatureFormat ,procedure? "A function formatting a tablature -note head; it takes a string number, a list of string tunings and a -@code{Pitch} object. It returns the text as a string.") - (tempoWholesPerMinute ,ly:moment? "The tempo in whole notes per -minute.") +note head. Called with three arguments: string number, context and event. +It returns the text as a string.") + (tempoHideNote ,boolean? "Hide the note=count in tempo marks.") + (tempoText ,markup? "Text for tempo marks.") (tempoUnitCount ,number? "Count for specifying tempo.") (tempoUnitDuration ,ly:duration? "Unit for specifying tempo.") + (tempoWholesPerMinute ,ly:moment? "The tempo in whole notes per +minute.") (tieWaitForNote ,boolean? "If true, tied notes do not have to follow each other directly. This can be used for writing out arpeggios.") @@ -441,6 +457,9 @@ signifying the time signature. For example, @code{#'(4 . 4)} is a (timing ,boolean? "Keep administration of measure length, position, bar number, etc.? Switch off for cadenzas.") (tonic ,ly:pitch? "The tonic of the current scale.") + (topLevelAlignment ,boolean? "If true, the @var{Vertical_align_engraver} +will create a @var{VerticalAlignment}; otherwise, it will create a +@var{StaffGrouper}") (trebleStaffProperties ,list? "An alist of property settings to apply for the up staff of @code{PianoStaff}. Used by @code{\\autochange}.") @@ -465,7 +484,6 @@ setting this property, you can make brackets last shorter. (useBassFigureExtenders ,boolean? "Whether to use extender lines for repeated bass figures.") - (verticallySpacedContexts ,list? "List of symbols, containing context names whose vertical axis groups should be taken into account for vertical spacing of systems.") @@ -506,8 +524,6 @@ are described in @rinternals{bar-line-interface}.") (barCheckLastFail ,ly:moment? "Where in the measure did the last barcheck fail?") (beamMelismaBusy ,boolean? "Signal if a beam is present.") - (breakableSeparationItem ,ly:grob? "The breakable items in this -time step, for this staff.") (busyGrobs ,list? "A queue of @code{(@var{end-moment} . @var{GROB})} cons cells. This is for internal (C++) use only. This property contains the grobs which are still busy (e.g. note heads, @@ -520,7 +536,9 @@ current breakable (clef, key signature, etc.) items.") non-breakable items (note heads, lyrics, etc.).") - (dynamicAbsoluteVolumeFunction ,procedure? "[DOCUMENT-ME]") + (dynamicAbsoluteVolumeFunction ,procedure? "A procedure that takes +one argument, the text value of a dynamic event, and returns the absolute +volume of that dynamic event.") (finalizations ,list? "A list of expressions to evaluate before @@ -543,8 +561,8 @@ instrument name to.") signature change.") (localKeySignature ,list? "The key signature at this point in the measure. The format is the same as for @code{keySignature}, but can -also contain @code{((@var{octave} . @var{name}) . (@var{alter} . -@var{barnumber}))} pairs. It is reset at every bar line.") +also contain @code{((@var{octave} . @var{name}) . (@var{alter} +@var{barnumber} . @var{measureposition}))} pairs.") (melismaBusy ,boolean? "Signifies whether a melisma is active.