X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;ds=inline;f=scm%2Fdefine-markup-commands.scm;h=c04f8ee58b1677daec4eb90621ddff22e32b2d77;hb=9c1b934050818defbcce7acf13593d837ee69894;hp=6b39e779d89c79401f61542cda0ae482f61f7b39;hpb=dc2e117a47485e492836576fea9b00158958b47d;p=lilypond.git

diff --git a/scm/define-markup-commands.scm b/scm/define-markup-commands.scm
index 6b39e779d8..c04f8ee58b 100644
--- a/scm/define-markup-commands.scm
+++ b/scm/define-markup-commands.scm
@@ -281,7 +281,7 @@ Draw a box with rounded corners around @var{arg}.  Looks at @code{thickness},
 thickness and padding around the markup; the @code{corner-radius} property
 makes possible to define another shape for the corners (default is 1).
 
-@lilypond[quote,verbatim,fragment,relative=2]
+@lilypond[quote,verbatim,relative=2]
 c4^\\markup {
   \\rounded-box {
     Overtura
@@ -330,9 +330,8 @@ Provide a white background for @var{arg}.
 @lilypond[verbatim,quote]
 \\markup {
   \\combine
-  \\filled-box #'(-1 . 10) #'(-3 . 4) #1
-  \\whiteout
-  whiteout
+    \\filled-box #'(-1 . 10) #'(-3 . 4) #1
+    \\whiteout whiteout
 }
 @end lilypond"
   (stencil-whiteout (interpret-markup layout props arg)))
@@ -345,7 +344,21 @@ Provide a white background for @var{arg}.
 @cindex padding text
 @cindex putting space around text
 
-Add space around a markup object."
+Add space around a markup object.
+
+@lilypond[verbatim,quote]
+\\markup {
+  \\box {
+    default
+  }
+  \\hspace #2
+  \\box {
+    \\pad-around #1 {
+      padded
+    }
+  }
+}
+@end lilypond"
   (let*
       ((stil (interpret-markup layout props arg))
        (xext (ly:stencil-extent stil X))
@@ -419,10 +432,9 @@ normally inserted before elements on a line.
 
 Use a stencil as markup.
 
-@c FIXME works in .ly file, produces empty stencil in docs
 @lilypond[verbatim,quote]
 \\markup {
-  \\stencil #(dimension-arrows '(15 . 0))
+  \\stencil #(make-circle-stencil 2 0 #t)
 }
 @end lilypond"
   stil)
@@ -626,6 +638,9 @@ An empty markup with extents of a single point.
 A simple text string; @code{\\markup @{ foo @}} is equivalent with
 @code{\\markup @{ \\simple #\"foo\" @}}.
 
+Note: for creating standard text markup or defining new markup commands,
+the use of @code{\\simple} is unnecessary.
+
 @lilypond[verbatim,quote]
 \\markup {
   \\simple #\"simple\"
@@ -1036,7 +1051,31 @@ the line width, where @var{X} is the number of staff spaces.
   (symbol?)
   align
   ()
-  "Wordwrap the data which has been assigned to @var{symbol}."
+  "Wordwrap the data which has been assigned to @var{symbol}.
+  
+@lilypond[verbatim,quote]
+\\header {
+  title = \"My title\"
+  descr = \"Lorem ipsum dolor sit amet, consectetur adipisicing elit,
+  sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris
+  nisi ut aliquip ex ea commodo consequat.\"
+}
+
+\\paper {
+  bookTitleMarkup = \\markup {
+    \\column {
+      \\fill-line { \\fromproperty #'header:title }
+      \\null
+      \\wordwrap-field #'header:descr
+    }
+  }
+}
+
+\\markup {
+  \\null
+}
+@end lilypond"
   (let* ((m (chain-assoc-get symbol props)))
     (if (string? m)
         (wordwrap-string-markup layout props m)
@@ -1046,7 +1085,31 @@ the line width, where @var{X} is the number of staff spaces.
   (symbol?)
   align
   ()
-  "Justify the data which has been assigned to @var{symbol}."
+  "Justify the data which has been assigned to @var{symbol}.
+  
+@lilypond[verbatim,quote]
+\\header {
+  title = \"My title\"
+  descr = \"Lorem ipsum dolor sit amet, consectetur adipisicing elit,
+  sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris
+  nisi ut aliquip ex ea commodo consequat.\"
+}
+
+\\paper {
+  bookTitleMarkup = \\markup {
+    \\column {
+      \\fill-line { \\fromproperty #'header:title }
+      \\null
+      \\justify-field #'header:descr
+    }
+  }
+}
+
+\\markup {
+  \\null
+}
+@end lilypond"
   (let* ((m (chain-assoc-get symbol props)))
     (if (string? m)
         (justify-string-markup layout props m)
@@ -1060,13 +1123,21 @@ the line width, where @var{X} is the number of staff spaces.
 @cindex merging text
 
 Print two markups on top of each other.
+
+Note: @code{\\combine} cannot take a list of markups enclosed in
+curly braces as an argument; the follow example will not compile:
+
+@example
+\\combine @{ a list @}
+@end example
+
 @lilypond[verbatim,quote]
 \\markup {
   \\fontsize #5
   \\override #'(thickness . 2)
   \\combine
-  \\draw-line #'(0 . 4)
-  \\arrow-head #Y #DOWN ##f
+    \\draw-line #'(0 . 4)
+    \\arrow-head #Y #DOWN ##f
 }
 @end lilypond"
   (let* ((s1 (interpret-markup layout props m1))
@@ -1321,7 +1392,21 @@ Set the dimensions of @var{arg} to @var{x} and@tie{}@var{y}."
   (number? markup?)
   align
   ()
-  "Add padding @var{amount} all around @var{arg}."  
+  "Add padding @var{amount} all around @var{arg}.
+  
+@lilypond[verbatim,quote]
+\\markup {
+  \\box {
+    default
+  }
+  \\hspace #2
+  \\box {
+    \\pad-around #0.5 {
+      padded
+    }
+  }
+}
+@end lilypond"
   (let* ((m (interpret-markup layout props arg))
          (x (ly:stencil-extent m X))
          (y (ly:stencil-extent m Y)))
@@ -1336,7 +1421,21 @@ Set the dimensions of @var{arg} to @var{x} and@tie{}@var{y}."
   "
 @cindex padding text horizontally
 
-Add padding @var{amount} around @var{arg} in the X@tie{}direction."
+Add padding @var{amount} around @var{arg} in the X@tie{}direction.
+
+@lilypond[verbatim,quote]
+\\markup {
+  \\box {
+    default
+  }
+  \\hspace #4
+  \\box {
+    \\pad-x #2 {
+      padded
+    }
+  }
+}
+@end lilypond"
   (let* ((m (interpret-markup layout props arg))
          (x (ly:stencil-extent m X))
          (y (ly:stencil-extent m Y)))
@@ -1344,8 +1443,8 @@ Add padding @var{amount} around @var{arg} in the X@tie{}direction."
                      (interval-widen x amount)
                      y)))
 
-(define-builtin-markup-command (put-adjacent layout props arg1 axis dir arg2)
-  (markup? integer? ly:dir? markup?)
+(define-builtin-markup-command (put-adjacent layout props axis dir arg1 arg2)
+  (integer? ly:dir? markup? markup?)
   align
   ()
   "Put @var{arg2} next to @var{arg1}, without moving @var{arg1}."
@@ -1375,7 +1474,21 @@ Add padding @var{amount} around @var{arg} in the X@tie{}direction."
   (number-pair? number-pair? markup?)
   align
   ()
-  "Make @var{arg} take at least @var{x-ext}, @var{y-ext} space."
+  "Make @var{arg} take at least @var{x-ext}, @var{y-ext} space.
+
+@lilypond[verbatim,quote]
+\\markup {
+  \\box {
+    default
+  }
+  \\hspace #4
+  \\box {
+    \\pad-to-box #'(0 . 10) #'(0 . 3) {
+      padded
+    }
+  }
+}
+@end lilypond"
   (let* ((m (interpret-markup layout props arg))
          (x (ly:stencil-extent m X))
          (y (ly:stencil-extent m Y)))
@@ -1388,7 +1501,27 @@ Add padding @var{amount} around @var{arg} in the X@tie{}direction."
   align
   ()
   "Center @var{arg} horizontally within a box of extending
-@var{length}/2 to the left and right."
+@var{length}/2 to the left and right.
+
+@lilypond[quote,verbatim]
+\\new StaffGroup <<
+  \\new Staff {
+    \\set Staff.instrumentName = \\markup {
+      \\hcenter-in #12
+      Oboe
+    }
+    c''1
+  }
+  \\new Staff {
+    \\set Staff.instrumentName = \\markup {
+      \\hcenter-in #12
+      Bassoon
+    }
+    \\clef tenor
+    c'1
+  }
+>>
+@end lilypond"
   (interpret-markup layout props
                     (make-pad-to-box-markup
                      (cons (/ length -2) (/ length 2))
@@ -1829,7 +1962,10 @@ some punctuation.  It doesn't have any letters.
   (markup?)
   font
   ()
-  "Set @code{font-shape} to @code{caps}"
+  "Set @code{font-shape} to @code{caps}
+  
+Note: @code{\\fontCaps} requires the installation and selection of
+fonts which support the @code{caps} font shape."
   (interpret-markup layout (prepend-alist-chain 'font-shape 'caps props) arg))
 
 ;; Poor man's caps
@@ -2342,7 +2478,6 @@ and continue with double letters.
      (number->markletter-string number->mark-alphabet-vector num)))
 
 (define-public (horizontal-slash-interval num forward number-interval mag)
-  (ly:message "Mag step: ~a" mag)
   (if forward
     (cond ;((= num 6) (interval-widen number-interval (* mag 0.5)))
           ;((= num 5) (interval-widen number-interval (* mag 0.5)))
@@ -2394,7 +2529,6 @@ and continue with double letters.
                                          ,(cdr num-x) ,(+ (interval-center num-y) dy))
                              num-x num-y)
                             #f)))
-(ly:message "Num: ~a, X-interval: ~a" num num-x)
     (if (ly:stencil? slash-stencil)
       (begin
         ; for some numbers we need to shift the slash/backslash up or down to make
@@ -2917,25 +3051,25 @@ when @var{label} is not found."
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
 (define-public (space-lines baseline stils)
-  (let space-stil ((prev-stil #f)
-		   (stils stils)
+  (let space-stil ((stils stils)
 		   (result (list)))
-    (cond ((null? stils)
-	   (reverse! result))
-	  ((not prev-stil)
-	   (space-stil (car stils) (cdr stils) (list (car stils))))
-	  (else
-	   (let* ((stil (car stils))
-		  (dy (max (- baseline
-			      (+ (- (interval-bound (ly:stencil-extent prev-stil Y) DOWN))
-				 (interval-bound (ly:stencil-extent stil Y) UP)))
-			   0.0))
-		  (new-stil (ly:make-stencil
-			     (ly:stencil-expr stil)
-			     (ly:stencil-extent stil X)
-			     (cons (interval-bound (ly:stencil-extent stil Y) DOWN)
-				   (+ (interval-bound (ly:stencil-extent stil Y) UP) dy)))))
-	     (space-stil stil (cdr stils) (cons new-stil result)))))))
+    (if (null? stils)
+	(reverse! result)
+	(let* ((stil (car stils))
+	       (dy-top (max (- (/ baseline 1.5)
+			       (interval-bound (ly:stencil-extent stil Y) UP))
+			    0.0))
+	       (dy-bottom (max (+ (/ baseline 3.0)
+				  (interval-bound (ly:stencil-extent stil Y) DOWN))
+			       0.0))
+	       (new-stil (ly:make-stencil
+			  (ly:stencil-expr stil)
+			  (ly:stencil-extent stil X)
+			  (cons (- (interval-bound (ly:stencil-extent stil Y) DOWN)
+				   dy-bottom)
+				(+ (interval-bound (ly:stencil-extent stil Y) UP)
+				   dy-top)))))
+	  (space-stil (cdr stils) (cons new-stil result))))))
 
 (define-builtin-markup-list-command (justified-lines layout props args)
   (markup-list?)