From 676e9ead2f2953945d0c6624b95b52ed0e4242b4 Mon Sep 17 00:00:00 2001 From: Mark Polesky Date: Thu, 17 Jul 2014 22:19:15 -0700 Subject: [PATCH] Issue 4024: Clarify break-align symbols and space-alist args in IR. --- lily/break-alignment-interface.cc | 71 +++++++++--------- scm/define-grob-properties.scm | 118 +++++++++++++++++++++++------- 2 files changed, 127 insertions(+), 62 deletions(-) diff --git a/lily/break-alignment-interface.cc b/lily/break-alignment-interface.cc index 76d1e48ca4..1744c60214 100644 --- a/lily/break-alignment-interface.cc +++ b/lily/break-alignment-interface.cc @@ -363,6 +363,42 @@ Break_aligned_interface::calc_break_visibility (SCM smob) return ret; } +ADD_INTERFACE (Break_alignment_interface, + "The object that performs break alignment.\n" + "\n" + "Three interfaces deal specifically with break alignment:\n" + "@enumerate\n" + "@item break-alignment-interface (this one),\n" + "@item @ref{break-alignable-interface}, and\n" + "@item @ref{break-aligned-interface}.\n" + "@end enumerate\n" + "\n" + " Each of these interfaces supports grob properties that use" + " @w{@emph{break-align symbols}}, which are Scheme symbols that" + " are used to specify the alignment, ordering, and spacing of" + " certain notational elements (@q{breakable}@tie{}items)." + "\n" + "@subsubheading Available break-align symbols:\n" + "\n" + "@example\n" + "ambitus\n" + "breathing-sign\n" + "clef\n" + "cue-clef\n" + "cue-end-clef\n" + "custos\n" + "key-cancellation\n" + "key-signature\n" + "left-edge\n" + "staff-bar\n" + "time-signature\n" + "@end example", + + /* properties */ + "positioning-done " + "break-align-orders " + ); + ADD_INTERFACE (Break_alignable_interface, "Object that is aligned on a break alignment.", @@ -372,31 +408,7 @@ ADD_INTERFACE (Break_alignable_interface, ); ADD_INTERFACE (Break_aligned_interface, - "Items that are aligned in prefatory matter.\n" - "\n" - "The spacing of these items is controlled by the" - " @code{space-alist} property. It contains a list" - " @code{break-align-symbol}s with a specification of the" - " associated space. The space specification can be\n" - "\n" - "@table @code\n" - "@item (minimum-space . @var{spc}))\n" - "Pad space until the distance is @var{spc}.\n" - "@item (fixed-space . @var{spc})\n" - "Set a fixed space.\n" - "@item (semi-fixed-space . @var{spc})\n" - "Set a space. Half of it is fixed and half is stretchable." - " (does not work at start of line. fixme)\n" - "@item (extra-space . @var{spc})\n" - "Add @var{spc} amount of space.\n" - "@end table\n" - "\n" - "Special keys for the alist are @code{first-note} and" - " @code{next-note}, signifying the first note on a line, and" - " the next note halfway a line.\n" - "\n" - "Rules for this spacing are much more complicated than this." - " See [Wanske] page 126--134, [Ross] page 143--147.", + "Breakable items.", /* properties */ "break-align-anchor " @@ -404,12 +416,3 @@ ADD_INTERFACE (Break_aligned_interface, "break-align-symbol " "space-alist " ); - -ADD_INTERFACE (Break_alignment_interface, - "The object that performs break alignment. See" - " @ref{break-aligned-interface}.", - - /* properties */ - "positioning-done " - "break-align-orders " - ); diff --git a/scm/define-grob-properties.scm b/scm/define-grob-properties.scm index cd5b663f3b..05cff648d4 100644 --- a/scm/define-grob-properties.scm +++ b/scm/define-grob-properties.scm @@ -125,43 +125,47 @@ visibility of the tuplet bracket. Setting it to false prevents printing of the bracket. Setting the property to @code{if-no-beam} makes it print only if there is no beam associated with this tuplet bracket.") - (break-align-anchor ,number? "Grobs aligned to this break-align -grob will have their X-offsets shifted by this number. In bar lines, + (break-align-anchor ,number? "Grobs aligned to this breakable +item will have their X-offsets shifted by this number. In bar lines, for example, this is used to position grobs relative to the (visual) center of the bar line.") (break-align-anchor-alignment ,number? "Read by @code{ly:break-aligned-interface::calc-extent-aligned-anchor} for aligning an anchor to a grob's extent.") - (break-align-orders ,vector? "Defines the order in which -prefatory matter (clefs, key signatures) appears. The format is a -vector of length@tie{}3, where each element is one order for -end-of-line, middle of line, and start-of-line, respectively. An -order is a list of symbols. + (break-align-orders ,vector? "This is a vector of 3@tie{}lists: +@w{@code{#(@var{end-of-line} @var{unbroken} @var{start-of-line}}}). +Each list contains @w{@emph{break-align symbols}} that specify an +order of breakable items (see @rinternals{break-alignment-interface}). -For example, clefs are put after key signatures by setting +For example, this places time signatures before clefs: @example -\\override Score.BreakAlignment #'break-align-orders = - #(make-vector 3 '(span-bar +\\override Score.BreakAlignment.break-align-orders = + #(make-vector 3 '(left-edge + cue-end-clef + ambitus breathing-sign - staff-bar - key + time-signature clef - time-signature)) + cue-clef + staff-bar + key-cancellation + key-signature + custos)) @end example") - (break-align-symbol ,symbol? "This key is used for aligning and -spacing breakable items.") - (break-align-symbols ,list? "A list of symbols that determine -which break-aligned grobs to align this to. If the grob selected by -the first symbol in the list is invisible due to break-visibility, we -will align to the next grob (and so on). Choices are @code{left-edge}, -@code{ambitus}, @code{breathing-sign}, @code{clef}, @code{staff-bar}, -@code{key-cancellation}, @code{key-signature}, @code{time-signature}, -and @code{custos}.") + (break-align-symbol ,symbol? "This key is used for aligning, +ordering, and spacing breakable items. See +@rinternals{break-alignment-interface}.") + (break-align-symbols ,list? "A list of +@w{@emph{break-align symbols}} that determines which breakable +items to align this to. If the grob selected by the first symbol +in the list is invisible due to @w{@code{break-visibility}}, we +will align to the next grob (and so on). Choices are listed in +@rinternals{break-alignment-interface}.") (break-overshoot ,number-pair? "How much does a broken spanner stick out of its bounds?") (break-visibility ,vector? "A vector of 3@tie{}booleans, -@code{#(@var{end-of-line} @var{unbroken} @var{begin-of-line})}. +@w{@code{#(@var{end-of-line} @var{unbroken} @var{begin-of-line})}}. @code{#t} means visible, @code{#f} means killed.") (breakable ,boolean? "Allow breaks here.") (broken-bound-padding ,number? "The amount of padding to insert @@ -862,11 +866,69 @@ elements closer together.") (slur-padding ,number? "Extra distance between slur and script.") (snap-radius ,number? "The maximum distance between two objects that will cause them to snap to alignment along an axis.") - (space-alist ,list? "A table that specifies distances between -prefatory items, like clef and time-signature. The format is an alist -of spacing tuples: @code{(@var{break-align-symbol} @var{type} -. @var{distance})}, where @var{type} can be the symbols -@code{minimum-space} or @code{extra-space}.") + (space-alist ,list? "An alist that specifies distances from this +grob to other breakable items, using the format: + +@example +'((@var{break-align-symbol} . (@var{spacing-style} . @var{space})) + (@var{break-align-symbol} . (@var{spacing-style} . @var{space})) + ...) +@end example + +Standard choices for @w{@code{@var{break-align-symbol}}} are listed in +@rinternals{break-alignment-interface}. Additionally, three special +@w{break-align} symbols available to @w{@code{space-alist}} are: + +@quotation +@table @code +@item first-note +used when the grob is just left of the first note on a line + +@item next-note +used when the grob is just left of any other note + +@item right-edge +used when the grob is the last item on the line (only compatible with +the @w{@code{extra-space}} spacing style) +@end table +@end quotation + +Choices for @code{@var{spacing-style}} are: + +@quotation +@table @code +@item extra-space +Put this much space between the two grobs. The space is stretchable +when paired with @w{@code{first-note}} or @w{@code{next-note}}; +otherwise it is fixed. + +@item minimum-space +Put at least this much space between the left sides of both grobs, +without allowing them to collide. The space is stretchable when paired +with @w{@code{first-note}} or @w{@code{next-note}}; otherwise it +is fixed. Not compatible with @w{@code{right-edge}}. + +@item fixed-space +Only compatible with @w{@code{first-note}} and +@w{@code{next-note}}. Put this much fixed space between the grob +and the note. + +@item minimum-fixed-space +Only compatible with @w{@code{first-note}} and +@w{@code{next-note}}. Put at least this much fixed space between +the left side of the grob and the left side of the note, without +allowing them to collide. + +@item semi-fixed-space +Only compatible with @w{@code{first-note}} and +@w{@code{next-note}}. Put this much space between the grob and +the note, such that half of the space is fixed and half is +stretchable. +@end table +@end quotation + +Rules for this spacing are much more complicated than this. +See [Wanske] page 126--134, [Ross] page 143--147.") (space-to-barline ,boolean? "If set, the distance between a note and the following non-musical column will be measured to the bar line instead of to the beginning of the non-musical column. If there is a -- 2.39.2