Re: adds documentation for the new bar line interface (issue 6742061)

[marc]

Reviewers: J_lowe,

Message:
James,

thanks for your remarks and corrections!

Some answers (partly preliminal) are listed below.


https://codereview.appspot.com/6742061/diff/2001/Documentation/notation/rhythms.itely
File Documentation/notation/rhythms.itely (right):

https://codereview.appspot.com/6742061/diff/2001/Documentation/notation/rhythms.itely#newcode2765
Documentation/notation/rhythms.itely:2765: New bar line styles can be
defined with @code{\defineBarLine}.
On 2012/10/22 11:09:58, J_lowe wrote:
> Could we have some

> @funindex \defineBarLine
> @cindex bar lines, defining
> @cindex defining bar lines

> or some similar case - I haven't checked this in the current documents
to see
> what else we are using.

Ok, I'll take a look.

https://codereview.appspot.com/6742061/diff/2001/Documentation/notation/rhythms.itely#newcode2779
Documentation/notation/rhythms.itely:2779: The second argument is a list
containing three entries
On 2012/10/22 11:09:58, J_lowe wrote:
> I think you need to clarify this more. I cannot see what the 'second
argument'
> is.

> So for example if you look here:

> http://lilypond.org/doc/v2.16/Documentation/notation/the-set-command

> you can see that we list the command with appropriate @var{..}. That
would help
> the non-technical user to at least get a handle on the command in
full.

> Then move this para above the @lilypond (after the \defineBarLine
@var{} @var{}

> and this is more coherent to read.

Ok, good point.

https://codereview.appspot.com/6742061/diff/2001/Documentation/notation/rhythms.itely#newcode2789
Documentation/notation/rhythms.itely:2789: segno sign, and @code{"["}
and @code{"]"} for the brackets.
On 2012/10/22 11:09:58, J_lowe wrote:
> Would it be too much to have an @lilypond example for all of them?
Instead of
> just listing them

There is no predefined \bar "[" or something similar,
so  one cannot show all "glyphs" without defining
additional bar lines. I don't know whether it worth it,
but it would be doable.
I'll play around and see how far I can get with that.

https://codereview.appspot.com/6742061/diff/2001/Documentation/notation/rhythms.itely#newcode2796
Documentation/notation/rhythms.itely:2796: The @code{"-"} sign allows to
distinguish bar lines with
On 2012/10/22 11:09:58, J_lowe wrote:
> The @code{"-"} sign distinguishes bar lines that have identical...

Yes, much better. Thanks!

https://codereview.appspot.com/6742061/diff/2001/Documentation/notation/rhythms.itely#newcode2802
Documentation/notation/rhythms.itely:2802: way to define new bar line
glyphs.  For more informations
On 2012/10/22 11:09:58, J_lowe wrote:
> are these actually 'glyphs'? I ask because if they are then they need
to appear
> somewhere like here:

> http://lilypond.org/doc/v2.16/Documentation/notation/the-feta-font

> I've never really understood why bar lines (apart from the very fancy
> scripts.varsegno) are not listed here. I am guessing they are not
glyphs and
> this therefore needs to be corrected?

No, they aren't.

The term "glyph" is taken from the grob property
BarLine #'glyph which holds the string that describes
the bar line. This string is transformed into a
series of drawing routines that build up the final stencil.

I am not very happy with this naming convention and tried
to explain it in scm/define-grob-properties.scm
(see glyph and glyph-name).

How shall I proceed? Use the term "glyph" as defined in the
grob properties, or replace it by a better term?

Description:
adds documentation for the new bar line interface

Please review this at https://codereview.appspot.com/6742061/

Affected files:
  M Documentation/notation/rhythms.itely
  M scm/define-context-properties.scm


Index: Documentation/notation/rhythms.itely
diff --git a/Documentation/notation/rhythms.itely  
b/Documentation/notation/rhythms.itely
index  
975017057ca64fcaf384ccfc228ddca0e9d8b9a5..7ccb51a7f8c691f741f502fefc0a2db832b23aac  
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 line:

 @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:
@@ -2710,8 +2714,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
address@hidden"|:"} except at line breaks, where it gives a double bar
+In addition, you can specify @code{".|:-||"}, which is equivalent to
address@hidden".|:"} 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 +2762,49 @@ Additionally there is an @code{\inStaffSegno}  
command which
 creates a segno bar, placed in cooperation
 with the @code{\repeat volta} command.

+New bar line styles can be defined with @code{\defineBarLine}.
+
address@hidden,relative=2,verbatim]
+\defineBarLine "[|;" #'("|" "[|;" " |")
+\defineBarLine ";|]" #'(";|]" "" " |")
+
+\new Staff {
+  c4 c \bar "[|;" c c \bar ";|]" \break
+  c4 c \bar ";|]" c c \bar "[|;" \break
+  c1
+}
+
address@hidden lilypond
+
+The second argument is a list containing three entries
+for defining the behavior at the end of a line, at the
+beginning of the next line and as a span bar, respectively.
+
+There are currently eleven glyphs available:
address@hidden"|"} for the thin bar line, @code{"."} for a thick bar line,
address@hidden"!"} and @code{";"} for a dashed/dotted bar line, @code{":"}
+for repeat dots, @code{"k"} for the kievan bar line,
address@hidden"S"} for the segno bar line and its counterpart @code{"="}
+which provides the double span bar line in combination with the
+segno sign, and @code{"["} and @code{"]"} for the brackets.
+
+Furthermore, the space character @code{" "} serves as a placeholder
+for defining span bars correctly aligned to the main bar lines;
+the repeat sign @code{":|."} has the span bar definition
address@hidden" |."} (note the space).
+
+The @code{"-"} sign allows to distinguish bar lines with
+identical appearance but different behavior at line breaks
+and/or different span bars, as mentioned above in the
address@hidden".|:-||"} example.
+
+If additional glyphs are needed, Lilypond provides a simple
+way to define new bar line glyphs.  For more informations
+on modifying or adding bar lines, see file @file{scm/bar-line.scm}.
+
+Installed Files:
address@hidden/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
Index: scm/define-context-properties.scm
diff --git a/scm/define-context-properties.scm  
b/scm/define-context-properties.scm
index  
76c5191bf1518b9a2e3e81eaefb274db877871d2..3e871e72cf03104ad36f686e7515d7dec9815b4c  
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}.")
      )))