From c4a449415e6a279a8e6cb5cbd2803eb036f40c10 Mon Sep 17 00:00:00 2001
From: Trevor Daniels <t.daniels@treda.co.uk>
Date: Mon, 30 Dec 2013 23:52:02 +0000
Subject: [PATCH] Issue 3751: Doc: Augment documentation for \inStaffSegno

  Slightly expand referring text in NR 1.2.5

  Expand NR 1.4.1 with additional text and examples

  Add regression test
---
 Documentation/notation/repeats.itely   | 95 +++++++++++++++++++++-----
 Documentation/notation/rhythms.itely   |  7 +-
 input/regression/repeat-volta-segno.ly | 33 +++++++++
 3 files changed, 114 insertions(+), 21 deletions(-)
 create mode 100644 input/regression/repeat-volta-segno.ly

diff --git a/Documentation/notation/repeats.itely b/Documentation/notation/repeats.itely
index ad555652fb..f3c4c5ac6c 100644
--- a/Documentation/notation/repeats.itely
+++ b/Documentation/notation/repeats.itely
@@ -239,24 +239,6 @@ g1 |
 The @code{measureLength} property is described in @ref{Time
 administration}.
 
-@funindex \inStaffSegno
-
-The @code{\inStaffSegno} command can be used to place the segno
-symbol in cooperation with the @code{\repeat volta} command.
-Alternative bar line symbols can be set in a Score context by
-overriding the properties @code{segnoType},
-@code{startRepeatSegnoType}, @code{endRepeatSegnoType} or
-@code{doubleRepeatSegnoType} as required.
-
-@lilypond[verbatim,quote,relative=1]
-e1
-\repeat volta 2 {
-  \inStaffSegno
-  f2 g a b
-}
-c1_"D.S." \bar "|."
-@end lilypond
-
 @cindex repeats, with ties
 @cindex alternative endings, with ties
 @cindex ties, in repeats
@@ -274,6 +256,83 @@ c1
 }
 @end lilypond
 
+@funindex \inStaffSegno
+@cindex repeats, with segno
+@cindex segno, with repeats
+
+The @code{\inStaffSegno} command can be used to generate a composite
+bar line incorporating the segno symbol with the appropriate repeat
+bar line when used with the @code{\repeat volta} command.  The
+correct type of repeat bar line, viz. start repeat, end repeat or
+double repeat, is selected automatically.  Note that the
+corresponding @qq{D.S.} mark must be added manually.
+
+Away from a repeat:
+
+@lilypond[verbatim,quote,relative=1]
+e1
+\inStaffSegno
+f2 g a b
+c1_"D.S." \bar "|."
+@end lilypond
+
+At the start of a repeat:
+
+@lilypond[verbatim,quote,relative=1]
+e1
+\repeat volta 2 {
+  \inStaffSegno  % start repeat
+  f2 g a b
+}
+c1_"D.S." \bar "|."
+@end lilypond
+
+At the end of a repeat:
+
+@lilypond[verbatim,quote,relative=1]
+e1
+\repeat volta 2 {
+  f2 g a b
+  \inStaffSegno  % end repeat
+}
+f2 g a b
+c1_"D.S." \bar "|."
+@end lilypond
+
+Between two repeats:
+
+@lilypond[verbatim,quote,relative=1]
+e1
+\repeat volta 2 {
+  f2 g a b
+}
+\inStaffSegno  % double repeat
+\repeat volta 2 {
+  f2 g a b
+}
+c1_"D.S." \bar "|."
+@end lilypond
+
+Alternative bar line symbols can be obtained by setting (in the Score
+context) the properties @code{segnoType}, @code{startRepeatSegnoType},
+@code{endRepeatSegnoType} or @code{doubleRepeatSegnoType} to the
+required bar line type.  The alternative bar line types must be
+selected from the pre-defined types or types previously defined
+with the @code{\defineBarLine} command (see @ref{Bar lines}).
+
+@lilypond[verbatim,quote,relative=1]
+\defineBarLine ":|.S[" #'(":|." "S[" "")
+\defineBarLine "]" #'("]" "" "")
+e1
+\repeat volta 2 {
+  f2 g a b
+  \once \set Score.endRepeatSegnoType = ":|.S["
+  \inStaffSegno
+}
+f2 g \bar "]" a b
+c1_"D.S." \bar "|."
+@end lilypond
+
 @snippets
 @lilypondfile[verbatim,quote,texidoc,doctitle]
 {shortening-volta-brackets.ly}
diff --git a/Documentation/notation/rhythms.itely b/Documentation/notation/rhythms.itely
index f935956922..048d3a58d7 100644
--- a/Documentation/notation/rhythms.itely
+++ b/Documentation/notation/rhythms.itely
@@ -2812,9 +2812,10 @@ c4 c c c \break
 c1
 @end lilypond
 
-Additionally there is an @code{\inStaffSegno} command which
-creates a segno bar, placed in cooperation
-with the @code{\repeat volta} command.
+Additionally there is an @code{\inStaffSegno} command which creates
+a segno bar line in conjunction with an appropriate repeat bar line
+when used with a @code{\repeat volta} command, see
+@ref{Normal repeats}.
 
 @funindex \defineBarLine
 @funindex defineBarLine
diff --git a/input/regression/repeat-volta-segno.ly b/input/regression/repeat-volta-segno.ly
new file mode 100644
index 0000000000..a03a95f144
--- /dev/null
+++ b/input/regression/repeat-volta-segno.ly
@@ -0,0 +1,33 @@
+\version "2.18.0"
+
+\header {
+  texidoc="
+  The segno sign should be automatically combined with the
+  appropriate repeat bar line when @code{\inStaffSegno} is
+  used.
+"
+}
+
+\relative c' {
+  c1
+  \inStaffSegno
+  c2^"no repeat" c c c
+  \repeat volta 2 {
+    \inStaffSegno  % start repeat
+  c2^"start repeat" c c c
+  }
+  \break
+  c1
+  \repeat volta 2 {
+  c2 c c c^"end repeat"
+    \inStaffSegno  % end repeat
+  }
+  c2 c c c
+  \repeat volta 2 {
+  c2 c c c
+  }
+  \inStaffSegno  % double repeat
+  \repeat volta 2 {
+  c2^"double repeat" c c c
+  }
+}
-- 
2.39.2