documentation for markups in scheme

[Nicolas Sceaux]

Hello,

This patch for Documentation/user/refman.itely contains documentation
for the def-markup-command and markup macros. Please feel free to
arrange it to your taste.

nicolas

--- refman.itely.~1.417.~       2004-02-07 14:25:29.000000000 +0100
+++ refman.itely        2004-02-07 21:42:40.000000000 +0100
@@ -8251,6 +8251,11 @@
 
 Init files:  @file{scm/new-markup.scm}.
 
address@hidden
+* Markup construction in scheme::
+* Markup command definition::
address@hidden menu
+
 @refbugs
 
 @cindex kerning
@@ -8267,8 +8272,113 @@
 for formatting.
 
 
address@hidden Markup construction in scheme
address@hidden Markup construction in scheme
+
+The @code{markup} macro aims at building markup expressions in
+scheme, by providing a LilyPond-like syntax. Example:
address@hidden
+(markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
+                  #:bigger #:line ("foo" "bar" "baz")))
address@hidden example
+is equivalent to:
address@hidden
+\markup \column < @{ \bold \italic "hello" \raise #0.4 "world" @}
+                  \bigger @{ foo bar baz @} >
address@hidden example
+This example exposes the main translation rules between regular
+LilyPond markup syntax and scheme markup syntax, which are summed up
+is this table:
address@hidden @columnfractions .5 .5
address@hidden @b{LilyPond} @tab @b{Scheme}
address@hidden @code{\command} @tab @code{#:command}
address@hidden @code{\variable} @tab @code{variable}
address@hidden @address@hidden ... @}} @tab @code{#:line ( ... )}
address@hidden @code{\center < ... >} @tab @code{#:center ( ... )}
address@hidden @code{string} @tab @code{"string"}
address@hidden @code{#scheme-arg} @tab @code{scheme-arg}
address@hidden multitable
+
+Besides, the whole scheme language is accessible inside the
address@hidden macro: thus, one may use function calls inside
address@hidden in order to manipulate character strings for
+instance. This proves useful when defining new markup commands
+(see @ref{Markup command definition}).
+
address@hidden: One can not feed the @code{#:line} (resp
address@hidden:center}, @code{#:column})  command with a variable or the
+result of a function call. Eg: 
address@hidden
+(markup #:line (fun-that-returns-markups))
address@hidden lisp
+is illegal. One should use the @code{make-line-markup} (resp
address@hidden, @code{make-column-markup}) function
+instead:
address@hidden
+(markup (make-line-markup (fun-that-returns-markups)))
address@hidden lisp
+
address@hidden Markup command definition
address@hidden Markup command definition
+
+New markup commands can be defined thanks to the @code{def-markup-command} 
scheme macro.
address@hidden
+(def-markup-command (@emph{command-name} paper props @emph{arg1} @emph{arg2} 
...) (@emph{arg1-type?} @emph{arg2-type?} ...)
+  ..command body..)
+
+    @emph{argi}: address@hidden command argument
+    @emph{argi-type?}: a type predicate for the address@hidden argument
address@hidden lisp
+
+Example: Typesetting a Recitative in an opera, we would like to define
+a command that will show character names, in a custom manner. Names
+should be printed with small caps, and translated a bit to the left
+and top. There is no markup command available to print a string with
+small caps, so we will first define a @code{\smallcaps} markup
+command. Then, we will define a @code{\character} command that takes
+into account the needed translation.
+
address@hidden,verbatim]
+#(def-markup-command (smallcaps paper props str) (string?)
+   "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
+   (interpret-markup paper props
+    (make-line-markup
+     (map (lambda (s)
+            (if (= (string-length s) 0)
+                s
+                (markup #:large (string-upcase (substring s 0 1))
+                        #:translate (cons -0.6 0) #:tiny (string-upcase 
(substring s 1)))))
+          (string-split str #\Space)))))
+
+#(def-markup-command (character paper props name) (string?)
+   "Print the character name in small caps, translated to the left and
+   top. Syntax: \\character #\"name\""
+   (interpret-markup paper props 
+    (markup "" #:translate (cons -4 2) #:smallcaps name)))
+
+\score {
+    \notes { \fatText
+        c''^\markup \character #"Cleopatra"
+        e'^\markup \character #"Giulio Cesare"
+    }
+}
address@hidden lilypond
 
+The @code{smallcaps} command first splits its string argument into
+tokens separated by spaces (@code{(string-split str #\Space)}); for
+each token, a markup is built with the first letter made large and
+upcased (@code{#:large (string-upcase (substring s 0 1))}), and a
+second markup built with the following letters made tiny and upcased
+(@code{#:tiny (string-upcase (substring s 1))}). As LilyPond
+introduces a space between markups on a line, the second markup is
+translated to the left (@code{#:translate (cons -0.6 0) ...}). Then,
+the markups built for each token are put in a line
+(@code{(make-line-markup ...)}). Finally, the resulting markup is
+passed to the @code{interpret-markup} function, with the @code{paper}
+and @code{props} arguments.
 
+The @code{character} command is just a combination of existing markup
+commands, including the newly defined @code{smallcaps} command.
 
 
 @node Global layout