Imported Upstream version 2.19.45

[lilypond.git] / Documentation / snippets / displaying-grob-ancestry.ly

diff --git a/Documentation/snippets/displaying-grob-ancestry.ly b/Documentation/snippets/displaying-grob-ancestry.ly
index d6c8d46a2a2534599c2d762f3ae70d91b76de6ed..dc55c346f292d241239bf3fd83329cc80767a489 100644 (file)
--- a/Documentation/snippets/displaying-grob-ancestry.ly
+++ b/Documentation/snippets/displaying-grob-ancestry.ly
@@ -1,29 +1,33 @@
 %% DO NOT EDIT this file manually; it is automatically
-%% generated from LSR http://lsr.dsi.unimi.it
+%% generated from LSR http://lsr.di.unimi.it
 %% Make any changes in LSR itself, or in Documentation/snippets/new/ ,
 %% and then run scripts/auxiliar/makelsr.py
 %%
 %% This file is in the public domain.
-\version "2.17.6"
+\version "2.18.0"
 
 \header {
   lsrtags = "devel, scheme-language, tweaks-and-overrides"
 
   texidoc = "
 When working with grob callbacks, it can be helpful to understand a
-grob's @qq{ancestry}. Most grobs have @qq{parents} which influence the
+grob’s ancestry. Most grobs have parents which influence the
 positioning of the grob. X- and Y-parents influence the horizontal and
 vertical positions for the grob, respectively. Additionally, each
 parent may have parents of its own.
 
 
-Unfortunately, there are several aspects of a grob's ancestry that can
+Unfortunately, there are several aspects of a grob’s ancestry that can
 lead to confusion:
 
-* The types of parents a grob has may depend on context. * For some
-grobs, the X- and Y-parents are the same. * A particular @qq{ancestor}
-may be related to a grob in multiple ways. * The concept of
-@qq{generations} is misleading.
+
+* The types of parents a grob has may depend on context.
+
+* For some grobs, the X- and Y-parents are the same.
+
+* A particular “ancestor” may be related to a grob in multiple ways.
+
+* The concept of “generations” is misleading.
 
 
 For example, the @code{System} grob can be both parent (on the Y-side)
@@ -31,51 +35,46 @@ and grandparent (twice on the X-side) to a @code{VerticalAlignment}
 grob.
 
 
-This macro prints (to the console) a textual representation of a grob's
+This macro prints (to the console) a textual representation of a grob’s
 ancestry.
 
+When called this way:
 
-When called this way
-
-
-@{
- \\once \\override NoteHead.before-line-breaking = #display-ancestry
- c @}
-
+@code{@{ \\once \\override NoteHead.before-line-breaking =
+#display-ancestry c @}}
 
 The following output is generated:
 
 
-------------------------------------
-
-NoteHead X,Y: NoteColumn
-    X: PaperColumn
-       X,Y: System
-    Y: VerticalAxisGroup
-       X: NonMusicalPaperColumn
-          X,Y: System
-       Y: VerticalAlignment
-          X: NonMusicalPaperColumn
-             X,Y: System
-          Y: System
-
-
+@code{NoteHead X,Y: NoteColumn
+     X: PaperColumn
+        X,Y: System
+     Y: VerticalAxisGroup
+        X: NonMusicalPaperColumn
+           X,Y: System
+        Y: VerticalAlignment
+           X: NonMusicalPaperColumn
+              X,Y: System
+           Y: System}
 
 "
   doctitle = "Displaying grob ancestry"
 } % begin verbatim
 
-#(define (grob-name grob)
-   (if (ly:grob? grob)
-       (assoc-ref (ly:grob-property grob 'meta) 'name)
-       #f))
+%% http://lsr.di.unimi.it/LSR/Item?id=622
+%% see also http://www.lilypond.org/doc/v2.18/Documentation/snippets/tweaks-and-overrides#tweaks-and-overrides-displaying-grob-ancestry
+
+%% Remark:
+%% grob::name is in the source since 2.19.x could be deleted during next LSR-upgrade
+#(define (grob::name grob)
+  (assq-ref (ly:grob-property grob 'meta) 'name))
 
 #(define (get-ancestry grob)
-   (if (not (null? (ly:grob-parent grob X)))
-       (list (grob-name grob)
-             (get-ancestry (ly:grob-parent grob X))
-             (get-ancestry (ly:grob-parent grob Y)))
-       (grob-name grob)))
+  (if (not (null? (ly:grob-parent grob X)))
+      (list (grob::name grob)
+            (get-ancestry (ly:grob-parent grob X))
+            (get-ancestry (ly:grob-parent grob Y)))
+      (grob::name grob)))
 
 #(define (format-ancestry lst padding)
    (string-append
@@ -111,7 +110,9 @@ NoteHead X,Y: NoteColumn
    (format (current-error-port)
       "~3&~a~2%~a~&"
       (make-string 36 #\-)
-      (format-ancestry (get-ancestry grob) 0)))
+      (if (ly:grob? grob)
+          (format-ancestry (get-ancestry grob) 0)
+          (format #f "~a is not a grob" grob))))
 
 \relative c' {
   \once \override NoteHead.before-line-breaking = #display-ancestry