Document/Example how to create "standalone" markup commands

[Urs Liska]

Hi all,

I have regularly struggled to get this to work, and now I think there 
should be an additional example in Extending, 2.4 and/or 2.5.

The description in 2.5 explains how to define a markup function that can 
be used as

{
  c' \markup \double-box "Some text"
}

This makes sense, as "double-box" is a natural name for a style applied 
to a markup. However, pretty often one may want to have "standalone" 
markup commands that can be used like e.g.

{
  c'1 \player "Perc. 1" d' player "Perc. 2
}

While it's perfectly possible to use "\markup \player" here too it's 
often relevant to semantically encode elements just like you encode 
\mark or \fermata.

It took me some time to figure out that \double-box can be written and 
used like

doubleBox =
#(define-event-function (text) (markup?)
   (make-music 'TextScriptEvent 'text
     (markup #:override '(box-padding . 0.4) #:box
       #:override '(box-padding . 0.6) #:box text)))

\relative {
  c'1 \doubleBox "Implicitly Neutral"
  c -\doubleBox "Explicitly neutral"
  c ^\doubleBox Above
  c _\doubleBox Below
}

And while it's theoretically possible to infer that from the description 
of the event-function \dyn in section 2.4 it is a quite far stretch to 
expect users to manage that.

I can't make a proposal as a patch because I still feel too insecure 
about it, but I would make two suggestions:

1) Add at the end of 2.4 something along the lines of

   It may also be useful to specify markup commands that way. See the
   example in "Markup Functions".

2) In 2.5, before the section "Adapting builtin commands", add something 
along the lines of

   Sometimes it is desirable to create "standalone" markup commands
   that can directly be used *in place* of `\markup` with formatting
   commands. To achieve this one has to write an "event function" and
   create a TextScriptEvent and within that a markup definition. Note
   how the following command can be used with or without directional
   operators.

I'm not sure if it's good to rewrite the \double-box example as I did 
above. While this would highlight the difference in implementation and 
usage it might be confusing as for the possible semantic use. Maybe the 
following example would be clearer:

player =
#(define-event-function (name) (markup?)
   (make-music 'TextScriptEvent 'text
     (markup #:italic #:with-color red name)))

\relative {
  c'1 ^\player Juliet
  d \player Romeo
}