Docs: NR -- add information on partcombine and autoBeamOff

diff --git a/Documentation/notation/rhythms.itely b/Documentation/notation/rhythms.itely
index 8d83dd3c9de4f86a636cba031d6e7cb2dc7ff746..9cbad9fba738f1ba65d8f797534eb62336c7dfd6 100644 (file)
--- a/Documentation/notation/rhythms.itely
+++ b/Documentation/notation/rhythms.itely
@@ -1666,6 +1666,9 @@ c16 c8
 automatic beaming should be switched off with @code{\autoBeamOff}
 and the beams indicated manually.}
 
+@warning{Using @code{@bs{}partcombine} with @code{@bs{}autoBeamOff} can
+produce unintended results.  See the snippet below for more information.}
+
 Beaming patterns that differ from the automatic defaults can be
 created; see @ref{Setting automatic beam behavior}.
 
@@ -1678,6 +1681,7 @@ created; see @ref{Setting automatic beam behavior}.
 
 @snippets
 
+
 @cindex line breaks and beams
 @cindex beams and line breaks
 
@@ -1689,6 +1693,13 @@ created; see @ref{Setting automatic beam behavior}.
 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 {changing-beam-knee-gap.ly}
 
+@cindex \partcombine and \autoBeamOff
+@cindex \autoBeamOff and \partcombine
+
+
+@lilypondfile [verbatim, lilyquote, ragged-right, texidoc, doctitle]
+{partcombine-and-autobeamoff.ly}
+
 
 @seealso
 Notation Reference:

diff --git a/Documentation/snippets/new/partcombine-and-autobeamoff.ly b/Documentation/snippets/new/partcombine-and-autobeamoff.ly
new file mode 100644 (file)
index 0000000..ffefba8
--- /dev/null
+++ b/Documentation/snippets/new/partcombine-and-autobeamoff.ly
@@ -0,0 +1,52 @@
+\version "2.13.31"
+
+\header {
+  lsrtags = "rhythms"
+
+  texidoc = "
+The function of @code{@bs{}autoBeamOff} when used with
+@code{@bs{}partcombine} can be difficult to understand.  It may
+be preferable to use
+
+@example
+\set Staff.autobeaming = ##f
+@end example
+
+@noindent
+instead, to ensure that autobeaming will be turned off for the entire
+staff.
+
+@code{\partcombine} apparently works with 3 voices -- stem up single,
+stem down single, stem up combined.
+
+An @code{\autoBeamOff} call in the first argument to partcombine will
+apply to the voice that is active at the time the call is processed,
+either stem up single or stem up combined.
+An @code{\autoBeamOff} call in the second argument will apply to the
+voice that is stem down single.
+
+In order to use @code{\autoBeamOff} to stop all autobeaming when used
+with @code{\partcombine},
+it will be necessary to use @emph{three} calls to @code{\autoBeamOff}.
+
+"
+doctitle = "Partcombine and autoBeamOff"
+}
+
+{
+  %\set Staff.autoBeaming = ##f % turns off all autobeaming
+  \partcombine
+      {
+        \autoBeamOff % applies to split up stems
+        \repeat unfold 4 a'16
+        %\autoBeamOff % applies to combined up stems
+        \repeat unfold 4 a'8
+        \repeat unfold 4 a'16
+      }
+      {
+        \autoBeamOff % applies to down stems
+        \repeat unfold 4 f'8
+        \repeat unfold 8 f'16 |
+      }
+}
+

diff --git a/Documentation/snippets/partcombine-and-autobeamoff.ly b/Documentation/snippets/partcombine-and-autobeamoff.ly
new file mode 100644 (file)
index 0000000..acd4270
--- /dev/null
+++ b/Documentation/snippets/partcombine-and-autobeamoff.ly
@@ -0,0 +1,57 @@
+% Do not edit this file; it is automatically
+% generated from Documentation/snippets/new
+% This file is in the public domain.
+%% Note: this file works from version 2.13.31
+\version "2.13.31"
+
+\header {
+  lsrtags = "rhythms"
+
+  texidoc = "
+The function of @code{@bs{}autoBeamOff} when used with
+@code{@bs{}partcombine} can be difficult to understand.  It may
+be preferable to use
+
+@example
+\set Staff.autobeaming = ##f
+@end example
+
+@noindent
+instead, to ensure that autobeaming will be turned off for the entire
+staff.
+
+@code{\partcombine} apparently works with 3 voices -- stem up single,
+stem down single, stem up combined.
+
+An @code{\autoBeamOff} call in the first argument to partcombine will
+apply to the voice that is active at the time the call is processed,
+either stem up single or stem up combined.
+An @code{\autoBeamOff} call in the second argument will apply to the
+voice that is stem down single.
+
+In order to use @code{\autoBeamOff} to stop all autobeaming when used
+with @code{\partcombine},
+it will be necessary to use @emph{three} calls to @code{\autoBeamOff}.
+
+"
+doctitle = "Partcombine and autoBeamOff"
+} % begin verbatim
+
+
+{
+  %\set Staff.autoBeaming = ##f % turns off all autobeaming
+  \partcombine
+      {
+        \autoBeamOff % applies to split up stems
+        \repeat unfold 4 a'16
+        %\autoBeamOff % applies to combined up stems
+        \repeat unfold 4 a'8
+        \repeat unfold 4 a'16
+      }
+      {
+        \autoBeamOff % applies to down stems
+        \repeat unfold 4 f'8
+        \repeat unfold 8 f'16 |
+      }
+}
+