+@file{scm/@/music@/-functions@/.scm}, @file{scm/@/music@/-types@/.scm},
+@inputfileref{input/@/test,add@/-staccato@/.ly},
+@inputfileref{input/@/test,unfold@/-all@/-repeats@/.ly}, and
+@inputfileref{input/@/test,music@/-box@/.ly}.
+
+
+@node Displaying music expressions
+@subsection Displaying music expressions
+
+@cindex internal storage
+@cindex @code{\displayMusic}
+@cindex @code{\displayLilyMusic}
+
+When writing a music function, it is often instructive to inspect how
+a music expression is stored internally. This can be done with the
+music function @code{\displayMusic}.
+
+@example
+@{
+ \displayMusic @{ c'4\f @}
+@}
+@end example
+
+Conversely, displaying a music expression in LilyPond notation can be
+done using the music function @code{\displayLilyMusic}. For instance:
+
+@example
+@{
+ \displayLilyMusic \transpose c a, @{ c e g a bes @}
+@}
+@end example
+
+will display:
+
+@example
+@{ a, cis e fis g @}
+@end example
+
+@node Using LilyPond syntax inside Scheme
+@subsection Using LilyPond syntax inside Scheme
+
+Creating music expressions in Scheme can be tedious, as they are
+heavily nested and the resulting Scheme code is large. For some
+simple tasks, this can be avoided, using common LilyPond syntax inside
+Scheme, with the dedicated @code{#@{ ... #@}} syntax.
+
+The following two expressions give equivalent music expressions:
+@example
+mynotes = @{ \override Stem #'thickness = #4
+ @{ c'8 d' @} @}
+
+#(define mynotes #@{ \override Stem #'thickness = #4
+ @{ c'8 d' @} #@})
+@end example
+
+The content of @code{#@{ ... #@}} is enclosed in an implicit @code{@{
+... @}} block, which is parsed. The resulting music expression, a
+@code{SequentialMusic} music object, is then returned and usable in Scheme.
+
+Arbitrary Scheme forms, including variables, can be used in @code{#@{ ... #@}}
+expressions with the @code{$} character (@code{$$} can be used to
+produce a single @code{$} character). This makes the creation of simple
+functions straightforward. In the following example, a function
+setting the TextScript's padding is defined:
+
+@lilypond[quote,verbatim,ragged-right]
+#(use-modules (ice-9 optargs))
+#(define* (textpad padding #:optional once?)
+ (ly:export ; this is necessary for using the expression
+ ; directly inside a block
+ (if once?
+ #{ \once \override TextScript #'padding = #$padding #}
+ #{ \override TextScript #'padding = #$padding #})))
+
+ {
+ c'^"1"
+ #(textpad 3.0 #t) % only once
+ c'^"2"
+ c'^"3"
+ #(textpad 5.0)
+ c'^"4"
+ c'^"5"
+ }
+@end lilypond
+
+Here, the variable @code{padding} is a number; music expression
+variables may also be used in a similar fashion, as in the following
+example:
+
+@lilypond[quote,verbatim,ragged-right]
+#(define (with-padding padding)
+ (lambda (music)
+ #{ \override TextScript #'padding = #$padding
+ $music
+ \revert TextScript #'padding #}))
+
+{
+ c'^"1"
+ \applyMusic #(with-padding 3) { c'^"2" c'^"3" }
+ c'^"4"
+}
+@end lilypond
+
+The function created by @code{(with-padding 3)} adds @code{\override} and
+@code{\revert} statements around the music given as an argument, and returns
+this new expression. Thus, this example is equivalent to:
+
+@example
+@{
+ c'^"1"
+ @{ \override TextScript #'padding = #3
+ @{ c'^"2" c'^"3"@}
+ \revert TextScript #'padding
+ @}
+ c'^"4"
+@}
+@end example
+
+This function may also be defined as a music function:
+
+@lilypond[quote,verbatim,ragged-right]
+withPadding =
+ #(define-music-function (parser location padding music) (number? ly:music?)
+ #{ \override TextScript #'padding = #$padding
+ $music
+ \revert TextScript #'padding #})