Doc addition to 8.1.2 "Text and line spanners" ... concerning \endSpanners

[Trevor Bača]

Hi Graham,

2.11.15 was the release that introduced a bunch of new spanner stuff.
I was just going through my mail from Jan / Feb this year (when
Han-Wen was working on the implementation) trying to find an answer to
Risto's question of whether or not 'to-barline should work correctly
with trill spanners. I haven't, unfortunately, been able to produce a
definitive answer to Risto's question; *but*, I did discover a new
spanner-related music function that has somehow escaped announcement
and documentation.

I describe the behavior below and then suggest a small doc addition to
8.1.2 "Text Spanners" at the end of this mail.

There's a new music function called \endSpanners. The list of music
functions in the music function appendix gives no documentation for
this function (together with a FIXME), but I can provide an
explanation here. \endSpanners makes it possible to issue a
\startTextSpan *without* a matching \stopTextSpan. For example ...

   \new Staff {
      c'1 \startTextSpan c'1
  }

... is syntactically incorrect -- no \stopTextSpan appears and so lily
issues the following warning ...

warning: unterminated text spanner
   c'1
       \startTextSpan c'1

But when we include the command \endSpanners ...

   \new Staff {
      \endSpanners
      c'1 \startTextSpan c'1
   }

... the example is now completely grammatical and interprets just fine.


The command also works for crescendi and decrescendi ...

   \new Staff {
      \endSpanners
      c'1 \< c'1
   }

... where, for example, we see that we need no closing \! to terminate
the crescendo.

The purpose of \endSpanners is not to encourage potentially confusing
input (where start-commands match no closing stop-commands) but rather
to allow for quick and easy input of successive spanners (and
hairpins) all of which terminate *at the very next note*.

So that's a brief explanation of the function. Could you please insert
the following at the very bottom of 8.1.2 "Text and line spanners",
immediately before the "see also"?


%%% BEGIN DOC ADDITION %%%

The music function \endSpanners terminates spanners and hairpins after
exactly one note.

  \new Staff {
    \endSpanners
    c'2 \startTextSpan c'2
    c'2 \< c'2
  }

When using \endSpanners it is not necessary to close \startTextSpan
with \stopTextSpan, nor is it necessary to close hairpins with \!.

%%% END DOC ADDITION %%%



One thing I realize now writing this update is that I don't know if
there is a way to turn \endSpanners *off* at some point in input and
return to specifying spanner (and hairpin) endpoints manually.

If anyone knows of a way to turn \endSpanners off, please reply back
so I can stick that in the docs, too.


Trevor.

-- 
Trevor Bača
address@hidden