Issue 3491: Add \displayMarkup command.

Issue 3491: http://code.google.com/p/lilypond/issues/detail?id=3491

[Mark Polesky, 2013-08-12 03:36:10]

Hi all, here's a new patch.

- Mark

[thomasmorley651, 2013-08-12 22:26:41]

This disturbed me to, though, not to a point that I started to work on it my
own. ;)

One thought:

https://codereview.appspot.com/12732043/diff/1/ly/music-functions-init.ly
File ly/music-functions-init.ly (right):

https://codereview.appspot.com/12732043/diff/1/ly/music-functions-init.ly#new...
ly/music-functions-init.ly:346: #(define-void-function (parser location markup)
(markup?)
I'd use define-scheme-function and return the markup in the end.

[thomasmorley651, 2013-08-14 20:33:18]

LGTM

[Ian Hulin (gmail), 2013-08-15 10:14:03]

LGTM, but add suggested clarification to EM text.
Ian

https://codereview.appspot.com/12732043/diff/7001/Documentation/extending/pro...
File Documentation/extending/programming-interface.itely (right):

https://codereview.appspot.com/12732043/diff/7001/Documentation/extending/pro...
Documentation/extending/programming-interface.itely:650: To prevent the markup
from printing on the page, use
"By default @code{\displayMarkup} will print to the console and the output
document.  To avoid affecting the output file, use "

[dak, 2013-08-15 10:36:06]

https://codereview.appspot.com/12732043/diff/7001/Documentation/extending/pro...
File Documentation/extending/programming-interface.itely (right):

https://codereview.appspot.com/12732043/diff/7001/Documentation/extending/pro...
Documentation/extending/programming-interface.itely:650: To prevent the markup
from printing on the page, use
On 2013/08/15 10:14:03, Ian Hulin (gmail) wrote:
> "By default @code{\displayMarkup} will print to the console and the output
> document.  To avoid affecting the output file, use "
>  

I find that even worse.  It's more like

"By default, @code{\displayMarkup} does not only display the markup but also
returns it for use in the document.  This allows you to insert
@code{\displayMarkup} before a markup expression in the document without
changing the resulting document.

If you only want the markup to be displayed but not used in the document, use
@code{\void \displayMarkup} instead."

Personally, I find this does not really meet the "to see how this works"
criterion since the markup expression does _not_ contain a call to the markup
macro at all.  Instead, it is a nested list.

Also, the only thing that makes this "\displayMarkup" rather than
"\displayScheme" is the restriction of the argument type to "markup?".  Perhaps
it would make sense to call the whole function \displayScheme instead and allow
arguments of type scheme? here?

[thomasmorley651, 2013-08-15 11:20:38]

https://codereview.appspot.com/12732043/diff/7001/Documentation/extending/pro...
File Documentation/extending/programming-interface.itely (right):

https://codereview.appspot.com/12732043/diff/7001/Documentation/extending/pro...
Documentation/extending/programming-interface.itely:277: If you want to evaluate
an expression only for its side-effect and
Here \void is declared.
Why repeat it later?
I think a reference should be sufficient.

https://codereview.appspot.com/12732043/diff/7001/Documentation/extending/pro...
Documentation/extending/programming-interface.itely:651: @w{@samp{\void
\displayMarkup @var{markup}}}.  Also, as with the
See above.

[thomasmorley651, 2013-08-15 11:24:15]

On 2013/08/15 10:36:06, dak wrote:

> Also, the only thing that makes this "\displayMarkup" rather than
> "\displayScheme" is the restriction of the argument type to "markup?". 
Perhaps
> it would make sense to call the whole function \displayScheme instead and
allow
> arguments of type scheme? here?

+1
Though, that would mean very little difference between \displayMusic and
\displayScheme.
Any chance to join them completely?

[dak, 2013-08-15 11:34:22]

On 2013/08/15 11:24:15, thomasmorley651 wrote:
> On 2013/08/15 10:36:06, dak wrote:
> 
> > Also, the only thing that makes this "\displayMarkup" rather than
> > "\displayScheme" is the restriction of the argument type to "markup?". 
> Perhaps
> > it would make sense to call the whole function \displayScheme instead and
> allow
> > arguments of type scheme? here?
> 
> +1
> Though, that would mean very little difference between \displayMusic and
> \displayScheme.
> Any chance to join them completely?

Not yet.  It's a long-term goal.  And of course, there are a few things that are
not easily reconciled: compare
\void\displayScheme -5
with
\void\displayMusic -5

[Ian Hulin (gmail), 2013-08-15 12:07:47]

Use David's wording for EM with some tweaks.

Re \displayMarkup \displayScheme:
Markup needs some special-casing as we have our own home-brew
customisable/extensible interpreter in there for interpreting \markup arguments.
 The markup interpreter sometimes does some surprising things under the bonnet -
like implicitly wrapping markup commands in #:line.
Would \displayScheme make debugging markups easier or more difficult?
Should we have a \display <class> <expression> or \dump <class> <expression> API
to part-interpret a LilyPond expression to scheme-primitives, display these to
the console and/or file and *never* affect the output document?  We now have
\displayMusic, \displayLilyMusic, \displayMarkup (and potentially
\displayScheme), so perhaps we need a one-stop shop function to interpret
Music/Markup/Scheme? E.g. \dump 'Music {c'4 e f g}, 
\dump 'Markup {\italic { "Hello " \bold {"Pond!"}}},
\dump 'Scheme #(reverse (list "Pond!" "the " "from " "Hello ")
These are good ideas but maybe stuff for another issue, given that Mark's
original fix was to clarify obtuse wording in the EM.

Ian

https://codereview.appspot.com/12732043/diff/7001/Documentation/extending/pro...
File Documentation/extending/programming-interface.itely (right):

https://codereview.appspot.com/12732043/diff/7001/Documentation/extending/pro...
Documentation/extending/programming-interface.itely:650: To prevent the markup
from printing on the page, use
"By default, @code{\displayMarkup} displays the markup and also returns it for
use in the document.  This allows you to insert 
@code{\displayMarkup} before a markup expression in the document without
changing the resulting document.
If you only want the markup to be displayed but not used in the document, use
@code{\void \displayMarkup} instead."

[dak, 2013-08-15 12:39:40]

ianhulin44@gmail.com writes:

> Use David's wording for EM with some tweaks.
>
> Re \displayMarkup \displayScheme:
> Markup needs some special-casing as we have our own home-brew
> customisable/extensible interpreter in there for interpreting \markup
> arguments.  The markup interpreter sometimes does some surprising things
> under the bonnet - like implicitly wrapping markup commands in #:line.
> Would \displayScheme make debugging markups easier or more difficult?

Uh, nobody suggested changing its internals (except for letting it
accept more arguments).  It uses display-scheme-music either way.

> Should we have a \display <class> <expression> or \dump <class>
> <expression> API to part-interpret a LilyPond expression to
> scheme-primitives, display these to the console and/or file and *never*
> affect the output document?  We now have \displayMusic,
> \displayLilyMusic, \displayMarkup (and potentially \displayScheme), so
> perhaps we need a one-stop shop function to interpret
> Music/Markup/Scheme? E.g. \dump 'Music {c'4 e f g},
> \dump 'Markup {\italic { "Hello " \bold {"Pond!"}}},
> \dump 'Scheme #(reverse (list "Pond!" "the " "from " "Hello ")
> These are good ideas but maybe stuff for another issue, given that
> Mark's original fix was to clarify obtuse wording in the EM.

I think you are confused.  We need separate \display*Music commands
because of having type coercion for its argument and being a music
expression, not because it would format things differently.

This requirement is not there for markups.  LilyPond's display-*-music
commands accept any Scheme expression; they just format those internal
to LilyPond in a friendlier manner.

[Mark Polesky, 2013-08-16 02:38:49]

David Kastrup wrote:
>> Any chance to join them completely?
>
> Not yet.  It's a long-term goal.  And of course, there are a
> few things that are not easily reconciled: compare
> \void\displayScheme -5
> with
> \void\displayMusic -5

Well, I played around with this, and David's example is
pretty convincing.  I vote to go ahead with adding 
\displayMarkup.  I can change the doc wording to suit 
everyone, but I'll wait for consensus on the function
itself.

One thing I don't understand though: what value is there in 
writing a \displayScheme command that takes a scheme 
argument and prints a scheme expression to the console?  
Seems pretty redundant to me.

- Mark

[dak, 2013-08-16 05:50:44]

On 2013/08/16 02:38:49, Mark Polesky wrote:
> David Kastrup wrote:
> >> Any chance to join them completely?
> >
> > Not yet.  It's a long-term goal.  And of course, there are a
> > few things that are not easily reconciled: compare
> > \void\displayScheme -5
> > with
> > \void\displayMusic -5
> 
> Well, I played around with this, and David's example is
> pretty convincing.  I vote to go ahead with adding 
> \displayMarkup.

Huh?  Can you name a _single_ advantage that is gained by having \displayMarkup
(which is only different from \displayScheme by refusing to accept a number of
arguments) instead of \displayScheme?

> One thing I don't understand though: what value is there in 
> writing a \displayScheme command that takes a scheme 
> argument and prints a scheme expression to the console?  
> Seems pretty redundant to me.

You are aware that a scheme? argument does not mean that the argument needs to
be entered with #?

\markup { "Hi" } is a perfectly valid Scheme argument for a music function.

[Mark Polesky, 2013-08-16 07:19:13]

David Kastrup wrote:
>> I vote to go ahead with adding \displayMarkup.
>
> Huh?  Can you name a _single_ advantage that is gained 
> by having \displayMarkup (which is only different from
> \displayScheme by refusing to accept a number of
> arguments) instead of \displayScheme?

Of course not.  I meant let's add \displayMarkup or
\displayScheme as opposed to Harm's or Ian's more generic
proposals.

Also, what is the issue with my original wording?  Seems
clear and concise compared to the other suggestions: 
"To prevent the markup from printing on the page, use
`\void \displayScheme markup'."

I didn't add a @ref to where \void was previously 
explained because reading 13 words is easier than 
following a link and finding the paragraph containing the 
relevant material in a separate section, which in that
specific case, was buried at the very end (Extending 1.3.1
"Displaying music expressions").

I *did* add a @ref to the "save to an external file" stuff
because that's more involved.

I've uploaded the latest incarnation.

Thanks.
- Mark

[janek, 2013-08-18 10:24:37]

LGTM.

[dak, 2013-08-20 13:19:03]

This looks fine for committing to me.  There are several obvious followup
issues/commits making a lot of sense afterwards, however.

One is the obvious complement with \displayLilyScheme which makes sense to do
before the others, namely providing a notice in Documentation/changes.itely and
making some regtest(s).  I'm not sure I have a good idea for a regtest, though. 
Something like input/regression/display-lily-tests.ly seems like quite a bit of
overkill.