From d4918b03dc235782cad8461f8e9d81fcd496d0d6 Mon Sep 17 00:00:00 2001
From: Marc Hohl <marc@hohlart.de>
Date: Mon, 22 Oct 2012 12:23:50 +0200
Subject: [PATCH] adds documentation for the new bar line interface

---
 Documentation/notation/rhythms.itely | 119 +++++++++++++++++++++++++--
 scm/define-context-properties.scm    |   2 +-
 2 files changed, 115 insertions(+), 6 deletions(-)

diff --git a/Documentation/notation/rhythms.itely b/Documentation/notation/rhythms.itely
index 975017057c..517b95b606 100644
--- a/Documentation/notation/rhythms.itely
+++ b/Documentation/notation/rhythms.itely
@@ -2662,15 +2662,19 @@ a1
 @end lilypond
 
 @noindent
-and five types of repeat bar line:
+and nine types of repeat bar lines:
 
 @lilypond[quote,relative=1,verbatim]
 f1 \bar ".|:"
 g1 \bar ":..:"
 a1 \bar ":|.|:"
 b1 \bar ":|.:"
-c1 \bar ":|."
-e1
+c1 \bar ":.|.:"
+d1 \bar "[|:"
+e1 \bar ":|][|:"
+f1 \bar ":|]"
+g1 \bar ":|."
+a1
 @end lilypond
 
 Additionally, a bar line can be printed as a simple tick:
@@ -2681,6 +2685,14 @@ However, as such ticks are typically used in Gregorian chant, it is
 preferable to use @code{\divisioMinima} there instead, described in
 the section @ref{Divisiones} in Gregorian chant.
 
+Lilypond supports kievan notation and provides a special kievan
+bar line:
+@lilypond[quote,relative=1,verbatim]
+f1 \bar "k"
+@end lilypond
+Further details of this notation are explained in
+@ref{Typesetting Kievan square notation}.
+
 @cindex segno
 
 For in-line segno signs, there are three types of bar lines which
@@ -2710,8 +2722,8 @@ a repeated section.  Such repeated sections are better entered
 using the various repeat commands (see @ref{Repeats}), which
 automatically print the appropriate bar lines.
 
-In addition, you can specify @code{"||:"}, which is equivalent to
-@code{"|:"} except at line breaks, where it gives a double bar
+In addition, you can specify @code{".|:-||"}, which is equivalent to
+@code{".|:"} except at line breaks, where it gives a double bar
 line at the end of the line and a start repeat at the beginning of
 the next line.
 
@@ -2758,6 +2770,100 @@ Additionally there is an @code{\inStaffSegno} command which
 creates a segno bar, placed in cooperation
 with the @code{\repeat volta} command.
 
+@funindex \defineBarLine
+@funindex defineBarLine
+@cindex bar lines, defining
+@cindex defining bar lines
+
+New bar line types can be defined with @code{\defineBarLine}:
+
+@example
+\defineBarLine @var{bartype} #'(@var{end} @var{begin} @var{span})
+@end example
+
+The @code{\defineBarline} variables can include the
+@q{empty} string @code{""}, which is equivalent to an invisible
+bar line being printed.  Or they can be set to @code{#f} which
+prints no bar line at all.
+
+After the definiton, the new bar line can be used by
+@code{\bar} @var{bartype}.
+
+There are currently ten bar line elements available:
+
+@lilypond[quote,verbatim]
+\defineBarLine ":" #'("" ":" "")
+\defineBarLine "=" #'("=" "" "")
+\defineBarLine "[" #'("" "[" "")
+\defineBarLine "]" #'("]" "" "")
+
+\new Staff {
+  s1 \bar "|"
+  s1 \bar "."
+  s1 \bar "!"
+  s1 \bar ";"
+  s1 \bar ":"
+  s1 \bar "k"
+  s1 \bar "S"
+  s1 \bar "="
+  s1 \bar "["
+  s1 \bar "]"
+  s1 \bar ""
+}
+@end lilypond
+
+The @code{"="} bar line provides the double span bar line, used
+in combination with the segno sign.  Do not use it as a standalone
+double thin bar line; here, @code{\bar} @var{"||"} is
+preferred.
+
+The @code{"-"} sign starts annotations to bar lines which
+are useful to distinguish those with identical appearance
+but different behavior at line breaks and/or different span bars.
+The part following the @code{"-"} sign is not used for building up
+the bar line.
+
+@lilypond[quote,relative=2,verbatim]
+\defineBarLine "||-dashedSpan" #'("||" "" "!!")
+
+\new StaffGroup <<
+  \new Staff {
+    c1 \bar "||"
+    c1 \bar "||-dashedSpan"
+    c1
+  }
+  \new Staff {
+    c1
+    c1
+    c1
+  }
+>>
+@end lilypond
+
+Furthermore, the space character @code{" "} serves as a placeholder
+for defining span bars correctly aligned to the main bar lines:
+
+@lilypond[quote,relative=2,verbatim]
+\defineBarLine ":|.-wrong" #'(":|." "" "|.")
+\defineBarLine ":|.-right" #'(":|." "" " |.")
+
+\new StaffGroup <<
+  \new Staff {
+    c1 \bar ":|.-wrong"
+    c1 \bar ":|.-right"
+    c1
+  }
+  \new Staff {
+    c1
+    c1
+    c1
+  }
+>>
+@end lilypond
+
+If additional elements are needed, LilyPond provides a simple
+way to define them.  For more informations on modifying or adding
+bar lines, see file @file{scm/bar-line.scm}.
 
 In scores with many staves, a @code{\bar} command in one staff is
 automatically applied to all staves.  The resulting bar lines are
@@ -2804,6 +2910,9 @@ Notation Reference:
 @ref{Repeats},
 @ref{Grouping staves}.
 
+Installed Files:
+@file{scm/bar-line.scm}.
+
 Snippets:
 @rlsr{Rhythms}.
 
diff --git a/scm/define-context-properties.scm b/scm/define-context-properties.scm
index 76c5191bf1..3e871e72cf 100644
--- a/scm/define-context-properties.scm
+++ b/scm/define-context-properties.scm
@@ -581,7 +581,7 @@ Example:
 
 @noindent
 This will create a start-repeat bar in this staff only.  Valid values
-are described in @rinternals{bar-line-interface}.")
+are described in @file{scm/bar-line.scm}.")
      )))
 
 
-- 
2.39.2