Doc: extend description of glissandi (2844)

 Add examples of
  - connecting notes across staves
  - connecting notes in chords
  - adding timing marks and expressions to long glissandi
  - making glissandi breakable

 (Based on original work by
  Tiresia GIUNO <tiresiag@googlemail.com>,
  a patch by Werner LEMBERG <wl@gnu.org> and
  advice from Benkő Pál <benko.pal@gmail.com>)

diff --git a/Documentation/notation/expressive.itely b/Documentation/notation/expressive.itely
index 25dbc81d798c75a3b3b1fef709d6fb2b7b66c2e8..6d88b53264093a829f672b97dfb813ec5efe8e69 100644 (file)
--- a/Documentation/notation/expressive.itely
+++ b/Documentation/notation/expressive.itely
@@ -1030,24 +1030,69 @@ follow a linear path: glissandos, arpeggios, and trills.
 @funindex \glissando
 @funindex glissando
 
-A @notation{glissando} is created by attaching @code{\glissando}
+A @notation{glissando} is created by appending @code{\glissando}
 to a note:
 
 @lilypond[verbatim,quote,relative=2]
 g2\glissando g'
 c2\glissando c,
+\afterGrace f,1\glissando f'16
+@end lilypond
+
+A glissando can connect notes across staves:
+
+@lilypond[verbatim,quote]
+\new PianoStaff <<
+  \new Staff = "right" {
+    e'''2\glissando
+    \change Staff = "left"
+    a,,4\glissando
+    \change Staff = "right"
+    b''8 r |
+  }
+  \new Staff = "left" {
+    \clef bass
+    s1
+  }
+>>
+@end lilypond
+
+A glissando can connect notes in chords.  If anything other than a
+direct one-to-one pairing of the notes in the two chords is required
+the connections between the notes are defined by setting
+@code{\glissandoMap}, where the notes of a chord are assumed to be
+numbered from zero in the order in which they appear in the input
+@file{.ly} file.
+
+@lilypond[verbatim,quote,relative=2]
+<c, e>1\glissando g' |
+<c, e>1\glissando |
+<g' b> |
+\break
+\set glissandoMap = #'((0 . 1) (1 . 0))
+<c, g'>1\glissando |
+<d a'> |
+\set glissandoMap = #'((0 . 0) (0 . 1) (0 . 2))
+c1\glissando |
+<d f a> |
+\set glissandoMap = #'((2 . 0) (1 . 0) (0 . 1))
+<f d a'>1\glissando |
+<c c'> |
 @end lilypond
 
 Different styles of glissandi can be created.  For details, see
 @ref{Line styles}.
 
+
 @snippets
+@lilypondfile[verbatim,quote,texidoc,doctitle]
+{contemporary-glissando.ly}
 
 @lilypondfile[verbatim,quote,texidoc,doctitle]
-{glissandi-can-skip-grobs.ly}
+{adding-timing-marks-to-long-glissandi.ly}
 
 @lilypondfile[verbatim,quote,texidoc,doctitle]
-{contemporary-glissando.ly}
+{making-glissandi-breakable.ly}
 
 @seealso
 Music Glossary:

diff --git a/Documentation/snippets/adding-timing-marks-to-long-glissandi.ly b/Documentation/snippets/adding-timing-marks-to-long-glissandi.ly
new file mode 100644 (file)
index 0000000..587a5d9
--- /dev/null
+++ b/Documentation/snippets/adding-timing-marks-to-long-glissandi.ly
@@ -0,0 +1,56 @@
+% DO NOT EDIT this file manually; it is automatically
+% generated from Documentation/snippets/new
+% Make any changes in Documentation/snippets/new/
+% and then run scripts/auxiliar/makelsr.py
+%
+% This file is in the public domain.
+%% Note: this file works from version 2.15.15
+\version "2.15.15"
+
+\header {
+  lsrtags = "expressive-marks, staff-notation, tweaks-and-overrides"
+
+  texidoc = "
+Skipped beats in very long glissandi are sometimes indicated by
+timing marks, often consisting of stems without noteheads.  Such
+stems can also be used to carry intermediate expression markings.
+
+If the stems do not align well with the glissando, they may need to
+be repositioned slightly.
+"
+
+  doctitle = "Adding timing marks to long glissandi"
+} % begin verbatim
+
+
+glissandoSkipOn = {
+  \override NoteColumn #'glissando-skip = ##t
+  \override NoteHead #'transparent = ##t
+  \override NoteHead #'no-ledgers = ##t
+}
+
+glissandoSkipOff = {
+  \revert NoteColumn #'glissando-skip
+  \revert NoteHead #'transparent
+  \revert NoteHead #'no-ledgers
+}
+
+\relative c'' {
+  r8 f8\glissando
+  \glissandoSkipOn
+  f4 g a a8\noBeam
+  \glissandoSkipOff
+  a8
+
+  r8 f8\glissando
+  \glissandoSkipOn
+  g4 a8
+  \glissandoSkipOff
+  a8 |
+
+  r4 f\glissando \<
+  \glissandoSkipOn
+  a4\f \>
+  \glissandoSkipOff
+  b8\! r |
+}

diff --git a/Documentation/snippets/making-glissandi-breakable.ly b/Documentation/snippets/making-glissandi-breakable.ly
new file mode 100644 (file)
index 0000000..9eee164
--- /dev/null
+++ b/Documentation/snippets/making-glissandi-breakable.ly
@@ -0,0 +1,39 @@
+% DO NOT EDIT this file manually; it is automatically
+% generated from Documentation/snippets/new
+% Make any changes in Documentation/snippets/new/
+% and then run scripts/auxiliar/makelsr.py
+%
+% This file is in the public domain.
+%% Note: this file works from version 2.15.15
+\version "2.15.15"
+
+\header {
+  lsrtags = "staff-notation, tweaks-and-overrides"
+
+  texidoc = "
+Setting the @code{breakable} property to @code{#t} in combination with
+@code{after-line-breaking} allows a glissando to break if it occurs
+at a line break:
+"
+
+  doctitle = "Making glissandi breakable"
+} % begin verbatim
+
+
+glissandoSkipOn = {
+  \override NoteColumn #'glissando-skip = ##t
+  \override NoteHead #'transparent = ##t
+  \override NoteHead #'no-ledgers = ##t
+}
+
+\relative c'' {
+  \override Glissando #'breakable = ##t
+  \override Glissando #'after-line-breaking = ##t
+  f1\glissando |
+  \break
+  a4 r2. |
+  f1\glissando
+  \once \glissandoSkipOn
+  \break
+  a2 a4 r4 |
+}

diff --git a/Documentation/snippets/new/adding-timing-marks-to-long-glissandi.ly b/Documentation/snippets/new/adding-timing-marks-to-long-glissandi.ly
new file mode 100644 (file)
index 0000000..f4ff3a7
--- /dev/null
+++ b/Documentation/snippets/new/adding-timing-marks-to-long-glissandi.ly
@@ -0,0 +1,48 @@
+\version "2.15.15"
+
+\header {
+  lsrtags = "expressive-marks, staff-notation, tweaks-and-overrides"
+
+  texidoc = "
+Skipped beats in very long glissandi are sometimes indicated by
+timing marks, often consisting of stems without noteheads.  Such
+stems can also be used to carry intermediate expression markings.
+
+If the stems do not align well with the glissando, they may need to
+be repositioned slightly.
+"
+
+  doctitle = "Adding timing marks to long glissandi"
+}
+
+glissandoSkipOn = {
+  \override NoteColumn #'glissando-skip = ##t
+  \override NoteHead #'transparent = ##t
+  \override NoteHead #'no-ledgers = ##t
+}
+
+glissandoSkipOff = {
+  \revert NoteColumn #'glissando-skip
+  \revert NoteHead #'transparent
+  \revert NoteHead #'no-ledgers
+}
+
+\relative c'' {
+  r8 f8\glissando
+  \glissandoSkipOn
+  f4 g a a8\noBeam
+  \glissandoSkipOff
+  a8
+
+  r8 f8\glissando
+  \glissandoSkipOn
+  g4 a8
+  \glissandoSkipOff
+  a8 |
+
+  r4 f\glissando \<
+  \glissandoSkipOn
+  a4\f \>
+  \glissandoSkipOff
+  b8\! r |
+}

diff --git a/Documentation/snippets/new/making-glissandi-breakable.ly b/Documentation/snippets/new/making-glissandi-breakable.ly
new file mode 100644 (file)
index 0000000..dc2bdfa
--- /dev/null
+++ b/Documentation/snippets/new/making-glissandi-breakable.ly
@@ -0,0 +1,31 @@
+\version "2.15.15"
+
+\header {
+  lsrtags = "staff-notation, tweaks-and-overrides"
+
+  texidoc = "
+Setting the @code{breakable} property to @code{#t} in combination with
+@code{after-line-breaking} allows a glissando to break if it occurs
+at a line break:
+"
+
+  doctitle = "Making glissandi breakable"
+}
+
+glissandoSkipOn = {
+  \override NoteColumn #'glissando-skip = ##t
+  \override NoteHead #'transparent = ##t
+  \override NoteHead #'no-ledgers = ##t
+}
+
+\relative c'' {
+  \override Glissando #'breakable = ##t
+  \override Glissando #'after-line-breaking = ##t
+  f1\glissando |
+  \break
+  a4 r2. |
+  f1\glissando
+  \once \glissandoSkipOn
+  \break
+  a2 a4 r4 |
+}