From 84e6243cfa30f294727192befbba5e746fec6d5f Mon Sep 17 00:00:00 2001
From: Mark Polesky <markpolesky@yahoo.com>
Date: Wed, 21 Aug 2013 11:28:00 -0700
Subject: [PATCH] Doc: Describe \displayScheme.

---
 .../extending/programming-interface.itely     | 46 +++++++++++++++----
 1 file changed, 37 insertions(+), 9 deletions(-)

diff --git a/Documentation/extending/programming-interface.itely b/Documentation/extending/programming-interface.itely
index 3b5e147664..aafb4fc5d3 100644
--- a/Documentation/extending/programming-interface.itely
+++ b/Documentation/extending/programming-interface.itely
@@ -609,21 +609,49 @@ Markups are implemented as special Scheme functions which produce a
 @subsection Markup construction in Scheme
 
 @cindex defining markup commands
+@funindex \displayScheme
+
+Markup expressions are internally represented in Scheme using the
+@code{markup} macro:
 
-The @code{markup} macro builds markup expressions in Scheme while
-providing a LilyPond-like syntax.  For example,
 @example
-(markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
-                  #:larger #:line ("foo" "bar" "baz")))
+(markup @var{expr})
+@end example
+
+To see a markup expression in its Scheme form, use the
+@code{\displayScheme} command:
+
+@example
+\displayScheme
+\markup @{
+  \column @{
+    \line @{ \bold \italic "hello" \raise #0.4 "world" @}
+    \larger \line @{ foo bar baz @}
+  @}
+@}
 @end example
 
 @noindent
-is equivalent to:
+Compiling the code above will send the following to the display
+console:
+
 @example
-#@{ \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
-                  \larger \line @{ foo bar baz @} @} #@}
+(markup
+  #:line
+  (#:column
+   (#:line
+    (#:bold (#:italic "hello") #:raise 0.4 "world")
+    #:larger
+    (#:line
+     (#:simple "foo" #:simple "bar" #:simple "baz")))))
 @end example
 
+To prevent the markup from printing on the page, use
+@w{@samp{\void \displayScheme @var{markup}}}.  Also, as with the
+@code{\displayMusic} command, the output of @code{\displayScheme}
+can be saved to an external file.  See
+@ref{Displaying music expressions}.
+
 @noindent
 This example demonstrates the main translation rules between regular
 LilyPond markup syntax and Scheme markup syntax.  Using @code{#@{
@@ -640,7 +668,7 @@ Scheme-only solution.
 @item @code{\markup-command} @tab @code{#:markup-command}
 @item @code{\variable} @tab @code{variable}
 @item @code{\center-column @{ @dots{} @}} @tab
-        @code{#:center-column ( @dots{} )} 
+        @code{#:center-column ( @dots{} )}
 @item @code{string} @tab @code{"string"}
 @item @code{#scheme-arg} @tab @code{scheme-arg}
 @end multitable
@@ -850,7 +878,7 @@ padding.
             \override #'(box-padding . 0.6) \box @{ #text @}#@}))
 @end lisp
 
-or, equivalently 
+or, equivalently
 
 @lisp
 #(define-markup-command (double-box layout props text) (markup?)
-- 
2.39.2